# xlfries/minecraft-mcp architecture

> Architecture diagram of the GitHub repository xlfries/minecraft-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xlfries/minecraft-mcp
- Repository: https://github.com/xlfries/minecraft-mcp

## Overview

This repository provides a Minecraft MCP server: an MCP client invokes registered tools, whose handlers check the bot connection and perform Minecraft actions. The tree also contains a separate agent/provider/history subsystem, but the sampled startup does not wire it into the server workflow. The README gives no capability overview, so tool capabilities are represented from the tool module names and available excerpts; unsampled tool internals and external-provider wiring remain uncertain.

Main entry points: [`src/register-tools.ts`](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/register-tools.ts) (Tool registration), [`src/main.ts`](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/main.ts) (Server startup), [`src/agent/agent.ts`](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/agent/agent.ts) (Agent loop), [`src/bot-connection.ts`](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/bot-connection.ts) (Bot connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP runtime"]
  node_entry["Server startup<br/>[main.ts]"]
  node_config["Configuration<br/>[config.ts]"]
  node_registry["Tool registry<br/>[tool-registry.ts]"]
  node_factory["Tool factory<br/>[tool-factory.ts]"]
  node_messages["Chat messages<br/>[message-store.ts]"]
end

subgraph group_connection["Minecraft connection"]
  node_bot["Bot connection<br/>[bot-connection.ts]"]
end

subgraph group_tools["Minecraft tools"]
  node_registration["Tool registration<br/>[register-tools.ts]"]
  node_position["Position tools<br/>[position-tools.ts]"]
  node_inventory["Inventory tools<br/>[inventory-tools.ts]"]
  node_blocks["Block tools<br/>[block-tools.ts]"]
  node_entities["Entity tools<br/>[entity-tools.ts]"]
  node_chattools["Chat tools<br/>[chat-tools.ts]"]
  node_flight["Flight tools<br/>[flight-tools.ts]"]
  node_gamestate["Game-state tools<br/>[gamestate-tools.ts]"]
  node_crafting["Crafting tools<br/>[crafting-tools.ts]"]
  node_furnace["Furnace tools<br/>[furnace-tools.ts]"]
  node_coordinates["Coordinate helper"]
end

subgraph group_agent["Agent subsystem"]
  node_agent["Agent loop<br/>[agent.ts]"]
  node_provider["Ollama provider<br/>[ollama-provider.ts]"]
  node_history[("History store<br/>[history-store.ts]")]
  node_schema["Tool schemas<br/>[tool-schema.ts]"]
end

node_client(("MCP client"))
node_minecraft(("Minecraft server"))

node_client -->|"sends MCP requests"| node_entry
node_entry -->|"parses settings"| node_config
node_entry -->|"connects bot"| node_bot
node_entry -->|"stores chat"| node_messages
node_entry -->|"registers tools"| node_registration
node_entry -->|"mounts tools"| node_registry
node_entry -->|"creates factory"| node_factory
node_bot -->|"connects to"| node_minecraft
node_bot -->|"forwards chat"| node_messages
node_registration -->|"registers"| node_position
node_registration -->|"registers"| node_inventory
node_registration -->|"registers"| node_blocks
node_registration -->|"registers"| node_entities
node_registration -->|"registers"| node_chattools
node_registration -->|"registers"| node_flight
node_registration -->|"registers"| node_gamestate
node_registration -->|"registers"| node_crafting
node_registration -->|"registers"| node_furnace
node_factory -->|"registers handlers"| node_registry
node_factory -->|"checks connection"| node_bot
node_blocks -->|"coerces coordinates"| node_coordinates
node_position -->|"uses coordinate helper"| node_coordinates
node_flight -->|"uses coordinate helper"| node_coordinates
node_furnace -->|"uses coordinate helper"| node_coordinates
node_blocks -->|"reads and changes world"| node_minecraft
node_crafting -->|"reads inventory, crafts"| node_minecraft
node_chattools -->|"reads chat history"| node_messages
node_agent -->|"builds tool specs"| node_schema
node_agent -->|"calls tools"| node_registry
node_agent -->|"restores and appends"| node_history
node_agent -.->|"uses provider"| node_provider

click node_entry "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/main.ts"
click node_config "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/config.ts"
click node_registry "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tool-registry.ts"
click node_factory "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tool-factory.ts"
click node_messages "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/message-store.ts"
click node_bot "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/bot-connection.ts"
click node_registration "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/register-tools.ts"
click node_position "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/position-tools.ts"
click node_inventory "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/inventory-tools.ts"
click node_blocks "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/block-tools.ts"
click node_entities "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/entity-tools.ts"
click node_chattools "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/chat-tools.ts"
click node_flight "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/flight-tools.ts"
click node_gamestate "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/gamestate-tools.ts"
click node_crafting "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/crafting-tools.ts"
click node_furnace "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/furnace-tools.ts"
click node_coordinates "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/coordinate-utils.ts"
click node_agent "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/agent/agent.ts"
click node_provider "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/agent/providers/ollama-provider.ts"
click node_history "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/memory/history-store.ts"
click node_schema "https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tool-schema.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_config,node_registry,node_factory,node_messages,node_client toneBlue
class node_bot toneAmber
class node_registration,node_position,node_inventory,node_blocks,node_entities,node_chattools,node_flight,node_gamestate,node_crafting,node_furnace,node_coordinates,node_minecraft toneMint
class node_agent,node_provider,node_history,node_schema toneRose
```

## Components

### MCP runtime

- [Server startup](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/main.ts): `src/main.ts`
- [Configuration](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/config.ts): `src/config.ts`
- [Tool registry](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tool-registry.ts): `src/tool-registry.ts`
- [Tool factory](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tool-factory.ts): `src/tool-factory.ts`
- [Chat messages](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/message-store.ts): `src/message-store.ts`

### Minecraft connection

- [Bot connection](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/bot-connection.ts): `src/bot-connection.ts`

### Minecraft tools

- [Tool registration](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/register-tools.ts): `src/register-tools.ts`
- [Position tools](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/position-tools.ts): `src/tools/position-tools.ts`
- [Inventory tools](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/inventory-tools.ts): `src/tools/inventory-tools.ts`
- [Block tools](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/block-tools.ts): `src/tools/block-tools.ts`
- [Entity tools](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/entity-tools.ts): `src/tools/entity-tools.ts`
- [Chat tools](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/chat-tools.ts): `src/tools/chat-tools.ts`
- [Flight tools](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/flight-tools.ts): `src/tools/flight-tools.ts`
- [Game-state tools](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/gamestate-tools.ts): `src/tools/gamestate-tools.ts`
- [Crafting tools](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/crafting-tools.ts): `src/tools/crafting-tools.ts`
- [Furnace tools](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/furnace-tools.ts): `src/tools/furnace-tools.ts`
- [Coordinate helper](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tools/coordinate-utils.ts): `src/tools/coordinate-utils.ts`

### Agent subsystem

- [Agent loop](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/agent/agent.ts): `src/agent/agent.ts`
- [Ollama provider](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/agent/providers/ollama-provider.ts): `src/agent/providers/ollama-provider.ts`
- [History store](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/memory/history-store.ts): `src/memory/history-store.ts`
- [Tool schemas](https://github.com/xlfries/minecraft-mcp/blob/gui-agent/src/tool-schema.ts): `src/tool-schema.ts`

### Other components

- **MCP client**
- **Minecraft server**

## Connections

- MCP client → Server startup: sends MCP requests (evidence: `src/main.ts`)
- Server startup → Configuration: parses settings (evidence: `src/main.ts`)
- Server startup → Bot connection: connects bot (evidence: `src/main.ts`)
- Server startup → Chat messages: stores chat (evidence: `src/main.ts`)
- Server startup → Tool registration: registers tools (evidence: `src/main.ts`)
- Server startup → Tool registry: mounts tools (evidence: `src/main.ts`)
- Server startup → Tool factory: creates factory (evidence: `src/main.ts`)
- Bot connection → Minecraft server: connects to (evidence: `src/bot-connection.ts`)
- Bot connection → Chat messages: forwards chat (evidence: `src/main.ts`)
- Tool registration → Position tools: registers (evidence: `src/register-tools.ts`)
- Tool registration → Inventory tools: registers (evidence: `src/register-tools.ts`)
- Tool registration → Block tools: registers (evidence: `src/register-tools.ts`)
- Tool registration → Entity tools: registers (evidence: `src/register-tools.ts`)
- Tool registration → Chat tools: registers (evidence: `src/register-tools.ts`)
- Tool registration → Flight tools: registers (evidence: `src/register-tools.ts`)
- Tool registration → Game-state tools: registers (evidence: `src/register-tools.ts`)
- Tool registration → Crafting tools: registers (evidence: `src/register-tools.ts`)
- Tool registration → Furnace tools: registers (evidence: `src/register-tools.ts`)
- Tool factory → Tool registry: registers handlers (evidence: `src/tool-factory.ts`)
- Tool factory → Bot connection: checks connection (evidence: `src/tool-factory.ts`)
- Block tools → Coordinate helper: coerces coordinates (evidence: `src/tools/block-tools.ts`)
- Position tools → Coordinate helper: uses coordinate helper (evidence: `src/tools/position-tools.ts`)
- Flight tools → Coordinate helper: uses coordinate helper (evidence: `src/tools/flight-tools.ts`)
- Furnace tools → Coordinate helper: uses coordinate helper (evidence: `src/tools/furnace-tools.ts`)
- Block tools → Minecraft server: reads and changes world (evidence: `src/tools/block-tools.ts`)
- Crafting tools → Minecraft server: reads inventory, crafts (evidence: `src/tools/crafting-tools.ts`)
- Chat tools → Chat messages: reads chat history (evidence: `src/register-tools.ts`)
- Agent loop → Tool schemas: builds tool specs (evidence: `src/agent/agent.ts`)
- Agent loop → Tool registry: calls tools (evidence: `src/agent/agent.ts`)
- Agent loop → History store: restores and appends (evidence: `src/agent/agent.ts`)
- Agent loop → Ollama provider: uses provider