MCP 服务器

Cocos MCP Gateway

Global MCP router and gateway for Cocos Creator, connecting Codex, Claude Code, and other stdio MCP clients to project extensions for offline Prefab querying and project snapshots.

README

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 共用的项目绑定和操作规则

常用命令

# 安装全局命令
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 秒超时。

升级前后对比

对比项	旧架构	0.3 新架构	实际收益
MCP Server	每个 Cocos 项目扩展各运行一套	只有全局 Gateway 运行 MCP Server	客户端只维护一个稳定入口
项目扩展职责	同时处理 MCP、HTTP、Editor.Message	只提供 Editor Bridge 与离线 CLI	代码边界更清楚，编辑器侧更轻
共享依赖	每个项目携带 `universal-mcp-sdk` 子库	SDK 已从运行链路移除	不再需要初始化、同步或排查嵌套子库
多项目发现	Gateway 仍需与每个项目级 MCP Server 握手	Gateway 直接发现并探测私有 Bridge	少一层重复协议，聚合链路更直接
本机安全	项目 MCP endpoint 容易被当作客户端入口	Bridge 仅限 loopback、随机 token、严格协议版本	降低误接入和本机跨进程误调用风险
生命周期	endpoint 随项目和编辑器进程变化	编辑器自动注册，Gateway 统一处理启动、重启与等待就绪	多开和项目切换更稳定
版本演进	MCP 能力与 Creator 扩展版本耦合	Gateway API 与 Bridge API 独立版本化	后续可为其他 Creator 系列提供独立扩展并复用 Gateway

这次升级带来的好处

配置更简单：Codex、Claude Code 等客户端只注册一次 Gateway，不再保存任何项目临时端口。
项目更干净：cc-3-8-x-mcp 保留 Creator 3.8.x 编辑器能力和 offline CLI，移除 universal-mcp-sdk 及其子库维护成本。
多项目体验更统一：工具继续使用 <shortName>__<tool> 隔离，Gateway 统一处理重名、重复实例和动态工具列表。
故障边界更明确：MCP 握手或客户端兼容问题查 Gateway；Cocos API 或场景/资源问题查 Editor Bridge。
安全边界更严格：Bridge 不是公开 MCP endpoint，也不会把 token 暴露到 tool 列表或诊断信息中。