# 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 操作历史或审计日志

## 开发安装

```bash
npm install
npm run build
```

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

```text
<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 客户端连接：

```text
http://127.0.0.1:38488/mcp
```

示例配置：

```json
{
  "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 场景

只支持：

```text
reject
save
```

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

## 常用命令

```bash
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`。它不会启动、保存、关闭或终止任何用户项目。

```bash
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 中导入、启动和退出这些临时项目。

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

### Attach 模式

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

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

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

```bash
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
```

## 仓库文档

- [当前契约摘要](docs/cocos-mcp/contract-summary.md)
- [开发状态与分支约定](DEVELOPMENT.md)
- [变更记录](CHANGELOG.md)
- [安全说明](SECURITY.md)

契约快照、测试夹具和实现代码均保存在本仓库内；不依赖 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 不实现事务或自动回滚。

## 开发阶段发布验证

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

```bash
# 普通 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。