minecraft-rcon-mcp: Instructions file for Claude Code

minecraft-rcon-mcp — agent guide

This package is a server-agnostic MCP server (RCON tool + in-game AI chat) plus a toolbox of scripts. Nothing here may hardcode knowledge of a particular server, world, player, or save location — that all comes from environment variables / arguments so the package stays reusable. Deployment-specific facts live in the consumer (server) repo, never here.

For how to run things and the full env-var reference, see README.md.

How to write a script

The goal is a toolbox of small, orthogonal primitives that compose efficiently, plus a few recipes that show how to combine them. Before writing a new script, decide which layer it belongs to:

• Primitive → src/minecraft_rcon_mcp/scripts/. Does one general thing, reusable across many tasks (e.g. count_entities, find_block_entities, check_chunk_generated). No task-specific logic, no version-coupled constants.
• Recipe → src/minecraft_rcon_mcp/recipes/. A specific task composed from primitives (e.g. reset_trial_spawners = find_block_entities + rcon). May be coupled to a Minecraft version's mechanics — say so in the docstring.

Prefer composition over new scripts. If a task is just two or three primitive calls, record it as a recipe in agent_memory/capabilities.md (capability memory) rather than adding a file. Only add a recipe module when it carries real logic worth keeping (parsing, thresholds, multi-step orchestration).

Authoring checklist

1. Server-agnostic. No hardcoded worlds, players, coordinates, or paths.
   • RCON: RCON_HOST / RCON_PORT / RCON_PASSWORD (use scripts.rcon.RconClient).
   • World save files: resolve via scripts._world.resolve_world_dir() (reads WORLD_DIR or a --world-dir arg). The world path cannot be derived over RCON.
   • Dimension: take --dimension (default overworld) and resolve region dirs with scripts._world.region_dir(world_dir, dimension) — it handles vanilla (DIM-1/DIM1) and data-driven (dimensions/<ns>/<name>/) layouts plus aliases. Never hardcode a single dimension.
2. Reuse the shared helpers — don't reimplement RCON, region/NBT parsing, or entity counting:
   • scripts.rcon — RconClient, run.
   • scripts._world — resolve_world_dir, region_dir.
   • scripts.count_entities — count_entities(rc, selector, at=...), parse_count.
   • scripts.find_block_entities — scan_block_entities(...) for region scans.
3. Module + importable API. Make it runnable as python -m minecraft_rcon_mcp.<scripts|recipes>.<name> and expose a plain function (not just a CLI) so the MCP server and other scripts can call it directly. This is what will let the in-game agent run scripts later (roadmap).
4. Version coupling lives in recipes, flagged in the docstring (e.g. "gates verified against 26.1 bytecode; may drift across versions").
5. Quality gates (all must pass — see README → Development):
   • ruff format + ruff check (line length 100).
   • ty check (annotate enough that it passes; guard __doc__ as (__doc__ or "")).
   • pytest — add tests for pure logic (parsers, path resolution, selector building) using fakes; don't require a live server.
   • Add any new dependency to pyproject.toml.
6. Docstring with a one-line purpose and copy-pasteable usage examples (use neutral placeholders like /path/to/world, Steve — never this deployment's real world/player names).