Skip to main content
Glama
arena-hero-mcp

arena-hero-mcp

by vhxubo

arena-hero MCP

npm version license

让 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"]
    }
  }
}

Related MCP server: mc-mcp-server

浏览器配置

  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 桥 即可使用。

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

按需启动

  • 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。

Available Tools

6 tools
get_all_cellsA

列出所有非 EMPTY 记忆格(RESOURCE + OBSTACLE).

Inputs: no named parameters.

get_userscriptA

返回 Tampermonkey 油猴脚本全文, 供用户粘贴进扩展安装. 顶部 NAMESPACE 需用户改成自己的 arena-hero 用户名. 不依赖浏览器连接, 随时可调.

Inputs: no named parameters.

list_obstaclesA

列出所有 kind=OBSTACLE 记忆格(永久地形, 可信).

Inputs: no named parameters.

list_resourcesA

列出 IndexedDB cells 中所有 kind=RESOURCE 的探索记忆格(你本局探索过的资源节点坐标). 每次调用通过 ws 让浏览器重读 IndexedDB 返回最新. ⚠️ 记忆会过时, 不可当当前可采.

Inputs: no named parameters.

refreshB

强制让浏览器重读 IndexedDB 并回推最新快照.

Inputs: no named parameters.

snapshot_infoA

返回最新快照元信息(数量/namespace/更新时间/kind 分布) + 浏览器连接状态.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool serves a clearly distinct purpose: listing resources, listing obstacles, combining both, providing snapshot metadata, forcing a refresh, and retrieving the userscript. No two tools could be easily confused even without reading descriptions in detail.

    Naming Consistency4/5

    Tool names mostly follow a verb_noun snake_case pattern (list_resources, get_all_cells, get_userscript) with a few exceptions like snapshot_info (noun_noun) and refresh (bare verb). Still, the naming is consistent in style and readable enough to infer function.

    Tool Count5/5

    Six tools is a well-scoped count for a specialized server. Each tool earns its place, covering the core read-oriented features and the script installation helper without unnecessary bloat.

    Completeness4/5

    The server covers the apparent domain of browsing arena-hero memory cells and installing the userscript, but lacks any mutation or configuration tools (e.g., clearing cache, changing namespace via MCP). These are minor gaps for a primarily read-only toolset.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables AI-driven interactions with Minecraft through a WebSocket-based server and MCP protocol, allowing external MCP clients and in-game chat to trigger AI tools.
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server that provides shared, real-time context across multiple AI agents via WebSocket and MCP resource notifications, enabling collaborative workspaces, memory, tasks, and messaging.
      26 npm
      2
      MIT