BlockHand

BlockHand — Minecraft Education 的 MCP 服务

English | 繁體中文

BlockHand 为 AI Agent 提供在 Minecraft Education Edition 中行动和观察的能力。Claude Code、Codex、Gemini CLI、Grok 或任何其他 Model Context Protocol 客户端都可以操控 Agent 机器人、建造结构、读取方块、比较区域并响应游戏事件。

它仅通过 Minecraft Education 内置的 /connect（/wsserver）WebSocket 命令与游戏通信。游戏中无需安装附加组件、行为包、模组或 Script API，不会向游戏进程注入任何内容，也不涉及读取屏幕。在学校电脑上，唯一需要安装的是 AI 客户端。

• 44 个工具和 2 个资源：Agent 机器人控制、世界编辑、24 种建造形状、蓝图、方块读取、区域比较、对称性检查和事件订阅。
• 快速建造：将形状合并为尽可能少的 /fill 命令（半径为 8 的实心球体所需命令从 2,000 多条降至不到 200 条）。
• 默认本地运行：除非更改 MINECRAFT_EDU_WS_HOST，否则游戏 WebSocket 会监听 127.0.0.1；无需账号，也不涉及在线服务。
• 固定地址：机器上的每个 AI 会话共用一个后台集线器，因此游戏始终使用 /connect 127.0.0.1:19131 进行连接。
• 安装程序：从源码运行时，可使用适用于 Claude Code、Codex、Gemini CLI 和 Grok CLI 的安装程序。

/connect 命令是官方接口。其背后的 WebSocket 消息协议没有公开的稳定性保证，因此游戏更新后应重新检查其行为。

目录

• 快速开始
• 从源码安装
• 工具
• 连接并保持连接
• 如何保持快速建造
• 读取方块
• 撤销（默认关闭）
• 配置
• 安全
• 故障排除
• 已知限制
• 开发
• 许可证和商标

快速开始

要求：

• Minecraft Education Edition，且所在世界已开启作弊。连接的玩家需要拥有操作员权限。已在 1.26.32 版本上验证（Windows 桌面版和 macOS 14 及更高版本）。
• 运行 AI 客户端的机器上需安装 Node.js 22 或更高版本。

1. 在 AI 客户端中注册服务

Claude Code：

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

Codex：

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

读取 mcpServers JSON 配置的客户端（Claude Desktop、Cursor、Gemini CLI）：

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

VS Code 使用顶层 servers 键，并且每个服务都有一个 type：

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

各客户端配置文件的位置：

客户端	配置文件
Claude Desktop	macOS：~/Library/Application Support/Claude/claude_desktop_config.json；Windows：%APPDATA%\Claude\claude_desktop_config.json。设置 → 开发者 → 编辑配置可打开该文件
Cursor	~/.cursor/mcp.json（适用于所有项目），单个项目内的 .cursor/mcp.json
Gemini CLI	~/.gemini/settings.json（用户级），.gemini/settings.json（项目级）
VS Code	工作区内的 .vscode/mcp.json，或通过 MCP: 打开用户配置命令打开的用户 mcp.json

来源：Claude Desktop、Cursor、Gemini CLI、VS Code。

从 Finder 或“开始”菜单启动的桌面应用通常无法访问 shell 的 PATH。如果服务因含糊的“服务未响应”错误而无法启动，请将 npx 替换为其绝对路径（macOS 上运行 which npx，Windows 上运行 where npx）。

注册后，重启 AI 客户端。

2. 连接游戏

游戏会连接到服务，而不是反过来。

1. 在 Minecraft Education 中打开一个世界。仅打开主菜单还不够。

2. 确保已启用 Cheats。

3. 在聊天中输入：

   /connect 127.0.0.1:19131
   

连接成功后，聊天中会出现一行绿色的“✔ BlockHand connected”，语言与游戏自身语言一致：英语、繁体中文或简体中文；其他游戏语言则显示为英语。你也可以让 AI 调用 mc_status，它会返回确切的 connectCommand。

3. 提出需求

在我面前建造一个半径为 6 的中空玻璃球。

召唤 Agent，让它向前走五格，并种下一排小麦。

检查坐标 0 64 0 到 20 80 20 之间的房子是否为镜面对称，并指出哪些方块破坏了对称性。

从源代码安装

如果要开发 BlockHand 本身，或使用安装程序和 doctor 检查，请选择此方式。

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

使用以下任一安装程序进行注册：

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

安装程序不只是写入配置项：

• 它们会填入这台机器上 Node 的绝对路径，因此即使桌面应用无法读取 nvm、Homebrew 或 shell PATH，也能启动该服务。
• 在更改任何设置之前，它们会使用即将保存的准确命令、参数和环境变量执行真实的 MCP initialize，并检查 44 个工具是否齐全。
• 如果服务已正确注册，它们不会执行任何操作，因此可以安全地重复运行。
• 如果存在同名但内容不同的条目，它们会停止并显示差异，而不会覆盖他人的设置。
• 它们只通过各客户端的官方 mcp add / mcp remove 命令写入，绝不会直接编辑配置文件。

使用 corepack pnpm run uninstall:claude（或 uninstall:codex 等）移除。如果无法确认条目属于此检出版本，它就会拒绝移除。

客户端	写入位置	然后
Codex	~/.codex/config.toml	退出并重启；桌面应用、CLI 和 IDE 共用此配置
Claude Code	~/.claude.json（用户范围）	重启会话
Gemini CLI	~/.gemini/settings.json（用户范围）	重启 CLI
Grok CLI	~/.grok/config.toml	重启 CLI

如要手动注册，请将客户端指向 <NODE> <REPO>/dist/index.js，其中 <NODE> 是通过 node -p "process.execPath" 获取的绝对路径，<REPO> 是检出版本的绝对路径。Claude Code 和 Gemini CLI 放置命令的位置不同：

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

Claude Code 要求在命令前加上 --。Gemini CLI 会在名称后直接接收命令（gemini mcp add [options] <name> <commandOrUrl> [args...]）；如果在此处加上 --，它就不会获得命令。只有当服务器参数与 Gemini 自身选项冲突时，Gemini 才需要在命令后、服务器参数前加上 --；而 BlockHand 不接受任何参数。Gemini 的默认范围是项目，因此要使用 --scope user 使其全局生效。Claude Code 的默认范围是本地；--scope project 会写入可共享的 .mcp.json，适合整个班级使用。来源：Claude Code、Gemini CLI。

工具

连接与备用方案（6）

工具	用途
mc_status	桥接状态、/connect 命令、已订阅事件、命令计数器。出现任何故障时，先检查此项
mc_await_connection	等待游戏连接（每次调用最长 120 秒）
mc_run_command	执行一条原始斜杠命令，适用于没有专用工具的情况
mc_run_commands	按顺序执行多条原始命令
mc_undo_control	检查、清除或配置单步撤销（默认关闭）
mc_undo	检查是否存在冲突更改后，撤销上一次受保护的建造

Agent 机器人（10）

工具	用途
mc_agent_create	召唤 Agent
mc_agent_move	沿一个方向行走 N 个方块
mc_agent_turn	向左或向右转 90 度
mc_agent_teleport	将迷路的 Agent 传送回玩家身边
mc_agent_act	攻击、破坏或耕地，可选择重复执行
mc_agent_place	放置物品栏槽位中的方块
mc_agent_collect	拾取掉落物
mc_agent_inventory	计数、查看空余空间和物品详情、丢弃、全部丢弃、转移
mc_agent_sense	检查、检查数据、侦测、侦测红石：Agent 的双眼
mc_agent_program	在一次调用中发送完整的动作序列，并获取每一步的结果

Agent 的方向是相对于其面朝方向，而非罗盘方向。

世界（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（时间、天气、游戏规则、难度）、mc_structure（保存和加载结构）、mc_ticking_area。

mc_query_target 会解析 querytarget 返回的 JSON。这是查找玩家或 Agent 所在位置的方式，可用于开始建造。

mc_compare_regions 使用单条 testforblocks 命令比较两个区域。其 masked 模式会忽略源区域中的空气，因此无论周围还有什么内容，都可以用它检查学生建造的内容是否齐全。

mc_analyze_symmetry 会检查某个区域是否镜像对称；若不对称，则指出不同的方块。它会先保存该区域，再将镜像副本加载到临时区域中进行比较，之后恢复临时区域。临时区域不得与待分析区域重叠；在发送任何命令之前都会对此进行检查。如果无法备份临时区域，则不会放置任何方块。

默认情况下，mc_structure 会将结构保存到内存中（游戏关闭后即消失）。仅当用户要求保留结构时，才使用 saveMode: "disk"；这会将结构写入世界文件夹。游戏没有列出已保存结构的命令，因此 mc_status 会报告当前会话中保存的结构名称。

玩家与反馈（7）

mc_teleport、mc_give、mc_gamemode、mc_effect、mc_player_action（击杀、清除、经验值、能力）、mc_message（说话、私聊、标题、副标题、动作栏）、mc_feedback（声音和粒子）。

建造（4）

工具	用途
mc_build_preview	仅规划：方块数量、包围盒、/fill 批次数
mc_build_shape	24 种几何形状；大多数支持中空
mc_blueprint_preview	预览逐方块蓝图
mc_build_blueprint	根据“坐标 → 方块”列表构建任意形状；相同方块会合并

分组	形状
实体	box、sphere、ellipsoid、cylinder、cone、pyramid、prism
线条与表面	line、curve（平滑曲线）、disk、tube（沿任意方向延伸的圆柱体）
建筑部件	wedge（单坡面）、roof（人字形或四坡顶）、arch、stairs、spiralStairs、polywall（折线墙）
地形与道路	heightfield（起伏地面）、ribbon（道路或桥面）
装饰	torus、helix、cross、star、revolution（旋转体）

24 种形状中，真正的风险在于 AI 选错形状：选错不会报错，而是会建出看似合理但实际错误的形状。因此，工具说明按建造目标组织，并明确列出最容易混淆的组合：

目标	使用	不要使用
倾斜的柱子、梁、管道	tube	cylinder（仅沿坐标轴对齐）
带尖角的墙	polywall	curve（会将角变圆）
带屋脊的屋顶	roof	wedge（只有一个坡面）
绕塔盘旋而上的楼梯	spiralStairs	helix（没有踏步）或 stairs（直梯）
逐渐收窄的塔或烟囱	使用 topRadius 的 cone / pyramid	堆叠的 box
穹顶、花瓶、冷却塔	使用截面轮廓的 revolution	为每种物体新增一种形状
不平整的地面	heightfield	多个 box

有几个参数容易看错：prism 和 pyramid 的 radius 表示中心到边的距离，而不是到角的距离；roof 的 ridgeAxis 表示屋脊延伸的方向，而不是坡面的朝向；heightfield 的角部参数表示以方块计的厚度；而 arch 绘制的是拱形本身，开口位于中央（宽度为 2 × 半径 − 1）。

事件（4）

mc_events_catalog、mc_events_subscribe、mc_events_unsubscribe、mc_events_poll。

事件会进入一个环形缓冲区，你可以通过游标读取。dropped > 0 表示轮询速度太慢，导致部分事件丢失。重新连接后会自动恢复订阅。已知事件名称包括 PlayerMessage、BlockPlaced、BlockBroken、ItemAcquired、ItemCrafted、MobKilled、PlayerTravelled、AgentCommand 等（参见 mc_events_catalog）。只有在事件实际发生时才会触发：玩家手动放置方块时会发送 BlockPlaced，而 /setblock 或 /fill 不会触发。

资源（2）

minecraft-edu://connection（实时连接状态）和 minecraft-edu://capabilities（桥接能做和不能做的事）。

连接并保持连接

同一台机器上的所有 AI 会话（桌面应用、命令行工具、IDE、并行任务）共用一个后台 hub，由它占用端口 19131 并管理唯一的游戏连接。每个会话的 MCP 服务都是连接到它的轻量代理。第一个需要 hub 的会话会启动它；每个打开的会话每分钟都会向它报到一次，因此只要有会话保持打开，端口 19131 就会持续提供服务；如果 hub 退出，会立即重启。最后一个会话和游戏都关闭约 10 分钟后，hub 才会退出。

• 切换会话、模型或 AI 工具不会断开游戏连接。
• 正常加载期间，/reload all 和切换到另一个世界也不会断开连接。在主菜单中，连接仍保持打开，但每条命令都会返回“Unknown command”。
• 只有在重启 Minecraft，或 hub 端关闭连接（聊天中会显示“Connection closed”）后，才需要再次输入 /connect。
• 连接期间无需输入 /connect。 输入后不会有任何响应，看起来像是卡住了；但输入和命令仍会照常工作。
• mc_run_command 可以发送 reload all。开发资源包、脚本和行为包 JSON 可通过这种方式重新加载；资源包只有在玩家于聊天中输入 /reload all 时才会重新加载。发送更多命令前，请等待世界加载完成。加载卡住时，桥接的 30 秒保活探测仍会运行；连续三次探测都没有响应后，桥接会关闭连接。
• 如果旧版、不支持 hub 的 BlockHand 已占用 19131，新会话会改用随机端口进入独立模式；请使用 mc_status 报告的地址。独立模式本身绝不会占用 19131。

若要快速重新连接，请在游戏中按 T，再按 ↑ 调出上一条命令，然后按 Enter。

如何保持快速建造

如果每个方块都发送一个 setblock，中等大小的球体就需要数万次 WebSocket 往返。BlockHand 的流水线如下：

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

合并过程具有确定性，测试会确保合并后的批次恰好覆盖原始方块集合，不多不少。所有中空形状都采用相同的“内部测试加壳层邻居测试”方法，因此新增形状只需实现一个 inside() 函数。tests/domain/fill-efficiency.test.ts 会为每种形状的每个方块设定填充命令数量上限。

对于超大型地形工程，请自行计算坐标，并使用 mc_run_commands 发送多条 /fill 命令（每次调用 200 条），或者编写 .mcfunction 文件并通过 /function 运行。有关相关限制，请参阅 agents/docs/large-builds.md。

读取方块

Minecraft Education 没有能直接返回指定位置方块的命令，因此读取功能存在内置限制：

• mc_test_block 是一个是非问题：你必须猜测方块 ID。
• mc_read_block 不需要猜测。它会询问方块是否为空气；若答案是否定的，游戏的错误消息会指出实际方块。结果是本地化的显示名称（“Dirt”），而不是方块 ID（dirt）。
• 如果无法解析消息，mc_read_block 会返回错误，绝不会成功返回 block: null。使用者是 AI；如果 AI 看到成功返回的 null，就会确信该位置为空，并可能在学生的作品上继续建造。
• mc_verify_reading 会检查解析功能是否仍然有效，最多使用两条只读命令。游戏更新后、更改游戏语言后（支持：繁体中文、简体中文、英语），或在 mc_read_block 无法读取你能看到的方块时，都应运行此工具。变异测试可确保解析规则遭到破坏时，探测器和解析器都会报错。

逐个读取整个区域的方块需要使用行为包和 Script API；BlockHand 特意避免了这种做法，因此学校电脑无需额外安装任何内容。

撤销（默认关闭）

自动撤销默认关闭。在 Minecraft Education 1.26.32（macOS）上，第一次小规模建造前撤销功能发送的原生区域检查（body.version=25）始终没有收到回复；此后，该连接上的每条命令都会超时，包括玩家在聊天中输入的内容，只有重启 Minecraft 才能恢复。此问题已复现三次。只有在你接受此风险的情况下，才可通过 MINECRAFT_EDU_UNDO_ENABLED=1 或 mc_undo_control 搭配 configure enabled=true 启用。设计说明：agents/docs/undo/region-undo.md。

启用后，撤销功能会保留一个操作，最多涉及 4,096 个方块，并使用 structure save ... memory 将快照保存在游戏内存中（不会写入磁盘）。不支持重做。此功能适用于主世界、绝对整数坐标和基本静态建筑方块；不支持的建造会在任何更改发生前被拒绝。

配置

所有选项都有默认值；无需使用 .env 文件。

变量	默认值	含义
MINECRAFT_EDU_WS_HOST	127.0.0.1	游戏 WebSocket 的监听地址；默认仅监听回环地址（参见安全）。中心的控制端口始终监听 127.0.0.1
MINECRAFT_EDU_WS_PORT	19131	游戏连接的端口。默认使用共享中心；设置为其他值（例如 0）时，将运行隔离的独立桥接服务
MINECRAFT_EDU_HUB	auto	0 禁用中心（每个会话使用一个桥接服务）；1 强制在自定义端口启用中心
MINECRAFT_EDU_HUB_PORT	19132	会话用于连接中心的本地控制端口；同时也是用于决定哪个进程担任中心的锁
MINECRAFT_EDU_HUB_DIR	~/.blockhand	存放中心状态文件 hub.json（包含中心访问令牌）和日志文件 hub.log 的文件夹；参见安全
MINECRAFT_EDU_HUB_IDLE_MS	600000	没有会话签到且没有游戏连接时，中心等待此时长后退出
MINECRAFT_EDU_HUB_ATTACH_MS	8000	会话等待刚启动的中心响应的时长（500–60,000 毫秒）；如果中心未能及时响应，会话将在随机端口运行独立桥接服务
MINECRAFT_EDU_CONNECT_NOTICE	on	在聊天中以游戏语言显示绿色的“✔ BlockHand connected”提示（先通过一次只读的 time query daytime 检测语言）；0 可关闭此提示
MINECRAFT_EDU_WS_PORT_FALLBACK	1	首选端口被占用时选择一个空闲端口；0 则直接失败
MINECRAFT_EDU_ENCRYPTION	on	游戏连接时尝试进行 WebSocket 加密握手；如果未协商加密，连接将继续以明文传输。0 可跳过握手
MINECRAFT_EDU_COMMAND_TIMEOUT_MS	10000	等待游戏响应一条命令的时长
MINECRAFT_EDU_KEEPALIVE_INTERVAL_MS	30000	空闲保活探测（time query daytime）的间隔；连续 3 次探测无响应后关闭连接
MINECRAFT_EDU_EVENT_BUFFER	500	事件环形缓冲区大小
MINECRAFT_EDU_MAX_BUILD_BLOCKS	40000000	每次建造的最大方块数；非实心形状的扫描体积上限也为 8,000,000 个方块
MINECRAFT_EDU_UNDO_ENABLED	0	1 可启用自动单步撤销（参见上方警告）
MINECRAFT_EDU_UNDO_MAX_BLOCKS	4096	撤销预算：1–32,768 个方块，最多覆盖 64 个区域
MINECRAFT_EDU_STEP_DELAY_MS	100	Agent 程序步骤之间的默认延迟
MINECRAFT_EDU_DEBUG_FRAMES	未设置	1 会将游戏发送的每个原始帧打印到 stderr

安全

• 默认情况下，游戏 WebSocket 仅监听 127.0.0.1。MINECRAFT_EDU_WS_HOST 可更改该地址。游戏端口不验证连接身份，而且新连接会替换当前连接，因此，使用其他地址会让所有能够访问该地址的机器都可以连接并取代游戏连接。集线器的控制端口（默认值为 19132 的 MINECRAFT_EDU_HUB_PORT）始终监听 127.0.0.1。BlockHand 本身不会连接互联网。
• 共享集线器会在 ~/.blockhand（或 MINECRAFT_EDU_HUB_DIR）中保存两个文件。集线器关闭时（设置 MINECRAFT_EDU_HUB=0，或设置自定义的 MINECRAFT_EDU_WS_PORT，但未设置 MINECRAFT_EDU_HUB=1），不会写入任何文件。
  • hub.json 保存集线器的进程 ID、端口、构建 ID、启动时间和随机访问令牌。集线器每次启动都会生成新令牌，并在关闭时删除该文件。每个发往控制端口的请求都必须提供作为 bearer token 的令牌；会话从此文件读取令牌以连接集线器。文件夹的权限模式为 0700，文件的权限模式为 0600。Node.js 无法在 Windows 上设置所有者／组／其他用户权限，因此这些模式仅在 macOS 和 Linux 上生效。
  • hub.log 是带时间戳的集线器日志。新集线器启动时，如果日志大于 1 MiB，就会将其重命名为 hub.log.1。设置 MINECRAFT_EDU_DEBUG_FRAMES=1 后，游戏发来的每个原始帧也会记录在其中。
• 除这些文件外，服务不会在主机上写入任何内容。mc_structure 使用 saveMode: "disk" 时，会让游戏将结构写入其世界文件夹；工具回复会告知保存位置。
• 不涉及任何在线服务的账号或凭据；集线器令牌仅用于保护本地控制端口。
• mc_run_command 接受斜杠命令，这些命令只会在本地游戏世界中生效。其限制机制基于结构检查，而不是关键词黑名单：
  1. 只能有一行。换行符和 NUL 都会被拒绝，因此单个请求不能变成两条命令。
  2. 会拒绝可能切断或重定向桥接的命令：wsserver、connect 和 closewebsocket，包括通过 execute 封装的情况。
  3. 其他命令都会标记为 read-only、world-write 或 wide-effect，因此 MCP 主机可根据工具注释要求确认。
• 传入命令行的方块 ID、选择器和状态字符串都会先依据允许列表模式进行检查，以防空格被用于插入额外参数。
• 在共享集线器上，同一时间只能有一个 AI 会话修改世界。第二个会话的写入工具会立即被拒绝，并显示清晰的提示；只读工具不受影响。

故障排除

玩家表示聊天不再响应。 请勿先重启游戏。按以下顺序检查：

1. 游戏画面显示的内容（在世界中、主菜单，还是加载画面）。
2. mc_status：commandState: "timed-out" 表示桥接自身的命令也没有得到响应。
3. 订阅 PlayerMessage，并让玩家输入一行文字。玩家聊天会产生 type: "chat" 事件。未收到事件本身并不能证明有问题，因为游戏不会确认订阅；请结合游戏画面判断。
4. 查看 ~/.blockhand/hub.log 的最后几行（每行都有时间戳，握手被拒绝的记录也会写入）。

如果内置命令（例如 time）回复“Unknown command”，工具会提供提示：游戏很可能不在某个世界中。

mc_status 显示的端口不是 19131。 另一个进程占用了 19131。使用 lsof -nP -iTCP:19131 -sTCP:LISTEN（macOS）查找该进程，并使用 ls ~/.blockhand 检查集线器是否正在运行。

Windows，Microsoft Store（UWP）版本。 Windows 应用隔离会阻止环回连接。使用 CheckNetIsolation LoopbackExempt 添加豁免。

大型构建被截断。 MCP 客户端通常会在约 60 秒后超时，但工具仍会继续发送填充操作。请先用 mc_build_preview 检查 fillBatches，并拆分大型构建。

已知限制

• 游戏中的文本仍使用游戏语言。 工具描述、服务说明和错误消息均为英文，但游戏本身返回的内容（statusMessage，以及 mc_read_block 返回的方块名称）使用游戏语言。
• 世界必须开启作弊；否则游戏会拒绝每条命令。
• Agent 仅存在于 Education Edition 中。
• Mojang 未正式记录事件名称和 agent 子命令；它们来自公开观察，可能会随游戏更新而变化。mc_events_subscribe 接受已知列表之外的名称，但会将其标记为未经验证。
• 通过 WebSocket 发送命令时，@s 并不总能正确解析，因此 mc_query_target 默认使用 @p。
• 有些响应携带的请求 ID 与任何请求都不匹配。当恰好有一个待处理请求，且连接上没有发生过超时时，桥接程序可能会通过推断将响应归属到该请求并记录日志；发生任何超时后，它只接受完全匹配的请求。修改类命令绝不会自动重新发送。
• 命令逐条发送，队列最多容纳 64 条；超出的命令会被拒绝，并返回 command-queue-full。排队后超过自身超时时间的命令会被丢弃，并报告为未发送。
• 重新构建后，正在运行的 hub 会继续使用旧版本，直到重启；重启 hub 会断开游戏连接。

开发

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 会依次演示连接、读取玩家位置、聊天、设置时间、召唤 Agent、感知、沿 L 形路径行走、预览并建造中空玻璃球、验证方块、合并蓝图、接收事件、测试命令门控并清理。向 node scripts/live-check.mjs 添加 --keep 可保留演示构建。

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

领域层不依赖 WebSocket，因此整个 MCP 工具流水线都使用内存中的模拟对象进行测试，无需运行中的游戏。

许可证和商标

MIT。

非官方 MINECRAFT 产品。未经 MOJANG 或 MICROSOFT 批准，也与其无关。Minecraft 和 Minecraft Education 是 Mojang Studios 和 Microsoft 的商标。BlockHand 是独立的开源项目。