cocos-mcp-server

# Cocos Creator MCP 服务器插件 **[📖 English](README.EN.md)** **[📖 中文](README.md)** 一个适用于 Cocos Creator 3.8+ 的综合性 MCP（模型上下文协议）服务器插件，使 AI 助手能够通过标准化协议与 Cocos Creator 编辑器进行交互。一键安装和使用，省去所有繁琐环境和配置。已经测试过Claude客户端Claude CLI和Cursor，其他的编辑器理论上也完美支持。 **🚀 现在提供 50 个强力融合工具，实现99%的编辑器控制！** ## 视频演示和教学 [<img width="503" height="351" alt="image" src="https://github.com/user-attachments/assets/f186ce14-9ffc-4a29-8761-48bdd7c1ea16" />](https://www.bilibili.com/video/BV1mB8dzfEw8?spm_id_from=333.788.recommend_more_video.0&vd_source=6b1ff659dd5f04a92cc6d14061e8bb92) ##快速链接 - **[📖 Complete Feature Guide (English)](FEATURE_GUIDE_EN.md)** - Detailed documentation for all 158 tools（待补充） - **[📖 完整功能指南 (中文)](FEATURE_GUIDE_CN.md)** - 所有158工具的详细文档（待补充） ## 更新日志 ## 🚀 重大更新 v1.5.0（2024年7月29日）（已经在cocos 商城更新，github版本将在下个版本同步更新） cocos store：https://store.cocos.com/app/detail/7941 - **工具精简与重构**：将原有150+工具浓缩规整为50个高复用、高覆盖率的核心工具，去除所有无效冗余代码，极大提升易用性和可维护性。 - **操作码统一**：所有工具均采用“操作码+参数”模式，极大简化AI调用流程，提升AI调用成功率，减少AI调用次数，降低50% token消耗。 - **预制体功能全面升级**：彻底修复和完善预制体的创建、实例化、同步、引用等所有核心功能，支持复杂引用关系，100%对齐官方格式。 - **事件绑定与老功能补全**：补充并实现了事件绑定、节点/组件/资源等老功能，所有方法与官方实现完全对齐。 - **接口优化**：所有接口参数更清晰，文档更完善，AI更容易理解和调用。 - **插件面板优化**：面板UI更简洁，操作更直观。 - **性能与兼容性提升**：整体架构更高效，兼容Cocos Creator 3.8.6及以上所有版本。 ## 工具体系与操作码 - 所有工具均以“类别_操作”命名，参数采用统一Schema，支持多操作码（action）切换，极大提升灵活性和可扩展性。 - 50个核心工具涵盖场景、节点、组件、预制体、资源、项目、调试、偏好设置、服务器、消息广播等全部编辑器操作。 - 工具调用示例： ```json { "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（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" } } } ``` ## 功能特性 ### 🎯 场景操作 (scene_*) - **scene_management**: 场景管理 - 获取当前场景、打开/保存/创建/关闭场景，支持场景列表查询 - **scene_hierarchy**: 场景层级 - 获取完整场景结构，支持组件信息包含 - **scene_execution_control**: 执行控制 - 执行组件方法、场景脚本、预制体同步 ### 🎮 节点操作 (node_*) - **node_query**: 节点查询 - 按名称/模式查找节点，获取节点信息，检测2D/3D类型 - **node_lifecycle**: 节点生命周期 - 创建