Cocos MCP Gateway

面向 Codex、Claude Code 和其他 stdio MCP 客户端的全局 Cocos Creator MCP Gateway。它是系统中唯一的 MCP Server，负责多项目发现、工具聚合、路由、编辑器 生命周期和离线 Prefab CLI。

第一次使用请先阅读：安装与使用指南。

每个 Cocos Creator 3.8.x 项目只安装轻量 cc-3-8-x-mcp。扩展通过私有本机 /bridge 把 Editor.Message 能力交给 Gateway，不再运行项目级 MCP Server， 也不再依赖 universal-mcp-sdk。

目录

• runtime/：全局 MCP Gateway 与离线 cocos-mcp-cli

• extension/：供新 Cocos 项目安装的 Editor Bridge 扩展快照（不含 mcp-sdk）

• scripts/connect-project.js：把扩展接入新项目，不覆盖已有扩展

• scripts/sync-runtime.js：从扩展源码同步 Gateway runtime、CLI 和扩展快照

• skills/：Codex 与 Claude 共用的项目绑定和操作规则

Related MCP server: Cocos Creator MCP Server

常用命令

# 安装全局命令
npm link

# 接入新 Cocos 项目
cocos-mcp-connect /path/to/cocos-project

# 离线查询 Prefab
cocos-mcp-cli query /absolute/path/to/file.prefab --selector tree

# 从扩展源码更新共享快照
node scripts/sync-runtime.js /path/to/cc-3-8-x-mcp

客户端入口

Codex 通过本仓库的个人插件清单加载 .mcp.json。Claude Code 和其他 MCP 客户端可运行：

cocos-mcp-setup-claude

该命令会同时注册用户级 stdio MCP，并把仓库中的 cocos-mcp-control 安装到 Claude Code 的个人 Skill 目录。后续再次运行只更新由 Gateway 管理的副本；如果 用户已经维护了同名自定义 Skill，安装器会保留它并给出提示，不会覆盖。

各 Cocos Creator 3.8.x 项目只负责运行 extensions/cc-3-8-x-mcp，并向 ~/.cocos-mcp/editors/ 注册自己的 projectPath、Bridge 版本、loopback endpoint 和进程级随机鉴权 token。客户端永远只连接 Gateway，不能直接连接 /bridge。

不同开发者可以把全局仓和 Cocos 项目放在任意目录；安装时由 npm/客户端配置解析 本机实际路径，项目代码和构建流程始终只依赖项目内扩展。

0.3 新架构

Codex / Claude Code / 其他 MCP 客户端
                  │ MCP over stdio
                  ▼
        全局 cocos-mcp-gateway
                  │ 私有 loopback /bridge + Bearer token
          ┌───────┴────────┐
          ▼                ▼
  Creator 3.8.x A   Creator 3.8.x B
   cc-3-8-x-mcp      cc-3-8-x-mcp

• Gateway 对客户端使用 MCP 2025-06-18，项目扩展不再解析 MCP。

• Gateway 在 initialize 响应中返回跨客户端 instructions，统一项目路径绑定、 Bridge 私有边界、Prefab 安全修改和编辑器生命周期约束。

• Gateway 每 15 秒发现活跃编辑器，统一聚合、加前缀并路由 tools/resources； 编辑器变化时发送 notifications/tools/list_changed。

• 注册目录权限为 0700，带 token 的实例记录原子写入并限制为 0600。

• Gateway 只接受 transport=editor-bridge、Gateway API v2、Bridge API v1 和 http://loopback:<port>/bridge。

• Editor Bridge 拒绝浏览器 Origin，只接受 JSON，请求体上限为 4 MiB，且每次启动 都生成新的 32 字节随机 bearer token。

• 探活、普通 tool 和 Cocos 长操作默认分别使用 8 秒、60 秒和 180 秒超时。

升级前后对比

这次升级带来的好处

1. 配置更简单：Codex、Claude Code 等客户端只注册一次 Gateway，不再保存任何项目临时端口。

2. 项目更干净：cc-3-8-x-mcp 保留 Creator 3.8.x 编辑器能力和 offline CLI，移除 universal-mcp-sdk 及其子库维护成本。

3. 多项目体验更统一：工具继续使用 <shortName>__<tool> 隔离，Gateway 统一处理重名、重复实例和动态工具列表。

4. 故障边界更明确：MCP 握手或客户端兼容问题查 Gateway；Cocos API 或场景/资源问题查 Editor Bridge。

5. 安全边界更严格：Bridge 不是公开 MCP endpoint，也不会把 token 暴露到 tool 列表或诊断信息中。

不兼容升级说明

0.3 不兼容旧项目的 /mcp Server，也不保留旧协议 fallback。升级时需要：

1. 将所有 Cocos Creator 3.8.x 项目统一升级到新版 cc-3-8-x-mcp。

2. 删除客户端里直连某个项目 /mcp endpoint 的配置，只保留全局 Gateway。

3. 将旧的 router_list_editors 调用改为 gateway_list_editors。

4. 更新 Gateway 或 Codex plugin 后开启新会话，让客户端重新获取完整 tools 列表。

当前 cc-3-8-x-mcp 严格限制为 Cocos Creator >=3.8.0 <3.9.0。其他 Creator 系列应提供独立扩展包，共用同一套 Bridge 协议，而不是放宽该扩展的版本范围。

相关项目

• cc-3-8-x-mcp