# Minecraft MCP Server Pro

Fork of [yuniko-software/minecraft-mcp-server](https://github.com/yuniko-software/minecraft-mcp-server) upgraded into a **layered platform** for AI control:

- Configurable Minecraft version (**default `1.20.1`**, not hard-pinned)
- Offline / LAN login
- **Command channel** (`/fill`, `/setblock`, batch files) for fast creative builds
- Survival helpers (status / collect / eat; craft tools from upstream)
- **Autonomous agent loop** (`agent-start`) — plan → skills → observe

Design: `../docs/superpowers/specs/2026-07-24-minecraft-mcp-pro-design.md`

## Prerequisites

- Node.js >= 20.10.0
- Minecraft Java **LAN world** (offline OK)
- Cheats enabled for `/fill` tools
- MCP client (ZCode, Claude Desktop, …)

## Install & run

```bash
cd minecraft-mcp-server
npm install
npm run build
npm start -- --username TraeBot --version 1.20.1 --host localhost --port 25565
```

Dev (tsx):

```bash
npm run dev -- --username TraeBot --version 1.20.1
```

## ZCode MCP config example

```json
{
  "minecraft": {
    "type": "stdio",
    "command": "node",
    "args": [
      "./dist/main.js",
      "--host", "localhost",
      "--port", "25565",
      "--username", "TraeBot",
      "--version", "1.20.1"
    ],
    "timeoutMs": 999999
  }
}
```

Optional: point `--batch-root` at your workspace so `run-command-batch` can load `minecraft-city-build/command_batches/*.txt`:

```text
--batch-root "."
```

## CLI flags

| Flag | Default | Meaning |
|------|---------|---------|
| `--host` | localhost | LAN host |
| `--port` | 25565 | LAN port |
| `--username` | LLMBot | Offline name |
| `--version` | **1.20.1** | Mineflayer protocol version (change freely) |
| `--auth` | offline | `offline` \| `microsoft` (v1: use offline) |
| `--capabilities` | all | `baseline,command,build,survival,agent` |
| `--batch-root` | parent of cwd | Sandbox for batch file paths |
| `--action-delay-ms` | 50 | Delay between commands |
| `--no-agent` | — | Disable agent tools |
| `--max-agent-steps` | 50 | Agent loop limit |

## New / enhanced tools

### Command
- `run-chat-command` — whitelisted chat commands
- `fill-region` — auto-split ≤32768
- `setblock-at`
- `clone-region`

### Build
- `build-box` — solid / hollow / outline
- `clear-region`
- `run-command-batch` — array or file under batch-root
- `build-status`

### Survival / storage / social
- `get-player-status` / `collect-blocks` / `eat-food` / `ensure-item`
- `sleep-nearby` — 附近床睡觉过夜
- `chest-deposit` / `chest-withdraw` / `chest-deposit-all`
- `find-player` / `go-to-player` / `follow-player` / `fight-nearby` / `world-time-status`
- `queue-reset` — 卡死队列强制恢复
- (+ upstream `craft-item` / `list-recipes` / …)

### Blueprint
- `build-blueprint` — JSON 蓝图（`blocks[]` 或 `palette`+`layers`），见 `examples/blueprints/mini-hut.json`

### Agent (autonomous, near-human) — package **3.11.0**
- `agent-start` — NL goal，如 `附近搭石屋` / `建高塔` / `盖别墅` / `修城堡` / `建灯塔` / `跟着我` / `护卫我` / …
- `agent-companion` — **持续队友模式**（靠近→注视→跟随→拾取→探索 循环，直到 `agent-cancel`）
- `agent-status` / `agent-memory` / `agent-wait` / `agent-cancel` / `agent-chat-control`
- **游戏内聊天也可驱动**：搭石屋/建塔/别墅/城堡/灯塔/修路/平整/巡逻/护卫 等

**Powerful builds (3.11):**
- MCP: `build-structure` + `list-structures` — templates: **tower, villa, castle, lighthouse, pyramid, arena, fountain, road, stairs, platform, wall, hut**
- Agent skill: `build-structure` (same templates, near player)
- Low-level still: `fill-region` / `build-box` / `build-blueprint` / `run-command-batch`

**Agent skills (40+):** … + **build-structure**, pick-up, flatten, patrol, place-bed, pillar-up, clear-lava, mark/go-waypoint

**Pathing / creative shortcuts:** fly/tp salvage; gather/craft/ensure/minekit creative `/give`

**MCP tools:** **54** (incl. build-structure, list-structures, agent-memory)

> **Reload ZCode MCP after rebuild** → `pro=3.11.0-dist`. Only one TraeBot.

**Memory:** `batch-root/.minecraft-mcp-memory/<bot>.json` 记住家坐标等（跨重启）

> **Reload ZCode MCP after rebuild** so the live bot process loads new `dist/` (agent plans otherwise stay on old skills). Only **one** TraeBot process — do not also run `node dist/main.js` in a terminal.

## Offline smoke (before opening the game)

```bash
npm run smoke
# or with LAN already open:
npm run smoke -- --host localhost --port 25565 --version 1.20.1
```

## Blueprint example

```bash
# after MCP connected + cheats on:
# build-blueprint filePath=examples/blueprints/mini-hut.json
# (batch-root should include this repo, e.g. the repo path or workspace)
```

## Example prompts

**Fast creative build**

> 用 fill-region 在我附近清空一块 20x20 地面，再用 build-box 搭一个 10x10x6 白混凝土空心房。

**Batch from city builder**

> run-command-batch filePath=`minecraft-city-build/command_batches/xxx.txt`（需设置 batch-root）

**Autonomous loop**

> agent-start goal=`在附近搭石屋，先保证自己不饿`

## Version policy

Version is **configurable**. Default validated target: **1.20.1**.  
If join fails, try matching your world version: `--version 1.20.4` etc.

## Safety

Default command blacklist: `op`, `stop`, `ban`, …  
Default reject: `kill @a` / `clear @a`.  
Batch files cannot escape `--batch-root`.

## License

Apache-2.0 (upstream). Pro changes in this fork under the same license terms.