# cocos-streamable-mcp

**Repository Path**: ArtfulCoder/cocos-streamable-mcp

## Basic Information

- **Project Name**: cocos-streamable-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cocos Streamable MCP

面向 **Cocos Creator 3.x** 的本机 Streamable HTTP MCP 扩展。它让 MCP 客户端以受控方式操作 Cocos 场景、节点、组件、资源、预制体、构建与日志，并获取带坐标参考的场景编辑器渲染截图。

[English](README.md) | [协议说明](docs/protocol.md) | [场景截图](docs/scene-capture.md) | [测试说明](docs/testing.md)

## 支持范围

- 仅支持 **Cocos Creator 3.x**，当前版本范围为 `>=3.8.8 <4.0.0`。
- 已验证编辑器：Cocos Creator 3.8.8 LTS。
- 不支持：Cocos Creator 2.x、Cocos Creator 4.x 及后续主版本。
- 仅支持本机 `127.0.0.1` 上的 MCP Streamable HTTP 传输。

## 特性

- 端口和 Token 持久化，并由用户手动启动和停止服务。
- Cocos 原生浮动控制面板，提供状态、地址、Token 显示/复制、启停和令牌轮换。
- 可一键复制 Codex、Claude Code / Claude Desktop 本机版、Qoder、Cursor 与 VS Code 兼容客户端的配置。
- 每个 MCP 工具以单一工具名加 `action` 字段区分操作。
- 基于 Creator 已验证 Electron Canvas 的场景编辑器截图，不使用桌面截图或侧边编辑器面板；默认保留网格、标尺和坐标参考线。
- 本机认证、Origin 校验、会话管理、Schema 校验和项目级写操作串行化。

## 安装

1. 下载发布包，或构建一个根目录名为 `cocos-streamable-mcp` 的扩展 ZIP。
2. 在 Cocos Creator 中打开 **扩展 > 扩展管理器**。
3. 在项目扩展分类导入 ZIP，启用扩展后重新载入。
4. 通过 **扩展 > Cocos Streamable MCP** 打开控制面板。

控制面板会在 Cocos Creator 主窗口内、场景编辑器旁打开。它是可调整大小的宽屏停靠面板，不会创建独立的操作系统窗口。

## 控制面板

扩展加载后服务默认停止，只有用户点击 **启动** 才会监听本机端口。

| 控件        | 行为                                                                       |
| ----------- | -------------------------------------------------------------------------- |
| 启动状态    | 显示未启动、启动中、已启动、停止中或安全的启动失败信息。                   |
| 端口        | 默认 `3307`，仅在未启动时可设置 `1` 到 `65535`。                           |
| Token       | 仅在缺失时生成；默认掩码、只读，并在启动、停止、重载和切换项目后保持不变。 |
| 完整地址    | 显示并复制 `http://127.0.0.1:<port>/mcp`。                                 |
| 启动 / 停止 | 显式控制本机 HTTP 服务。                                                   |
| 生成新令牌  | 唯一的令牌轮换入口。轮换后旧客户端配置立即失效。                           |

启动与停止日志均会在 Cocos 控制台输出扩展版本、完整地址和本机 Bearer Token，便于直接核对当前 Agent 接入配置：

```text
[cocos-streamable-mcp@0.7.3] started
[cocos-streamable-mcp@0.7.3] http://127.0.0.1:3307/mcp
[cocos-streamable-mcp@0.7.3] Bearer <token>
[cocos-streamable-mcp@0.7.3] stopped
[cocos-streamable-mcp@0.7.3] http://127.0.0.1:3307/mcp
[cocos-streamable-mcp@0.7.3] Bearer <token>
```

## Agent 接入

在 **Agents 工具接入** 页签选择使用中的客户端并复制配置。配置中会自动填入当前地址和 `Authorization: Bearer <token>` 请求头。

- **Codex**：TOML 配置。
- **Claude Code / Claude Desktop**：仅支持本机 HTTP JSON 配置；云端连接器无法访问 `127.0.0.1`。
- **Qoder**：Streamable HTTP JSON 配置。
- **Cursor / VS Code 兼容客户端**：通用 HTTP JSON 配置。

端口或 Token 改变后必须重新复制配置。不要将 Token 提交到源码仓库。

### Agent Skill

仓库的 [`skills/cocos-streamable-mcp/SKILL.md`](skills/cocos-streamable-mcp/SKILL.md) 提供编辑器操作、预制体/组件绑定、截图比较和失败恢复流程。它与 Cocos 扩展 ZIP 分开安装；ZIP 只安装 MCP 服务，不会自动注册 Agent Skill。将整个 `skills/cocos-streamable-mcp` 目录放入 Agent 支持的 Skill 目录（Codex 可用 `~/.codex/skills/`），重启或刷新 Agent 后使用。Skill 不包含地址或 Token，连接配置仍从扩展面板复制。

## v0.7.2 修复

- 未命名场景可调用 `scene(action: "save", sceneUrl: "db://assets/scenes/New.scene")` 首次保存，不再依赖人工文件对话框。Creator 原生序列化当前编辑内容，AssetDB 创建资源和元数据，再打开命名场景，后续可以正常保存。
- `scene(action: "create", sceneUrl: "db://assets/scenes/New.scene")` 可以一次完成新建和保存。不传 `sceneUrl` 仍创建未命名场景，首次保存时必须传入路径；已有场景继续调用 `scene(action: "save")`。本次不提供另存为或覆盖其他资源。
- 拒绝非法路径、符号链接逃逸、目标冲突和丢弃未保存修改的新建操作。保存会核验资源身份和未保存状态，不再无条件返回成功。预制体仍可以不传 `sceneUrl` 使用原生保存。

### 新建并保存场景

下面的对象作为 `scene` MCP 工具参数传入。首次保存有两种方式，任选其一：

```json
{ "action": "create", "sceneUrl": "db://assets/scenes/NewMenu.scene" }
```

或者先创建未命名场景，用 `node`、`component` 工具编辑，首次保存时再指定路径：

```json
{"action":"create"}
{"action":"save","sceneUrl":"db://assets/scenes/NewMenu.scene"}
```

首次保存后，后续修改使用 `{"action":"save"}`。再用 `asset(action: "query", url: "db://assets/scenes/NewMenu.scene")` 查询资源，用 `scene(action: "open", sceneUrl: "db://assets/scenes/NewMenu.scene")` 重新打开并查询节点，以确认内容持久化。上述未命名场景首次保存、后续保存及重新打开流程已在 Cocos Creator 3.8.8 中实测。目标路径必须是新资源；此接口不覆盖已有场景，也不是“另存为”。

## v0.7.1 修复

- 修复 `scene.list`、`scene_render.probe` 等列表结果被 MCP SDK 拒绝的问题：`structuredContent` 中的数组统一包装为 `{ "items": [...] }`，对象字段和原始 JSON 文本保持兼容。
- 增加真实 Streamable HTTP 与官方 SDK 客户端的列表、空列表、捕获诊断和对象结果回归测试。
- 更新扩展后请重新连接 MCP 客户端以刷新工具清单；新连接应显示包含 `workflow` 的 9 个工具。

## MCP 工具

| 工具           | action                                                                       |
| -------------- | ---------------------------------------------------------------------------- |
| `scene`        | `list`、`open`、`create`、`save`、`hierarchy`、`close`、`delete`、`validate` |
| `node`         | `create`、`query`、`inspect`、`update`、`delete`                             |
| `component`    | `add`、`remove`、`query`、`inspect`、`set_property`、`bind`                  |
| `asset`        | `list`、`import`、`query`、`delete`                                          |
| `prefab`       | `create`、`build`、`preview`、`instantiate`、`query`、`delete`               |
| `build`        | `start`、`query`                                                             |
| `log`          | `query`、`clear`                                                             |
| `scene_render` | `capture`、`probe`、`compare`                                                |
| `workflow`     | `apply`                                                                      |

`node(query)` 在传入 `uuid`、`name`、`path`、`maxDepth` 或 `includeComponents` 时返回保持层级顺序的轻量匹配列表；不传过滤条件时继续返回完整层级树。`component(inspect)` 支持可选 `properties` 数组，只返回指定 Inspector 字段并在字段不存在时报告参数错误。

`prefab(instantiate)` 会保留 Prefab 关联，不再默认解除实例链接；创建后会同时回读层级和 Inspector 元数据，只有确认源资源 UUID 一致才报告成功，验证失败会清理刚创建的节点。`workflow(apply)` 用步骤 `id` 和 `{ "$ref": "stepId.field" }` 组织多个节点、组件和预制体编辑，先完成引用预检，失败或取消时按逆序补偿，只有 `save: true` 且全部成功才保存。

`scene(validate)` 是只读结构化验收：可限制 `scopeUuid` 和 `maxNodes`，并检查组件、脚本注册、Prefab 关联、Inspector 引用以及 active 状态。返回 `valid`、统计摘要和稳定 issue code，不把业务验收失败伪装成 MCP 传输错误。

`asset(import)` 用于图片、脚本等静态文件：先把源文件放在项目 `.cocos-mcp/imports/`，再指定 `sourcePath` 和 `db://assets/...` 格式的 `targetUrl`。MCP 通过 Creator AssetDB 导入并回读 URL、UUID；同名目标默认拒绝，明确授权后传 `replace: true` 才覆盖，且必须保留原 UUID。不会自动重命名，也不支持用此接口导入 `.scene`、`.prefab`、`.meta`。导入脚本时可传 `expectedComponent`（`@ccclass` 类名），等待该类注册到脚本 UUID 后再继续挂载；未传时仅等待 AssetDB 与 Scene 就绪。若当前文档有未保存编辑或弹出外部变更冲突提示，仍需先核查；MCP 不会自动处理这类编辑器弹窗。更新扩展后重新连接 MCP 客户端以刷新工具 Schema。

```json
{
  "action": "import",
  "sourcePath": ".cocos-mcp/imports/MenuController.ts",
  "targetUrl": "db://assets/scripts/MenuController.ts",
  "replace": true,
  "expectedComponent": "MenuController"
}
```

`scene_render(compare)` 复用当前 Scene 的 Canvas 聚焦与 Scene View 截图流程，只捕获一次图片，然后读取项目 `assets/` 或 `.cocos-mcp/references/` 下的参考 PNG。它返回实际图、差异图和 `changedPixelRatio`、RGBA `meanAbsoluteError`、`similarity`；尺寸不一致时三个指标均为 `null`。默认 `threshold` 为 `0.1`，默认保留网格、标尺和坐标参考线。

本版本实现需求清单中的 1、3、4、5、6、7；运行时启动场景、点击设置按钮等第 2 项自动化暂不实现，避免在未完成 Creator 运行时控制契约前误操作业务场景。

### 调用示例

所有示例对象均作为相应 MCP 工具的 `arguments` 传入：

```json
{
  "action": "instantiate",
  "assetUuid": "<prefab-asset-uuid>",
  "parent": "<parent-node-uuid>"
}
```

```json
{
  "action": "query",
  "path": "Canvas/SafeAreaRoot/SettingsButton",
  "includeComponents": true
}
```

```json
{
  "action": "inspect",
  "nodeUuid": "<node-uuid>",
  "component": "SettingsDialogController",
  "properties": ["closeButton", "musicToggle"]
}
```

```json
{
  "action": "apply",
  "save": false,
  "steps": [
    { "id": "dialog", "operation": "node.create", "name": "SettingsDialog" },
    {
      "id": "controller",
      "operation": "component.add",
      "nodeUuid": { "$ref": "dialog.uuid" },
      "component": "SettingsDialogController"
    }
  ]
}
```

```json
{
  "action": "validate",
  "requiredComponents": [
    {
      "nodeUuid": "<dialog-node-uuid>",
      "component": "SettingsDialogController"
    }
  ],
  "expectedActive": [{ "nodeUuid": "<dialog-node-uuid>", "active": false }]
}
```

```json
{
  "action": "compare",
  "referencePath": "assets/references/settings-dialog.png",
  "threshold": 0.1
}
```

`build(start)`、`asset(delete)` 与 `prefab(delete)` 已在公开协议中定义，但首个发布版默认禁用；后续版本会在明确配置后开放。

`node(inspect)` 必须传入节点 UUID，返回 Cocos Inspector 使用的完整序列化属性 dump，包括节点变换和全部已挂载组件属性。它读取当前编辑器内存状态，因此也会包含尚未保存到场景文件的修改。

`component(query)` 只需 `nodeUuid`，返回节点上每个组件的类名、数组索引和 UUID；随后可用 `component(inspect)` 加 `nodeUuid`、`component` 读取指定组件的完整 Inspector 属性。`component(add)` 接受 Creator 注册类名、CID、脚本 `db://` 路径或脚本资源 UUID，并通过 Creator 组件注册表解析真实类名。`component(set_property)` 保留 Inspector 类型元数据写入普通属性，`component(bind)` 则把目标节点上的组件引用自动写入脚本字段；两者都会回读验证，Creator 未真正接受写入时不会返回虚假的成功结果。

例如，把 `CloseButton` 节点的 `cc.Button` 绑定到根节点 `SettingsDialogController.closeButton`：

```json
{
  "action": "bind",
  "nodeUuid": "<SettingsDialog 节点 UUID>",
  "component": "SettingsDialogController",
  "property": "closeButton",
  "targetNodeUuid": "<CloseButton 节点 UUID>",
  "targetComponent": "cc.Button"
}
```

`prefab(build)` 能把完整声明式节点树直接创建为目标 Prefab，不会在当前业务场景中添加节点。它先拒绝未保存的业务场景，再在临时空场景内构建节点树，调用 Creator 自身 Scene 序列化器生成 Prefab 数据，通过 AssetDB 创建资源并回读确认，最后无论成功或失败都会等待原场景真正恢复。输入必须包含 `url` 和 `root`；节点支持 `name`、可选稳定别名 `id`、`properties`、`components` 与 `children`。组件属性可使用 `{ "ref": "close-button", "component": "cc.Button" }` 引用同一声明树内 `id` 为 `close-button` 的节点组件，MCP 会先创建整棵树并挂载组件，再解析真实组件 UUID、写入并回读验证。同路径资源默认拒绝覆盖；只有明确传入 `replace: true` 时才会删除该目标资源后重建。

`prefab(preview)` 通过 dockable MCP 面板渲染进程投递 AssetDB 打开目标预制体，与 Creator 原生资源工作流使用相同上下文。打开后先等待官方异步 `scene` 面板真正获得焦点，跳过 Creator 内部的 `cc.Scene` 和 `should_hide_in_hierarchy` 包装节点，清空旧选中态，再选择层次管理器中用户实际可见的第一个根节点并让 Scene View 完整居中渲染；只有 Scene View 不可用时才回退到 Inspector 官方预览。整个过程不会创建临时场景，也不会覆盖或恢复用户业务场景。`scene_render` 会对当前场景的直接子节点 `Canvas` 执行同样的等待聚焦、清空、选中和居中流程，默认保留网格、标尺和坐标参考线；只有显式传入 `includeReferenceLines: false` 才隐藏场景辅助线。MCP 客户端负责对返回 PNG 进行比对和总结。

`scene(delete)` 接收 `sceneUrl`，仅删除经 AssetDB 解析出的非当前活动 `.scene` 资源。

## 场景编辑器截图

`scene_render` 会先聚焦当前场景的直属 `Canvas` 节点，定位经过验证的 Cocos Scene View guest WebContents，再从宿主编辑器页面裁剪已经合成的可见像素。Creator 同时保留更大的隐藏 `preview.js` 画布时，定位器会优先选择宿主 `<webview>` 具有有效可见矩形的 guest，从而避免误选隐藏预览，也避开 Creator 3.8.8 中 guest `capturePage()` 不返回的问题。截图默认保留 WebGL 画面、网格、标尺和坐标参考线；宿主截图不可用时会降级订阅 Electron 合成帧。传入 `includeReferenceLines: false` 可请求无辅助线图片，传入 `includeEditorChrome: true` 可获取包含完整编辑器界面的诊断截图。`scene_render(compare)` 的参考图只能来自项目 `assets/` 或 `.cocos-mcp/references/`，比较产物会写入同一 `.cocos-mcp/artifacts/<operation-id>/` 目录中的 `scene-view.png`、`difference.png` 和 `comparison.json`。

截图 PNG 和元数据保存到：

```text
.cocos-mcp/artifacts/<operation-id>/
```

该目录必须保持在 Git 版本管理之外。详细行为请见[场景截图说明](docs/scene-capture.md)。

## 安全模型

- 仅绑定 `127.0.0.1`，不会把项目暴露到局域网或互联网。
- 初始化后要求本机 Bearer Token、允许的 Origin、兼容的 MCP 协议版本和会话 ID。
- 文件访问限制于当前 Cocos 项目和经过批准的导入/产物目录。
- 不直接写入 `.scene`、`.prefab` 或 `.meta` 序列化文件，所有变更均通过 Cocos Editor API 完成。

## 开发与验证

```bash
npm install
npm run bundle
npm test
npm run test:mcp-interop
npm run format:check
```

Creator 交互验收请遵循 [docs/testing.md](docs/testing.md)。自动化测试不能替代真实 Cocos Creator 会话中的视觉验证。

## 贡献

贡献前请阅读 [AGENTS.md](AGENTS.md)。新增工具 action 必须包含 Schema 校验、授权、错误映射、测试和公开文档。所有 TypeScript / JavaScript 源码必须遵守项目规定的中文 TSDoc/JSDoc 注释要求。

## 作者

ArtfulCoder · undefined788@qq.com · [Gitee](https://gitee.com/ArtfulCoder)

## 许可证

[MIT](LICENSE)