Skip to main content
Glama
BlockHand

BlockHand

by gjlmotea
README.md
# BlockHand — MCP server for Minecraft Education

**English** | [繁體中文](https://github.com/gjlmotea/blockhand-mcp/blob/main/README.zh-TW.md)

![BlockHand: an MCP server for Minecraft Education Edition](https://github.com/gjlmotea/blockhand-mcp/raw/main/assets/social-preview.png)

BlockHand gives AI agents hands and eyes inside **Minecraft Education Edition**. Claude Code, Codex, Gemini CLI, Grok or any other [Model Context Protocol](https://modelcontextprotocol.io) client can drive the Agent robot, build structures, read blocks, compare regions and react to game events.

It talks to the game only through Minecraft Education's built-in `/connect` (`/wsserver`) WebSocket command. There is **no add-on, behavior pack, mod or Script API** to install in the game, nothing is injected into the game process, and no screen reading is involved. On a school computer, the only thing to install is the AI client.

- **44 tools and 2 resources**: Agent robot control, world edits, 24 build shapes, blueprints, block reading, region comparison, symmetry checks and event subscription.
- **Fast building**: shapes are merged into the fewest possible `/fill` commands (a solid sphere of radius 8 goes from 2,000+ blocks to under 200 commands).
- **Local by default**: the game WebSocket listens on `127.0.0.1` unless `MINECRAFT_EDU_WS_HOST` changes it, and no account or online service is involved.
- **One fixed address**: every AI session on the machine shares one background hub, so the game always connects with `/connect 127.0.0.1:19131`.
- **Hands-off by design**: the agent reloads packs, rejoins the world and restarts a hung game by itself instead of asking the player to. The player is needed only to sign in. See [Hands-off operation](#hands-off-operation).
- **Installers** for Claude Code, Codex, Gemini CLI and Grok CLI when you run from source.

> The `/connect` command is an official interface. The WebSocket message protocol behind it has no published stability guarantee, so behavior should be re-checked after game updates.

## Contents

- [Quick start](#quick-start)
- [Install from source](#install-from-source)
- [Tools](#tools)
- [Connecting and staying connected](#connecting-and-staying-connected)
- [Hands-off operation](#hands-off-operation)
- [How building stays fast](#how-building-stays-fast)
- [Reading blocks](#reading-blocks)
- [Undo (off by default)](#undo-off-by-default)
- [Configuration](#configuration)
- [Safety](#safety)
- [Troubleshooting](#troubleshooting)
- [Known limitations](#known-limitations)
- [Development](#development)
- [License and trademarks](#license-and-trademarks)

## Quick start

Requirements:

- Minecraft Education Edition, in a world with **Cheats on**. The player who connects needs operator rights. Verified on 1.26.32 (Windows desktop and macOS 14+).
- Node.js 22 or newer on the machine that runs the AI client.

### 1. Register the server with your AI client

Claude Code:

```bash
claude mcp add blockhand --scope user -- npx -y @gjlmotea/blockhand-mcp
```

Codex:

```bash
codex mcp add blockhand -- npx -y @gjlmotea/blockhand-mcp
```

Clients that read an `mcpServers` JSON config (Claude Desktop, Cursor, Gemini CLI):

```json
{
  "mcpServers": {
    "blockhand": {
      "command": "npx",
      "args": ["-y", "@gjlmotea/blockhand-mcp"]
    }
  }
}
```

VS Code uses a top-level `servers` key instead, and each server has a `type`:

```json
{
  "servers": {
    "blockhand": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@gjlmotea/blockhand-mcp"]
    }
  }
}
```

Where each client keeps the file:

| Client | Config file |
|---|---|
| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json`. **Settings → Developer → Edit Config** opens it |
| Cursor | `~/.cursor/mcp.json` for every project, `.cursor/mcp.json` inside one project |
| Gemini CLI | `~/.gemini/settings.json` (user), `.gemini/settings.json` (project) |
| VS Code | `.vscode/mcp.json` in the workspace, or the user `mcp.json` that the **MCP: Open User Configuration** command opens |

Sources: [Claude Desktop](https://modelcontextprotocol.io/docs/develop/connect-local-servers), [Cursor](https://cursor.com/docs/context/mcp), [Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md), [VS Code](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration).

Desktop apps started from Finder or the Start menu often do not see your shell's `PATH`. If the server fails to start with a vague "server not responding" error, replace `npx` with its absolute path (`which npx` on macOS, `where npx` on Windows).

Restart the AI client after registering.

### 2. Connect the game

The game connects to the server, not the other way round.

1. Open a world in Minecraft Education. The main menu is not enough.
2. Make sure Cheats are on.
3. Type in the chat:

   ```
   /connect 127.0.0.1:19131
   ```

If your agent can send keys to the game window (see [Hands-off operation](#hands-off-operation)), it types this itself; it reads the exact command from `mc_status`.

When the connection is made, a green "✔ BlockHand connected" line appears in the chat, in the game's own language: English, Traditional Chinese or Simplified Chinese, and English for any other game language. You can also ask the AI to call `mc_status`, which returns the exact `connectCommand`.

### 3. Ask for something

> Build a hollow glass sphere with radius 6 in front of me.

> Summon the Agent, walk it five blocks forward and plant a row of wheat.

> Check whether the house at 0 64 0 to 20 80 20 is mirror-symmetric and show me which blocks break the symmetry.

## Install from source

Use this route to work on BlockHand itself, or to use the installers and the `doctor` check.

```bash
git clone https://github.com/gjlmotea/blockhand-mcp.git
cd blockhand-mcp
corepack pnpm install --frozen-lockfile
corepack pnpm run build
```

Register with one of the installers:

```bash
corepack pnpm run setup:claude    # or setup:codex / setup:gemini / setup:grok
corepack pnpm run doctor          # add --client=claude etc. to check another client
```

The installers do more than write a config entry:

- They fill in the absolute path of this machine's Node, so desktop apps that cannot read nvm, Homebrew or your shell `PATH` still start the server.
- Before changing any setting, they run a real MCP `initialize` with the exact command, arguments and environment they are about to save, and check that all 44 tools are there.
- They do nothing when the server is already registered correctly, so re-running is safe.
- When an entry with the same name exists but differs, they stop and show the difference instead of overwriting someone else's settings.
- They write only through each client's official `mcp add` / `mcp remove` command, never by editing config files directly.

Remove with `corepack pnpm run uninstall:claude` (or `uninstall:codex`, and so on). It refuses to remove entries it cannot identify as belonging to this checkout.

| Client | Writes to | Then |
|---|---|---|
| Codex | `~/.codex/config.toml` | Quit and restart; desktop app, CLI and IDE share it |
| Claude Code | `~/.claude.json` (user scope) | Restart the session |
| Gemini CLI | `~/.gemini/settings.json` (user scope) | Restart the CLI |
| Grok CLI | `~/.grok/config.toml` | Restart the CLI |

To register by hand, point the client at `<NODE> <REPO>/dist/index.js`, where `<NODE>` is the absolute path from `node -p "process.execPath"` and `<REPO>` is the absolute path of the checkout. Claude Code and Gemini CLI place the command differently:

```bash
claude mcp add blockhand --scope user -- <NODE> <REPO>/dist/index.js
gemini mcp add --scope user blockhand <NODE> <REPO>/dist/index.js
```

Claude Code wants `--` before the command. Gemini CLI takes the command right after the name (`gemini mcp add [options] <name> <commandOrUrl> [args...]`); a `--` there would leave it without a command. Gemini only needs `--` after the command, in front of server arguments that collide with its own options, and BlockHand takes no arguments. Gemini's default scope is project, so use `--scope user` to make it global. Claude Code's default scope is local; `--scope project` writes a shareable `.mcp.json`, which is handy for a whole class. Sources: [Claude Code](https://code.claude.com/docs/en/mcp), [Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).

## Tools

### Connection and fallback (6)

| Tool | Purpose |
|---|---|
| `mc_status` | Bridge state, the `/connect` command, subscribed events, command counters. Check this first when anything fails |
| `mc_await_connection` | Wait for the game to connect (up to 120 seconds per call) |
| `mc_run_command` | One raw slash command, for anything without a dedicated tool |
| `mc_run_commands` | Several raw commands in order |
| `mc_undo_control` | Inspect, clear or configure single-step undo (off by default) |
| `mc_undo` | Undo the last protected build, after checking for conflicting changes |

### Agent robot (10)

| Tool | Purpose |
|---|---|
| `mc_agent_create` | Summon the Agent |
| `mc_agent_move` | Walk N blocks in a direction |
| `mc_agent_turn` | Turn left or right by 90 degrees |
| `mc_agent_teleport` | Bring a lost Agent back to the player |
| `mc_agent_act` | Attack, destroy or till, optionally repeated |
| `mc_agent_place` | Place a block from an inventory slot |
| `mc_agent_collect` | Pick up dropped items |
| `mc_agent_inventory` | Count, free space, item detail, drop, drop all, transfer |
| `mc_agent_sense` | Inspect, inspect data, detect, detect redstone: the Agent's eyes |
| `mc_agent_program` | Send a whole sequence of actions in one call and get a result per step |

Agent directions are relative to the way the Agent is facing, not compass directions.

### World (13)

`mc_set_block`, `mc_fill`, `mc_clone`, `mc_test_block`, `mc_read_block`, `mc_verify_reading`, `mc_compare_regions`, `mc_analyze_symmetry`, `mc_query_target`, `mc_summon`, `mc_world_settings` (time, weather, game rules, difficulty), `mc_structure` (save and load structures), `mc_ticking_area`.

`mc_query_target` parses the JSON that `querytarget` returns. It is the way to find where the player or the Agent is before building.

`mc_compare_regions` compares two regions with a single `testforblocks`. Its `masked` mode ignores air in the source, which is how you check that a student's build contains everything it should, whatever else is around it.

`mc_analyze_symmetry` checks whether a region is mirror-symmetric and, when it is not, points to the cells that differ. It works by saving the region, loading a mirrored copy into a scratch area, comparing, and restoring the scratch area afterwards. The scratch area may not overlap the region being analyzed; this is checked before any command is sent. If backing up the scratch area fails, nothing is placed.

`mc_structure` saves to memory by default (gone when the game closes). Use `saveMode: "disk"` only when the user asks to keep a structure; it writes into the world folder. The game has no command that lists saved structures, so `mc_status` reports the names saved during the current session.

### Player and feedback (7)

`mc_teleport`, `mc_give`, `mc_gamemode`, `mc_effect`, `mc_player_action` (kill, clear, xp, ability), `mc_message` (say, tell, title, subtitle, action bar), `mc_feedback` (sounds and particles).

### Building (4)

| Tool | Purpose |
|---|---|
| `mc_build_preview` | Plan only: block count, bounding box, number of `/fill` batches |
| `mc_build_shape` | 24 geometric shapes; most support hollow |
| `mc_blueprint_preview` | Preview a block-by-block blueprint |
| `mc_build_blueprint` | Any shape from a list of "coordinate → block"; identical blocks are merged |

| Group | Shapes |
|---|---|
| Solids | `box`, `sphere`, `ellipsoid`, `cylinder`, `cone`, `pyramid`, `prism` |
| Lines and surfaces | `line`, `curve` (smooth curve), `disk`, `tube` (cylinder along any direction) |
| Building parts | `wedge` (single slope), `roof` (gable or hip), `arch`, `stairs`, `spiralStairs`, `polywall` (polyline wall) |
| Terrain and paths | `heightfield` (rolling ground), `ribbon` (road or bridge deck) |
| Decorative | `torus`, `helix`, `cross`, `star`, `revolution` (solid of revolution) |

With 24 shapes, the real risk is the AI picking the wrong one: a wrong pick does not fail, it builds something plausible but wrong. The tool description is therefore organized by what you want to build, with the most commonly confused pairs spelled out:

| You want | Use | Not |
|---|---|---|
| Slanted pillars, beams, pipes | `tube` | `cylinder` (axis-aligned only) |
| Walls with sharp corners | `polywall` | `curve` (rounds the corners) |
| A roof with a ridge | `roof` | `wedge` (one slope only) |
| Stairs winding up a tower | `spiralStairs` | `helix` (no treads) or `stairs` (straight) |
| Towers or chimneys that taper | `cone` / `pyramid` with `topRadius` | stacked `box`es |
| Domes, vases, cooling towers | `revolution` with a profile | a new shape per object |
| Uneven ground | `heightfield` | many `box`es |

A few parameters are easy to misread: the `radius` of `prism` and `pyramid` is the distance from the center to an edge, not to a corner; the `ridgeAxis` of `roof` is the direction the ridge runs, not the way the slopes face; `heightfield` corners are thicknesses in blocks; and `arch` draws the arch itself, with the opening (width 2 × radius − 1) in the middle.

### Events (4)

`mc_events_catalog`, `mc_events_subscribe`, `mc_events_unsubscribe`, `mc_events_poll`.

Events go into a ring buffer that you read with a cursor. `dropped > 0` means polling was too slow and some events were lost. Subscriptions are restored automatically after a reconnect. Known event names include `PlayerMessage`, `BlockPlaced`, `BlockBroken`, `ItemAcquired`, `ItemCrafted`, `MobKilled`, `PlayerTravelled`, `AgentCommand` and more (see `mc_events_catalog`). Events only fire when the thing actually happens: `BlockPlaced` is sent when a player places a block by hand, not for `/setblock` or `/fill`.

### Resources (2)

`minecraft-edu://connection` (live connection state) and `minecraft-edu://capabilities` (what the bridge can and cannot do).

## Connecting and staying connected

All AI sessions on one machine (desktop apps, CLIs, IDEs, parallel tasks) share a background **hub** that owns port 19131 and the single game connection. Each session's MCP server is a thin proxy to it. The first session that needs the hub starts it; every open session checks in once a minute, so port 19131 stays served while any session is open, and a hub that dies is restarted right away. The hub exits about 10 minutes after the last session and the game are both gone.

- Switching sessions, models or AI tools does not drop the game connection.
- `/reload all`, moving to another world, and going back to the main menu and into a world again do not drop it either during a normal load. At the main menu the connection stays open, but every command answers "Unknown command". The main menu and the world list have no chat bar, so `/connect` can only be typed inside a world.
- You only need to type `/connect` again after restarting Minecraft, or after the hub side closes the connection (the chat shows "Connection closed").
- **You do not need to type `/connect` while connected.** Doing so shows nothing at all, which looks like a hang; typing and commands keep working as usual.
- `mc_run_command` can send `reload all`. For development packs, scripts, behavior pack JSON and custom blocks reload this way. Whether resource packs (textures, language files) also reload this way has differed between the two setups tested, cause unknown: a Windows machine reloaded changed and added language strings and changed item textures, a macOS machine did not reload a changed language file. So the agent works in this order: send `reload all`, wait until the game is back in the world (send nothing else meanwhile), then check (a `titleraw` with a `translate` component shows what the client resolves; look at a texture). Only if the new content is missing does it type `/reload all` in the game chat itself.
- A script cannot connect the game: `/connect` run from a behavior pack script, whether as the player or as a dimension, is accepted but opened no connection in the setups tested, while `/connect` typed in the chat did. An in-game "connect" button therefore cannot replace typing it; the agent types it instead. While a load hangs, the bridge's 30-second keepalive probe keeps running, and after three unanswered probes in a row the bridge closes the connection.
- If an old BlockHand without hub support already holds 19131, new sessions fall back to standalone mode on a random port; use the address `mc_status` reports. Standalone mode never takes 19131 itself.

Manual fallback, for a player working without an agent that can send keys: to reconnect quickly, press `T` in the game, press `↑` to recall the last command, then Enter.

## Hands-off operation

BlockHand is built so that an agent can keep working without stopping to ask the player to click, type or confirm things it can do itself. Every pause costs the player's time, and a tool people have to babysit does not get used.

**The agent does these itself, without asking first:**

- `/reload all` after changing a pack: send `reload all` with `mc_run_command`, wait until the game is back in the world, check that the new content arrived, and only if a resource pack change is missing, type `/reload all` in the game chat.
- Leaving the world and entering it again.
- Restarting Minecraft when a reload hangs on the loading screen (see [Troubleshooting](#troubleshooting)), or before a reload when the game process has been open for hours. The world was saved when the reload began.
- Typing the `connectCommand` that `mc_status` reports whenever the game is not connected (check `connected` first; the port is not always 19131).

**Only the player does:**

- Signing in. Passwords are never typed or read by the agent. If the game comes back already signed in, nothing is needed from the player at all.

**Before acting, the agent checks:**

- That nobody is in the middle of playing. Look at the screen and compare `mc_query_target` position and rotation twice a few seconds apart; if either changed, the player is playing, so wait instead of interrupting. No change only means no movement was seen (a player in their inventory or crafting stands still too), so it is not permission by itself: reload when the person asked for it or is working with the agent right now, and ask when unsure.
- That the right world is selected before pressing Play: never enter or test in a world that is not the one being worked on.

**How it reaches the game window.** BlockHand itself only talks to the game over the WebSocket. Typing in chat, picking a world and restarting the game go through the AI client's own desktop automation. Work in this order, and keep the person at the computer in control of their screen:

1. **Background.** Game commands go through BlockHand. Keys for the chat bar and menus go through a tool that delivers them to the game window without bringing it forward.
2. **Foreground**, only for the one step the background cannot do. Before taking the screen, tell the person which step it is, which background method was tried or checked, and what blocked it (if you cannot name all three, you do not need the foreground). Give focus back right after.
3. **The player**, only for what an agent cannot do, such as signing in.

When unsure, move up this list, not down: losing the screen for a few seconds costs the person less than being interrupted to type a command themselves.

Practical notes from Windows:

- This package ships a background key tool for Windows, `blockhand-keys` (`npx -p @gjlmotea/blockhand-mcp blockhand-keys --help`, or `node scripts/game-keys.mjs --help` in a source checkout). It posts keyboard messages to the game window with Win32 `PostMessage` (`WM_KEYDOWN`, `WM_KEYUP`, `WM_CHAR`), which never changes focus, and it sends no mouse input.
  - `--probe` finds the game window and sends nothing. With several games open, pass `--pid`.
  - `--open-chat` presses `T`; take a screenshot to confirm the chat bar opened, then `--send "/reload all"` types into it and presses Enter. `--chat` does both at once; use it only when the game shows no screen or menu.
  - `--keys escape`, `--keys down,return`, `--keys shift+tab` and so on drive the menus.
  - It prints `focus_unchanged=True` when the foreground window did not change. Its output says what was queued, not what the game did, so confirm on screen or through BlockHand. A second call while one is sending gets `ERROR=busy`; that lock covers one call, so between calls (open the chat bar, screenshot, send) another agent could still type. Let only one agent drive the game screen at a time.
  - It only targets the Education edition: the executable must report the product name `Minecraft Education` (regular Bedrock runs under the same process name).
- Keyboard messages sent this way reach the chat bar, the pause menu and the world list while another app keeps the focus. Chat commands, menu navigation with the arrow keys and Enter, leaving the world and entering it again all work this way.
- Leaving and re-entering a world with keys only: Escape opens the pause menu; Down twice selects the save-and-leave button, then Enter; the confirmation starts on Cancel, so Up, then Enter. On the play screen, Down moves the white frame to the worlds tile, then Enter. In the world list, Tab twice reaches the search box, and Down from there lands on the most recently played world. Enter opens that world's small menu; before pressing Play, check that the date and size shown under the menu belong to the intended world.
- Mouse buttons posted the same way did not mine blocks in the setup tested, so mining or attacking cannot be done in the background with this method.
- Git Bash rewrites an argument that starts with `/` into a file path, so a chat command passed through it arrives as `C:/Program Files/Git/reload all`; `blockhand-keys` detects this and refuses. Send chat commands from PowerShell, or set `MSYS_NO_PATHCONV=1`.

Practical notes from macOS:

- Chat: press `T`, wait for the chat bar to appear (the first characters are lost if you type immediately), type, then Enter.
- World list: mouse clicks on world tiles sent in the background can land on "New world" instead. Use the keyboard: type the world's name into the search box so only that world remains, press the right arrow to select it, Enter for its menu, Enter again for Play.
- Restart: `osascript -e 'tell application id "com.microsoft.minecraft-edu" to quit'`, then `open -g -j -b com.microsoft.minecraft-edu` starts it again in the background.
- Right-click and attack clicks sent in the background are not received by the game, so entity interactions cannot be tested by clicking. Give the add-on a `/scriptevent` probe that calls the same handler the interaction event would (for example, run the before-interact gate and the interact handler for the nearest entity of a type) and another that prints the entity's state without opening it. Then the agent can test interactive mechanics end to end without the player.
- Photos for checking a build: note the player's position, horizontal rotation and game mode, tell them with `tellraw`, move them with `tp`, take the screenshot, then put them back. Pitch cannot be read back, so say beforehand that the view will return level.

## How building stays fast

Sending one `setblock` per block would mean tens of thousands of WebSocket round trips for a medium-sized sphere. BlockHand's pipeline is:

```
shape parameters → inside() test over the bounding box → set of block coordinates
  → merge runs along X → merge rectangles along Z → merge boxes along Y (3-stage greedy)
  → split by the 32,768-block /fill limit
  → send
```

The merge is deterministic, and tests pin that the merged batches cover exactly the original set of blocks, no more and no less. Hollow shapes all come from the same "inside test plus shell-neighbor test", so a new shape only needs an `inside()` function. `tests/domain/fill-efficiency.test.ts` sets an upper bound on fill commands per block for every shape.

For very large terrain work, compute the coordinates yourself and send many `/fill` commands with `mc_run_commands` (200 per call), or write a `.mcfunction` file and run it with `/function`. See [agents/docs/large-builds.md](https://github.com/gjlmotea/blockhand-mcp/blob/main/agents/docs/large-builds.md) for the limits involved.

## Reading blocks

Minecraft Education has no command that simply returns the block at a position, so reading has built-in limits:

- `mc_test_block` is a yes/no question: you have to guess a block ID.
- `mc_read_block` does not need a guess. It asks whether the block is air, and when the answer is no, the game's error message names the actual block. The result is the localized display name ("Dirt"), not the block ID (`dirt`).
- When the message cannot be parsed, `mc_read_block` returns an error, never a successful response with `block: null`. The consumer is an AI, and an AI that sees a successful `null` will confidently treat the spot as empty and may build over a student's work.
- `mc_verify_reading` checks that the parsing still works, with at most two read-only commands. Run it after a game update, after changing the game language (supported: Traditional Chinese, Simplified Chinese, English), or whenever `mc_read_block` starts failing on blocks you can see. Mutation tests make sure the probe and the parser turn red when the parsing rules are broken.

Reading a whole region block by block would need a behavior pack and the Script API, which BlockHand deliberately avoids so that school computers need no extra installs.

## Undo (off by default)

> Automatic undo is **off by default**. On Minecraft Education 1.26.32 (macOS), the native region check that undo sends before the first small build (`body.version=25`) never got a reply; after that, every command on the connection timed out, including what the player typed in chat, and only restarting Minecraft recovered. This was reproduced three times. Turn it on with `MINECRAFT_EDU_UNDO_ENABLED=1` or `mc_undo_control` with `configure enabled=true` only if you accept that risk. Design notes: [agents/docs/undo/region-undo.md](https://github.com/gjlmotea/blockhand-mcp/blob/main/agents/docs/undo/region-undo.md).

When enabled, undo keeps one operation of up to 4,096 blocks, snapshotted in game memory with `structure save ... memory` (nothing is written to disk). There is no redo. It covers the overworld, absolute integer coordinates and basic static building blocks; unsupported builds are rejected before anything is changed.

## Configuration

Everything has a default; no `.env` file is needed.

| Variable | Default | Meaning |
|---|---|---|
| `MINECRAFT_EDU_WS_HOST` | `127.0.0.1` | Listen address of the game WebSocket; loopback only by default (see [Safety](#safety)). The hub's control port always listens on `127.0.0.1` |
| `MINECRAFT_EDU_WS_PORT` | `19131` | Port the game connects to. The default uses the shared hub; any other value (such as `0`) runs an isolated standalone bridge |
| `MINECRAFT_EDU_HUB` | auto | `0` disables the hub (one bridge per session); `1` forces the hub on a custom port |
| `MINECRAFT_EDU_HUB_PORT` | `19132` | Local control port the sessions use to reach the hub; also the lock that decides which process is the hub |
| `MINECRAFT_EDU_HUB_DIR` | `~/.blockhand` | Folder for the hub's state file `hub.json` (holds the hub's access token) and its log `hub.log`; see [Safety](#safety) |
| `MINECRAFT_EDU_HUB_IDLE_MS` | `600000` | The hub exits after this long with no session check-ins and no game connection |
| `MINECRAFT_EDU_HUB_ATTACH_MS` | `8000` | How long a session waits for a hub it has just started to answer (500–60,000 ms); if the hub does not answer in time, the session runs a standalone bridge on a random port |
| `MINECRAFT_EDU_CONNECT_NOTICE` | on | Show the green "✔ BlockHand connected" line in chat, in the game language (detected with one read-only `time query daytime` first); `0` turns it off |
| `MINECRAFT_EDU_WS_PORT_FALLBACK` | `1` | Pick a free port when the preferred one is taken; `0` fails instead |
| `MINECRAFT_EDU_ENCRYPTION` | on | When the game connects, try the WebSocket encryption handshake; if it is not negotiated, the connection continues in plaintext. `0` skips the handshake |
| `MINECRAFT_EDU_COMMAND_TIMEOUT_MS` | `10000` | How long to wait for the game to answer one command |
| `MINECRAFT_EDU_KEEPALIVE_INTERVAL_MS` | `30000` | Interval of the idle keepalive probe (`time query daytime`); three unanswered probes in a row close the connection |
| `MINECRAFT_EDU_EVENT_BUFFER` | `500` | Event ring buffer size |
| `MINECRAFT_EDU_MAX_BUILD_BLOCKS` | `40000000` | Maximum blocks per build; non-solid shapes are also capped at an 8,000,000-block scan volume |
| `MINECRAFT_EDU_UNDO_ENABLED` | `0` | `1` turns on automatic single-step undo (see the warning above) |
| `MINECRAFT_EDU_UNDO_MAX_BLOCKS` | `4096` | Undo budget, 1–32,768 blocks, in at most 64 regions |
| `MINECRAFT_EDU_STEP_DELAY_MS` | `100` | Default delay between Agent program steps |
| `MINECRAFT_EDU_DEBUG_FRAMES` | unset | `1` prints every raw frame from the game to stderr |

## Safety

- By default the game WebSocket listens on `127.0.0.1` only. `MINECRAFT_EDU_WS_HOST` changes that address. The game port does not authenticate connections, and a new connection replaces the current one, so any other address lets every machine that can reach it connect in place of the game. The hub's control port (`MINECRAFT_EDU_HUB_PORT`, `19132` by default) always listens on `127.0.0.1`. BlockHand itself makes no connections to the internet.
- The shared hub keeps two files in `~/.blockhand` (or `MINECRAFT_EDU_HUB_DIR`). When the hub is off (`MINECRAFT_EDU_HUB=0`, or a custom `MINECRAFT_EDU_WS_PORT` without `MINECRAFT_EDU_HUB=1`), neither file is written.
  - `hub.json` holds the hub's process ID, ports, build ID, start time and a random access token. The hub creates a new token each time it starts and removes the file when it shuts down. Every request to the control port must present the token as a bearer token; sessions read it from this file to reach the hub. The folder is created with mode `0700` and the file with mode `0600`. Node.js cannot set owner/group/other permissions on Windows, so these modes only take effect on macOS and Linux.
  - `hub.log` is the hub's timestamped log. When a new hub starts and the log is larger than 1 MiB, it is renamed to `hub.log.1`. With `MINECRAFT_EDU_DEBUG_FRAMES=1`, every raw frame from the game is logged there too.
- Apart from those files, the server writes nothing on the host. `mc_structure` with `saveMode: "disk"` makes the game write a structure into its world folder; the tool reply says where.
- No accounts or credentials for any online service are involved; the hub token only guards the local control port.
- `mc_run_command` accepts slash commands, which only act inside the local game world. Its gate is structural rather than a keyword blocklist:
  1. One line only. Newlines and NUL are rejected, so one request cannot become two commands.
  2. Commands that would cut or redirect the bridge are refused: `wsserver`, `connect` and `closewebsocket`, including when wrapped in `execute`.
  3. Everything else is tagged `read-only`, `world-write` or `wide-effect`, so the MCP host can ask for confirmation based on the tool annotations.
- Block IDs, selectors and state strings that go into a command line are checked against allow-list patterns first, so spaces cannot smuggle in extra arguments.
- On a shared hub, only one AI session can change the world at a time. A second session's write tool is refused immediately with a clear message; read-only tools are not affected.

## Troubleshooting

**The player says chat stopped responding.** Do not restart the game first. Check, in order:

1. What the game screen shows (in a world, main menu, or a loading screen).
2. `mc_status`: `commandState: "timed-out"` means the bridge's own commands are not being answered either.
3. Subscribe to `PlayerMessage` and ask the player to type a line. Player chat produces a `type: "chat"` event. Not receiving one is not proof by itself, because a subscription is not confirmed by the game; compare with the screen.
4. The last lines of `~/.blockhand/hub.log` (every line is timestamped, rejected handshakes are logged too).

When a built-in command such as `time` answers "Unknown command", the tools add a hint: the game is most likely not in a world.

**A reload hangs on the loading screen.** In a world with development packs, `/reload all` (from chat or from the bridge) is a full rejoin: the game saves the world, returns to the menu and loads the world again, and `camera` settings are cleared. A fresh game process does this in under 10 seconds; one that has been open for hours takes 30–45 seconds, and the progress bar pauses around 25% for a while. On macOS 1.26.x it has also stopped for good at 25% or 60% (four times, each after the same game process had been open for an hour or more and had reloaded several times).

- While it hangs, the world has in fact loaded: a process sample shows the server and the client world ticking normally while the main thread draws the loading screen. It is waiting for a signal that does not come. Escape and closing the bridge connection do not help. Once, a bar stopped at 50% did enter the world by itself after about 3 minutes.
- Treat a bar that has not moved for about 90 seconds as stuck. Take a sample first if you want evidence (`sample <pid> 5 -file <file>` on macOS); waiting one or two more minutes before restarting costs little.
- Recovery: quit Minecraft and start it again; the agent does this itself without asking (see [Hands-off operation](#hands-off-operation)). The world was saved when the reload began. On macOS, `osascript -e 'tell application id "com.microsoft.minecraft-edu" to quit'` ends it within a second (it may still print "User canceled"; check that the process is gone), and `open -g -j -b com.microsoft.minecraft-edu` starts it again without taking the screen. Then sign in, enter the world and type `/connect` again.
- Do not send bridge commands while a reload is loading; they time out. Restarting a game that has been open for a long time before a reload makes a hang less likely.

**A reload ends on "Couldn't connect to the world … Invalid tenant ID".** The Education sign-in has expired (seen on macOS 1.26.x from about 3.5 hours after signing in). Pressing OK saves the world and returns to the menu, but starting any world from the menu shows the same error. Only a restart and a fresh sign-in fix it: quit and start Minecraft as above, the player signs in, then enter the world and type `/connect` again. In long sessions, do the important checks first, or restart before a reload when the game has been signed in for several hours.

**`mc_status` shows a port other than 19131.** Another process holds 19131. Find it with `lsof -nP -iTCP:19131 -sTCP:LISTEN` (macOS) and check whether the hub is running with `ls ~/.blockhand`.

**Windows, Microsoft Store (UWP) version.** Windows app isolation blocks loopback connections. Grant an exemption with `CheckNetIsolation LoopbackExempt`.

**A large build gets cut off.** MCP clients usually time out requests after about 60 seconds, while the tool keeps sending fills. Check `fillBatches` with `mc_build_preview` first and split large builds.

## Known limitations

- **Text from the game stays in the game's language.** Tool descriptions, server instructions and error messages are in English, but what the game itself returns (`statusMessage`, and the block names from `mc_read_block`) comes back in the game language.
- The world must have Cheats on; otherwise the game rejects every command.
- The Agent exists only in Education Edition.
- Event names and the `agent` subcommands are not formally documented by Mojang; they come from public observation and may change with game updates. `mc_events_subscribe` accepts names outside the known list but marks them unverified.
- `@s` does not always resolve for commands sent over WebSocket, so `mc_query_target` defaults to `@p`.
- Commands sent over WebSocket are parsed with an older command version: `execute as @e … at @s run …` is a syntax error, use the legacy form `execute @e[...] ~ ~ ~ <command>`; in Education 1.26.x `summon` also rejects the rotation arguments, so summon first and turn the entity with `tp`. Add-on scripts calling `runCommand` are a different path; prefer the script API there instead of relying on either syntax.
- Some responses arrive with a request ID that matches no request. When exactly one request is pending and no timeout has happened on the connection, the bridge may attribute the response by inference and logs it; after any timeout it only accepts exact matches. Modifying commands are never resent automatically.
- Commands are sent one at a time with a queue of at most 64; anything beyond that is refused with `command-queue-full`, and queued commands that outlive their own timeout are dropped and reported as not sent.
- After rebuilding, the running hub keeps the old version until it restarts; a hub restart drops the game connection.

## Development

```bash
corepack pnpm run verify   # typecheck, tests, build, stdio smoke, shared-hub smoke
corepack pnpm run live     # end-to-end check against a running game (prints the /connect to type)
```

`live` walks through connect, read player position, chat, set time, summon the Agent, sense, walk an L-shaped path, preview and build a hollow glass sphere, verify the blocks, merge a blueprint, receive events, test the command gate and clean up. Add `--keep` to `node scripts/live-check.mjs` to keep the demo build.

```
src/
  domain/          pure logic, no MCP, ws or Node dependencies
    commands.ts            slash command builders and injection allow-lists
    command-policy.ts      structural gate for raw commands
    build/shapes.ts        the 24 shapes: inside() plus shell-neighbor test
    build/fill-planner.ts  3-stage greedy merge and batch splitting
    build/undo-plan.ts     undo regions, budgets and native region checks
  adapters/ws-minecraft-connection.ts   WebSocket server, request matching, events, reconnects
  application/     services: Agent programs, querytarget parsing, building, undo
  hub/             shared hub, session proxy, cross-session write lock
  server/          MCP server, schemas and the tools
  composition.ts   wiring; accepts a fake connection for tests
  index.ts         stdio entry point
```

The domain layer knows nothing about WebSockets, so the whole MCP tool pipeline is tested with in-memory fakes, without a running game.

## License and trademarks

[MIT](https://github.com/gjlmotea/blockhand-mcp/blob/main/LICENSE).

NOT AN OFFICIAL MINECRAFT PRODUCT. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT. Minecraft and Minecraft Education are trademarks of Mojang Studios and Microsoft. BlockHand is an independent open-source project.

TDQS

A3.9/5.0

Scored across 42 tools

Disambiguation5/5

每个工具都有明确且独特的用途,例如mc_agent_*系列管理Agent行为,mc_build_*系列处理建造,mc_events_*系列订阅事件。即使有类似工具(如mc_set_block与mc_fill、mc_run_command与mc_run_commands),也在描述中明确区分了使用场景,没有模糊边界。

Naming Consistency5/5

所有工具均以mc_前缀开头,使用小写下划线命名,且按功能领域分组(如mc_agent_、mc_build_、mc_events_),模式高度一致。动词与名词的组合虽然不完全统一,但整体规律清晰,易于预测。

Tool Count5/5

工具数量为42个,但对Minecraft这样一个功能丰富的游戏来说,覆盖了Agent操作、建筑、世界管理、事件订阅等多个方面,每个工具都有存在的必要,没有冗余或缺失,规模与服务器目的匹配。

Completeness5/5

工具集涵盖了建造、查询、修改、事件处理、世界设置等完整生命周期,包括创建、读取、更新、删除的基本操作,也提供了预览和验证工具来避免错误。没有明显的功能死角,代理可以独立完成从规划到执行的完整流程。

Maintenance

ActivityActive
ResponsivenessNo recent community issues