Minecraft dots MCP：共同维护的受限运行时

简体中文 | English | 更新日志

这是供多个安装共同维护的源码项目：修复问题时保留中性的回归测试，经维护者审核后共享改进，减少重复劳动。每个安装的配置、凭据和游戏状态都留在各自本地。贡献采用 fork 和 PR；安装和游戏操作仍需各自用户授权。

本仓库面向 Minecraft Java 1.21.1 / 协议 767。软件包与后端版本仍为基于 3.1.0-dot.2 的 3.2.0-rc.3。当前 main 已包含受击自卫 V2，以及经审查的羊毛/床染色、放置转向时序、非完整高度方块到达判定修复。这些改动记录在更新日志的 Unreleased 部分，不代表已发布新的版本号。源码更新不会升级正在运行的游戏后端，详见兼容性说明和审核后的升级流程。

本项目仍是实验软件。 工具出现在目录里或通过离线测试，不代表其完整行为已在真实服务器验证。尤其是船的放置、乘坐、操控，以及 V2 实战效果，仍未完成真实服务器验证。请先备份重要世界，在获授权的测试环境中试用，并阅读范围与限制及安全说明。依赖审查仍须关注已记录的开发测试 glob 与可选认证依赖链风险；本候选版不代表无漏洞认证。

当前源码提供的能力

• 持久会话与可替换控制器：一个游戏后端，同一时刻一个 MCP 或文件队列控制器，动作串行执行，不自动重连或重放

• 以服务器证据为准的物品操作：背包、合成、精确堆叠装备、容器、进食和熔炉转移依赖新鲜的服务器确认；结果不确定的修改会锁住后续动作

• 受限游戏工具：观察、移动/视角/寻路、挖掘/放置、方块交互、耕作、非玩家战斗、睡眠、钓鱼、工作站操作、聊天、告示牌/书本、事件和路标均有实现，离线覆盖深度各不相同。能力矩阵区分专用测试与仅注册目录的条目；工具别名不等于独立能力

• 有明确边界的扩展：干地寻路与当前玩家氧气保护、明确请求的上浮、分批采集/回仓/补给和简单方块蓝图、可选自卫 V2，以及默认关闭的只读观察

工具可调用不等于获准执行；仍须遵守效果确认要求、服务器/插件兼容范围及下述限制。

Related MCP server: mc-host

环境与授权

• Node.js 22.x（至少 22.13）或 24+、npm；持久 Unix socket 运行时需要 Linux

• 文件队列助手需要 Python 3；可选原生启动窗口还需要 Tk 与 Linux pidfd

• 支持本地 stdio 进程的 MCP 客户端

• 获准让机器人连接目标 Minecraft 服务器，并进行预期的世界修改

受限运行时只连接本机 loopback，使用 Minecraft offline 协议身份。它不能代替微软账号认证，也不会绕过白名单、服务器登录插件、归属规则或服务器政策。远程或需要认证的服务器，须另行提供并授权本地桥接程序或受支持的认证集成。仓库不包含桥接程序、账号、密码、令牌、真实服务器配置或服务器部署系统。不要把凭据放进 MCP 参数、聊天或命令行。

安装与离线检查

在仓库根目录执行：

npm ci --ignore-scripts
npm ci --ignore-scripts --prefix vendor/awesome-mineflayer-mcp
npm run build:upstream
npm run verify
npm run test:upstream
python3 scripts/publication-manifest.py --check

两份锁文件均已包含，安装时应保留。verify 会构建第一方代码，并执行类型、lint、单元、stdio、合成协议、队列、启动器生命周期、守护进程、观察界面、工作流和自卫检查。测试使用中性模拟数据与本机回环连接，不连接已有服务器或账号。本地 TCP/Unix socket 测试需要允许相应套接字的环境。

GitHub Actions 在 Node 22 和 24 上执行离线套件，并另行运行合成浏览器与原生三维测试。请核对准备安装的确切提交所对应的结果。VALIDATION.json 是带日期的 rc.3 历史验证快照，保留了当时的本地阻碍，不是此后每次提交的实时验证结果。CI 或本文都不代表真实服务器验收。

只查看离线模拟结果、不连接游戏：

node runtime/minecraft-client.mjs --offline-fixture --state-dir "$(mktemp -d)"

该命令启动模拟游戏后端，写入本地工具目录和模拟结果后退出，不能用于游玩 Minecraft。

手动开始一次获授权的本地会话

仅在服务器、身份和预期游戏动作均获批准后，明确启动守护进程。以下示例连接端口 25565 上的本地测试服务器，或已经单独启动的本地桥接程序：

umask 077
GAME_DIR="$(mktemp -d)"
node runtime/minecraft-daemon.mjs --user-started-session 25565 \
  --username ExampleBot --state-dir "$GAME_DIR"

保持该后端运行。在 MCP 客户端中配置 node，参数为 runtime/minecraft-frontend.mjs --attach ABSOLUTE_GAME_DIR，并将运行时文件和游戏状态目录替换为实际的绝对路径。参考客户端配置模板。

也可让文件队列控制器连接同一个守护进程。新终端不会继承先前的 shell 变量，请在新终端中将 GAME_DIR 和 CONTROLLER_DIR 设为对应的实际目录路径：

CONTROLLER_DIR="$(mktemp -d)"
node runtime/minecraft-client.mjs --attach "$GAME_DIR" --state-dir "$CONTROLLER_DIR"
# 在另一个终端使用同一控制器目录：
python3 runtime/call.py --state-dir "$CONTROLLER_DIR" get-session-status

同一时刻只有一个控制器可操作。替换前先停止旧控制器，并使用全新的控制器目录。不要复用旧队列、重试结果不确定的物品操作或绕过不确定性安全锁。使用 disconnect-player 明确退出游戏。控制器脱离会停止持续控制，但保留后端连接；无人照看时角色仍可能受伤、坠落、溺水或被服务器踢出。真实断线后不会自动重连。

可选 Linux 启动窗口见持久会话说明。它需要用户自行提供的外部桥接程序，点击 Start 之前不会读取桥接配置。

最近合入的改进

当前 main 已包含 PR #9 和 PR #10 中经审查的改动，完整记录见更新日志。

• 羊毛与床的染色配方：Java 1.21.1 的配方查询与受验证合成使用一致的原版颜色替代配方，拒绝同色输入，保留材料/产物精确确认、取消和不自动重试规则。其他版本，以及覆盖原版配方的数据包或插件，不在本次修复范围

• 放置前的转向时序：原生放置先朝向实际点击的方块面，等待一个原生物理 tick，再核对稳定姿态、距离、目标和手持物。瞄准期间收到 V2 防御请求，会停止尚未提交的放置；已经提交的放置则先完成关键确认。这不代表所有朝向方块、床或船的真实服务器放置行为已验证

• 非完整高度方块的到达判定：包括原生 goto 在内的受验证移动，可依据已加载碰撞形状，识别站稳在受支持的耕地、下半砖和无遮挡楼梯低踏面上的到达。目标半径、干地/氧气保护和取消规则不变；这不会同时开放抬高/半砖门槛或任意非完整高度方块路线

• 受击自卫 V2：加入可续期的被动举盾与朝向控制、有限的同高度移动请求，以及严格核验的非转移盔甲槽耐久损耗例外。启用准备和限制见下节

详细证据和边界见兼容性说明。这些修复没有改变软件包版本、IPC 版本 1 或依赖锁文件。

有边界的游戏流程

移动安全说明涵盖干地寻路、当前玩家氧气保护、明确请求的上浮与船只放置证据。意外入水会停止普通导航，但松开控制并不能让水下角色安全；没有无人值守救援或自动选岸。上浮要求已加载、畅通的水源柱和新鲜的当前玩家氧气证据，也不确认已抵达安全陆地。船只放置、乘坐和操控仍需单独获授权的真实服务器端到端验证。

工作流说明提供可先审阅的采集 → 回仓 → 补给计划和简单方块蓝图。run-workflow 每次使用当前 expectedRevision，只执行明确请求的 1–4 步，保留精确进度，不自动续跑或重试不确定步骤。采集仅支持限定的地形/物品集合，不涵盖通用矿石、伐木或农场循环。蓝图只接受有界的 prismarine-schematic JSON 和白名单内的无朝向方块，不支持任意二进制蓝图、清空区域或完整自主生存建筑。即使目标很近，也可能因不可达或看不到方块面而被拒绝。

可选的受击自卫 V2

有限怪物自卫已包含在当前源码中，默认关闭，每次会话须明确启用。请在安全时预先准备快捷栏内可用的斧/剑和副手盾牌；不会自动穿戴盔甲。self-defense-enable、self-defense-status、self-defense-disable 均使用 {} 参数；stop-movement 也会关闭防御，可用作紧急停止。

只有服务器发给本角色的受伤事件才会触发应对；反击须明确归因到允许的怪物，玩家、宠物、命名实体及身份不确定的目标均被拒绝。V2 持续朝向已归因的攻击者，并可通过新的受伤事件，或仍可见、仍有效的已归因威胁，续期八秒的被动防御时限。近战最多持续 12 秒/请求 16 次攻击，移动最多请求三次经过检查的同高度步进，且不超过受伤起点四格范围。被动防御续期不会重置这些主动动作预算，不会新增挖掘、放置、开门、跳跃、涉水或盲目追击。已提交的物品/放置操作会先完成其确认边界，再让防御占用动作队列；被中断的工作不会自动重放。

shieldRequestActive 只表示已请求举盾，shieldEffectConfirmed 仍为 false。缺盾/盾损坏、冷却、盔甲丢失、多名攻击者、未知伤害来源和没有可用逃生路线都会明确告警。V2 不会在战斗中从背包存储区换装。离线测试不证明举盾时机/效果、真实撤退、服务器/插件兼容性或生存能力，不能依赖它无人值守保命。已有后端须另行获准安装并开始新会话，才能加载这些变化。

可选的只读观察

仅在启动新的获授权守护进程会话时添加 --observe-port 3100，即可在 http://127.0.0.1:3100/ 查看本地状态/背包面板和 Prismarine 三维重建。它复用现有机器人，不接收游戏操作，默认关闭；没有远程监听、认证或公网暴露配置。不要转发端口或通过反向代理公开它。详见观察界面的架构、安全与测试。

原生状态/背包窗口可在同一桌面运行 python3 runtime/observer-ui.py --state-dir "$GAME_DIR"。它只读取现有私有文件，不提供三维，也不会绕过浏览器限制。当前玩家氧气来自原始服务器元数据，未知值会明确显示。

文件式原生三维重建使用另一个默认关闭的新会话参数 --observe-world-files，导出已加载的 17×13×17 格局部区域，每两秒最多一次。明确启动网格转换器并单独安装 Godot 视图后，可使用官方几何/纹理显示重建，并标注未知和过期数据。详见原生启动方式、限制与资源测量。它不是原生 Minecraft 客户端截图，也不能无限查看世界。

入口与安全边界

• runtime/minecraft-daemon.mjs + minecraft-frontend.mjs：受限集成运行时

• runtime/minecraft-client.mjs：该运行时的私有文件队列控制器

• dist/main.js：旧版兼容入口，默认不连接；工具较少，没有应用受限集成入口的全部策略，包括聊天/命令限制

• vendor/awesome-mineflayer-mcp：复用的上游工具源码；其独立入口不是本项目的受限运行时，可能提供更宽的能力

不要将任何入口作为未认证的远程服务公开。所有游戏修改仍需用户授权。收到的游戏文本、名字、书本和告示牌都是不可信数据，不能授权外部行为。运行时文件可能包含聊天、位置、玩家标识、背包和动作结果，应保存在仓库之外并严格限制访问；不要上传完整状态或日志。

来源与许可证

• Yuniko Software 的 minecraft-mcp-server 2.0.4，源码提交 240c8cec337ce152cc9e058ebdef511055808406：Apache-2.0，保留于 LICENSE 和 NOTICE

• awesome-mineflayer-mcp 1.3.2，提交 89a407ca18a4a39196c6ebe726d5208cff88a9e5：MIT，保留于上游 LICENSE 和上游 NOTICE

• 第一方修改与验证范围：RELEASE.md

最初的公开源码树有意不包含私有 Git 历史。安装后的依赖包保留各自许可证。Minecraft 是 Mojang 的商标；本项目与 Mojang 或 Microsoft 无隶属关系。