b1db9692a7
feat(mcp-bridge): 添加 MCP Bridge 插件 添加完整的 MCP (Model Context Protocol) 桥接插件，用于连接外部 AI 工具与 Cocos Creator 编辑器，实现对场景、节点等资源的自动化操作。 功能包括： - HTTP 服务接口，提供标准 MCP 协议支持 - 场景节点操作：获取、创建、修改节点 - 资源管理：创建场景、预制体，打开指定资源 - 实时日志记录和展示 - 自动启动服务支持 提供多个 API 接口如 get_selected_node、set_node_name、 save_scene、get_scene_hierarchy 等，支持外部工具调用。 更新作者信息为 Firekula。 ```
150 lines
4.4 KiB
Markdown
150 lines
4.4 KiB
Markdown
# MCP Bridge 插件
|
||
|
||
这是一个为 Cocos Creator 设计的 MCP (Model Context Protocol) 桥接插件，用于连接外部 AI 工具与 Cocos Creator 编辑器，实现对场景、节点等资源的自动化操作。
|
||
|
||
## 适用版本
|
||
|
||
此插件适用于 Cocos Creator 2.4.x 版本。由于使用了特定的编辑器 API，可能不兼容较新或较老的版本。
|
||
|
||
## 功能特性
|
||
|
||
- **HTTP 服务接口**: 提供标准 HTTP 接口，外部工具可以通过 MCP 协议调用 Cocos Creator 编辑器功能
|
||
- **场景节点操作**: 获取、创建、修改场景中的节点
|
||
- **资源管理**: 创建场景、预制体，打开指定资源
|
||
- **实时日志**: 提供详细的操作日志记录和展示
|
||
- **自动启动**: 支持编辑器启动时自动开启服务
|
||
|
||
## 安装与使用
|
||
|
||
### 安装
|
||
|
||
将此插件复制到 Cocos Creator 项目的 `packages` 目录下即可。
|
||
|
||
### 启动
|
||
|
||
1. 打开 Cocos Creator 编辑器
|
||
2. 在菜单栏选择 `Packages/MCP Bridge/Open Test Panel` 打开测试面板
|
||
3. 在面板中点击 "Start" 按钮启动服务
|
||
4. 服务默认运行在端口 3456 上
|
||
|
||
### 配置选项
|
||
|
||
- **端口**: 可以自定义 HTTP 服务监听的端口，默认为 3456
|
||
- **自动启动**: 可以设置编辑器启动时自动开启服务
|
||
|
||
## API 接口
|
||
|
||
服务提供以下 MCP 工具接口：
|
||
|
||
### 1. get_selected_node
|
||
- **描述**: 获取当前编辑器中选中的节点 ID
|
||
- **参数**: 无
|
||
|
||
### 2. set_node_name
|
||
- **描述**: 修改指定节点的名称
|
||
- **参数**:
|
||
- `id`: 节点的 UUID
|
||
- `newName`: 新的节点名称
|
||
|
||
### 3. save_scene
|
||
- **描述**: 保存当前场景的修改
|
||
- **参数**: 无
|
||
|
||
### 4. get_scene_hierarchy
|
||
- **描述**: 获取当前场景的完整节点树结构（包括 UUID、名称和层级关系）
|
||
- **参数**: 无
|
||
|
||
### 5. update_node_transform
|
||
- **描述**: 修改节点的坐标、缩放或颜色
|
||
- **参数**:
|
||
- `id`: 节点 UUID
|
||
- `x`, `y`: 坐标
|
||
- `scaleX`, `scaleY`: 缩放值
|
||
- `color`: HEX 颜色代码（如 #FF0000）
|
||
|
||
### 6. create_scene
|
||
- **描述**: 在 assets 目录下创建一个新的场景文件
|
||
- **参数**:
|
||
- `sceneName`: 场景名称
|
||
|
||
### 7. create_prefab
|
||
- **描述**: 将场景中的某个节点保存为预制体资源
|
||
- **参数**:
|
||
- `nodeId`: 节点 UUID
|
||
- `prefabName`: 预制体名称
|
||
|
||
### 8. open_scene
|
||
- **描述**: 在编辑器中打开指定的场景文件
|
||
- **参数**:
|
||
- `url`: 场景资源路径，如 `db://assets/NewScene.fire`
|
||
|
||
### 9. create_node
|
||
- **描述**: 在当前场景中创建一个新节点
|
||
- **参数**:
|
||
- `name`: 节点名称
|
||
- `parentId`: 父节点 UUID (可选，不传则挂在场景根部)
|
||
- `type`: 节点预设类型（`empty`, `sprite`, `label`, `canvas`）
|
||
|
||
## 技术实现
|
||
|
||
### 架构设计
|
||
|
||
插件采用了典型的 Cocos Creator 扩展架构，包含以下几个部分：
|
||
|
||
- **main.js**: 插件主入口，负责启动 HTTP 服务和处理 MCP 请求
|
||
- **scene-script.js**: 场景脚本，负责实际执行节点操作
|
||
- **panel/**: 面板界面，提供用户交互界面
|
||
- `index.html`: 面板 UI 结构
|
||
- `index.js`: 面板交互逻辑
|
||
|
||
### HTTP 服务
|
||
|
||
插件内置了一个 HTTP 服务器，提供了两个主要接口：
|
||
|
||
- `GET /list-tools`: 返回所有可用的 MCP 工具定义
|
||
- `POST /call-tool`: 执行具体的工具操作
|
||
|
||
### MCP 协议集成
|
||
|
||
插件遵循 MCP (Model Context Protocol) 标准，使得外部 AI 工具能够理解并调用 Cocos Creator 的功能。
|
||
|
||
### 数据流
|
||
|
||
1. 外部工具发送 MCP 请求到插件的 HTTP 接口
|
||
2. main.js 接收请求并解析参数
|
||
3. 通过 Editor.Scene.callSceneScript 将请求转发给 scene-script.js
|
||
4. scene-script.js 在场景线程中执行具体操作
|
||
5. 将结果返回给外部工具
|
||
|
||
## 开发指南
|
||
|
||
### 添加新功能
|
||
|
||
要在插件中添加新的 MCP 工具，需要：
|
||
|
||
1. 在 main.js 的 `/list-tools` 响应中添加工具定义
|
||
2. 在 handleMcpCall 函数中添加对应的处理逻辑
|
||
3. 如需在场景线程中执行，需要在 scene-script.js 中添加对应函数
|
||
|
||
### 日志管理
|
||
|
||
插件会记录所有操作的日志，包括：
|
||
- 服务启动/停止
|
||
- MCP 请求接收
|
||
- 操作成功/失败状态
|
||
- 错误信息
|
||
|
||
## 注意事项
|
||
|
||
- 插件需要在 Cocos Creator 环境中运行
|
||
- HTTP 服务会占用指定端口，请确保端口未被其他程序占用
|
||
- 插件会自动标记场景为"已修改"，请注意保存场景
|
||
- 不同版本的 Cocos Creator 可能会有 API 差异，请根据实际情况调整
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request 来改进这个插件！
|
||
|
||
## 许可证
|
||
|
||
MIT License |