MazeBench Local MCP

MazeBench Local MCP 是基于 MazeBenchEngine 改造的本地游戏控制与实时观战版本。

本地 CLI 或桌面端（Gemini、Antigravity、Codex、Claude Code、Claude Desktop 等）通过 stdio MCP 控制同一套 MazeBench JavaScript 游戏引擎；浏览器实时显示 3D 游戏画面、动作时间线和当前状态，并在达到动作上限或场次结束后展示总结与回放。

该模式的核心特点：

• 模型由本地 CLI 或桌面端自行选择，不绑定 Prime Inference 模型目录；

• 不需要模型网关、Docker 或 Prime CLI；

• 不托管外部 CLI，也不采集模型思考过程、token 或费用；

• 游戏状态只能通过 MCP 工具修改；

• 网页只在本机 loopback 地址提供服务；

• External Play 结果作为普通 EXTERNAL 历史记录保存，可回放并参与本地全局排行榜；内部仍标记为不具备正式 benchmark eligibility。

当前维护仓库：zaixiakongyiji/mazebench-local-mcp

环境要求

• Python 3.9+

• Node.js

• 支持本地 stdio MCP 的 CLI 或桌面端

可选：如果需要导出视频回放，还需要 Chromium 系浏览器和 ffmpeg。

Related MCP server: terminal-use-mcp

安装

本仓库包含尚未进入上游 PyPI 版本的 Local MCP 功能，请从当前仓库安装，不要只执行 pip install mazebench。

git clone https://github.com/zaixiakongyiji/mazebench-local-mcp.git
cd mazebench-local-mcp
npm ci
python -m pip install -e .

安装后确认 CLI 来自当前源码：

mazebench help

帮助中应当包含：

mazebench mcp

Windows 用户可以使用以下命令确认实际可执行文件路径：

where.exe mazebench

如果 MCP 客户端无法从 PATH 找到 mazebench，请在 MCP 配置中填写 where.exe mazebench 返回的绝对路径。

启动本地服务

在当前源码仓库中前台启动：

npm run start

该命令直接运行当前仓库的 server.js，适合开发和本地调试。服务启动后需要手动打开终端输出的地址。

通过已安装的 mazebench CLI 前台启动：

mazebench launch

CLI 会运行其已安装 runtime 中的 server.js，并默认打开浏览器。需要后台运行时使用：

mazebench launch bg

默认会打开 External Play 页面：

http://127.0.0.1:3000/external-play

如果端口被占用，MazeBench 会从指定端口开始自动寻找可用端口。实际地址以终端输出为准。

服务管理命令：

mazebench status
mazebench restart
mazebench stop

后台服务日志保存在：

~/.mazebench/server.log

配置本地 MCP

MazeBench 服务和 MCP adapter 是两个独立进程：先在源码仓库运行 npm run start，或使用已安装的 CLI 运行 mazebench launch；再让 CLI 或桌面端启动 mazebench mcp。

Gemini / Antigravity / Claude Desktop 等 JSON 配置

在对应客户端的 MCP 配置中加入：

{
  "mcpServers": {
    "mazebench": {
      "command": "mazebench",
      "args": ["mcp"]
    }
  }
}

Windows 上如果客户端继承不到终端的 PATH，建议使用绝对路径，例如：

{
  "mcpServers": {
    "mazebench": {
      "command": "C:\\Users\\your-name\\miniconda3\\Scripts\\mazebench.exe",
      "args": ["mcp"]
    }
  }
}

修改配置后需要完全退出并重新启动 MCP 客户端，使其重新创建 MCP 进程。

Codex 配置

在 config.toml 中加入：

[mcp_servers.mazebench]
command = "mazebench"
args = ["mcp"]

Windows 上同样可以把 command 替换为 mazebench.exe 的绝对路径。

开始一局

1. 在源码仓库执行 npm run start，或执行 mazebench launch。

2. 在浏览器打开 External Play 页面。

3. 创建单局、并发组或比赛组，并设置统一的游戏 actions 上限；运行组支持 2–8 个席位。

4. 启动或重启已经配置 MCP 的 CLI/桌面端。

5. 给每个模型指定名称，并发送统一初始提示词：调用 MazeBench 的 start 工具，填写指定的 model_name，然后严格按照返回的 run_instructions 继续游戏。（若需跨会话恢复先前未结束的对局，请让模型调用 resume 工具传入 run_id 并在网页控制台完成审批）。

6. 在浏览器中实时观看 3D 画面、动作记录、房间和 gems 状态。

7. 达到 actions 上限后，在同一页面查看总结和回放。

单局和运行组都必须先在 External Play 页面创建。单局保持独立历史；运行组为每个席位创建独立 run，并冻结相同地图、起点、预算和结束规则。concurrent 组只聚合结果，competition 组会在所有席位结束后额外保存本场排名快照；两种模式的子 run 都进入历史、回放和全局排行榜。

同一时间只允许一个运行组等待认领。全部席位被模型调用 start 认领后，即可创建下一组，即使上一组仍在游玩。模型名称由 start 的 model_name 参数登记，harness 自动取自 MCP initialize 的 clientInfo.name，无需在网页表单中填写。

MCP 工具

当前提供 15 个工具：

• start

• resume

• observe

• up、down、left、right

• rotate_camera_up、rotate_camera_down

• rotate_camera_left、rotate_camera_right

• undo

• reset

• go_to_level

• action_sequence

认领与恢复规则

每个独立的 stdio MCP adapter 进程会自动与 External Play 服务协商独立的 controller 会话（MAZEBENCH_LOCAL_MCP_TOKEN 环境变量已废弃并被禁止使用）。并发或比赛模式下，每个模型都需要独立的 adapter 连接，不能共享同一 controller。

同一客户端中的不同对话、窗口或模型不一定拥有独立 MCP 连接，取决于客户端如何管理 MCP 进程。判断依据是是否分别启动了 adapter 并协商了不同的 controller，而不是客户端品牌或对话数量；无需强制使用不同品牌的客户端。

首次认领 armed 席位时调用 start：

{
  "model_name": "gpt-5.6"
}

注意：start 仅用于认领全新空闲席位，严格拒绝传入 run_id 参数。同一 controller 已绑定未结束的运行将拒绝认领新席位。

start 会返回 run_id、可选的 group_id/entry_id、模型与 harness 身份、run_instructions、初始观察和本局预算。

跨会话恢复已有运行： 若因客户端重启或断开需要接管先前未结束的运行，调用 resume：

{
  "run_id": "<此前返回的 run_id>"
}

resume 会创建授权恢复申请，立即返回 pending_approval 与 review_url，adapter 每 2 秒后台查询审批状态。用户可在 External Play 网页控制台（首页待审批申请面板或对局详情页）进行审核批准。若原 controller 仍在线，审批时会弹出二次确认对话框，确认后强制接管（force: true），原子撤销旧租约并绑定新 controller。获批后 adapter 自动附着租约并启动心跳，不执行游戏动作；调用 observe 获取当前观察，或再次调用 resume 获取最新提示词与环境元数据。拒绝、过期或断连会停止轮询；租约已过期或被接管时，重新调用 resume 必须再次审批。

已认领运行的 adapter 若丢失认证，后续 start 重试不会创建新 controller 或领取下一席位；只能通过 resume 重新申请并获批后继续游戏。审批和新认领共用 controller 绑定锁，同一 controller 不会同时持有两个运行的租约。

在服务端，运行结束或授权接管成功会解除原 controller 的绑定；接管时也会清理已经断开或超时的旧绑定。仅断开或租约超时不代表自动解除绑定。服务端解绑不等于 adapter 自动获得新局权限：进入重新授权状态的 adapter 仍受上述恢复审批限制。

start 成功认领或 resume 获批后建立控制 lease。之后的游戏操作必须使用持有当前有效租约的 MCP 会话，不能直接调用或修改游戏引擎状态。

action_sequence 接受 1 到 1,000 个有序 action 字符串。它逐步执行并保留实时观战与动作记录；默认返回紧凑步骤摘要和 final_observation。遇到 ended: true、玩家死亡或动作错误时会提前停止，以便模型恢复或重新规划。

上一局结束后，可以保留原 MCP 连接，显式调用 start({ model_name }) 认领新运行组中的空席位。如果旧连接认证失效，adapter 会先向服务端确认旧局已结束，再在本次 start 中更新认证并认领，无需额外审批。若旧局仍在进行，则必须通过 resume 和网页审批；若旧局记录缺失或无法可靠确认，模型应报告错误并暂停，由用户检查服务和历史记录。

同一 adapter 的 start 与 resume 不能同时执行。取消认领或切换会话后，迟到响应不能继续发起认领或将旧动作发送到新局。并发模型仍须使用独立 adapter 连接。

推荐的自主游玩提示词

将 <指定模型名称> 替换为本次模型的名称，单局、并发组和比赛组统一使用：

调用 MazeBench 的 start 工具，填写 model_name 为“<指定模型名称>”，然后严格按照返回的 run_instructions 继续游戏。

目标、允许工具、动作或时间预算、死亡恢复方式和结束规则以服务端返回的 run_instructions 及运行状态为准，不需要根据模式或预算手工修改初始提示词。不要为新局填写 run_id。

若因客户端重启或断开需要恢复未完成的对局，可让模型使用以下恢复提示词：

调用 MazeBench 的 resume 工具，填写 run_id 为“<此前返回的 run_id>”，不要调用 start。
收到 pending_approval 后等待用户在 review_url 对应的本地网页批准，不要尝试绕过审批。
获批后再次调用 resume 获取最新 run_instructions 和 observation，严格按返回的规则继续游戏，直到服务端报告 ended: true。

结束条件与运行产物

场次在以下条件之一满足时结束：

• 达到创建场次时设定的 game actions 上限（默认 256）；

• 使用旧版时间预算配置的运行达到服务端截止时间；

• 用户在本地网页明确取消；

• 服务或运行发生不可恢复错误。

运行数据默认保存在：

~/.mazebench/external-runs/<run-id>/

主要产物包括：

• manifest.json

• journal.jsonl

• actions.jsonl

• base-viewer-state.json

• world-bundle.json

• summary.json

• replay 使用的不可变 blobs

运行组数据默认保存在 ~/.mazebench/external-groups/<group-id>/：

• manifest.json：共同规则和席位关联；

• result.json：全部子 run 终止后保存的结算快照；比赛组含本场排名，并发组的 ranking 为 null；

• seat-failures.json：存在席位恢复失败等情况时保存的失败记录。

子 run 的历史和回放仍保存在各自的 external-runs/<run-id>/ 目录。组结算写入失败时保持 finalizing，服务会重试补写，而不是提前将组标记为结算完成。

取消与删除运行组

网页中的“取消未结束的运行”会停止尚未结束的子 run，并保留已有历史、结果和回放。“删除”则会移除整个运行组及其子 run 的持久化记录和回放资源，不是隐藏列表，也没有撤销功能；需要保留结果时应使用取消。

其他本地命令

交互式 ASCII 游戏：

mazebench ascii
mazebench ascii --level CxD

模型视角 JSON 观测：

mazebench json --level CxD
mazebench json --level CxD --omniscient

交互式命令 REPL：

mazebench play level=HxI view=top-diagonal

重新生成已有运行的回放：

mazebench replay <session-dir | session.json | results.jsonl>

Prime 集成

Local MCP、实时观战、总结和回放默认不依赖 Prime CLI。

仓库仍保留可选的 Prime 兼容集成，但默认关闭。只有确实需要维护旧的 Prime evaluation 路径时，才应显式设置：

MAZEBENCH_ENABLE_PRIME=1

Prime 集成不是本仓库 Local MCP 主流程的前置条件。

开发与测试

安装开发依赖：

npm ci

常用验证命令：

npm run test:pr
npm run test:browser
python -m unittest tests/test_mazebench_cli.py

涉及 schema 时，修改生成源 scripts/build-standalone-validators.js 后重新构建；不要手工编辑 shared/validators.standalone.js 或 public/validators.standalone.js。涉及 runtime 源文件时，通过同步脚本更新 environments/mazebench/mazebench/runtime/，不要直接修改镜像副本；新增运行时文件需确认已被同步清单覆盖。

npm run build:validators
npm run sync-runtime
node tests/runtime-drift.test.js

External Play / MCP 改动的专项回归和完整 Node 验证：

node tests/external-play-service.test.js
node tests/external-run-groups.test.js
node tests/maze-external-mcp.test.js
node tests/adversarial-mcp-external-stress.test.js
npm run test:browser
npm test

报告测试结果时应分别注明通过、失败和因环境限制跳过的项目，不能把跳过当作通过。仅修改 README 或 AGENTS.md 无需重新生成 validators 或同步 runtime。

相关文档：

• Maze level 格式

• Python 打包说明

致谢

本项目基于原始 MazeBenchEngine 项目开发。感谢原作者 Jonathan Pappas、David Pappas 及所有上游贡献者提供 MazeBench 游戏引擎、关卡、网站与评测基础。

Local MCP 改造版本的维护仓库为 zaixiakongyiji/mazebench-local-mcp。

License

本项目及其上游代码依据 MIT License 提供。

Copyright (c) 2026 Jonathan Pappas and David Pappas

原作者的上述版权声明与 MIT 许可全文均原样保留在仓库的 LICENSE 文件中。使用、修改或再分发本项目时，必须按照 MIT License 的要求保留该版权声明和许可文本。

长时间运行与长记录观战

• 恢复时逐条对照权威 WAL 校验 actions.jsonl，修复内容不一致、缺失记录或末尾缺少换行的投影；恢复索引、逐步重建游戏状态、结算校验及诊断均分块读取日志，不将整份 WAL 转为字符串，并保留完整 UTF-8 字符。

• 活动 controller 的有效凭据随成功的租约心跳续期，持续连接不会因为最初的 24 小时期限被强制中断。租约仍为 30 秒，adapter 每 10 秒发送心跳；已过期、撤销、被接管或服务重启后的旧授权仍需按 resume 审批恢复。

• adapter 的普通 HTTP 请求总期限为 20 秒，心跳为 8 秒，并禁止重叠心跳。超时与响应中断会返回错误和不含凭据的 stderr 诊断。start 结果不明时，使用相同参数显式重试会沿用原操作 ID；不能更换身份自动领取新席位。

• 观战进入时直接同步最新状态，只加载附近的动作；拖动时间轴按需加载历史。指令列表最多 200 个节点，浏览器缓存最多 1000 条动作。宝石提示按相邻历史步骤的计数变化计算，与播放位置无关。

• 动作分页和 SSE 重连使用 WAL 恢复的内存索引，不再逐页扫描整个历史文件。事件落后超过 500 条时，观众重新同步最新快照；慢观众的发送积压超过 1 MiB 时断开重连，避免持续堆积。