Cocos Mcp Server

开发 TypeScript

🚀 Cocos Creator MCP Server插件

Cocos Creator MCP Server插件是一款全面的MCP（模型上下文协议）服务器插件，适用于Cocos Creator 3.8+版本。它允许AI助手通过标准化协议与Cocos Creator编辑器进行交互，支持一键安装和使用，无需复杂的环境配置。该插件已在Claude客户端Claude CLI和Cursor上进行了测试，理论上也能完美支持其他编辑器。

🚀 目前提供13大类共151种工具，实现了98%的编辑器控制！（预制体实例化存在已知的子节点恢复问题）

🚀 快速开始

链接导航

📖 完整功能指南（英文） - 所有151个工具的详细文档（待完成）
📖 完整功能指南（中文） - 所有151个工具的详细文档（待完成）

不同客户端配置示例

Claude cli配置

claude mcp add --transport http cocos-creator http://127.0.0.1:3000/mcp (使用您自己配置的端口号)

Claude客户端配置

{
"mcpServers": {
"cocos-creator": {
"type": "http",
"url": "http://127.0.0.1:3000/mcp"
}
}
}

Cursor或VS类MCP配置

{
"mcpServers": {
"cocos-creator": {
"url": "http://localhost:3000/mcp"
}
}
}

✨ 主要特性

🎯 场景操作

获取当前场景信息和完整的场景列表
通过路径打开场景并保存当前场景
创建具有自定义名称的新场景
获取包含组件信息的完整场景层次结构

🎮 节点操作

创建不同类型的节点（Node、2DNode、3DNode）
通过UUID获取节点信息并按名称模式查找节点
设置节点属性（位置、旋转、缩放、激活状态）
删除、移动和复制节点，支持完整的层次结构

🔧 组件操作

从节点添加/移除组件
获取节点的所有组件及其属性
动态设置组件属性
从资源路径附加脚本组件
按类别列出可用的组件类型

📦 预制体操作

列出项目中按文件夹组织的所有预制体
加载、实例化和创建预制体
更新现有预制体并还原预制体实例
获取包括依赖项在内的详细预制体信息
⚠️ 已知问题：由于Cocos Creator API的限制，预制体实例化可能无法正确恢复子节点。

🚀 项目控制

在预览模式下运行项目（浏览器/模拟器）
为不同平台（Web、移动、桌面）构建项目
获取项目信息和设置
刷新资源数据库并导入新资源
获取详细的资源信息

🔍 调试工具

获取经过过滤的编辑器控制台日志
清除控制台并在场景上下文中执行JavaScript
获取用于调试的详细节点树
性能统计和场景验证
获取编辑器和环境信息

⚙️ 附加功能

偏好设置管理：获取/设置编辑器偏好和全局设置
服务器控制：服务器信息、项目详细信息和编辑器控制
消息广播：监听和广播自定义消息
资源管理：创建、复制、移动、删除和查询资源
构建系统：项目构建和预览服务器控制
参考图像管理：在场景视图中添加、移除和管理参考图像
场景视图控制：控制小控件工具、坐标系和视图模式
高级场景操作：撤销/重做、快照和高级节点操作

📦 安装指南

1. 复制插件文件

将整个 cocos-mcp-server 文件夹复制到您的Cocos Creator项目的 extensions 目录中：

YourProject/
├── assets/
├── extensions/
│   └── cocos-mcp-server/          <- 将插件放置在此处
│       ├── source/
│       ├── dist/
│       ├── package.json
│       └── ...
├── settings/
└── ...

2. 安装依赖项

cd extensions/cocos-mcp-server
npm install

3. 构建插件

npm run build

4. 启用插件

重启Cocos Creator或刷新扩展。
插件将出现在扩展菜单中。
点击 扩展 > Cocos MCP Server 打开控制面板。

💻 使用示例

基础用法

创建新的精灵节点

{
"tool": "node_create_node",
"arguments": {
"name": "MySprite",
"nodeType": "2DNode",
"parentUuid": "parent-node-uuid"
}
}

添加精灵组件

{
"tool": "component_add_component",
"arguments": {
"nodeUuid": "node-uuid",
"componentType": "cc.Sprite"
}
}

实例化预制体

{
"tool": "prefab_instantiate_prefab",
"arguments": {
"prefabPath": "db://assets/prefabs/Enemy.prefab",
"position": { "x": 100, "y": 200, "z": 0 }
}
}

⚠️ 重要提示

由于Cocos Creator API的限制，带有子节点的复杂预制体可能无法正确实例化，实例化的预制体中可能会缺少子节点。

在浏览器中运行项目

{
"tool": "project_run_project",
"arguments": {
"platform": "browser"
}
}

📚 详细文档

工具配置

设置存储在 YourProject/settings/mcp-server.json 中：

{
"port": 3000,
"autoStart": false,
"enableDebugLog": true,
"allowedOrigins": ["*"],
"maxConnections": 10
}

图标设置

要为插件面板添加图标：

创建一个PNG图标文件（推荐尺寸：32x32或64x64）。
将其放置在 static/ 目录中：static/icon.png。
图标路径已在 package.json 中配置。

🔧 技术细节

项目结构

cocos-mcp-server/
├── source/                    # TypeScript源文件
│   ├── main.ts               # 插件入口点
│   ├── mcp-server.ts         # MCP服务器实现
│   ├── settings.ts           # 设置管理
│   ├── types/                # TypeScript类型定义
│   ├── tools/                # 工具实现
│   │   ├── scene-tools.ts
│   │   ├── node-tools.ts
│   │   ├── component-tools.ts
│   │   ├── prefab-tools.ts
│   │   ├── project-tools.ts
│   │   ├── debug-tools.ts
│   │   ├── preferences-tools.ts
│   │   ├── server-tools.ts
│   │   ├── broadcast-tools.ts
│   │   ├── scene-advanced-tools.ts
│   │   ├── scene-view-tools.ts
│   │   ├── reference-image-tools.ts
│   │   └── asset-advanced-tools.ts
│   ├── panels/               # UI面板实现
│   └── test/                 # 测试文件
├── dist/                     # 编译后的JavaScript输出
├── static/                   # 静态资产（图标等）
├── i18n/                     # 国际化文件
├── package.json              # 插件配置
└── tsconfig.json             # TypeScript配置

从源代码构建

# 安装依赖项
npm install

# 在开发模式下进行构建并开启监听
npm run watch

# 进行生产环境构建
npm run build

添加新工具

在 source/tools/ 中创建一个新的工具类。
实现 ToolExecutor 接口。
将工具添加到 mcp-server.ts 的初始化中。
工具将通过MCP协议自动公开。

TypeScript支持

该插件完全用TypeScript编写，具有以下特点：

启用严格的类型检查
为所有API提供全面的类型定义
开发时支持智能感知
自动编译为JavaScript

运行测试

# 运行综合测试套件
node comprehensive-test.js

# 运行特定功能测试
./test-all-features.sh

# 运行Node.js测试脚本
node test-mcp-server.js

故障排除

常见问题

服务器无法启动：检查端口可用性和防火墙设置。
工具无法正常工作：确保场景已加载且UUID有效。
构建错误：运行 npm run build 检查TypeScript错误。
连接问题：验证HTTP URL和服务器状态。

调试模式

在插件面板中启用调试日志以获取详细的操作日志。

使用调试工具

{
"tool": "debug_get_console_logs",
"arguments": {"limit": 50, "filter": "error"}
}

{
"tool": "debug_validate_scene",
"arguments": {"checkMissingAssets": true}
}

系统要求

Cocos Creator 3.8.6或更高版本
Node.js（随Cocos Creator捆绑）
TypeScript（作为开发依赖项安装）

架构说明

此插件使用简化的MCP协议实现，与Cocos Creator的CommonJS环境兼容。HTTP服务器为AI助手提供了一个JSON-RPC接口，用于与编辑器进行交互。

协议支持

HTTP连接：http://localhost:3000/mcp（端口可配置）
JSON-RPC 2.0：标准请求/响应格式
工具发现：tools/list 方法返回可用工具
工具执行：tools/call 方法执行特定工具

📄 许可证

本插件用于Cocos Creator项目，源代码未加密且打包在一起，可用于学习和交流。支持您进行二次开发和优化，但本项目的任何代码或其衍生代码不得用于任何商业目的或转售。如需商业使用，请与我联系。

0 条评论
分类：开发