cocos-mcp

Cocos Creator 3.8.x 的 MCP 桥接扩展 + 离线 prefab / AnimationClip 工具。

把编辑器的 scene/asset/preview/local 能力以 MCP 协议暴露给 Claude Code；同时提供无需编辑器运行的 offline prefab 编辑，以及 AnimationClip 查询和数值曲线创建能力。

版本状态

• 现有稳定 tag：v1.0.0；它早于当前正式制品规范，GitHub Releases 尚无对应的自包含发布。stable/v1.0 仅作为 1.0 维护分支。

• main：下一版本的未发布开发线；公开能力变化见 CHANGELOG.md。

• 历史 test/* 分支和 *-test.* tag 只保留实验记录，不作为稳定发布使用。

Related MCP server: Cocos MCP Server

文档导航

架构

Claude Code (MCP client)
        │  stdio (JSON-RPC)
        ▼
┌─────────────────────────────┐
│  router/bin.js              │  ← 统一入口，聚合多个编辑器
│  - 扫 ~/.cocos-mcp/editors/ │
│  - offline resource tools   │
└───────────┬─────────────────┘
            │  HTTP MCP (JSON-RPC)
    ┌───────┴────────┐
    │                │
    ▼                ▼
编辑器实例 A      编辑器实例 B       ← 每个项目一个编辑器进程
main.js + server/tools.js         ← HTTP MCP 生命周期 + tool/resource 定义

offline resource tools 在 router 进程内直接执行，调用 cli/src/index.js，不需要编辑器运行：

• prefab：prefab_query / prefab_edit / prefab_batch

• AnimationClip：animation_query / animation_create

三个组件

1. 编辑器扩展（main.js + panel + server）

在 Cocos Creator 编辑器进程内运行。main.js 使用 mcp-sdk 启动 HTTP MCP Server，server/tools.js 定义 tools/resources，并把实例地址、项目身份和当前加载的扩展运行身份写入 ~/.cocos-mcp/editors/<pid>.json（心跳注册）。

暴露的 tool 域：

2. stdio router（router/）

入口：router/bin.js

职责：

• 扫描 ~/.cocos-mcp/editors/ 发现活跃编辑器（心跳超 120s 视为已死）

• 每隔 15s 自动发现新实例

• 给每个编辑器的 tool 加 <shortName>__ 前缀，合并后暴露给 Claude Code

• 内置 offline prefab 与 AnimationClip tools，不带前缀，全局可用

tool 路由示例：

forest__scene_query_node_tree  →  forest 编辑器的 HTTP MCP server
another__asset_query_assets    →  another 编辑器的 HTTP MCP server
prefab_query                   →  router 本地执行（cli），无需编辑器

3. cocos-mcp-cli（cli/）

零依赖 Node CLI，直接读写 .prefab 文件，无需 Cocos 编辑器运行。详见 doc/cli.md。

功能面板

通过菜单「扩展 → Cocos MCP → 功能面板」打开，或在编辑器扩展面板停靠。

自定义 Debug 按钮：在项目根目录新建 .dev/cc-mcp-panel.json：

{ "buttons": [{ "label": "解锁签到", "code": "app.userMod.setUserValue(0,1)" }] }

Tools 清单

scene 域（需编辑器运行）

修改 prefab 资源文件属性建议用 prefab_edit（offline），scene_set_property 只适用于运行时节点或需要编辑器上下文的情况。

asset-db 域（需编辑器运行）

asset_query_assets 的兼容策略是 opt-in 分页：省略 offset / limit 时，assets 仍包含全部匹配项；响应同时给出 total、offset、limit、hasMore 和 nextOffset。fields 只保留每项指定的顶层字段。大工程应主动分页，因为不传参数仍可能产生大响应。

preview 域（需编辑器运行）

预览页面截图、点击、JS 执行等浏览器交互不由本扩展注册 preview tool，agent 应先用 preview_query_url 获取当前 URL，再交给 Playwright / Chrome 验证真实页面。

local / maintenance 域（需编辑器运行）

offline 域（router 级，无需编辑器运行）

完整 op 列表与配方见 doc/cli.md。

offline tools 的 filePath 和 opsJsonPath 必须为绝对路径；router 以 stdio 模式运行，cwd 不确定，相对路径有歧义。

router / editor-control 域（无需编辑器内 server）

多开支持

每个 Cocos 编辑器实例启动时向 ~/.cocos-mcp/editors/<pid>.json 写入注册信息：

{
  "pid": 12345,
  "url": "http://127.0.0.1:7788/mcp",
  "shortName": "forest",
  "projectPath": "/path/to/project",
  "sourceRealPath": "/path/to/cocos-mcp",
  "sourceGitHead": "<full-git-head>",
  "sourceDirty": false,
  "runtimeBuildId": "<runtime-source-hash>",
  "toolSchemaHash": "<tool-schema-hash>",
  "loadedAt": "<iso-timestamp>"
}

HTTP Server 直接尝试 bind；遇到 EADDRINUSE 会递增端口重试，并在 bind 成功后才注册实际 endpoint。router 定期扫注册目录，心跳超过 120s 的记录视为死亡自动剔除。tool 名以 <shortName>__ 为前缀隔离；router_list_editors 会透传运行身份，用于判断两个实例是否真的加载了同一份代码，而不是只比较 Git 工作树当前状态。

direct HTTP 与 router 都会在调用 handler 或转发前检查 schema 顶层 required 字段，缺失时返回 isError: true 和包含 tool/参数名的错误。当前不执行完整 JSON Schema 类型、嵌套或条件校验；这些仍由具体 tool 处理。

接入 Claude Code

⚠️ 本仓库通过 git submodule 依赖 universal-mcp-sdk，clone 后必须先拉 submodule，否则 MCP server 起不来：

git submodule update --init --recursive

正式 GitHub Release 应提供已嵌入 SDK 的自包含 ZIP、manifest 与 SHA-256；从源码分支或 GitHub source archive 安装时仍必须按上面步骤初始化 submodule。制品与校验规则见 RELEASING.md。

claude mcp add cocos -- node /path/to/cocos-mcp/router/bin.js

接入后 Claude Code 即可调用所有活跃编辑器的 tool，以及全局 offline prefab 与 AnimationClip tools。

.dev/refresh 信号协议

外部往 <project>/.dev/refresh 文件写一行命令，编辑器扩展的 watcher 读到后执行并清空文件。fire-and-forget，无返回值。

协议精简：只支持 restart-package——清除目标扩展目录内的 Node 模块缓存，再调度 Creator Extension Manager reload。资源刷新 / 场景重载 / 预览刷新都走 MCP tool（preview_refresh_and_reload / asset_reimport 等）或面板按钮；浏览器截图和交互验证交给 Playwright / Chrome。

echo "restart-package" > .dev/refresh

面板上的「重启 MCP Server」按钮只重启 HTTP server 实例，Node require 缓存不动，不能证明 main.js 代码已重载。restart-package 是无返回值的 fire-and-forget 信号；local_reload_package 会明确返回 state: "scheduled"、completionObserved: false 和 runtimeIdentityBefore，保留的 ok / reloaded 字段仅用于兼容旧调用。调用方应等待 router 重新发现实例，并比较新 registry/status 的 loadedAt；时间戳必须变化。runtimeBuildId 与 toolSchemaHash 只有在相应源码或 schema 改变时才应变化。

已知限制

1. 多层嵌套组件引用：CLI 已通过 refSubNode 字符串数组路径支持。极端深嵌套场景仍建议走 tools pipeline（tools/step-3-script/bind-prefab-components.ts）

2. offline 改完后需手动触发刷新：直接写磁盘 Cocos 编辑器不会自动感知。改完后调用 asset_reimport（编辑器在线时）或 preview_refresh_and_reload，否则编辑器和预览页面看到的仍是旧内容

3. 分页为兼容性 opt-in：asset_query_assets 省略 limit 时仍返回全部匹配项；分页减少 MCP wire payload，但 Cocos AssetDB 仍先产生完整匹配数组

4. 参数校验范围：当前统一检查顶层 required 字段，不执行完整 JSON Schema 类型、嵌套或条件校验

5. 扩展 reload 不可同步确认：reload 会中断当前扩展自己的 MCP endpoint，所以 local_reload_package 只报告 scheduled；调用方必须从 router/registry 观察新 loadedAt

反馈

使用本扩展（MCP tool / offline CLI）时遇到 bug、行为异常或文档与实际不符，agent 必须把问题反馈给用户，由用户决定是否修复扩展本身，不要在调用方加 workaround 绕过。