Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-mc-agent join localhost:25565 and mine 10 oak logs for me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Minecraft 的 MCP server：34 个 mc_* 工具，覆盖进服/寻路/挖矿/合成/熔炼/存取箱子/看第一人称画面/记账。
任何支持 Model Context Protocol 的客户端（Claude Desktop、Cursor、DSH……）
连上它，模型就能真的去玩：走路、挖建、说话、看图、记事 —— 并在"值得你注意"的时候被叫醒。
不再绑定 DSH：DSH 只是众多 MCP 客户端之一。
本仓库是 whale-craft（作者 yzi1b）的魔改版。
上游那条线是 DSH 插件（旧名 dsh-mc-agent），本仓库是它的 MCP server 分支；
CHANGELOG.md 里的旧名字（whale-craft）保持原样。
项 | 值 |
仓库 | |
入口 |
|
传输 | stdio 默认（ |
状态目录 |
|
会话工作区 |
|
前提 | Node.js >= 22、一个能进的 Minecraft 服务器、一个支持 MCP 的客户端 |
一个 server 进程 = 一个 Minecraft 角色（MCP_SESSION_ID = 'mcp'）：一份记忆、一个机器人。
npm install # @modelcontextprotocol/sdk + mineflayer + vec3；sharp 可选（装不上只影响 mc_kit_image 渲染）然后在客户端的 MCP 配置里加一条 server。stdio（默认，推荐）：
{
"mcpServers": {
"minecraft": {
"command": "node",
"args": ["<仓库绝对路径>/mcp/server.mjs"],
"env": { "MCP_MC_AGENT_CWD": "<想当会话工作区的目录>" }
}
}
}Claude Desktop 写进 claude_desktop_config.json，Cursor 写进 .cursor/mcp.json，其它客户端找各自文档里的
mcpServers 段 —— 形状都是上面这个。
args 用绝对路径。Windows 上 JSON 里要转义反斜杠（C:\\path\\mcp\\server.mjs），或者干脆写正斜杠。
env 可以整段省掉：不设 MCP_MC_AGENT_CWD 就用客户端拉起进程时的当前目录当工作区。
想省掉路径：npm link（或 npm i -g .）之后把 command 写成 "mcp-mc-agent"。
HTTP（可选，给远程 / 网页客户端）：
node mcp/server.mjs --http 3921 # 端口默认 3921
node mcp/server.mjs --http 3921 --cwd /path/to/world --state-dir /path/to/state客户端那边填 http://<主机>:3921/mcp（Streamable HTTP）；探活用 GET http://<主机>:3921/health。
命令行 / 环境变量速查：
参数 | 作用 |
| 用 stdio 传输（默认；写了也只是显式声明） |
| 用 Streamable HTTP 传输，默认端口 |
| 会话工作区（记忆、落盘图片挂它下面；默认当前目录） |
| 状态目录（配置 + 账户库 + 凭据；默认 |
| 打印版本后退出（读 |
| 这条帮助 |
🔴 --version / -h 在起 server 之前就短路退出 —— 不然进程会先进 stdio 模式挂住等 stdin，
命令看起来就是"卡死"。
矛盾 / 非法参数直接报错退出（exit 2），不悄悄挑一个：--stdio 与 --http 同时给、
端口不是 1–65535 的整数，都会打一行 stderr 就退。
环境变量：MCP_MC_AGENT_STATE_DIR · MCP_MC_AGENT_HOME · MCP_MC_AGENT_CWD · MCP_MC_AGENT_HTTP_PORT ·
MCP_MC_AGENT_VERBOSE=1（多打 stderr 日志）。
没有 DSH 时代的兼容别名 —— 只有 MCP_MC_AGENT_* 这一套。
没装 mineflayer-pathfinder 时 mc_move 会直接拒绝（返回 via:"pathfinder-unavailable"），
只剩"在水里游"和"原地跳"能用 —— 寻路能力完全依赖它。
依赖树体检：node tools\check-mc-deps.mjs（8 项）。
不想连服务器也能跑的自检：node tools\check-all.mjs。
那五个生态插件（pathfinder / collectblock / tool / pvp / auto-eat）是可选的，装哪儿由你定：
src\plugins.mjs 的 loadMcDep 依次找 ① MCP_MC_AGENT_MC_DEPS 指的目录（目录本身或它的 node_modules）
② 包旁边的 vendor\mc-deps\node_modules\ ③ 状态目录下的 vendor\mc-deps\node_modules\ ④ 包自己的 node_modules\
（package.json 里已列为 dependencies，npm i 之后就在这儿）。
缺哪个只是少那项能力，其它照旧。
Related MCP server: haksnbot-tools
MCP 协议里没有"填账号密码"这种交互，所以账户从命令行管。账户库和凭据都落在状态目录里，
和 MCP 那边共用同一份 —— 在终端建好，AI 那边 mc_accounts 立刻就能看到。
node mcp/server.mjs accounts list # 看有哪些账户（★ = 默认）
node mcp/server.mjs accounts add offline 史蒂夫 # 离线（盗版服 / 单机）—— 最常用
node mcp/server.mjs accounts add yggdrasil \
--url https://littleskin.cn/api/yggdrasil \
--login 你的账号 --password-stdin --name 游戏名 # 皮肤站 / 第三方认证服
node mcp/server.mjs accounts add microsoft --email a@b.com # 正版（微软）：先只登记邮箱
node mcp/server.mjs accounts login acc-xxxxxxxx # 正版：打设备码，去 microsoft.com/link 授权
node mcp/server.mjs accounts refresh acc-xxxxxxxx # 换令牌 / 修登录状态
node mcp/server.mjs accounts use acc-xxxxxxxx # 设为默认（之后 mc_connect 用它）
node mcp/server.mjs accounts remove acc-xxxxxxxxaccounts 与 --version / -h 一样在起 server 之前就短路退出 —— 不会挂住等 stdin。
--password-stdin 从管道读密码（别把密码写进命令行，那会进 shell 历史与进程列表）；
accounts 的输出从不打印密码或令牌。
accounts add microsoft 只登记邮箱，真正登录要再跑一次 accounts login（设备码得你去网页点）。
忘了怎么用：node mcp/server.mjs accounts help。
node tools\check-all.mjs # 49 个套件：48 个 tools\check-*.mjs + mcp\selfcheck-mcp.mjs（几分钟）
node tools\check-all.mjs --fast # 跳过端到端那一个（快）
node tools\check-all.mjs --only check-core-dig # 只跑名字含这个子串的（`check-core-dig` 会连 `check-core-digtime` 一起跑）任何 ❌ 都会让整体 exit 1。套件自己收拾现场（--keep 保留现场供排查）。
端到端那个（mcp\selfcheck-mcp.mjs）真起一个 server 子进程 + 真 MCP 客户端走完整 stdio 握手，
验的是"从客户端看这 server 像不像样"，共 43 项：握手（instructions 非空）/ 34 个工具一个不少 /
一批离线工具真调 / 图片内联 / 34 个工具全传 {} 都不崩 / 并发不串台 / 4 个 resources 逐个读 /
状态落盘（含"凭据库不在工作区里"）/ 协议通道干净（stdout 只有 JSON-RPC）。单跑：node mcp\selfcheck-mcp.mjs。
各套件的期望值（2026-10-16 实测：49/49 全过）：
套件 | 期望 | 盯的是什么 |
| 184/0 | 合成链条、合成格不吞料 |
| 267/267 | 熔炼、燃料挑选、产物名反查 |
| 126/126 | 存取箱子、全搬 |
| 246/0 | 自主层：反射/空闲决策/威胁判据；危险名单与搭路共用一份（含灵魂火）；叫醒简报带"脚下一层"摘要 |
| 143/143 | 单次调用 ≤11 秒、抢占推号 |
| 37/0 |
|
| 77/0 | 放置判据、依附面、垫脚 |
| 42/0 | 挖掘出口、复原包判决 |
| 27/0 | 挖矿速度修正（含附魔效率） |
| 99/99 | 水里游/上浮/憋气 |
| 162/0 | 地形图字形与配色、地板层图、竖列图（几格实心 / 哪里开始空 / 空腔·水·岩浆分开说）、坐标换算、危险格、导航摘要 |
| 70/70 | 背包视图、动作与装备/工具耐久（"快坏了"看得见） |
| 78/0 | 换工具/穿护甲 |
| 39/0 | 用物品 |
| 53/0 | 实体名单与挑选 |
| 86/0 | 攻击判据（"打死了"要有掉血证据） |
| 45/0 | "报成功要有证据" |
| 13/0 | 每会话独立记忆 |
| 48/0 | RULES.md 注入 + 内置默认准则（进服那段 / 工具名）+ 「随版本更新」只动默认那块 + 版本标记（ |
| 96/0（ | 第一人称感知 |
| 112/0 | 渲染内核 |
| 78/0 | 皮肤 |
| 59/59 | "等一件事"只有一份实现： |
| 61/0 | Worker 池：默认关（一行线程都不开）/ 小活不搬 / 大活真搬且结果逐字节一致 / 搬了主线程真的不堵（心跳实测）/ 超时·中止·未知任务都如实退回原地 / 统计形状 |
| 55/0 | 微软正版登录： |
| 86/0 | 任务代次：只有重排步骤/取消/收工才换代、两个 await 后各对一次、过期的结果不写账 |
| 26/0 | 寻路接入 |
| 21/21 | 看门狗聊天唤醒 |
| 46/0 | 会话审计 |
| 55/55 | 日志轮转/级别/去重；端到端自检用临时状态目录跑（不往真日志/真账户库里写） |
| 8/0 | vendor 依赖可加载 |
| 144/0 | 动作调度器：资源登记/父子复用 |
| 48/0 | 性能监测： |
| 104/0 | 移动进度监控：只认"既没挪动也没靠近"、正常等待豁免有上限、脱困阶梯 → |
| 108/0 | 搭路状态机：铺一块→回读确认→才走一格、危险/落差/血量/材料任一项不过就停、断点续铺； |
| 132/0 | 地形分类（危险/沟/落差/台阶/窄道/平地）与按类调权重：优先级从最要命的往下、一格台阶不把平地判成台阶、用户配置永远赢；导航缓存（没挪窝、世界没变就不重扫， |
| 95/95 | 水下出口搜索：只读扫描 + 6 邻域分层 BFS、三类出口（干燥落脚点 > 可呼吸空间 > 可通行水道）、空气口袋只当中间目标、预算用完/找不到都如实报 |
| 103/103 | 水下恢复控制器：氧气/掉血/没进展触发、"搜出口 → 执行 → 复核真的动了吗"循环、没走通就拉黑换下一条、绝不偷偷接管（每次都通知 AI 一声） |
| 30/0 | 拆出去的模块全都 import 得进来（含 |
| 14 |
|
| 50 | MCP 唤醒链路 + job 结算： |
| 36 | 账户库 + 文件凭据库： |
| ✅ 全树正常 | 全树语法（ |
| 56/0 | 工具结果 → MCP content blocks：DSH 形状的 |
| 67/0 | 两块：① CLI 短路 —— |
| 67 | 打包 / 改名彻底性 / MCP 接线（工具表与 |
| 23 | HTTP 传输： |
| ✅ 成功 |
|
| 43 ✅ / 0 ❌ | 端到端：真起 server 子进程 + 真 MCP 客户端握手（见上） |
🔴 静态断言（"读源码文本 → 正则匹配"那一类）在拆分模块时最容易悄悄失效 —— 代码搬到别的文件、
this.改成self.，断言还在原地找，于是一直红着没人看。 搬完模块先跑node tools\scan-moved-assertions.mjs（顾问型），再核对上表数字。
会话级配置用 mc_config 读写；下面的键写在状态目录的 config.json（~/.mcp-mc-agent/config.json），
或者直接用 mc_admin_config / mc_config 工具改 —— 改完立即生效，不用重启 server。
键 | 默认 | 说明 |
|
| 记忆根。MCP 的"工作区"就是 |
|
|
|
|
| 关掉/给路径，等价于 |
|
| 寻路能不能挖穿墙 |
|
| 垫方块的代价（上游默认 1，比挖还便宜 ⇒ 会往空气上搭） |
|
| 最多往下跳几格 |
|
| 跑酷 |
|
| A* 思考上限 / 搜索半径 |
|
| 饱食度低于它就吃 |
| 很大 | 会被 10 秒上限钳住 |
|
| 自动穿护甲 |
|
| 自主层自保（躲岩浆/火/仙人掌） |
|
| 空闲多久叫醒 AI / 每小时上限 |
|
| 两次叫醒最小间隔 / 旁边有人时的间隔 |
单独文件（都在 <memoryDir>\）：
auto.json —— 自主层开关；view.json —— 看图门禁（{"gate":true,"maxActions":8,"maxAgeMs":120000}，默认不强制）。
RULES.md —— 行事准则（2026-10-08 起内置默认与记忆里那份是同一份文本）。
版本提示.md —— 2026-10-08 起只投一行指针。
server 自己的环境变量（决定进程怎么起，见上一节）：MCP_MC_AGENT_STATE_DIR · MCP_MC_AGENT_HOME ·
MCP_MC_AGENT_CWD · MCP_MC_AGENT_HTTP_PORT · MCP_MC_AGENT_VERBOSE=1。
插件行为类环境变量：MCP_MC_AGENT_PATHFINDER（off 或路径）· MCP_MC_AGENT_MC_DEPS · MCP_MC_AGENT_MEMORY_DIR ·
MCP_MC_AGENT_AUTO · MCP_MC_AGENT_VIEW_GATE / _VIEW_GATED / _VIEW_MAX_ACTIONS / _VIEW_MAX_AGE_MS ·
MCP_MC_AGENT_SKIN_TIMEOUT_MS · MC_LOG_LEVEL(quiet|info|debug) · MC_LOG_MAX_BYTES · MC_LOG_KEEP ·
MC_HOST / MC_PORT · MCP_MC_AGENT_SCHEDULER（observe-only(默认) / enforce = 撞车时排队等、够高就叫停低的）·
MCP_MC_AGENT_PERF（off 关掉性能监测，默认开）· MCP_MC_AGENT_PERF_RESOLUTION（事件循环延迟直方图分辨率 ms，默认 100，最小 10）·
MCP_MC_AGENT_PERF_KEEP（每个动作留多少条样本，默认 20）·
MCP_MC_AGENT_WORKERS（Worker 线程池：不给 = 关；数字 = 池子上限（≤4）；on = 自动取）。
默认关是量过才这么定的 —— 唯一够格搬走的是 mc_map {format:"image", radius:96, scale:16} 的像素循环（943 万像素、28ms），
其余候选都在 16ms 以内，而且大头是搬不动的 bot.blockAt()。
三层命名空间：mc_* 游戏内动作、mc_kit_* 宿主能力、mc_admin_* 管理。
mc_connect / mc_disconnect / mc_map / mc_kit_image 不受 11 秒闸门（一次调用要把握手或算图做完）。
工具 | 干什么 |
| 在线/坐标/朝向/血量/饱食度/手持/模式/看门狗/最近 3 条聊天； |
| 探测局域网服务器（只读）：只听多播 |
| 已知地址时发一次 STATUS ping：通不通/版本/协议号/MOTD/人数/延迟；不登录不进服；连不上会翻译成人话（ |
| 进服。没有账号密码，用哪个账户由账户库（ |
| 列出/搜索/刷新/选定账户。永远拿不到密码或 token； |
| 边界信息：支持的 MC 版本范围（ |
| 列出所有活跃 MC 会话实例（诊断用） |
| 从 MC 下线，不影响其他会话的机器人；看门狗自动关闭 |
| 先优雅退游戏、再清本会话全部后台任务（看门狗在内）。不中断当前这一轮，适合"我不想玩了，下线" |
工具 | 干什么 |
| 👁 第一人称视角：从眼睛（眼高 1.62）朝正看方向渲染截图并内联，附三段式感知：① 我看到（图里数出来的）② 程序检测到（坐标/射线打到的方块/半径内实体带血量）③ 不确定（客户端预测、未加载区块、读不到的血量）。两套眼睛对不上时点名，以程序射线为准。门禁默认关，写 |
| 扫描周围方块：给 |
| 看周围地形；默认给"脚下方块那一层"（地板层： |
| 看背包、装备栏和手持物品 |
| 读/消费看门狗记下的事件（聊天、系统消息、受伤、上线/死亡/重连/断线）； |
| 看门狗控制（进服自动挂载、退服自动卸载）。默认叫醒：有人喊我 / 身边有人说话 / 任何玩家说话 / 受击 / 死亡 / 被传送 / 断线。⚠️ MCP 下唤醒走"事件队列 + MCP 日志通知 + |
| 读写本会话 MC 配置（唤醒条件、近距半径、心跳、观察窗口、叫法）。不传参 = 看当前 + 默认；嵌套项用点号键 |
| 诊断：机器人内部状态（物理/控制位/收包/事件队列/合成窗口）+ 提示词注入状态（ |
工具 | 干什么 |
|
|
|
|
| 挖方块：给 |
| 批量搭方块： |
| 按顺序执行一串世界交互（替代"写脚本"）： |
| 创造模式直接获取物品（不走 |
| 在 MC 公屏说话（所有玩家可见） |
| 以玩家身份执行服务器指令。白名单可配（默认 |
工具 | 干什么 |
| 长活儿进度台账（挖 4 个以上自动开），存 |
| 🤖 自主行为层。① 反射层（不花 token、常开）：环顾、饿了吃、捡掉落物、躲岩浆火仙人掌、跟随玩家；被怪打或有怪贴上来立刻叫醒 AI 定策略（自己不跑不还手）；在水里憋气也叫醒 AI 上浮；附近有玩家时一直看着他。② 空闲决策层（花 token）：AI 停下 |
工具 | 干什么 |
| 🧱 真合成（走服务端合成台）。自动补齐中间产物（要 |
| 🔥 真熔炼（走服务端熔炉）。写产物名也行（ |
| 📦 真仓库（服务端箱子/木桶）。 |
工具 | 干什么 |
| 图像能力。SVG 是编辑语言：布局/画框/加中文/拼网格都写 SVG 文本，再光栅化成 PNG。 |
| 把发布区 |
| 长期记忆（跨会话、重启还在），按服务器建子文件夹（ |
| 【管理】读写全局配置（状态目录的 |
MCP 是**"你问它答"：server 不能主动往模型上下文里塞消息（DSH 的 agent.steer 能直接起一轮 /
在下一步插话，MCP 没有对应能力 —— mcp/host.mjs 桩上那个同名 steer 只是把消息转进下面这三条通道**，
好让 src/watchdog.mjs 和 extensions/mc_auto.mjs 那些 typeof agent.steer === 'function' 的守卫照常成立）。
所以看门狗的唤醒走三条腿，模型要主动收：
通道 | 机制 | 谁看得见 |
主通道：会话事件队列 | 唤醒文案以 | 模型下次调 |
提示通道：MCP 日志通知 | 同时发一条 | 支持 logging 的客户端会立刻显示给模型；它只是提示，内容以 |
兜底： | 最近 50 条唤醒存在内存里（服务端进程内环形缓冲） | 通知丢了/客户端不支持 logging，读这个 resource 补 |
看门狗照旧进服自动挂载、退服自动卸载；唤醒条件（有人喊我 / 身边有人说话 / 任何玩家说话 / 受击 / 死亡 / 被传送 / 断线）与 DSH 版一致。
想安静等：mc_events {waitSec} 会被"要唤醒你"打断（返回 interrupted:true），不会把唤醒压到等待结束。
结论：该做的是定期 mc_events；不要指望通知一定送到。
本仓库的 DSH 插件分支（旧名 dsh-mc-agent）和这个 MCP server 是同一套代码的两个壳：
34 个工具的名字、参数、返回值一模一样，账户库与记忆格式也兼容 —— 记忆里写的工具名不用改。
要搬的东西 | 旧位置（DSH 插件） | 新位置（MCP server） |
全局配置 |
|
|
账户库 |
|
|
密码 / token | 宿主凭据服务（ |
|
MSA 令牌缓存 |
|
|
记忆 / 提示词 |
| 一样（"工作区"= |
不会自动接管（目录名和位置都变了）。想带着配置和账户过来，手动搬一次：
cp -r "$DSH_HOME/dsh-mc-agent/." ~/.mcp-mc-agent/ # 搬过去
# 或者干脆指回老目录：
MCP_MC_AGENT_STATE_DIR="$DSH_HOME/dsh-mc-agent" node mcp/server.mjs🔴 密码搬不过来：DSH 版把密码/token 交给宿主凭据服务，MCP server 是独立进程，用的是自己的
credentials.json（key 仍按 mcp-mc-agent/<innerID> 组织）。所以正版 / 皮肤站账户要重新登录一次
（离线账户不用）；账户条目本身在 accounts.json 里，会跟着搬过来。
重新登录就是在终端跑 node mcp/server.mjs accounts login <innerID>（正版，打设备码）或
accounts refresh <innerID>（皮肤站，会问你密码）—— 见 账户。
另外两处"没了"：MC 模式 / MC+ 那套 preset 与权限隔离在 MCP 下不生效（改成"这个进程只暴露这 34 个工具"），
Web GUI / 设置页也没有了（改配置用 mc_admin_config / mc_config，或者直接编辑 config.json）。
mcp\ 六个文件 + index.js + 62 个 src\ 模块 + 7 个扩展。依赖方向：
mcp\server.mjs → mcp\host.mjs → index.js → extensions\ → src\；
src\ 内部单向，新模块不许反向 import 回 core.mjs（靠 setXxx() 注入或收 ctx）。
文件 | 干什么 |
| MCP 入口：stdio / Streamable HTTP 两种传输、 |
| 给 |
| 工具结果 → MCP content blocks： |
|
|
| 本地文件凭据库（ |
| 端到端自检：真起 server 子进程 + 真 MCP 客户端握手（43 项） |
| 5251 行。工具注册（29 个）、看门狗接线、 |
src\ 模块模块 | 干什么 |
|
|
| 连接与保活： |
| 运行时管线： |
| 连接/状态视图（ |
| 配置默认值与合并（715 行） |
| 账户管理与认证（全插件唯一碰凭据的地方： |
| STATUS ping / 局域网多播监听（ |
| vendor 依赖加载器（ |
| 移动原语： |
| 放置那一层（ |
| 搭建：范围 → 坐标 → 逐个 |
| 搭路（ |
| 地形分类 + 路径评分（导航 P2）：量脚边一圈的柱子，归成危险 / 沟 / 落差 / 台阶 / 窄道 / 平地，每类给一套寻路权重（ |
| 水下出口搜索（只读 + 纯计算，一行按键操作都没有）：以脚下为中心，水平 8 格 / 上下 8 格做 6 邻域分层 BFS，把格子分成水 / 空气 / 挡路 / 未加载，挑出三类出口 —— 干燥落脚点（最优先）> 可呼吸空间 > 可通行水道。不只看"是不是空气"：要查脚位 + 头位 + 脚下支撑 + 一条真的连得通的路；空气口袋只当中间目标；预算用完老实回 |
| 水下恢复控制器： |
| 微软正版登录（叶子模块，只 import |
| 挖掘： |
| 采集/落地守卫： |
| 挖矿速度修正（上游把 108 个方块的 |
| 服务端破坏判决（ |
| 捡掉落物（ |
| 攻击（ |
| 使用/交互： |
| 感知最后两块： |
| 只读观察： |
| 世界观察器整层： |
| 地图： |
| 朝向/相机： |
| 背包那一层（读 + 动）： |
| 连串动作调度： |
| 可恢复的任务状态机（落 |
| 任务执行器：每轮只推一步（ |
| 任务收工报告（三种形状并存）： |
| 统一动作调度器： |
| 性能监测（ |
| 看门狗（唤醒矩阵 |
| 记忆四分类 + 元数据（world/lessons/tasks/RULES；来源·更新·成功失败次数·适用版本·条件） |
| 聊天记录（签名/未签名两条路 + 按渲染形状兜底；1.5 秒去重； |
| AGENTS.md / 提示词注入（326 行）。MCP 下这些条目由 |
| 版本提示 / 进服提示 / 玩家消息转成提示 |
| 受保护文件（RULES.md / AGENTS.md / config.json 不许改） |
| 方块名判据（空气/液体/能穿过去/软顶）+ 地形图字形与配色 + 右键交互判据 |
| 实体名单与分类（敌对/远程/掉落物）、中文别名、 |
| 单次调用时间预算（纯常量 + 纯函数）： |
| 无损 JSON + 家目录脱敏 / 日志基建（本地时间、级别、去重、轮转） |
| 异步叶子： |
| Worker 线程池（默认关）： |
| 图像编解码 / PNG 写出 / 文件分享 |
| 工作区配置 / 服务器历史 |
| 工具定义辅助（294 行） |
extensions\（改完重启 server 即生效）文件 | 干什么 |
| 共用件（不是扩展）：物品/方块名与 id、 |
| 第一人称截图 + 三段式感知（注册 |
| 渲染内核（不注册工具） |
| 皮肤解析与渲染（不注册工具） |
| 自主行动层（注册 |
| 合成 / 熔炼 / 存取箱子 |
| 包 | 接管了什么 | 接在哪 |
| 寻路 / 防卡住 |
| |
| 走过去挖方块 + 捡掉落物 |
| |
| 按方块挑最好的工具 |
| |
| 追击 + 近战节奏 |
| |
| 饿了自动吃 |
|
#movements() 造的那份 Movements 同时给 pathfinder / collectBlock / pvp 用 —— 免得"我自己走不乱跳、
插件走就乱跳"。缺哪个只是少那项能力，其它照旧。
mcp\server.mjs MCP 入口（stdio / Streamable HTTP）
mcp\host.mjs 宿主桩（假 ctx / 假 exec）
mcp\credentials.mjs 本地文件凭据库
mcp\selfcheck-mcp.mjs 端到端自检（真 server + 真 MCP 客户端，43 项）
index.js 宿主侧（工具注册 / 看门狗 / 配置）
src\ 62 个模块（见上表）
extensions\ 7 个扩展 + mc_util.mjs
tools\check-*.mjs 47 个离线自检套件
tools\check-all.mjs 一条命令全跑完 + ✓/✗ 汇总表
tools\scan-moved-assertions.mjs 顾问型：搬模块后的断言扫描
README.md / 插件说明.md / 踩坑档案.md / PATHFINDER.md / CHANGELOG.md东西都落哪去了：
东西 | 位置 |
状态目录（全局配置 · 账户库 · 凭据 · 日志 · MSA 令牌缓存） |
|
记忆 / 提示词 / 出图 |
|
默认输出 / 发布区 |
|
任务台账 |
|
.mcp-mc-agent/ 里的东西只读写文件，不执行任何东西。凭据绝不写进工作区（工作区是喂给 AI 的）。
上游 whale-craft 是一个能连服的 mineflayer 壳；这个版本把它做成了"能长期自己玩"的 agent。 按能力分类（每条的具体来龙去脉在 踩坑档案.md）：
安全与诚实
"报成功必须有证据"：break/place/dig 的判据一律回读服务端状态；服务端发回原方块包
（拒绝破坏）绝不算成功（server-break.mjs 三态判决）。
不许骗人：place 没出现方块、use 没开窗口、attack 没打死，都如实说；
mc_connect {force:true} 的说明写明"玩家会看到你退游戏几秒"。
受保护文件（RULES.md / AGENTS.md / config.json）不许改。
不卡死
单次调用 ≤11 秒：mc_move/mc_dig/mc_build/mc_sequence 到点带结果收手，
返回 remaining + hint 让模型接着叫 —— 挂住的时候用户看不到任何消息。
超时闸门走 abort signal + 本地 deadline；客户端取消这次调用能立刻真停（interruptMove 推号 + 停采集 + 松控制位）。
挖矿速度修正：上游 material 写错导致铁矿石要 4.5 秒，现在石镐挖铜矿 4550ms → 1302ms。
pathfinder 接进来 + 两处补丁 + walkPlaceCost 调高（上游默认 1 会让机器人往空气上搭）。
能自己玩
看门狗：进服自动挂载，聊天/受击/死亡/传送/断线都会叫醒 AI（MCP 下是"事件队列 + 通知"，见 MCP 唤醒机制）。
自主层 mc_auto：反射层不花 token 地环顾/吃/捡/躲/跟随，被怪打或憋气时叫醒 AI 定策略；
空闲决策层带"玩家在干什么 + 长期目标 + 没做完的任务"叫醒它，不许反问 Master。
任务台账 + 步骤表 + 执行器：挖 4 个以上自动开工，tasks.json 掉线重连都还在；
mc_task {action:"run"} 一次推进一步，四道闸门防跑飞。
记忆：四分类（world/lessons/tasks/RULES）带来源·成功失败次数·适用版本；按服务器建子文件夹，可每会话独立。
统一动作调度器：资源冲突（interaction/movement）记账；enforce 模式下撞车先排队等（waitMs，默认 3 秒），
够高就叫停低的（同级不抢、preemptible:false 不抢、取消边界在 cleanup/unknown 不抢）；
父子动作复用 actionId，而且子步骤忘了说自己是谁也不会把自己锁死（AsyncLocalStorage 兜底）。
看得见
第一人称视角 mc_observe：从眼睛渲染截图 + 三段式感知（我看到 / 程序检测到 / 不确定），
两套眼睛对不上时点名，以程序射线为准；门禁默认关，AI 自己决定何时看。
地形图：地表图 + 地下自动切洞穴层；format:"image" 出俯视图。
生活技能
合成/熔炼/存取箱子三个扩展走真服务端界面（不是作弊给物）：自动补齐中间产物、 写产物名反查原料、自己挑燃料、附近没工作台/熔炉/箱子就自己放一个。
装备栏、附魔台、铁砧、锻造台。
图像工具链（mc_kit_image / mc_kit_express / mc_kit_memory）与 mc_admin_config。
工程
src\core.mjs 从 4896 行拆到 999 行，62 个模块单向依赖（拆的规矩见下一节）。
日志：本地时间、级别、去重、轮转（上游是 UTC + 从不轮转 + 59.7% 启动噪声）。
tools\check-all.mjs 49 个套件离线自检 + 顾问型断言扫描器。
src\core.mjs 是分 43 刀拆出来的（4896 → 999 行）。以后继续拆照这 46 条来 ——
每条都是踩出来的，括号里的"第 N 刀"是它第一次被踩到的位置（对应提交见 CHANGELOG.md）。
core.mjs 里保留同名导出：export { lossless, redactPath } from './format.mjs' —— 外部一行都不用改。
一次只搬一个模块，搬完立刻 node --check + 真的 import 一遍，确认导出还在、行为没变。
移动和挖掘最后再拆：#walkPathfinder() / dig() 共享 _moveGen、_ctrlLease、11 秒预算和一堆事件监听。
静态断言也要跟着搬：套件里有"core.mjs 里有没有 const SOFT_ROOF = "这种按文件找代码的断言，代码一搬它就红。
先 grep 谁在 import 这个名字：被别的模块 import 就必须 re-export，否则报的是加载期的
does not provide an export named '…'（整个扩展起不来），不是运行期。
grep 要 grep 整个仓库（tools\ 与 *.md 都算），不只看 import —— 有一批断言是"按名字找代码"的。
搬家脚本别手写"要加 export 的白名单"：node --check 只查语法不查导出，漏一个要等真 import 才报。
新模块不许反向 import 回 core.mjs（循环导入）⇒ 改成 core 注入 setXxx()。
"模块加载时读一次"的环境变量搬进单例模块后必须改成现读：core.mjs 每个连接会重新 import 一份，
src\log.mjs 整个进程只加载一次 ⇒ MC_LOG_MAX_BYTES/MC_LOG_KEEP 要写成 logLimits() 现读。
搬之前先问一句"这个模块会被加载几次"。
搬"私有方法"比搬"纯函数"多两件事：签名要多一个 b（this.#heldText(b) → heldText(b)，所有调用点都得改）；
公开方法要在 core 留薄包装。"逐字等价"验证法失效（签名变了），改用行为对照。
"grep 整个仓库"要连 tools\check-*.mjs 一起 grep：47 个套件里大量是"读源码文本 → 正则匹配"
的静态断言，代码一搬就在原地红着没人看。改完跑 node tools\check-all.mjs --fast 全绿才算搬完，
别只看你改的那个套件。
能并进已有模块就别新开（依赖方向要天然是顺的）。
搬常量/工具函数时先分清"哪部分是纯的、哪部分绑在实例上"：纯的进模块，读 this.xxx 的留类里。
判据："公开面不变"= "以前 export 过"，不是"有没有人用"。
一个名字在两个模块里表示两件事时顺手改名（#reachOf → blockReachOf，与 mc_craft.mjs 那个"材料够不够做"的 reachOf 区分）；
改名时用脚本统计命中数，命中 0 处就抛错。
搬"公开方法"要给类留同名薄包装（不是 re-export）：heightmap (opts = {}) { return heightmapOf(this.requireBot(), opts) }。
验证用 A/B 对照（把 git HEAD 的 core.mjs 临时拷回 src\，跑完即删）。
薄包装的参数形状要跟原来一模一样：scan ({…} = {}) 收对象、entities (radius = 24, {…} = {}) 是位置参数 + 可选对象 ——
调用方是照签名调的，签名一改就是静默改行为。
实例状态不属于 bot：多给模块一个 ctx 参数（statusOf(b, ctx)）。
判据：凡是被搬走的代码里出现 this.xxx，就问这个 xxx 是 bot 的还是插件的。
A/B 的假数据必须复刻真实数据的形状，否则"等价"可能只是"两边都走了同一条死路"
（dig-speed.mjs 第一版冒烟 82/0 全绿，但假 registry 把工具表写成了 {900:2, 901:2}，真实数据只有木工具）。
搬"实例状态 + 收尾动作"混在一起的方法：模块只做动作，状态全走 ctx
（cancelCollect(b, ctx)，ctx = { force, budgetMs, bumpGen, stopPathing, releaseControls, log }）。
薄包装里保留字面 this._moveGen++（check-call-budget.mjs 按字面数"抢占时把代号往前推 ≥2 处"）；
收尾类动作一律 try { … } catch {} 包住每一步。
有可变实例状态的层，第一参数直接收 self（不是 ctx）。判据："要读"进 ctx，"要改"就直接收 self。
每搬一个模块都要跑 node tools\scan-moved-assertions.mjs（顾问型，不判红）。
它做两遍：① 按导出名找"提到这些名字且正则带实现细节"的断言；② 把断言的正则拿去它断言的文件里试，
在 core 里找不到、却能在别的 src/*.mjs 找到的就报。
一个 ok() 里塞两条正则时，扫描器可能只看到第一条：要抠掉整行所有 .test(<ident>) 再判，
并把 = 、.方法(、??、|| 也算实现细节。教训：两条正则都要单独看一眼。
lines.splice(n, …) 是 0-based，锚点自检用的是 1-based；split('\n') 后每行带 \r，比对要 .replace(/\r$/, '')。
node --check 不会报这类错（多一行孤立 /** 语法完全合法）。
搬"要发包的动作"时模块只做动作，实例/库相关的全走 ctx（giveItem/clearInventory/tossItem
要 ctx = { t, makeItem }，模块不 import 任何游戏库）。
搬"服务端不回执的动作"：把 await 留在模块里，别把 promise 交回实例
（容器看 currentWindow、门看 getProperties() 翻没翻）。
混合行尾的文件不能按行号切（既有 CRLF 又有孤立 LF ⇒ 从第一个孤立 LF 起整体错开）。
自检：(raw.match(/\r\n/g)||[]).length 与 raw.split('\n').length - 1 对不上就是混合行尾。
手术脚本要么按内容定位（raw.indexOf(锚点) + 括号配平），要么先统一了再切、搬完换回去。
要回调一堆实例方法的层，第一参数收 self。判据："只读几项"用 ctx，"要改"或"要回调"用 self。
模块够不着私有方法，就把它塞进 ctx：cancelCollect: (bb, o) => this.#cancelCollect(bb, o)
（私有名在模块外面不能用字符串取）。
搬方法时 JSDoc 也要一起搬（脚本删到哪儿，就把那儿的 JSDoc 写进新模块，或在 core 原位留一行指针）；
分节注释（/* ─── 世界观察器 ─── */）同样跟着走。丢了注释不影响任何自动检查。
薄包装和 import 撞名时 import 取别名：import { startObserver as startObserverImpl, … }
（类方法名不进词法作用域，能跑但读的人会以为是递归）。
搬进"已经存在的模块"时，那个模块头注释里的"N 件事"也要改 —— 头注释是这个项目"这个模块负责什么"的索引。
搬进已有模块时把新成员要用的兄弟依赖补进 import，补之前先确认不会成环。
新写的头注释里不许出现 */：写 $DSH_HOME/profiles/*/vendor 这种 glob 会提前关掉块注释，
node --check 报的行号在注释中间很迷惑。用 <profile> 占位或反斜杠。
A/B 两边抛同一个错也算"通过" ⇒ 每条 A/B 都要配"真的走通了吗"的断言（输出非 null、!ea && !eb）。
手术脚本的"不许残留 this."自检要先把注释剥掉：
const bare = s.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^[ \t]*\/\/.*$/gm, '')
—— 注释里的 this. 是踩坑说明，代码里的才是残留。
改调用点的正则要连"尾参"一起改（await this.connect({...}) → await connect(self, {...}, ctx)）；
自检里加一条"新调用点的参数个数对得上"。
A/B 两边不能共用一份"状态会变"的假件（假 bot 的 entity.isInWater 是时变的）；
假件里带时间 / 次数 / 状态的字段，A/B 就不能共享 —— 新旧各造一份，B 要在 A 跑完之后再造。
按签名找函数体时 indexOf('{') 会先撞上参数里的解构 {
（async #walkPathfinder (target, { arrive = 1.6, … } = {}) {）⇒ 先取第一个换行、再 lastIndexOf('{', nl)。
手术脚本要"先全查、后写盘"：所有锚点（要删的、要插的、import 的）先验完，最后才写文件。
import 锚点别按"单行 import"去猜（movement 的 import 是多行的，锚点只取 } from './movement.mjs'）。
A/B 全绿不等于那条路走到了：写完用例回头问一句"这条分支的前置条件是什么"，照着摆世界。
A/B 全绿 + 调用序列一致，也可能是同一份用例把两边带到同一条错路上
（dig 的 40 条断言全绿，四条出口全走的是"够不着"那条）⇒ 每条用例配一条"这条路真的走到了"的断言，
并把输出打出来看一眼。
带定时器的状态层：状态字段留在实例，读写逻辑搬进模块（holdControl/#releaseControls 只搬读写，
租约表 _ctrlLease 留 core.mjs）。
"抠旧实现"要连它依赖的模块级 import 一起搬：判据是"方法体 + 它引用的所有模块级标识符 （函数、常量、类）"，不只是 import 名。
模块里出现 mineflayer / prismarine 字样（哪怕只是 import）就该停下来看看。
自写冒烟的 t 兜底写成 ctx.t ?? ((p) => p)，不必每次造一个真的闸门。
拆分收尾用 check-module-load.mjs 体检（30/0：拆出去的模块全都 import 得进来）。
文档 | 给谁看 | 讲什么 |
本文件 | 开发者 | 接到 MCP 客户端、跑自检、配置速查、工具速查、唤醒机制、迁移、架构速览、拆分模块的规矩 |
模型 / 维护者 | 工具与机制细节：34 个工具的设计取舍、提示词怎么进去、唤醒链路、账户与凭据、安全边界、已知限制、English | |
开发者 | 119 个真 bug 的现象 → 根因 → 证据 → 修法 → 回归（"为什么现在这么写"） | |
开发者 | 寻路/防卡住专题：为什么用现成的、装在哪、打过的补丁、上游复核、已知缺口 | |
开发者 | 按日期的改动流水（含拆 core.mjs 的 43 刀 + 分叉成 MCP server 那一版） |
【账户】列出 / 搜索 / 刷新 / 选定 MC 账户。永远拿不到密码或 token。
action：
· list（默认）列出所有账户：innerID / 游戏名 / UUID / 类型（离线或皮肤站）/ 服务器名与地址 / 是否已存凭据
· search 按关键词搜（名字、UUID、服务器名、登录账号）：给 query
· use 选定本会话要用的账户：给 innerID（之后 mc_connect 用它）
· refresh 刷新登录状态（皮肤站去认证服换新令牌）：innerID 不传用当前选定/默认的
⚠️ 失败时带 needUserAction —— 明确告诉用户在终端跑 mcp-mc-agent accounts refresh <innerID>（皮肤站）或 accounts login <innerID>（正版）；密码只有用户能填。
Inputs: query, action, innerID.
与游戏世界互动（优先用它，别用服务器指令）。mode： · look 看向坐标(x,y,z)或玩家(who)："看向我" = look + who · toward 看向并走近某个玩家(who) · place 放方块到 (x,y,z)；悬空先垫脚（=搭高） · bridge 搭路：朝 (x,y,z) 一格格铺（铺在脚下一层），每块等服务端确认了才走；有坠落/岩浆风险就停 · break 破坏 (x,y,z)：先自动换对的工具；换不上就拒绝 · use 使用方块或实体(who)：开门、按钮、拉杆、喂动物；都不给=用手上的东西 · useitem 用手上的东西：扔眼睛/雪球、拉弓、喝药水 · attack 打实体：who 按名字找（中英文都认，24 格内会追）；不给就打 4.5 格内最近的（怪优先）。约 10 秒 · equip 装备(name)：护甲自动穿到对应格（盾→副手），其余拿到手上；to 指定格子 · enchant 附魔台：自动开窗放料；option:0-2 真附魔，不给只报选项 · anvil 铁砧：action:combine(默认) / rename；item + name · smithing 锻造台：item 底座、name 附加、template 模板 · toss 丢弃物品(name, count)
Inputs: x, y, z, to, +11 more.
【管理】读写 mcp-mc-agent 的全局配置（指令白名单、记忆目录…）。
⚠️ MCP 下没有 preset 分档：注册的工具全都能调，mcModePresets/mcPlusPresets/mcMode.* 是 DSH 遗留键，改了没效果（真限制只有 commandWhitelist）。
action：
· get（默认）看生效配置（给 path 看单项）
· set 改一项（path + value）· unset 删一项（回默认）· reset 全恢复默认 · list 默认值 + 生效值
可用键：commandWhitelist（数组；"tp" 精确、"/^gi./" 正则、"" 全放行）· mcModePresets/mcPlusPresets/mcMode.allowOtherTools/mcMode.hideAdminTools（DSH 遗留，见上）· memoryDir（记忆根目录）· memoryPerSession（true = 每会话一份独立记忆 <memoryDir>/sessions/<短会话 id>/，看不到别的会话；默认 false = 共用一份）。
⚠️ expressEnabled/expressBase（文件分享）是 DSH 遗留键：MCP 没有内置文件服务托管发布区，mc_kit_express 会直接回"请把绝对路径告诉用户"。
改完立即生效，落在状态目录的 config.json（默认 ~/.mcp-mc-agent/config.json）。
Inputs: path, value, action.
🤖 自主行为层（"让它像正常玩家一样"）：不传参数 = 看状态。
两层：① 反射层（不花 token、常开）：AI 没调工具时我自己环顾、饿了吃、捡掉落物、躲岩浆火仙人掌、跟随玩家。被怪打 / 有怪贴上来 → 立刻叫醒 AI 定策略（还手/撤/垒方块由 AI 决定）；我自己不跑、不还手，只把手里那件活停下（dangerStopWork 可关；叫醒文案带怪名/坐标/距离/血量）。远程怪（骷髅/掠夺者/女巫…）22 格内且看得见我才算威胁；挨打却看不到怪会报上次看到它在哪。水里憋气（头在水下）也会叫醒 AI 上浮：掉血或超 10 秒；真要憋死了我只按住 jump 抬一下，不横向跑。附近有玩家时我一直看着他（不动位置、不碰东西）；任何工具调用后静默 6s；走路类只在 AI 这一轮跑完时才动。
② 空闲决策层（花 token）：AI 停下来（默认 5 秒没事干）且这一轮结束时，我用插件提示叫醒它，文案带"玩家在干什么"（距离/在动/手持/面向/最近聊天）+ 长期目标 + 没做完的任务，让它按长期目标自己开工（看图不强制；默认目标"像正常玩家一样发展、最后打末影龙"，路线木头/石具→铁→钻石→下界→末地；旁边有人一起干）。不许反问 Master"要我做什么"（不回话 = 让它自己决定）；只有要动 Master 的箱子/建筑时才 mc_say 问一句、问完不等。叫醒 45s 后还没动手，我会再补一条"别问，直接做"的催促（每次叫醒最多一条，也占额度）。
每小时最多 120 次；叫醒后 AI 没做任何事就自动翻倍拉长间隔（封顶 30 分钟），做了事就复位。
用法：action:"status"（默认）｜"off" 关反射层（🔴 不是"全停"：空闲叫醒还开着，要 set {"idleWake":false} 才全静音；自保 avoid 独立，要一起关得 set {"avoid":false}）｜"on" 全开｜"stay" 站定（停跟随）｜"follow" + who:"玩家名" 跟着谁走｜"wake" 立刻叫醒一次（不等间隔）｜"set" + patch:{"standing":"先盖个小屋再挖矿","idleWakeSec":600} 改参数（落 .mcp-mc-agent/auto.json）。
Master 在对话里改了主意 → 立刻用 set 把 standing 写成他那句新的；他没发话就别自己改。
🔴 默认只做无害动作：不会自己拆别人建筑、动别人箱子、乱丢东西、跑太远。
Inputs: who, patch, action.
批量搭方块：把 (x1,y1,z1)–(x2,y2,z2) 这个实心长方体用 name 方块搭出来（会自己走近/垫脚，上限 max 个）。适合"搭一面墙/一根柱子/一个平台"，比一个个 mc_act{place} 省事。结果带 used/held。
🔴 一次只放 10 秒的量（用户要求：单次调用别超过 11 秒）。没放完会返回 remaining + hint——再叫一次 mc_build、范围原样重发就行，已经放对的格子会自动跳过（不会报"这格已经有方块"）。
Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +4 more.
【边界信息】这个插件能做什么、边界在哪：支持的 MC 版本范围（testedVersions）、底层 mineflayer 版本、支持的登录方式、工具命名空间、各种上限（序列步数/记忆大小/事件队列）以及当前配置要点。 进服前不确定版本能不能连时先看它；确实不支持就如实告诉 Master，别硬试。
Inputs: no named parameters.
📦 存取箱子（真·仓库，走服务端的箱子/木桶，不是作弊给物）。背包只有 36 格，攒家当就靠它。
· action:"list"（默认）：看背包里有什么、附近有哪些箱子；给 x/y/z 就打开那个箱子列内容。
· action:"put"：把背包里的东西放进箱子（name:"iron_ingot", count:16，或 all:true 全放）。
· action:"take"：从箱子里拿出来（name:"coal", count:8，或 all:true 全拿）。
· 附近没有箱子、但背包里有，就自己放到脚边再用（placeChest:false 可关）；都没有会告诉你去 mc_craft {name:"chest"} 做一个（8 个木板）。
· all:true 是真的全搬（工具也会被放进去！想留东西就写 name，或者用 keep:"wooden_pickaxe,stone_sword" 留一手）。
· 背包满 / 箱子满 / 开不开都会如实说；搬完会重新读一遍箱子，告诉你现在里面有什么。
🔴 会动世界里的箱子，所以受 mc_observe 门禁限制（强制模式下要先看一眼）。
Inputs: x, y, z, all, +7 more.
以玩家身份执行服务器指令。白名单可配置（默认 tp/give/time/weather/say/gamemode/effect/setblock/fill/clone/summon/title/clear/xp）。要放行别的指令，在普通会话里用 mc_admin_config 改 commandWhitelist（MC 模式会话改不了）。
⚠️ 这是最后手段：正经动作优先 mc_act / mc_build / mc_move（那些不需要 OP）。
Inputs: command (required).
读写本会话的 MC 配置（看门狗唤醒条件、近距半径、心跳间隔、观察窗口、叫法等）。不传参数 = 看当前配置 + 默认值。改配置传 patch；嵌套项用点号键，如 {"wakeOn.itemPickup":true,"nearRadius":24,"mentionPatterns":["ds","用户"]}。嫌"任何玩家说话都叫醒"太吵就把 "wakeOn.anyChat" 设成 false。叫法是配置不是硬编码——学到玩家的新称呼就加进 mentionPatterns。
Inputs: patch, reset.
连接到 MC 服务器。这里没有账号密码——用哪个账户由mc_accounts 维护的账户决定：
先用 mc_accounts 看有哪些账户（action:"use" 选定，或用 account 参数指名 innerID）。
服务器地址/端口/子服由你传（host 不传就看环境变量 MC_HOST，两个都没有会直接报错）；连接成功后会等区块加载完成。
登录失败时会明确说"需要用户处理"——那就告诉用户去终端跑 mcp-mc-agent accounts login <innerID>（正版）或 accounts refresh <innerID>（皮肤站）。
Inputs: host, port, force, account, +2 more.
🧱 合成物品（真合成，走服务端的合成台，不是作弊给物）。生存模式下"原木→木板→工作台→木镐"就靠它。
· 会自动补齐中间产物：给它 name:"wooden_pickaxe"，它自己排"木板→木棍→木镐"的顺序一起做，不用你一步步算。
· 需要工作台时：附近有就直接用；附近没有但背包里有，就自己放到脚边再用（placeTable:false 可关）。
· 原料不够会告诉你缺什么、缺几个、现在有几个，并给出下一步该调哪个工具（比如先 mc_dig 砍原木）。
· name 可以写简称：planks 会自动选背包里那种原木对应的木板（选了哪个会写在结果里）。
· list:true 看配方/看当前能做什么；dryRun:true 只出计划不动手（拿不准就先 dryRun）。
· count 是"背包里一共要到几个"（默认 1）：已经够了就一个都不做，结果会如实说"一个都没做"。要"再做 4 个"就写 {count:4, more:true}。
· 🔴 连着两三次都"超时"就先 mc_scan 复核现场（我每次动手前都会先把合成格里的材料点回背包）。
🔴 合成只动背包、不动世界，所以不受 mc_observe 门禁限制。
Inputs: x, y, z, list, +7 more.
诊断：当前会话的机器人内部状态（物理/控制位/收包/事件队列/合成窗口与合成格）——排查"走不动/收不到消息/合成说缺料"用。同时报提示词状态（promptInjection：RULES.md / 版本提示.md 的文件位置、存在与否、字数、有没有进 instructions——MCP 没有"会话中注入"，提示词是握手时一次性给的），以及性能监测（perf：每个动作的墙钟 / CPU / 期间事件循环延迟 —— 判断"要不要把某个动作搬进 Worker 线程"就看它）。
Inputs: resetPerf.
挖方块：给 name 挖最近的，或给 pos 挖指定坐标；count 可连续挖多个（会自己换成对的工具；结果带 held）。 🔴 一次只挖 10 秒的量（用户要求：单次调用别超过 11 秒）。没挖完会返回"这一轮的 11 秒用完了"——再叫一次 mc_dig 接着挖就行（挖到的方块留在背包里，不会白挖）。
Inputs: x, y, z, name, +2 more.
从 MC 下线（当前会话的机器人退出游戏）。不影响其他会话的机器人。看门狗会自动关闭并提醒你。
Inputs: reason.
读取/消费当前会话的 MC 事件队列（看门狗记下来的：聊天、系统消息、受伤、上线/死亡/重连/断线）。默认消费掉；peek=true 只看不清（都是最早的先出）。返回一行一条（时间 + 类型 + 内容），省 token。
⚠️ 被传送 / 捡物 / 其他玩家上下线不在这里（那些只在看门狗的留档里，用 mc_watch {action:"log"} 看）。
⚠️ waitSec 是兜底，别用它长时间空等：有人叫你（mention）/ 受击 / 死亡 / 断线时，看门狗会打断这个等待（返回里 interrupted:true 就是在告诉你"有人找你了"，唤醒内容同时已经记进事件队列——就在上面那几行里）。真需要盯着某一类事件时才给 waitSec（上限 10 秒）。
Inputs: kind, peek, limit, waitSec.
🔥 熔炼（真熔炼，走服务端的熔炉，不是作弊给物）。生存模式下"粗铁 → 铁锭 → 铁镐"就靠它。
· 能烧：矿石/粗矿（铁、铜、金、远古残骸…）、沙 → 玻璃、圆石 → 石头、原木 → 木炭、生肉/马铃薯 → 熟的、黏土球 → 砖、海带 → 干海带、仙人掌 → 绿色染料 等等。
· 写产物名也行：name:"iron_ingot" 会自动找背包里的粗铁/铁矿石去烧。
· 附近没有熔炉、但背包里有，就自己放到脚边再用（placeFurnace:false 可关）；都没有会告诉你去 mc_craft {name:"furnace"} 做一个（8 个圆石）。
· 自己挑燃料：按要烧的数量算，一次放够 —— 有煤炭/木炭就先烧煤（木棍、原木、木板是合成料，只有没有正经燃料时才拿来烧）；要烧 1 个放 1 块煤（够烧 8 个），要烧 9 个放 2 块。可以 fuel:"coal" 指定；list:true 看背包里有哪些燃料。
· 🔴 装好料就返回，不用盯着：炉子在服务端自己烧。默认不盯（maxWaitSec 默认 0，最多给 10 秒）；过一会儿再叫一次 mc_furnace 就能收成品（不用重新装料）。要烧很多就少量多次（一次最多装 8 个）。
· takeOnly:true = 只把熔炉里已经烧好的拿走（不新塞东西）；dryRun:true 只出计划。
🔴 熔炼会动世界里的熔炉，所以受 mc_observe 门禁限制（强制模式要先看）。
Inputs: x, y, z, fuel, +8 more.
创造模式直接获取物品（协议级改槽位，非 OP 也能用）。给英文物品 id，如 oak_planks / diamond_sword / white_concrete。clearAll=true 清空背包。
Inputs: name, slot, count, clearAll.
看背包、装备栏和手持物品。
Inputs: no named parameters.
把发布区（.mcp-mc-agent/.express/）里的文件给用户。
· 入参 path：发布区下的文件（相对或绝对；必须在 .mcp-mc-agent/.express/ 下）；
· 返回一行，内容取决于 mc_admin_config 里 expressBase 有没有配：
· 没配（默认）：只回一句"文件分享已关闭…"——那就把文件的绝对路径告诉用户，让用户自己打开；
· 开启：回完整 URL——图片 、其它文件 [文件名](url) 嵌进回复里；
· 链接原样使用，不要再补 http://… 或域名。
⚠️ 只有发布区（.mcp-mc-agent/.express/）下的文件可分享。
Inputs: path (required).
图像能力。SVG 是编辑语言：布局/画框/加文字（含中文）/拼网格都直接写 SVG 文本，再用这个工具光栅化成 PNG。
action：
· info 看图的尺寸/格式（也能确认文件是不是能用的图）
· embed 把图片变成 data URI + 现成 <image> 标签 —— 往 SVG 里引图必须这么做
· render SVG → PNG（可给 width/height/scale；svg 文本或 svgPath 二选一）
· grid 把多张图按网格拼成可继续编辑的 SVG 文本（省掉重复写 N 个 和算坐标）
· save 把 SVG 文本或 PNG 字节落盘
输出默认落 .mcp-mc-agent/.out/。图会直接内联给你；要留一份给别人看就写发布区 .mcp-mc-agent/.express/<子目录>/x.png，再用 mc_kit_express 取。
Inputs: gap, out, svg, cell, +10 more.
长期记忆（跨会话、重启后还在），放在 .mcp-mc-agent/ 里，按服务器建子文件夹（_global/ 放通用的）。
索引由你自己维护：README.md（server 把它的内容 + 目录树放进 instructions，忘了更新也不失真，但改了记忆就顺手更新它）。
action：
· index（默认）看总览：有哪些文件夹/文件、各多少条、README 现状
· kinds 四类记忆的说明 + 各类各有几个文件
· record 记一条带元数据的记忆（推荐；同 key 累加成功/失败，不堆重复）
· read 读文件（path 或 topic+server）；读图片会直接给你看
· append 追加一条（同 key 覆盖）—— 只对文本文件
· write 整文件覆盖（重组内容/小标题/表格）
· put 把工作区里的任意文件（图片最常用）复制进记忆
· delete 删文件（path 指向目录则整目录删）
· search 跨文本文件搜关键词，返回命中行
路径写法：path:"mc.example.com/maps/town.png" 或 topic:"landmarks"（server 默认当前服，不传进 _global/）。
⚠️ 只读写文件，不执行任何东西（没有 shell）。
Inputs: ok, key, from, kind, +12 more.
探测局域网里的 Minecraft 服务器（只读：不连接、不进服）。只听原版"对局域网开放"那条多播公告（224.0.2.60:4445，[MOTD]…[/MOTD][AD]端口[/AD]，1.5 秒一次），听到就拿到地址+端口+MOTD。
🔴 不扫端口、不发探测包，所以恒定在 seconds 秒内返回（默认 3，上限 15）；拿到后用 mc_connect 进服。
没听到时：确认对方真开了"对局域网开放"（或 enable-lan-visibility）；部分 WiFi / VPN / 容器会挡多播，那种直接问对方地址。
Inputs: mode, seconds.
看周围地形。默认给"脚下方块那一层"（地板层图：这一层哪里是实心地面、哪里是坑/岩浆/未加载）：· 能站 # 墙 v 会掉下去 ~ 水 ≈ 岩浆 ? 未加载。mode="floor"（默认）/ "auto"（地下自动切洞穴层：# 墙 · 能站 ↓ 低一格 v 会掉 * 矿石）/ "surface"（地表：@ 我 · . 沙 · " 草木 · T 木构 · : 石/建筑 · _ 土/农田）/ "cave"/ "column"（竖列：只看你脚下这一格，往下几格实心、哪里开始是空的）；slab = 洞穴层上下各看几格（默认 2）。format="image" 出俯视图像（有视觉的模型能直接看，并落盘）。字符图省 token 且坐标精确；形状/外观问题用图像。
Inputs: out, mode, slab, yTop, +9 more.
移动。mode="walk" 走过去（自动避障；在水里会自动改成"直接游"，实测 2 格/秒）；mode="fly" 创造模式直飞（最稳，创造模式默认用它）；mode="jump" 原地跳一下（爬台阶/脱困，不需要坐标）；mode="swim" 在水里游到 x/y/z（不给坐标就只上浮换气）。
🔴 一次只走 10 秒（用户要求：单次调用别超过 11 秒）。没走到会返回 arrived:false + remaining（还差几格）+ hint——直接再叫一次 mc_move 往同一个目标走就行，会从当前位置接着走；走远路就是连着叫几次，比一次挂 90 秒好（挂住的时候用户看不到消息）。
🔴 在水里（mc_status 里 在水里）寻路基本不动（A* 不把水当节点，实机"4 秒只挪 1 格"）：mc_move 会自动直接游（按住 forward+jump 浮在水面，实测 2 格/秒），上了岸再交回寻路。快淹死了就 mode:"swim" 不给坐标（只上浮换气）：水挖不掉，别去 mc_dig 水。
🔴 路上自己垫方块上去（pillared）会报 pillaredWith/held——手上会变成垫脚那种方块，别以为还攥着镐（要挖就 mc_act{mode:"break"}，它会自己换）。
Inputs: x, y, z, mode, +1 more.
👁 第一人称视角：从我眼睛（眼高 1.62）朝我正在看的方向渲染截图，直接内联给你看，并附三段式感知：① 我看到（图里数出来的：像素占比、谁在哪一侧、准星压着什么、手里拿什么）；② 程序检测到（游戏数据：坐标/朝向/独立射线打到的方块/半径内实体带坐标·距离·血量/脚下）；③ 不确定（客户端预测的方块世界、没加载的区块、读不到的血量 —— 别把推测当事实）。两套眼睛对不上时点名（以程序射线为准）。
图里：玩家（人形，正版皮肤就贴真的）· 怪物（敌对红/被动黄）· 掉落物（黑描边）、右下角手上的东西；暗紫色块=区块没加载。
👁 什么时候看，你自己定：只读查询（mc_status / mc_inventory / mc_scan…）不用看；动手前先看一眼最划算 —— 挖/放/拆/建、走路、找路找东西、确认玩家或怪在哪、看不清、被卡住；一张图够做一段动作；环境变了（走远/天黑/挨打）就再看一眼。
（想变回强制模式：.mcp-mc-agent/view.json 写 {"gate":true}。）
🔴 图已直接内联给你；想另存一份给别人看就把 out:"\.mcp-mc-agent/.express/<子目录>/view.png" 写进发布区，再用 mc_kit_express 取（默认落 .mcp-mc-agent/.out/）。
Inputs: fov, out, image, width, +5 more.
【单地址探测】已知地址时先问一句"你是谁、通不通"——发一次 Minecraft STATUS ping，拿 通不通 / 版本 / 协议号 / MOTD / 人数 / 延迟。
🔴 不登录、不用账户、不进服，拿到就断；超时自己兜，不会挂住。连不上时把原因说成人话（ECONNREFUSED=端口没人听 / ENOTFOUND=域名拼错 / 超时=防火墙或 enable-status=false）。
分工：先用 mc_ping 确认地址与版本（推荐）再 mc_connect 进服；不知道地址时用 mc_lan 听局域网公告。
Inputs: port, address, subserver, timeoutMs.
在 MC 公屏说话（游戏里所有玩家能看到）。
Inputs: message (required).
扫描我周围方块：给 name 就找这种方块的位置；不给就返回方块统计。
Inputs: name, limit, height, radius.
按顺序执行一串世界交互（替代"写脚本"）：适合"走到这里放几个方块，再走到那里放几个"这类连串动作。
steps 是数组，每项 op 可为：wait(sec) / move(x,y,z,mode) / look(x,y,z 或 who) / toward(who) / place(x,y,z,name) / break(x,y,z) / dig(name 或 x,y,z,count) / use(x,y,z 或 who) / useitem(hold) / attack(who) / equip(name) / give(name,count) / toss(name,count) / say(text) / jump / swim(x,y,z 或 hold)。
逐步执行，默认遇错即停。
🔴 整串只跑 10 秒（用户要求：单次调用别超过 11 秒）。没跑完会返回 stoppedAt（停在第几步，从 0 数）+ remaining + hint——再叫一次 mc_sequence，steps 从停下的那一步往后发就行，前面已经做完了。所以宁可拆成"一串 3~4 步"叫几次，也别写一大串（一大串跑到 10 秒就断了）。
Inputs: steps, budgetMs, stopOnError.
列出当前所有活跃的 MC 会话实例（诊断用：确认各会话的 bot 状态、连接信息）。
Inputs: no named parameters.
看我在 Minecraft 里的状态：在线 / 坐标 / 朝向 / 血量 / 饱食度 / 手持物 / 模式（active 或 standby）/ 看门狗是否在守 / 最近 3 条聊天。
要完整明细（连接信息、看门狗全部开关、最近 5 条聊天原文）传 verbose:true。
Inputs: verbose.
停止本会话的 Minecraft：先尝试优雅退出游戏，再清空本会话全部后台任务（看门狗在里面）。
⚠️ 它不会中断你自己当前这一轮（你正跑在这轮里，自我 abort 会表现为 "tool call aborted"）。所以它适合"我不想玩了，下线"——想停掉自己正在跑的动作，直接别再调工具就行。
⚠️ MCP 下没有"强制停止"按钮（旧 Web GUI 入口已无），且 server 管不到客户端那一轮（stoppedLLM 恒为 false 就是这个意思）——这个工具就是唯一的停止路径。
Inputs: reason.
长活儿进度台账（挖 4 个以上自动开），存记忆根 tasks.json，掉线重连都还在。
run 一轮推进一步；resume 复核；plan/step 记账。
Inputs: all, step, text, force, +5 more.
看门狗控制。进服自动挂载、退服自动卸载，整局持续运行：记录事件，命中唤醒条件就写一条进事件队列（用 mc_events 取走），并发一条 MCP 日志通知（只是提示，内容以 mc_events 为准）。
⚠️ MCP 是"你问它答"：没人能把消息塞进你的上下文——叫醒不会自己蹦到你面前，得主动 mc_events 去收。
action="status"（默认）看状态与配置；"arm" 手动挂载；"disarm" 关闭；"log" 看最近事件留档（含被传送/捡物这类不进队列的）。默认叫醒：有人喊我 / 身边有人说话 / 任何玩家说话（wakeOn.anyChat，默认开）/ 受击 / 死亡 / 被传送 / 断线。唤醒条件/近距半径/心跳/观察窗口等用 mc_config 调（有默认值）。
Inputs: action, reason.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 34 tools
There is substantial functional overlap: mc_act{mode:"break"} vs mc_dig, mc_act{mode:"place"} vs mc_build, mc_act{mode:"toward"} vs mc_move, and mc_sequence re-exposes nearly every primitive (move, place, break, attack, dig, give). mc_act's own description says "优先用它" even though specialized tools exist for the same operations, so an agent must rely on prose notes rather than clear boundaries.
Every tool is lowercase snake_case with an `mc_` prefix, and the helper family consistently uses `mc_kit_*`. Minor deviations exist (mc_admin_config vs mc_config, and mixed verb/noun forms like mc_scan vs mc_status), but the pattern remains predictable.
34 tools is heavy for the stated purpose, above the typical 15-tool ceiling. Most tools do earn their place (accounts, connect, craft, furnace, chest, observe, task, memory), but grouping dig/build/act/sequence into one another suggests some count inflation.
The surface covers the full lifecycle: account selection, LAN/ping discovery, connect/disconnect/stop, perception (status/inventory/scan/map/observe), movement and world interaction, survival workflows (craft, furnace, chest, dig, build), long-lived task and memory state, plus diagnostics and autonomy. No obvious dead ends for the Minecraft-agent domain.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Hosted X (Twitter) MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Hosted YouTube MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
