Cocos MCP Server 0.0.1-dev.0（开发版）

当前分支：develop · 当前状态：开发中 · 当前没有正式发行版本

包版本为 0.0.1-dev.0；协议和 Tool 契约版本仍为 0.0.1。

面向 Cocos Creator 3.8.8 的本机多项目 MCP 扩展。Cocos Dashboard 负责项目创建、导入、Creator 版本选择与启动；扩展中的 Worker 向单机 Manager 注册，Agent 只连接 Manager，并在每次项目级调用中显式提供 projectId。

开发状态

• 代码和验证工作以 develop 分支为准；main 不作为当前开发工作分支。
• 当前包是开发版本，不能当作正式发布包直接分发。
• 包版本 0.0.1-dev.0 表示当前开发预发布状态；协议、Schema 和 Tool 契约仍使用 0.0.1。
• verify:release、build:release 等命令是开发阶段的发布门禁和候选包验证工具；通过它们不等于已经发布正式版本。
• 正式发布前仍需完成干净候选版本、Direct Creator Live、Dashboard Creator Live 和发布证据闭环。

核心边界

• 版本：包 0.0.1-dev.0；协议/契约 0.0.1；发行状态 development
• 连接：http://127.0.0.1:38488/mcp
• 传输：MCP Streamable HTTP
• Agent 连接：不使用认证；仅允许回环地址、合法 Host/Origin
• 项目启动：用户项目只能通过 Cocos Dashboard 启动；仅 Direct Creator Live 会启动并终止 Runner 自有的临时 Fixture，绝不操作用户项目
• 多项目：一个 Manager 路由多个已启动 Worker；最后一个 Worker 离线且没有 pending 启动时 Manager 自动退出
• 写操作：预检、revision 比较、执行、回读验证、部分变更报告
• 不提供：事务、自动回滚、文件备份、MCP 操作历史或审计日志

开发安装

npm install
npm run build

将扩展目录放入目标项目：

<project>/extensions/cocos-mcp-server

然后通过 Cocos Dashboard：

1. 导入或选择项目；
2. 选择 Cocos Creator 3.8.8；
3. 启动项目；
4. 等待扩展 Worker 注册到 Manager。

不要直接执行 CocosCreator 可执行文件启动用户项目；这会绕过 Dashboard 的版本与登录上下文。Direct Creator Live 仅适用于 Runner 自有的可丢弃临时 Fixture。

Agent 连接

MCP 客户端连接：

http://127.0.0.1:38488/mcp

示例配置：

{
  "mcpServers": {
    "cocos": {
      "url": "http://127.0.0.1:38488/mcp"
    }
  }
}

连接后的推荐流程：

1. MCP initialize；
2. MCP tools/list，发现 Manager 注册的 Tool 与 Schema；
3. 调用 system_control.list_projects；
4. 选择目标 projectId；
5. 在生成执行计划前，由 Agent 根据 Action 元数据提示需要玩家确认的范围和影响；
6. 逐项目串行执行写操作并检查返回的 revision、verification 和 ChangeManifest。

Cocos 面板不承担审批，MCP 也不签发审批令牌。审批提示统一留在 Agent 上下文中。

Dirty 场景

只支持：

reject
save

默认 reject。不支持 discard，不会无提示丢弃未保存修改。

常用命令

npm run build
npm test
npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:live:matrix
npm run build:release
npm run scan:release

Creator Live

Creator Live 用于开发阶段验证，不替代正式发布所需的完整证据。

Direct 临时 Fixture 模式（默认）

npm run test:live 的默认模式是 Direct：Runner 复制只读 Fixture 后，仅对本次创建的副本直接执行 Creator -nologin，并且只会向其自身追踪的临时 Creator 子进程发送 SIGTERM。它不会启动、保存、关闭或终止任何用户项目。

npm run test:live
npm run test:live:direct
npm run test:live:action -- LIVE-SYS-001
npm run test:live:action:direct -- LIVE-SYS-001

Dashboard 临时 Fixture 模式

Dashboard 模式同样只准备 Runner 自有临时 Fixture，但不直接启动或关闭 Creator；Runner 输出 manifest 和绝对项目路径，操作者在 Cocos Dashboard 中导入、启动和退出这些临时项目。

npm run test:live:dashboard
npm run test:live:action:dashboard -- LIVE-SYS-001

Attach 模式

Attach 仅连接已通过 Dashboard 启动、并且由 Runner manifest 显式登记的临时 Fixture；它是只读验收模式。

npm run test:live:attach
npm run test:live:action:attach -- LIVE-SYS-001

要 attach 当前某次 Dashboard run，必须显式指定该次运行生成的 manifest；Runner 不会扫描目录或默默选择“最新” manifest：

COCOS_MCP_LIVE_DASHBOARD_MANIFEST=/absolute/path/cocos-mcp-live-dashboard-XXXXXX/dashboard-fixtures.json \
npm run test:live:attach

COCOS_MCP_LIVE_DASHBOARD_MANIFEST=/absolute/path/cocos-mcp-live-dashboard-XXXXXX/dashboard-fixtures.json \
npm run test:live:action:attach -- LIVE-SYS-001

仓库文档

• 当前契约摘要
• 开发状态与分支约定
• 变更记录
• 安全说明

契约快照、测试夹具和实现代码均保存在本仓库内；不依赖 Cocos 父项目中的相对路径文档。

故障诊断

Manager 不可用

确认至少一个 Cocos Dashboard 启动的项目仍在线。Manager 不作为常驻项目管理器运行；没有 Worker 且没有 pending 启动时会自动退出。

项目未出现

• 确认 Creator 版本为 3.8.8；
• 确认项目包含已构建的扩展；
• 检查 settings/cocos-mcp.json 中 projectId 与当前项目身份一致；
• 不要同时打开两个使用相同 projectId、但路径不同的项目。

端口修改未立即生效

Manager 运行期间只更新 desired port，不在线重启。通过可见 Cocos GUI 退出全部项目，等待最后一个 Worker 注销和 Manager 自动退出；再次从 Dashboard 启动项目后，新 Manager 才使用新端口。

写操作失败

优先检查：

• projectId 是否正确；
• 权限类别是否允许；
• 路径是否在项目范围内；
• expectedRevisions 是否过期；
• 当前 Scene/Prefab 是否 Dirty；
• Creator AssetDB、Scene 或编译状态是否 ready。

恢复由 Agent Session 和 Git 承担；MCP 不实现事务或自动回滚。

开发阶段发布验证

以下命令用于验证开发候选包，不代表正式发布：

# 普通 CI：干净安装、构建、测试、契约、扫描和高危依赖审计
npm run verify:release:ci

# 开发候选包的完整验证步骤
npm run test:live:release
npm run test:live:dashboard:release
npm run release:evidence
npm run verify:release

正式发布前必须在干净且已提交的候选版本上完成 Direct Creator Live、Dashboard Creator Live、SBOM、校验和和 provenance，并由维护者明确批准发布。dist/release/ 和 dist/release/release/ 均为生成产物，不纳入 Git。