# nice2mu/muumc architecture

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

- Interactive diagram: https://gitdiagram.com/nice2mu/muumc
- Repository: https://github.com/nice2mu/muumc

## Overview

muu-mc is an MCP server that exposes Minecraft control and world-information tools to an AI host. The main workflow is a host task request through the MCP tool handler into cached skills or generated, sandboxed code, which acts on the game through a safety DSL and normalized bot driver. The README also documents autonomous planning, construction, persistent world memory, and voice-chat integration. Some subsystems are represented from documented capabilities and the file tree; their internal wiring is omitted where excerpts do not establish it.

Main entry points: [`src/mcp/tools.js`](https://github.com/nice2mu/muumc/blob/main/src/mcp/tools.js) (Tool handler), [`src/bot/client.js`](https://github.com/nice2mu/muumc/blob/main/src/bot/client.js) (Bot client), [`src/index.js`](https://github.com/nice2mu/muumc/blob/main/src/index.js) (MCP server), [`src/bot/autonomous_engine.js`](https://github.com/nice2mu/muumc/blob/main/src/bot/autonomous_engine.js) (Autonomous engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP Interface"]
  node_server["MCP server<br/>[index.js]"]
  node_tools["Tool handler<br/>[tools.js]"]
  node_resources["Resource handler<br/>[resources.js]"]
end

subgraph group_gameplay["Gameplay Runtime"]
  node_client["Bot client<br/>[client.js]"]
  node_chat["Chat companion<br/>[chat_companion.js]"]
  node_dsl["Safe game DSL<br/>[dsl.js]"]
  node_watchdog["Game watchdog<br/>[watchdog.js]"]
  node_adapter["Driver adapter<br/>[adapter.js]"]
end

subgraph group_cognition["Planning and Skills"]
  node_engine["Autonomous engine"]
  node_planner["Goal planner<br/>[goal_plan.js]"]
  node_evaluator["Situation evaluator"]
  node_skillmanager["Skill cache<br/>[skill_manager.js]"]
  node_skills["Skill library"]
  node_coder["AI coder<br/>[agent.js]"]
  node_sandbox["Code sandbox<br/>[sandbox.js]"]
  node_debugger["Self-healing debugger<br/>[debugger.js]"]
end

subgraph group_world["World Services"]
  node_worldmemory[("World memory<br/>[world_memory.js]")]
  node_builder["Construction subsystem"]
end

subgraph group_integrations["External Integrations"]
  node_voiceclient["Voice bridge client<br/>[voice_client.js]"]
  node_voicemanager["Voice event manager<br/>[voice_manager.js]"]
end

node_host(("AI host"))
node_game(("Minecraft server"))
node_voicebridge(("Voice bridge service"))
node_ollama(("Ollama model"))

node_host -->|"MCP requests"| node_server
node_server -->|"dispatches tools"| node_tools
node_server -->|"dispatches resources"| node_resources
node_server -->|"starts connection"| node_client
node_tools -->|"matches skills"| node_skillmanager
node_skillmanager -->|"loads skills"| node_skills
node_tools -->|"requests code"| node_coder
node_coder -.->|"generates code"| node_ollama
node_tools -->|"executes code"| node_sandbox
node_sandbox -->|"invokes helpers"| node_dsl
node_tools -->|"repairs failures"| node_debugger
node_debugger -->|"re-executes code"| node_sandbox
node_engine -->|"dispatches tasks"| node_tools
node_engine -->|"manages goals"| node_planner
node_engine -->|"checks progress"| node_evaluator
node_client -->|"creates adapter"| node_adapter
node_client -->|"wires watchdog"| node_watchdog
node_client -->|"wires DSL"| node_dsl
node_dsl -->|"uses game API"| node_adapter
node_watchdog -->|"monitors actions"| node_adapter
node_adapter -->|"controls bot"| node_game
node_tools -->|"dispatches builds"| node_builder
node_tools -->|"manages memory"| node_worldmemory
node_resources -->|"reads world data"| node_worldmemory
node_client -->|"records landmarks"| node_worldmemory
node_server -->|"starts bridge"| node_voiceclient
node_voiceclient -.->|"connects outbound"| node_voicebridge
node_voiceclient -->|"forwards utterances"| node_voicemanager
node_voicemanager -->|"sends notifications"| node_server
node_voicemanager -->|"pauses on command"| node_engine
node_client -->|"processes chat"| node_chat

click node_server "https://github.com/nice2mu/muumc/blob/main/src/index.js"
click node_tools "https://github.com/nice2mu/muumc/blob/main/src/mcp/tools.js"
click node_resources "https://github.com/nice2mu/muumc/blob/main/src/mcp/resources.js"
click node_client "https://github.com/nice2mu/muumc/blob/main/src/bot/client.js"
click node_engine "https://github.com/nice2mu/muumc/blob/main/src/bot/autonomous_engine.js"
click node_planner "https://github.com/nice2mu/muumc/blob/main/src/bot/planner/goal_plan.js"
click node_evaluator "https://github.com/nice2mu/muumc/blob/main/src/bot/planner/situation_evaluator.js"
click node_chat "https://github.com/nice2mu/muumc/blob/main/src/bot/chat_companion.js"
click node_skillmanager "https://github.com/nice2mu/muumc/blob/main/src/memory/skill_manager.js"
click node_skills "https://github.com/nice2mu/muumc/tree/main/data/skills"
click node_coder "https://github.com/nice2mu/muumc/blob/main/src/coder/agent.js"
click node_sandbox "https://github.com/nice2mu/muumc/blob/main/src/coder/sandbox.js"
click node_debugger "https://github.com/nice2mu/muumc/blob/main/src/coder/debugger.js"
click node_dsl "https://github.com/nice2mu/muumc/blob/main/src/coder/dsl.js"
click node_watchdog "https://github.com/nice2mu/muumc/blob/main/src/bot/watchdog.js"
click node_adapter "https://github.com/nice2mu/muumc/blob/main/src/driver/adapter.js"
click node_worldmemory "https://github.com/nice2mu/muumc/blob/main/src/memory/world_memory.js"
click node_builder "https://github.com/nice2mu/muumc/tree/main/src/builder"
click node_voiceclient "https://github.com/nice2mu/muumc/blob/main/src/voice/voice_client.js"
click node_voicemanager "https://github.com/nice2mu/muumc/blob/main/src/voice/voice_manager.js"

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_server,node_tools,node_resources toneBlue
class node_client,node_chat,node_dsl,node_watchdog,node_adapter toneAmber
class node_engine,node_planner,node_evaluator,node_skillmanager,node_skills,node_coder,node_sandbox,node_debugger,node_game toneMint
class node_worldmemory,node_builder toneRose
class node_voiceclient,node_voicemanager,node_host,node_voicebridge,node_ollama toneIndigo
```

## Components

### MCP Interface

- [MCP server](https://github.com/nice2mu/muumc/blob/main/src/index.js): `src/index.js`
- [Tool handler](https://github.com/nice2mu/muumc/blob/main/src/mcp/tools.js): `src/mcp/tools.js`
- [Resource handler](https://github.com/nice2mu/muumc/blob/main/src/mcp/resources.js): `src/mcp/resources.js`

### Gameplay Runtime

- [Bot client](https://github.com/nice2mu/muumc/blob/main/src/bot/client.js): `src/bot/client.js`
- [Chat companion](https://github.com/nice2mu/muumc/blob/main/src/bot/chat_companion.js): `src/bot/chat_companion.js`
- [Safe game DSL](https://github.com/nice2mu/muumc/blob/main/src/coder/dsl.js): `src/coder/dsl.js`
- [Game watchdog](https://github.com/nice2mu/muumc/blob/main/src/bot/watchdog.js): `src/bot/watchdog.js`
- [Driver adapter](https://github.com/nice2mu/muumc/blob/main/src/driver/adapter.js): `src/driver/adapter.js`

### Planning and Skills

- [Autonomous engine](https://github.com/nice2mu/muumc/blob/main/src/bot/autonomous_engine.js): `src/bot/autonomous_engine.js`
- [Goal planner](https://github.com/nice2mu/muumc/blob/main/src/bot/planner/goal_plan.js): `src/bot/planner/goal_plan.js`
- [Situation evaluator](https://github.com/nice2mu/muumc/blob/main/src/bot/planner/situation_evaluator.js): `src/bot/planner/situation_evaluator.js`
- [Skill cache](https://github.com/nice2mu/muumc/blob/main/src/memory/skill_manager.js): `src/memory/skill_manager.js`
- [Skill library](https://github.com/nice2mu/muumc/tree/main/data/skills): `data/skills`
- [AI coder](https://github.com/nice2mu/muumc/blob/main/src/coder/agent.js): `src/coder/agent.js`
- [Code sandbox](https://github.com/nice2mu/muumc/blob/main/src/coder/sandbox.js): `src/coder/sandbox.js`
- [Self-healing debugger](https://github.com/nice2mu/muumc/blob/main/src/coder/debugger.js): `src/coder/debugger.js`

### World Services

- [World memory](https://github.com/nice2mu/muumc/blob/main/src/memory/world_memory.js): `src/memory/world_memory.js`
- [Construction subsystem](https://github.com/nice2mu/muumc/tree/main/src/builder): `src/builder`

### External Integrations

- [Voice bridge client](https://github.com/nice2mu/muumc/blob/main/src/voice/voice_client.js): `src/voice/voice_client.js`
- [Voice event manager](https://github.com/nice2mu/muumc/blob/main/src/voice/voice_manager.js): `src/voice/voice_manager.js`

### Other components

- **AI host**
- **Minecraft server**
- **Voice bridge service**
- **Ollama model**

## Connections

- AI host → MCP server: MCP requests
- MCP server → Tool handler: dispatches tools
- MCP server → Resource handler: dispatches resources
- MCP server → Bot client: starts connection
- Tool handler → Skill cache: matches skills
- Skill cache → Skill library: loads skills
- Tool handler → AI coder: requests code
- AI coder → Ollama model: generates code
- Tool handler → Code sandbox: executes code
- Code sandbox → Safe game DSL: invokes helpers
- Tool handler → Self-healing debugger: repairs failures
- Self-healing debugger → Code sandbox: re-executes code
- Autonomous engine → Tool handler: dispatches tasks
- Autonomous engine → Goal planner: manages goals
- Autonomous engine → Situation evaluator: checks progress
- Bot client → Driver adapter: creates adapter
- Bot client → Game watchdog: wires watchdog
- Bot client → Safe game DSL: wires DSL
- Safe game DSL → Driver adapter: uses game API
- Game watchdog → Driver adapter: monitors actions
- Driver adapter → Minecraft server: controls bot
- Tool handler → Construction subsystem: dispatches builds
- Tool handler → World memory: manages memory
- Resource handler → World memory: reads world data
- Bot client → World memory: records landmarks
- MCP server → Voice bridge client: starts bridge
- Voice bridge client → Voice bridge service: connects outbound
- Voice bridge client → Voice event manager: forwards utterances
- Voice event manager → MCP server: sends notifications
- Voice event manager → Autonomous engine: pauses on command
- Bot client → Chat companion: processes chat