Files

DaxianLee af7df2cea7 Update README.md

2025-07-28 16:20:37 +08:00

15 KiB

Raw Blame History

Cocos Creator MCP 服务器插件

一个适用于 Cocos Creator 3.8+ 的综合性 MCP（模型上下文协议）服务器插件，使 AI 助手能够通过标准化协议与 Cocos Creator 编辑器进行交互。一键安装和使用，省去所有繁琐环境和配置。已经测试过Claude客户端Claude CLI和Cursor，其他的编辑器理论上也完美支持。

🚀 现在提供 13 个类别的 158 个工具，实现98%的编辑器控制！

视频演示和教学

视频演示配置工具列表

##快速链接

📖 Complete Feature Guide (English) - Detailed documentation for all 158 tools（待补充）
📖 完整功能指南 (中文) - 所有158工具的详细文档（待补充）

更新日志

v1.4.0 - 2025年7月26日（已经在cocos 商城更新，github版本将在近期同步）

cocos store：https://store.cocos.com/app/detail/7941 如果不愿意购买，加入沟通群我也可以直接发送最新版给你！

🎯 重大功能修复

完全修复预制体创建功能: 彻底解决了预制体创建时组件/节点/资源类型引用丢失的问题
正确的引用处理: 实现了与手动创建预制体完全一致的引用格式
- 内部引用: 预制体内部的节点和组件引用正确转换为 {"__id__": x} 格式
- 外部引用: 预制体外部的节点和组件引用正确设置为 null
- 资源引用: 预制体、纹理、精灵帧等资源引用完整保留UUID格式
组件/脚本移除API规范化: 现在移除组件/脚本时，必须传入组件的cid（type字段），不能用脚本名或类名。AI和用户应先用getComponents获取type字段（cid），再传给removeComponent。这样能100%准确移除所有类型组件和脚本，兼容所有Cocos Creator版本。

🔧 核心改进

索引顺序优化: 调整预制体对象创建顺序，确保与Cocos Creator标准格式一致
组件类型支持: 扩展组件引用检测，支持所有cc.开头的组件类型（Label、Button、Sprite等）
UUID映射机制: 完善内部UUID到索引的映射系统，确保引用关系正确建立
属性格式标准化: 修复组件属性顺序和格式，消除引擎解析错误

🐛 错误修复

修复预制体导入错误: 解决 Cannot read properties of undefined (reading '_name') 错误
修复引擎兼容性: 解决 placeHolder.initDefault is not a function 错误
修复属性覆盖: 防止 _objFlags 等关键属性被组件数据覆盖
修复引用丢失: 确保所有类型的引用都能正确保存和加载

📈 功能增强

完整组件属性保留: 包括私有属性（如_group、_density等）在内的所有组件属性
子节点结构支持: 正确处理预制体的层级结构和子节点关系
变换属性处理: 保留节点的位置、旋转、缩放和层级信息
调试信息优化: 添加详细的引用处理日志，便于问题追踪

💡 技术突破

引用类型识别: 智能区分内部引用和外部引用，避免无效引用
格式兼容性: 生成的预制体与手动创建的预制体格式100%兼容
引擎集成: 预制体可以正常挂载到场景中，无任何运行时错误
性能优化: 优化预制体创建流程，提高大型预制体的处理效率

🎉 现在预制体创建功能已完全可用，支持复杂的组件引用关系和完整的预制体结构！

v1.3.0 - 2024年7月25日

🆕 新功能

集成工具管理面板: 在主控制面板中直接添加了全面的工具管理功能
工具配置系统: 实现了选择性工具启用/禁用，支持持久化配置
动态工具加载: 增强了工具发现功能，能够动态加载MCP服务器中的所有158个可用工具
实时工具状态管理: 添加了工具计数和状态的实时更新，当单个工具切换时立即反映
配置持久化: 在编辑器会话间自动保存和加载工具配置

🔧 改进

统一面板界面: 将工具管理合并到主MCP服务器面板作为标签页，消除了对单独面板的需求
增强服务器设置: 改进了服务器配置管理，具有更好的持久化和加载功能
Vue 3集成: 升级到Vue 3 Composition API，提供更好的响应性和性能
更好的错误处理: 添加了全面的错误处理，包含失败操作的回滚机制
改进的UI/UX: 增强了视觉设计，包含适当的分隔符、独特的块样式和非透明模态背景

🐛 错误修复

修复工具状态持久化: 解决了工具状态在标签页切换或面板重新打开时重置的问题
修复配置加载: 纠正了服务器设置加载问题和消息注册问题
修复复选框交互: 解决了复选框取消选中问题并改进了响应性
修复面板滚动: 确保工具管理面板中的正确滚动功能
修复IPC通信: 解决了前端和后端之间的各种IPC通信问题

🏗️ 技术改进

简化架构: 移除了多配置复杂性，专注于单一配置管理
更好的类型安全: 增强了TypeScript类型定义和接口
改进数据同步: 前端UI状态和后端工具管理器之间更好的同步
增强调试: 添加了全面的日志记录和调试功能

📊 统计信息

总工具数: 从151个增加到158个工具
类别: 13个工具类别，全面覆盖
编辑器控制: 实现98%的编辑器功能覆盖

v1.2.0 - 之前版本

初始发布，包含151个工具
基本MCP服务器功能
场景、节点、组件和预制体操作
项目控制和调试工具

快速使用

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 获取节点信息，按名称模式查找节点
设置节点属性（位置、旋转、缩放、激活状态）
删除、移动和复制节点，完整支持层级结构

🔧 组件操作

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

📦 预制体操作

列出项目中的所有预制体，支持文件夹组织
加载、实例化和创建预制体
更新现有预制体并还原预制体实例
获取详细的预制体信息，包括依赖关系

🚀 项目控制

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

🔍 调试工具

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

⚙️ 其他功能

偏好设置管理: 获取/设置编辑器偏好和全局设置
服务器控制: 服务器信息、项目详情和编辑器控制
消息广播: 监听和广播自定义消息
资源管理: 创建、复制、移动、删除和查询资源
构建系统: 项目构建和预览服务器控制
参考图片管理: 在场景视图中添加、删除和管理参考图片
场景视图控制: 控制Gizmo工具、坐标系和视图模式
高级场景操作: 撤销/重做、快照和高级节点操作
🆕 工具管理: 选择性启用/禁用工具、保存配置和管理工具状态

安装说明

1. 复制插件文件

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

您的项目/
├── 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 打开控制面板

使用方法

启动服务器

从 扩展 > Cocos MCP Server 打开 MCP 服务器面板
配置设置：
- 端口: HTTP 服务器端口（默认：3000）
- 自动启动: 编辑器启动时自动启动服务器
- 调试日志: 启用详细日志以便开发调试
- 最大连接数: 允许的最大并发连接数
点击"启动服务器"开始接受连接

连接 AI 助手

服务器在 http://localhost:3000/mcp（或您配置的端口）上提供 HTTP 端点。

AI 助手可以使用 MCP 协议连接并访问所有可用工具。

工具分类

工具按类别组织，命名约定为：category_toolname

scene_*: 场景相关操作 (8个工具)
node_*: 节点操作 (9个工具)
component_*: 组件管理 (7个工具)
prefab_*: 预制体操作 (11个工具)
project_*: 项目控制 (22个工具)
debug_*: 调试工具 (10个工具)
preferences_*: 编辑器偏好设置 (7个工具)
server_*: 服务器信息 (6个工具)
broadcast_*: 消息广播 (5个工具)
assetAdvanced_*: 高级资源操作 (10个工具)
referenceImage_*: 参考图片管理 (12个工具)
sceneAdvanced_*: 高级场景操作 (23个工具)
sceneView_*: 场景视图控制 (14个工具)

📖 查看完整工具文档 了解详细的使用示例和参数。

工具使用示例

创建新的精灵节点

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

添加 Sprite 组件

{
  "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 }
  }
}

在浏览器中运行项目

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

配置

设置存储在 您的项目/settings/mcp-server.json 中：

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

工具配置存储在 您的项目/settings/tool-manager.json 中：

{
  "currentConfigId": "default",
  "configurations": {
    "default": {
      "id": "default",
      "name": "默认配置",
      "description": "默认工具配置",
      "tools": [
        {
          "category": "scene",
          "name": "get_current_scene",
          "enabled": true,
          "description": "获取当前场景信息"
        }
      ]
    }
  }
}

图标设置

为插件面板添加图标：

创建 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 提供全面的类型定义
开发时的 IntelliSense 支持
自动编译为 JavaScript

故障排除

常见问题

服务器无法启动: 检查端口可用性和防火墙设置
工具不工作: 确保场景已加载且 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（作为开发依赖安装）

许可证

本插件供 Cocos Creator 项目使用,并且源代码一并打包，可以用于学习和交流。没有加密。可以支持你自己二次开发优化，任何本项目代码或者衍生代码均不能用于任何商用、转售，如果需要商用，请联系本人。

15 KiB Raw Blame History Unescape Escape

Cocos Creator MCP 服务器插件

视频演示和教学

视频演示配置工具列表

更新日志

v1.4.0 - 2025年7月26日 （已经在cocos 商城更新，github版本将在近期同步）

🎯 重大功能修复

🔧 核心改进

🐛 错误修复

📈 功能增强

💡 技术突破

v1.3.0 - 2024年7月25日

🆕 新功能

🔧 改进

🐛 错误修复

🏗️ 技术改进

📊 统计信息

v1.2.0 - 之前版本

快速使用

功能特性

🎯 场景操作

🎮 节点操作

🔧 组件操作

📦 预制体操作

🚀 项目控制

🔍 调试工具

⚙️ 其他功能

安装说明

1. 复制插件文件

2. 安装依赖

3. 构建插件

4. 启用插件

使用方法

启动服务器

连接 AI 助手

工具分类

工具使用示例

创建新的精灵节点

添加 Sprite 组件

实例化预制体

在浏览器中运行项目

配置

图标设置

开发

项目结构

从源码构建

添加新工具

TypeScript 支持

故障排除

常见问题

调试模式

使用调试工具

系统要求

许可证

联系我加入群

15 KiB

Raw Blame History

v1.4.0 - 2025年7月26日（已经在cocos 商城更新，github版本将在近期同步）