STARWARCLOUD STARWAR.AI
返回市场
<中文翻译> cocos-mcp服务器

<中文翻译> cocos-mcp服务器

作者：DaxianLee275 星标更新：2025-11-19
安装使用来源：spider==github.com

项目介绍

Cocos Creator MCP Server 插件

📖 英文 📖 中文

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

🚀 我们现在提供了50个强大的融合工具，实现了99%的编辑器控制！

视频演示和教学

<img width="503" height="351" alt="image" src="https://gips0.baidu.com/it/u=204984402,2037899201&fm=3081&app=3081&f=PNG?w=2014&h=1406" />

快速链接

更新日志

🚀 主要更新 v1.5.0 (2024年7月29日) （已在cocos商店更新，GitHub版本将在下一个版本同步更新）

cocos商店： https://store.cocos.com/app/detail/7941

  • 工具简化和重构 将原有的150多个工具集中并组织成50个高度可复用和高覆盖率的核心工具，移除所有无效冗余代码，大大提高了易用性和维护性。
  • 统一操作码 所有工具采用“操作码+参数”模式，极大地简化了AI调用过程，提高了AI调用的成功率，减少了AI调用次数，并降低了50%的令牌消耗。
  • 预制体功能全面升级 彻底修复和完善了所有核心的预制体创建、实例化、同步、引用等功能，支持复杂的引用关系，并完全符合官方格式。
  • 事件绑定和旧功能完成 增加并实现了事件绑定、节点/组件/资源等旧功能，所有方法都完全对齐官方实现。
  • 接口优化 所有接口参数更加清晰，文档更完整，AI更容易理解和调用。
  • 插件面板优化 面板UI更加简洁，操作更加直观。
  • 性能和兼容性提升 整体架构更加高效，兼容Cocos Creator 3.8.6及以上版本。

工具系统和操作码

  • 所有工具命名格式为 'Class_operations'，参数使用统一的模式，并支持在多个操作码（动作）之间切换，极大地提高了灵活性和可扩展性。
  • 50个核心工具覆盖了场景、节点、组件、预制体、资源、项目、调试、偏好设置、服务器、消息广播等所有编辑器操作。
  • 工具调用示例：
{
  "tool": "node_lifecycle",
  "arguments": {
    "action": "create",
    "name": "MyNode",
    "parentUuid": "parent-uuid",
    "nodeType": "2DNode"
  }
}

主要功能类别（部分示例）

  • scene_management 场景管理（获取/打开/保存/创建/关闭场景）
  • node_query / node_lifecycle / node_transform 节点查询、创建、删除、属性变更
  • component_manage / component_script / component_query 组件添加和删除、脚本挂载、组件信息
  • prefab_browse / prefab_lifecycle / prefab_instance 预制体浏览、创建、实例化、同步
  • asset_manage / asset_analyze 资源导入、删除、依赖分析
  • project_manage / project_build_system 项目操作、构建和配置信息
  • debug_console / debug_logs 控制台和日志管理
  • preferences_manage 偏好设置
  • server_info 服务器信息
  • broadcast_message 消息广播

V1.4.0-2025年7月26日（当前GitHub版本）

🎯 主要功能修复

  • 彻底修复预制体创建功能 解决了在创建预制体时缺少组件/节点/资源类型引用的问题
  • 正确引用处理 实现了一种完全一致于手动创建预制体的引用格式
    • 内部引用 预制体内的节点和组件引用被正确转换为 {"__id__": x} 格式
    • 外部引用 预制体外的节点和组件引用被正确设置为 null
    • 资源引用 完全保留了预制体、纹理、精灵帧等资源引用的UUID格式
  • 组件/脚本移除API标准化 移除组件/脚本时必须传递组件的cid（类型字段），不能使用脚本名称或类名。AI和用户应首先使用getComponents获取类型字段（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组合API，提高了响应性和性能
  • 更好的错误处理 添加了全面的错误处理，包括失败操作的回滚机制

改进的UI/UX

  • 增强视觉设计，包括适当的分隔符、独特的区块样式和非透明模态背景🐛 错误修复
  • 修复工具状态持久化 解决了切换标签或重新打开面板时工具状态重置的问题
  • 修复配置加载 纠正了服务器设置加载和消息注册的问题
  • 修复复选框交互 解决了复选框取消选中和提高响应性的问题
  • 修复面板滚动 确保工具管理面板的正确滚动功能

修复IPC通信

  • 解决了前端和后端之间的各种IPC通信问题🏗️ 技术改进
  • 简化架构 移除了多个配置的复杂性，专注于单一配置管理
  • 更好的类型安全性 增强了TypeScript类型定义和接口
  • 改善数据同步 前端UI状态和后端工具管理之间的更好同步

提升调试

  • 增加了全面的日志和调试功能📊 统计信息
  • 总工具数 从151个增加到158个工具
  • 类别 13个工具类别，全面覆盖

编辑器控制

  • ：实现98%的编辑器功能覆盖
  • V1.2.0- 早期版本
  • 初始发布，包括151个工具
  • 基础MCP服务器功能

场景、节点、组件和预制体操作

项目控制和调试工具

claude mcp add --transport http cocos-creator http://127.0.0.1:3000/mcp（使用你自己配置的端口号）

快速使用

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

Claude CLI配置：

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

Claude客户端配置：

Cursor或VS类MCP配置

  • 特性🎯 场景操作（scene_ *）
  • scene_management 场景管理 - 获取当前场景，打开/保存/创建/关闭场景，支持场景列表查询
  • scene_hierarchy 场景层次 - 获取完整的场景结构，支持组件信息包括

scene_execution_control

  • 执行控制 - 执行组件方法、场景脚本、预制体同步🎮 节点操作（node_ *）
  • node_query 节点查询 - 按名称/模式搜索节点，获取节点信息，检测2D/3D类型
  • node_lifecycle 节点生命周期 - 创建/删除节点，支持组件预安装和预制体实体实例化
  • node_transform 节点变换 - 修改节点名称、位置、旋转、缩放、可见性等属性
  • node_hierarchy 节点层次 - 移动、复制、粘贴节点，支持层级结构操作
  • node_clipboard 节点剪贴板 - 复制/粘贴/剪切节点操作

node_property_management

  • 属性管理 - 重置节点属性、组件属性、变换属性🔧 组件操作（component_ *）
  • component_manage 组件管理 - 添加/删除引擎组件（cc.Sprite、cc.Button等）
  • component_script 脚本组件 - 挂载/删除自定义脚本组件
  • component_query 组件查询 - 获取组件列表、详细信息和可用组件类型

set_component_property

  • ：属性设置 - 设置单个或多个组件属性值📦 预制体操作（prefaf_ *）
  • prefab_browse 预制体浏览 - 列出预制体单元，查看信息，验证文件
  • prefab_lifecycle 预制体生命周期 - 从节点创建和删除预制体
  • prefab_instance 预制体实例 - 实例化到场景，解除链接，应用更改，恢复原始

prefab_edit

  • 预制体编辑 - 进入/退出编辑模式，保存预制体，测试更改🚀 项目控制（project_ *）
  • project_manage 项目管理 - 运行项目，构建项目，获取项目信息，设置项目

project_build_system

  • 构建系统 - 控制构建面板，检查构建状态，预览服务器管理🔍 调试工具（debug_ *）
  • debug_console 控制台管理 - 获取/清除控制台日志，支持过滤和限制
  • debug_logs 日志分析 - 读取/搜索/分析项目日志文件，支持模式匹配

debug_system

  • 系统调试 - 获取编辑器信息、性能统计和环境信息📁 资源管理（asset_ *）
  • asset_manage 资源管理 - 批量导入/删除资源，保存元数据，生成URL
  • asset_analyze 资源分析 - 获取依赖关系，导出资源清单
  • asset_system 资源系统 - 刷新资源，查询资源数据库状态
  • asset_query 资源查询 - 按类型/文件夹查询资源并获取详细信息

asset_operations

  • 资源操作 - 创建/复制/移动/删除/保存/重新导入资源⚙️ 偏好设置（advantess_ *）
  • preferences_manage 偏好管理 - 获取/设置编辑器偏好

preferences_global

  • 全局设置 - 管理全局配置和系统设置🌐 服务器和广播（Server_ */broadcast_ *）
  • server_info 服务器信息 - 获取服务器状态、项目详情和环境信息

broadcast_message

  • 消息广播 - 监控和广播自定义消息🖼️ 参考图像（referenceImage_ *）
  • reference_image_manage 参考图像管理 - 在场景视图中添加/删除/管理参考图像

reference_image_view

  • 参考图像视图 - 控制参考图像的显示和编辑🎨 场景视图（sceneView_ *）
  • scene_view_control 场景视图控制 - 控制辅助工具、坐标系、视图模式

scene_view_tools

  • 场景视图工具 - 各种管理和场景视图的选项✅ 验证工具（validation_ *）
  • validation_scene 场景验证 - 验证场景的完整性，检查缺失资源

validation_asset

  • 资源验证 - 验证资源引用，检查资源完整性🛠️ 工具管理
  • 工具配置系统 选择性启用/禁用工具体，支持多配置
  • 配置持久化 自动保存和加载工具配置
  • 配置导入和导出 支持工具配置的导入和导出功能

实时状态管理

  • 实时更新和同步工具状态🚀 核心优势
  • 统一操作码 所有工具命名为 "Class_operations" 并具有统一的参数模式
  • 高复用性 50个核心工具覆盖了99%的编辑器功能
  • AI友好 清晰的参数，完整的文档，简单的调用
  • 性能优化 减少50%的令牌消耗，提高AI调用成功率

完全兼容

100%对齐Cocos Creator官方API

安装说明 cocos-mcp-server 1. 复制插件文件 extensions 整个

您的项目/
├── assets/
├── extensions/
│   └── cocos-mcp-server/          <- 将插件放在这里
│       ├── source/
│       ├── dist/
│       ├── package.json
│       └── ...
├── settings/
└── ...

将文件夹复制到您的Cocos Creator项目

cd extensions/cocos-mcp-server
npm install

在目录中，您也可以直接在扩展管理器中导入项目：

npm run build

2. 安装依赖

  1. 3. 构建插件
  2. 4. 启用插件
  3. 重启Cocos Creator或刷新扩展 扩展 > Cocos MCP Server 插件将出现在扩展菜单中

点击

打开控制面板

  1. 使用说明 扩展 > Cocos MCP Server 启动服务器

  2. 从

    • 打开MCP服务器面板 配置设置：
    • 端口 HTTP服务器端口（默认：3000）
    • 自动启动 当编辑器启动时自动启动服务器
    • 调试日志 为了开发和调试目的启用详细日志

  3. 最大连接数

：允许的最大并发连接数

点击“启动服务器”以开始接受连接 http://localhost:3000/mcp 连接AI助手

服务器位于

提供HTTP端点（或您配置的端口）。

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

cocos-mcp-server/
├── source/                    # TypeScript 源文件
│   ├── main.ts               # 插件入口点
│   ├── mcp-server.ts         # MCP 服务器实现
│   ├── settings.ts           # 设置管理
│   ├── types/                # TypeScript 类型定义
│   ├── tools/                # 工具实现
│   │   ├── scene-tools.ts
│   │   ├──