arenapro-kit

把 AI 接进官方 ArenaPro（dao3.fun / 神奇代码岛的桌面创作端）。 一个本地 MCP 端点 + 一份给 AI 的规范，让 IDE 里的 Agent 能认工程、改脚本、查官方 API， 而不是只能"写一段代码等人贴进去"。

介绍页：https://deepseekv5.github.io/arenapro-kit/

它不是什么

先划清边界，这三条是设计决定，不是待办：

需要出网的工具照样出现在 tools/list 里，调用返回 isError + 原因 + 该跑什么。 不列出来才会出问题：客户端按官方清单调用拿到 unknown tool，Agent 就认为契约对不上， 然后开始猜接口。

Related MCP server: defold-mcp

三十秒接上

node mcp/server.mjs --project /path/to/my-arena

arenapro-kit MCP 已启动     http://127.0.0.1:25316/ap-mcp
工程目录                  /path/to/my-arena
官方插件在线              http://127.0.0.1:25315/ap-mcp · 透传 24 个工具
本包工具                  本地 16 个 · 明确不做 46 个

IDE 侧加一个 server（默认端口 25316，故意让开官方的 25315）：

{ "servers": { "arenapro-kit": { "type": "sse", "url": "http://localhost:25316/ap-mcp" } } }

插件没装也照样能起，只是那 46 个会返回"不支持 + 该跑什么命令"。 插件中途启动/退出都会自动重探（5 秒节流），不用重启本服务。

装 Skill

./install.sh /path/to/your/project     # 软链进该工程的 .qoder/skills/
./install.sh --copy                    # 要落盘副本时用

装完 /arenapro 即可。默认软链：改这份仓库，所有装了它的工程立刻跟着变—— 这类"给 AI 的规范"最容易出的事故就是各处副本各自漂移。

官方 MCP 其实是三个东西

搞清拓扑是接进去的前提，官方文档里它们分散在三个页面：

官方插件那 24 个工具的参数 schema 没有公开，所以本包不猜形状、只做转发—— 猜出来的入参比没有更危险。

本地能做的 16 件事

API 规范读的是工程自带的 d.ts

不自带一份规范副本。 官方类型声明由 apc map resource --type dts 拉进工程，跟着工程版本走； 自带一份等于把规范冻结在某个时间点，AI 会拿旧签名写新工程。

• 官方 GameAPI.d.ts 有 24585 行、134 个顶层类型、880 个成员，ClientAPI.d.ts 另有 48 / 145。

• 完整文档 1.7 万词，不该整篇进上下文——所以是"目录 + 按需查"：api_search 命中才展开。

• 查不到的输出直接写：这通常意味着官方没有这个接口——不要凭印象编一个出来。

解析器踩到的官方写法，都有回归测试钉住：@zh 单独一行、@param 后第二个 @zh、 private constructor()、参数里带内联对象类型、返回值是对象类型、CRLF 行尾。

三条会咬人的规范

• 单位是「格 / tick」，TICK_MS = 64 → 15.625 tick/秒（不是 20 TPS）。 walkSpeed 0.22 ≈ 3.4 格/秒。当成格/秒，人物慢 15 倍。

• 四元数是 xyzw。 实测官方 432 个实体朝向：276 个 [0,0,0,1]、0 个 [1,0,0,0]。

• 两端全局不是一套。 服务端独占 storage voxels resources 与全部 Game*； 客户端独占 ui input screen 与全部 Ui*。写错端不会立刻报错，是 undefined。

CLI

零依赖，不需要 npm install，和 MCP 共用同一份工具实现（所以两边行为不会各说一套）。

node skill/arenapro/scripts/arenapro.mjs info
node skill/arenapro/scripts/arenapro.mjs api say
node skill/arenapro/scripts/arenapro.mjs class GamePlayer
node skill/arenapro/scripts/arenapro.mjs read server/src/App.ts
node skill/arenapro/scripts/arenapro.mjs write server/src/App.ts -     # 从 stdin
node skill/arenapro/scripts/arenapro.mjs plan upload
node skill/arenapro/scripts/arenapro.mjs help

验证

node test/parser.test.mjs     # 22 条：d.ts 解析器 vs 独立实现
node test/engine.test.mjs     # 24 条：Creator 探测、apc 只读白名单、confirm 闸门
node test/kit.test.mjs        # 50 条：MCP 契约、透传优先级、脱敏、写边界
node test/example.test.mjs    # 8~11 条：示例代码逐个成员对官方 d.ts（带 ARENA_PROJECT 时更多）
node test/site.mjs            # 25 条：文档里的数字必须等于代码里的数字

kit.test.mjs 里自己实现了一个最小 MCP 客户端（开 SSE、按 JSON-RPC 走 initialize → tools/list → tools/call），不 import 被测模块——自己测自己等于自己给自己打分。 另外起了一个假插件当夹具：官方插件本机没装时，"能不能透传、谁优先"也得有地方测。

覆盖：插件提供的名字不被本包的"不支持"盖掉、插件报错如实传回、拒绝文本不含凭据样串、 .env 里的 AUTH 值不出现在任何输出、路径穿越与绝对路径被明确拒绝、插件掉线后本地工具照常。

这条踩过一次：MCP 的 endpoint 帧按规格是纯文本 URL，实现时多包了一层 JSON 引号， 结果任何真实 MCP 客户端都连不上，而本地测试全绿——因为测试客户端跟着一起错。 自测自洽证明不了兼容。

许可与来源

Apache-2.0。本仓库只含接入层代码与自写文档，不含官方 CLI 源码、官方 d.ts、地图数据或美术素材。 references/ 里对官方规范的转述基于 box3-product-document （Apache-2.0 © 神岛实验室）；官方两个 stdio MCP 仓库没有 LICENSE 文件， 因此这里只对齐它们的工具命名与形状，不复制其文案。

ArenaPro / dao3 及其素材版权归 box3lab 所有。本项目是独立的第三方接入层， 未复制或反编译官方源码。