Agent runtime

Agent runtime

On top of the bridge tools (the agent's body: move, mine, look) the MCP server ships a runtime with what an autonomous agent needs across sessions:

• long-term memory: notes, places, container contents, events and skills, with full-text search;
• a persistent goal tree;
• a chunk-level world map with exploration by frontier;
• a crafting planner over the game's own recipes, vanilla and modded;
• background jobs that run multi-step actions without the model driving every tick.

Everything is stored per world in one SQLite file, ~/.mcpfabric/agent.db. The file is created the first time an agent tool is called, not when the server starts. The full reference is docs/AGENT.md.

Suggested loop for the model

1. agent_brief: where am I, what was I doing.
2. goal_list, or goal_add with a checkable doneWhen and concrete subgoals.
3. recall before searching the world again. plan_craft before gathering.
4. Start a job (collect_blocks, craft_item, travel_to, explore) and follow it with job_status.
5. observe after arriving somewhere new. remember what matters: bases, dangers, player requests.
6. goal_update with an outcome, then the next goal.

Jobs

travel_to, explore, collect_blocks and craft_item return at once; job_status long-polls and job_cancel stops one. Only one job runs at a time (there is one body). A job belongs to the MCP session that started it; closing the session cancels it, and every job stops after 31 minutes. Jobs check health before each step and stop with a reason when it drops to the limit (6 by default). While walking or mining a job also fights back against hostile mobs in melee range, except creepers.

Settings

Variable	Default	Meaning
MCPFABRIC_AGENT	on	0, false or off serves only the bridge tools
MCPFABRIC_DATA_DIR	~/.mcpfabric	where agent.db lives
MCPFABRIC_WORLD	from the game	force a world id, for example to share memory between two saves

Needs Node.js 22.16 or newer (node:sqlite with FTS5).

Known limits

• The walker cannot swim, climb ladders, pillar up or dig tunnels; buried blocks are skipped.
• On 1.21.2+ multiplayer the client only sees recipes it has unlocked, so some crafts cannot be planned.
• Smelting and smithing steps are planned but not executed automatically.