arena-hero MCP

让 AI 读取 Arena Hero 浏览器中的探索地图、移动目标、指令上下文，并预览路线。MCP 常驻于宿主的 stdio 生命周期，浏览器 bridge 只在调用相关工具时启动，空闲 2 分钟后退出。

安装

npx -y arena-hero-mcp install <agent>          # 当前项目
npx -y arena-hero-mcp install <agent> --global # 全局

支持 claude、claude-desktop、cursor、windsurf、cline、continue 和 codex。claude-desktop、codex 仅支持 --global。安装后重启 agent。

手动配置：

{
  "mcpServers": {
    "arena-hero-mcp": {
      "command": "npx",
      "args": ["-y", "arena-hero-mcp"]
    }
  }
}

浏览器配置

1. 安装 Tampermonkey 或 Violentmonkey。
2. 点击 快速安装油猴脚本。也可调用 MCP 工具 get_userscript 手动安装。
3. 在 https://app.arenahero.io 的站点设置中允许“不安全内容”，使 HTTPS 页面可以连接本机 ws://127.0.0.1:7790。
4. 登录并打开 https://app.arenahero.io/arena。右上角显示 📡 已连 MCP 桥 即可使用。

脚本自动识别当前用户名，无需修改配置。

• 用户脚本地址：https://raw.githubusercontent.com/vhxubo/arena-hero-mcp/main/tampermonkey.user.js
• 本地桥地址：ws://127.0.0.1:7790（按需监听）

按需启动

• tools/list、get_userscript、snapshot_info 不启动浏览器 bridge。
• 其它工具首次调用时自动启动 bridge；油猴脚本会在下一次重连时接入。
• bridge 空闲 2 分钟自动退出并释放端口，MCP 配置无需增加第二个进程。
• arena-hero-bridge 仅供本地调试，普通用户无需手动启动。

工具

| 工具 | 用途 | |---|---| | get_exploration_map | 查询已探索的 EMPTY、RESOURCE、OBSTACLE，支持 kind 和坐标范围筛选 | | get_movement_goals | 查询 Web 保存的跨 Tick 移动目标 | | get_command_context | 查询当前 Agent、Manual 和合并后的有效指令 | | get_web_game_context | 查询 Tick、连接阶段、指令窗口剩余时间和移动目标 | | preview_route | 按 Web 规则预览对象到目标坐标的路线 | | list_resources | 查询探索记忆中的资源坐标 | | list_obstacles | 查询已知永久障碍坐标 | | get_all_cells | 查询所有非空探索记忆格 | | snapshot_info | 查询版本、namespace、格子统计和浏览器连接状态 | | refresh | 强制浏览器重读 IndexedDB | | get_userscript | 获取当前版本的用户脚本 |

首次安装可调用 snapshot_info 验证：

{
  "bridgeRunning": true,
  "browserConnected": true,
  "versionMatch": true
}

边界

• 未探索区域没有数据。
• RESOURCE 是探索记忆，可能已被采集、补充或移位；实时资源以游戏状态为准。
• preview_route 在油猴脚本中复刻 Web 的视野、地形、占位和移动规则。
• selected_object_id 无稳定浏览器资源来源，因此固定返回 null。
• 关闭 Arena 页面后浏览器桥会断开。

排错

• bridgeRunning: false：尚未调用浏览器工具，属于正常按需状态。
• browserConnected: false：调用浏览器工具后，确认 Arena 页面已打开，并允许了不安全内容。
• “无探索数据”：先进入 Arena 探索地图。
• 脚本版本不匹配：重新调用 get_userscript 并覆盖旧用户脚本。
• EADDRINUSE：端口 7790 已被另一实例占用。
• Codex 日志出现 listen EPERM：当前沙箱禁止监听本机端口，需要在允许本地监听的环境中运行 MCP server。

开发

需要 Node.js 18+。

npm install
PORT=17790 npm test

PORT 默认是 7790；修改后需要同步修改用户脚本中的 WS_URL。