Cocos MCP Server

🚀 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. 启用插件

1. 重启Cocos Creator或刷新扩展。
2. 插件将出现在扩展菜单中。
3. 点击 扩展 > 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
}

图标设置

要为插件面板添加图标：

1. 创建一个PNG图标文件（推荐尺寸：32x32或64x64）。
2. 将其放置在 static/ 目录中：static/icon.png。
3. 图标路径已在 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

添加新工具

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

TypeScript支持

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

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

运行测试

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

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

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

故障排除

常见问题

1. 服务器无法启动：检查端口可用性和防火墙设置。
2. 工具无法正常工作：确保场景已加载且UUID有效。
3. 构建错误：运行 npm run build 检查TypeScript错误。
4. 连接问题：验证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项目，源代码未加密且打包在一起，可用于学习和交流。支持您进行二次开发和优化，但本项目的任何代码或其衍生代码不得用于任何商业目的或转售。如需商业使用，请与我联系。