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 那一版） |
This server cannot be deployed
One AI endpoint to search and call 22k+ MCP servers; 50+ hosted tools work instantly, no key.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
