Skip to content
Back to search

cocos-mcp-server

一款全面的、便捷的cocos creator AI MCP服务插件,适用于3.8.0以上cocos版本,一键安装,一键启动。A comprehensive and convenient cocos creator AI MCP service plug-in, suitable for cocos versions above 3.8.0, one-click installation and one-click start.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/daxianlee--cocos-mcp-server/badge.svg)](/listings/daxianlee--cocos-mcp-server)

HTML

<a href="/listings/daxianlee--cocos-mcp-server"><img src="/api/listings/daxianlee--cocos-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 525 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Cocos Creator MCP 服务器插件
  2. 🌐 **简体中文** · [English](README.EN.md) · [繁體中文](README.zh-TW.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Español](README.es.md) · [Português](README.pt.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Русский](README.ru.md) · [Tiếng Việt](README.vi.md)
  3. 一个适用于 Cocos Creator 3.8+ 的综合性 MCP(模型上下文协议)服务器插件,使 AI 助手能够通过标准化协议与 Cocos Creator 编辑器进行交互。一键安装和使用,省去所有繁琐环境和配置。已经测试过Claude客户端Claude CLI和Cursor,其他的编辑器理论上也完美支持。
  4. **🚀 现在提供 50 个强力融合工具,实现99%的编辑器控制!**
  5. ## PRO版本已经更新到了1.7.8
  6. | 类型 | 链接 |
  7. |------|------|
  8. | **视频预览** | [Bilibili 视频](https://www.bilibili.com/video/BV1rTAXzuEH3/) |
  9. | **免费体验** | [vberai cocos creator 3.x版本 mcp Pro 体验地址](https://www.vberai.com/game-engines/cocos) |
  10. | **免费体验** | [vberai cocos creator 2.x版本 mcp Pro 体验地址](https://www.vberai.com/game-engines/cocos2x) |
  11. | **AI 设计画布** | [VberAI Studio —— 全球首个游戏 AI 原生设计平台](https://studio.vberai.com) |
  12. | **官网** | [VberAI 官网 vberai.com](https://www.vberai.com) |
  13. ## Cocos MCP 3.x Pro 版本特性
  14. > 🚀 Pro 版由 **VberAI** 打造并持续维护 —— [立即体验 Pro 版](https://www.vberai.com/game-engines/cocos) | [观看视频演示](https://www.bilibili.com/video/BV1rTAXzuEH3/)
  15. 专为 **Cocos Creator 3.8.6+** 打造的专业级 MCP(模型上下文协议)插件,让 AI 助手通过标准化协议直接操控编辑器。**16 个意图级工具**覆盖 **231 项操作**,横跨 **12 大能力模块**,贯穿 Cocos Creator 3.x 开发全流程。采用 **Streamable HTTP** 协议,配合 Token 优化设计,更省 Token、调用更稳定,支持一键配置主流 AI 客户端(Cursor、Claude、Windsurf 等)。
  16. | 意图级工具 | 覆盖操作 | 覆盖模块 | 通信协议 |
  17. |:---:|:---:|:---:|:---:|
  18. | **16** | **231** | **12 大模块** | **Streamable HTTP** |
  19. ### 十二大能力模块
  20. | 模块 | 操作数 | 说明 |
  21. | ------------- | -----: | ------------------------------------------------------------ |
  22. | 场景管理 | 24 | 场景的打开、保存、创建与切换,层级查询与快照,支持撤销操作和脚本执行。 |
  23. | 节点操作 | 18 | 节点的完整 CRUD,支持批量修改、脚本挂载、节点类型检测和剪贴板操作。 |
  24. | 组件系统 | 8 | 组件的增删查改和属性设置,支持点击事件绑定和批量事件配置。 |
  25. | 预制体系统 | 13 | 预制体的创建、实例化、编辑模式切换,支持应用/还原变更和预制体验证。 |
  26. | 资源管理 | 19 | 资源的查询、搜索、CRUD 与导入,支持依赖分析、UUID 与路径转换。 |
  27. | 编辑器控制 | 33 | 工程设置、日志、偏好、构建与预览等编辑器级操作。 |
  28. | 场景视图 | 32 | Gizmo、相机、网格与参考图,提供视口上下文与边界感知控制。 |
  29. | UI 与模板构建 | 13 | 一键创建 UI 组件,JSON 树构建完整节点层级,内置多种 UI 模板。 |
  30. | 动画系统 | 39 | 关键帧编辑、曲线调整、动画事件、预设应用,及 Spine 骨骼动画管理。 |
  31. | 知识库查询 | 8 | 内置组件属性、UI 设计规则、布局模式和最佳实践知识库,AI 精准辅助开发。 |
  32. | 验证与快照 | 6 | 场景布局检查、资源引用验证、层级分析,配合场景快照回归校验。 |
  33. | 字体与 Label | 9 | 字体资源管理与富文本 Label 操作,覆盖文字排版设置。 |
  34. #### 智能特性
  35. - **智能路径解析** — 所有节点参数接受 UUID、路径(如 `Canvas/Panel/Button`)或名称,自动解析
  36. - **UI 自动检测** — 在 UI 父节点下创建节点时自动添加 `cc.UITransform`
  37. - **视口上下文** — 创建/修改节点时返回设计分辨率、可见范围,越界自动警告
  38. - **内置知识库** — AI 可查询组件属性表、坐标系规则、布局模式等知识
  39. - **场景构建器** — 用 JSON 描述完整 UI 层级,一次调用构建出来,自动处理 Canvas/Camera/组件配置
  40. - **参考图片系统** — 在场景视图叠加 UI 设计稿,AI 看着设计图搭界面
  41. - **节点树缓存** — 2 秒 TTL 缓存避免重复查询,变更操作后自动失效
  42. - **原子化操作** — builder/composite 使用 snapshot 机制,失败时自动回滚
  43. ### Pro 版 vs 开源版
  44. | 功能 | 开源版 | Pro 版 |
  45. |------|:---:|:---:|
  46. | 通信协议 | HTTP 协议 | **Streamable HTTP** |
  47. | Token 优化 | 基础设计 | 优化设计,更省 Token 更稳定 |
  48. | 操作码方法 | ✕ | ✅ |
  49. | 一键配置 | ✕ | ✅ |
  50. | 工具自定义 | ✕ | ✅ |
  51. | 意图级工具 | 基础工具 | 16 种,覆盖 231 项操作 |
  52. | 一次性创建场景 | ✕ | ✅ |
  53. | 内置知识库 | ✕ | ✅ |
  54. | 动画 / Spine 系统 | ✕ | ✅ 39 项动画操作 |
  55. ---
  56. ## 🌐 关于 VberAI —— AI 原生游戏生产力平台
  57. **VberAI** 是面向游戏开发者、美术团队与内容团队的 **AI 原生游戏生产力平台**,也是本 Cocos MCP 插件 Pro 版的开发与维护方。VberAI 是目前**唯一同时为 Unity、Godot、Cocos Creator 三大主流引擎提供 MCP 插件**的厂商,围绕「让 AI 真正融入游戏生产管线」打造三条产品线:
  58. - **🎮 游戏引擎 MCP 插件** —— 在引擎编辑器内运行 MCP 服务,让 Claude Desktop、Claude Code、Cursor、Windsurf、Cline 等 AI 客户端直接读取并操作场景、组件、资源、动画与脚本。
  59. - **🎨 AI Studio** —— AI 原生游戏设计画布,一端导入 PSD / Figma / 引擎项目,另一端导出 Unity / Cocos / Godot 场景与预制体。
  60. - **✂️ AI 超强抠图(AI Super Matting)** —— 浏览器端一键抠图,发丝级精度 + 真实 Alpha 通道输出,按量计费。
  61. ### 引擎 MCP 插件家族
  62. | 插件 | 说明 |
  63. |------|------|
  64. | **Unity MCP** | 企业级 MCP 插件,覆盖场景 / GameObject / 组件 / 预制体 / 材质 / 动画 / Shader,支持 Unity 2022.3+ 与 Unity 6 |
  65. | **Cocos MCP 3.x Pro** | 本项目 Pro 版,16 个意图级工具 / 231 项操作,Cocos Creator 3.8.6+,Streamable HTTP |
  66. | **Cocos MCP 2.x Pro** | 面向 Cocos Creator 2.4.x+ 老项目(仍在运营的 2.x 线上项目)量身打造 |
  67. | **Godot MCP** | 完全免费、MIT 开源,100+ 工具命令覆盖 21 个系统,Godot 4.x,兼容 GDScript 与 C# |
  68. ---
  69. ## 🎨 VberAI Studio —— 全球首个游戏 AI 原生设计平台
  70. > **为游戏而生的 AI 原生设计平台。** 从底层开始兼容 Unity、Cocos、Godot 引擎,超多高频 AI 工具与自动化流程,让美术生成、一键换皮、资产管理、设计稿到引擎一体化交付,再加上引擎反向回流,彻底打通「AI 设计 → 游戏引擎 AI」全开发链路。
  71. >
  72. > 👉 **[立即进入 AI Studio](https://studio.vberai.com)** | [了解更多](https://www.vberai.com/studio)
  73. ### 完整生产链路
  74. **导入设计与项目资产 → AI 高频生成与编辑 → 组件化引擎交付 → 通过 Engine MCP 实时同步到引擎 → 引擎反向回流**
  75. 配合本 Cocos MCP 插件,AI Studio 把场景、预制体、组件与美术资源回写到工程后,Engine MCP 让 AI 在 Cocos Creator 中继续完成脚本、组件配置、资源管理与调试,形成端到端的开发闭环 —— 大幅提升团队效率,甚至让一个人就是一支队伍。
  76. **🔗 相关链接**:[VberAI 官网](https://www.vberai.com) | [AI Studio](https://studio.vberai.com) | [AI 超强抠图](https://www.vberai.com/ai-studio/bg-removal) | [平台定价](https://www.vberai.com/pricing) | 联系支持:support@vberai.com
  77. ---
  78. ## 开源版本更新日志
  79. ## 🚀 重大更新 v1.5.4
  80. ## 当前开源本视频演示
  81. [<img width="503" height="351" alt="视频演示" 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)
  82. - **工具精简与重构**:将原有150+工具浓缩规整为50个高复用、高覆盖率的核心工具,去除所有无效冗余代码,极大提升易用性和可维护性。
  83. - **操作码统一**:所有工具均采用“操作码+参数”模式,极大简化AI调用流程,提升AI调用成功率,减少AI调用次数,降低50% token消耗。
  84. - **预制体功能全面升级**:彻底修复和完善预制体的创建、实例化、同步、引用等所有核心功能,支持复杂引用关系,100%对齐官方格式。
  85. - **事件绑定与老功能补全**:补充并实现了事件绑定、节点/组件/资源等老功能,所有方法与官方实现完全对齐。
  86. - **接口优化**:所有接口参数更清晰,文档更完善,AI更容易理解和调用。
  87. - **插件面板优化**:面板UI更简洁,操作更直观。
  88. - **性能与兼容性提升**:整体架构更高效,兼容Cocos Creator 3.8.6及以上所有版本。
  89. ## 工具体系与操作码
  90. - 所有工具均以“类别_操作”命名,参数采用统一Schema,支持多操作码(action)切换,极大提升灵活性和可扩展性。
  91. - 50个核心工具涵盖场景、节点、组件、预制体、资源、项目、调试、偏好设置、服务器、消息广播等全部编辑器操作。
  92. - 工具调用示例:
  93. ```json
  94. {
  95. "tool": "node_lifecycle",
  96. "arguments": {
  97. "action": "create",
  98. "name": "MyNode",
  99. "parentUuid": "parent-uuid",
  100. "nodeType": "2DNode"
  101. }
  102. }
  103. ```
  104. ---
  105. ## 主要功能类别(部分示例)
  106. - **scene_management**:场景管理(获取/打开/保存/新建/关闭场景)
  107. - **node_query / node_lifecycle / node_transform**:节点查询、创建、删除、属性变更
  108. - **component_manage / component_script / component_query**:组件增删、脚本挂载、组件信息
  109. - **prefab_browse / prefab_lifecycle / prefab_instance**:预制体浏览、创建、实例化、同步
  110. - **asset_manage / asset_analyze**:资源导入、删除、依赖分析
  111. - **project_manage / project_build_system**:项目运行、构建、配置信息
  112. - **debug_console / debug_logs**:控制台与日志管理
  113. - **preferences_manage**:偏好设置
  114. - **server_info**:服务器信息
  115. - **broadcast_message**:消息广播
  116. ### v1.4.0 - 2025年7月26日
  117. #### 🎯 重大功能修复
  118. - **完全修复预制体创建功能**: 彻底解决了预制体创建时组件/节点/资源类型引用丢失的问题
  119. - **正确的引用处理**: 实现了与手动创建预制体完全一致的引用格式
  120. - **内部引用**: 预制体内部的节点和组件引用正确转换为 `{"__id__": x}` 格式
  121. - **外部引用**: 预制体外部的节点和组件引用正确设置为 `null`
  122. - **资源引用**: 预制体、纹理、精灵帧等资源引用完整保留UUID格式
  123. - **组件/脚本移除API规范化**: 现在移除组件/脚本时,必须传入组件的cid(type字段),不能用脚本名或类名。AI和用户应先用getComponents获取type字段(cid),再传给removeComponent。这样能100%准确移除所有类型组件和脚本,兼容所有Cocos Creator版本。
  124. #### 🔧 核心改进
  125. - **索引顺序优化**: 调整预制体对象创建顺序,确保与Cocos Creator标准格式一致
  126. - **组件类型支持**: 扩展组件引用检测,支持所有cc.开头的组件类型(Label、Button、Sprite等)
  127. - **UUID映射机制**: 完善内部UUID到索引的映射系统,确保引用关系正确建立
  128. - **属性格式标准化**: 修复组件属性顺序和格式,消除引擎解析错误
  129. #### 🐛 错误修复
  130. - **修复预制体导入错误**: 解决 `Cannot read properties of undefined (reading '_name')` 错误
  131. - **修复引擎兼容性**: 解决 `placeHolder.initDefault is not a function` 错误
  132. - **修复属性覆盖**: 防止 `_objFlags` 等关键属性被组件数据覆盖
  133. - **修复引用丢失**: 确保所有类型的引用都能正确保存和加载
  134. #### 📈 功能增强
  135. - **完整组件属性保留**: 包括私有属性(如_group、_density等)在内的所有组件属性
  136. - **子节点结构支持**: 正确处理预制体的层级结构和子节点关系
  137. - **变换属性处理**: 保留节点的位置、旋转、缩放和层级信息
  138. - **调试信息优化**: 添加详细的引用处理日志,便于问题追踪
  139. #### 💡 技术突破
  140. - **引用类型识别**: 智能区分内部引用和外部引用,避免无效引用
  141. - **格式兼容性**: 生成的预制体与手动创建的预制体格式100%兼容
  142. - **引擎集成**: 预制体可以正常挂载到场景中,无任何运行时错误
  143. - **性能优化**: 优化预制体创建流程,提高大型预制体的处理效率
  144. **🎉 现在预制体创建功能已完全可用,支持复杂的组件引用关系和完整的预制体结构!**
  145. ### v1.3.0 - 2024年7月25日
  146. #### 🆕 新功能
  147. - **集成工具管理面板**: 在主控制面板中直接添加了全面的工具管理功能
  148. - **工具配置系统**: 实现了选择性工具启用/禁用,支持持久化配置
  149. - **动态工具加载**: 增强了工具发现功能,能够动态加载MCP服务器中的所有158个可用工具
  150. - **实时工具状态管理**: 添加了工具计数和状态的实时更新,当单个工具切换时立即反映
  151. - **配置持久化**: 在编辑器会话间自动保存和加载工具配置
  152. #### 🔧 改进
  153. - **统一面板界面**: 将工具管理合并到主MCP服务器面板作为标签页,消除了对单独面板的需求
  154. - **增强服务器设置**: 改进了服务器配置管理,具有更好的持久化和加载功能
  155. - **Vue 3集成**: 升级到Vue 3 Composition API,提供更好的响应性和性能
  156. - **更好的错误处理**: 添加了全面的错误处理,包含失败操作的回滚机制
  157. - **改进的UI/UX**: 增强了视觉设计,包含适当的分隔符、独特的块样式和非透明模态背景
  158. #### 🐛 错误修复
  159. - **修复工具状态持久化**: 解决了工具状态在标签页切换或面板重新打开时重置的问题
  160. - **修复配置加载**: 纠正了服务器设置加载问题和消息注册问题
  161. - **修复复选框交互**: 解决了复选框取消选中问题并改进了响应性
  162. - **修复面板滚动**: 确保工具管理面板中的正确滚动功能
  163. - **修复IPC通信**: 解决了前端和后端之间的各种IPC通信问题
  164. #### 🏗️ 技术改进
  165. - **简化架构**: 移除了多配置复杂性,专注于单一配置管理
  166. - **更好的类型安全**: 增强了TypeScript类型定义和接口
  167. - **改进数据同步**: 前端UI状态和后端工具管理器之间更好的同步
  168. - **增强调试**: 添加了全面的日志记录和调试功能
  169. #### 📊 统计信息
  170. - **总工具数**: 从151个增加到158个工具
  171. - **类别**: 13个工具类别,全面覆盖
  172. - **编辑器控制**: 实现98%的编辑器功能覆盖
  173. ### v1.2.0 - 之前版本
  174. - 初始发布,包含151个工具
  175. - 基本MCP服务器功能
  176. - 场景、节点、组件和预制体操作
  177. - 项目控制和调试工具
  178. ## 快速使用
  179. **Claude cli配置:**
  180. ```
  181. claude mcp add --transport http cocos-creator http://127.0.0.1:3000/mcp(使用你自己配置的端口号)
  182. ```
  183. **Claude客户端配置:**
  184. ```
  185. {
  186. "mcpServers": {
  187. "cocos-creator": {
  188. "type": "http",
  189. "url": "http://127.0.0.1:3000/mcp"
  190. }
  191. }
  192. }
  193. ```
  194. **Cursor或VS类MCP配置**
  195. ```
  196. {
  197. "mcpServers": {
  198. "cocos-creator": {
  199. "url": "http://localhost:3000/mcp"
  200. }
  201. }
  202. }
  203. ```
  204. ## 功能特性
  205. ### 🎯 场景操作 (scene_*)
  206. - **scene_management**: 场景管理 - 获取当前场景、打开/保存/创建/关闭场景,支持场景列表查询
  207. - **scene_hierarchy**: 场景层级 - 获取完整场景结构,支持组件信息包含
  208. - **scene_execution_control**: 执行控制 - 执行组件方法、场景脚本、预制体同步
  209. ### 🎮 节点操作 (node_*)
  210. - **node_query**: 节点查询 - 按名称/模式查找节点,获取节点信息,检测2D/3D类型
  211. - **node_lifecycle**: 节点生命周期 - 创建/删除节点,支持组件预装、预制体实例化
  212. - **node_transform**: 节点变换 - 修改节点名称、位置、旋转、缩放、可见性等属性
  213. - **node_hierarchy**: 节点层级 - 移动、复制、粘贴节点,支持层级结构操作
  214. - **node_clipboard**: 节点剪贴板 - 复制/粘贴/剪切节点操作
  215. - **node_property_management**: 属性管理 - 重置节点属性、组件属性、变换属性
  216. ### 🔧 组件操作 (component_*)
  217. - **component_manage**: 组件管理 - 添加/删除引擎组件(cc.Sprite、cc.Button等)
  218. - **component_script**: 脚本组件 - 挂载/移除自定义脚本组件
  219. - **component_query**: 组件查询 - 获取组件列表、详细信息、可用组件类型
  220. - **set_component_property**: 属性设置 - 设置单个或多个组件属性值
  221. ### 📦 预制体操作 (prefab_*)
  222. - **prefab_browse**: 预制体浏览 - 列出预制体、查看信息、验证文件
  223. - **prefab_lifecycle**: 预制体生命周期 - 从节点创建预制体、删除预制体
  224. - **prefab_instance**: 预制体实例 - 实例化到场景、解除链接、应用更改、还原原始
  225. - **prefab_edit**: 预制体编辑 - 进入/退出编辑模式、保存预制体、测试更改
  226. ### 🚀 项目控制 (project_*)
  227. - **project_manage**: 项目管理 - 运行项目、构建项目、获取项目信息和设置
  228. - **project_build_system**: 构建系统 - 控制构建面板、检查构建状态、预览服务器管理
  229. ### 🔍 调试工具 (debug_*)
  230. - **debug_console**: 控制台管理 - 获取/清空控制台日志,支持过滤和限制
  231. - **debug_logs**: 日志分析 - 读取/搜索/分析项目日志文件,支持模式匹配
  232. - **debug_system**: 系统调试 - 获取编辑器信息、性能统计、环境信息
  233. ### 📁 资源管理 (asset_*)
  234. - **asset_manage**: 资源管理 - 批量导入/删除资源、保存元数据、生成URL
  235. - **asset_analyze**: 资源分析 - 获取依赖关系、导出资源清单
  236. - **asset_system**: 资源系统 - 刷新资源、查询资源数据库状态
  237. - **asset_query**: 资源查询 - 按类型/文件夹查询资源、获取详细信息
  238. - **asset_operations**: 资源操作 - 创建/复制/移动/删除/保存/重新导入资源
  239. ### ⚙️ 偏好设置 (preferences_*)
  240. - **preferences_manage**: 偏好管理 - 获取/设置编辑器偏好设置
  241. - **preferences_global**: 全局设置 - 管理全局配置和系统设置
  242. ### 🌐 服务器与广播 (server_* / broadcast_*)
  243. - **server_info**: 服务器信息 - 获取服务器状态、项目详情、环境信息
  244. - **broadcast_message**: 消息广播 - 监听和广播自定义消息
  245. ### 🖼️ 参考图片 (referenceImage_*)
  246. - **reference_image_manage**: 参考图片管理 - 添加/删除/管理场景视图中的参考图片
  247. - **reference_image_view**: 参考图片视图 - 控制参考图片的显示和编辑
  248. ### 🎨 场景视图 (sceneView_*)
  249. - **scene_view_control**: 场景视图控制 - 控制Gizmo工具、坐标系、视图模式
  250. - **scene_view_tools**: 场景视图工具 - 管理场景视图的各种工具和选项
  251. ### ✅ 验证工具 (validation_*)
  252. - **validation_scene**: 场景验证 - 验证场景完整性、检查缺失资源
  253. - **validation_asset**: 资源验证 - 验证资源引用、检查资源完整性
  254. ### 🛠️ 工具管理
  255. - **工具配置系统**: 选择性启用/禁用工具,支持多套配置
  256. - **配置持久化**: 自动保存和加载工具配置
  257. - **配置导入导出**: 支持工具配置的导入导出功能
  258. - **实时状态管理**: 工具状态实时更新和同步
  259. ### 🚀 核心优势
  260. - **操作码统一**: 所有工具采用"类别_操作"命名,参数Schema统一
  261. - **高复用性**: 50个核心工具覆盖99%编辑器功能
  262. - **AI友好**: 参数清晰、文档完善、调用简单
  263. - **性能优化**: 降低50% token消耗,提升AI调用成功率
  264. - **完全兼容**: 与Cocos Creator官方API 100%对齐
  265. ## ⚠️ 安装前必读(重要)
  266. > **首次安装或升级前,请务必删除当前项目 `settings/` 目录下的 `mcp-server.json` 和 `tool-manager.json` 两个文件,否则插件的工具列表显示会出现异常!**
  267. >
  268. > 文件路径:`你的项目/settings/mcp-server.json` 与 `你的项目/settings/tool-manager.json`
  269. > 删除这两个文件后,重新打开插件面板即可恢复正常。
  270. ## 安装说明
  271. ### 1. 复制插件文件
  272. 将整个 `cocos-mcp-server` 文件夹复制到您的 Cocos Creator 项目的 `extensions` 目录中,您也可以直接在扩展管理器中导入项目:
  273. ```
  274. 您的项目/
  275. ├── assets/
  276. ├── extensions/
  277. │ └── cocos-mcp-server/ <- 将插件放在这里
  278. │ ├── source/
  279. │ ├── dist/
  280. │ ├── package.json
  281. │ └── ...
  282. ├── settings/
  283. └── ...
  284. ```
  285. ### 2. 安装依赖
  286. ```bash
  287. cd extensions/cocos-mcp-server
  288. npm install
  289. ```
  290. ### 3. 构建插件
  291. ```bash
  292. npm run build
  293. ```
  294. ### 4. 启用插件
  295. 1. 重启 Cocos Creator 或刷新扩展
  296. 2. 插件将出现在扩展菜单中
  297. 3. 点击 `扩展 > Cocos MCP Server` 打开控制面板
  298. ## 使用方法
  299. ### 启动服务器
  300. 1. 从 `扩展 > Cocos MCP Server` 打开 MCP 服务器面板
  301. 2. 配置设置:
  302. - **端口**: HTTP 服务器端口(默认:3000)
  303. - **自动启动**: 编辑器启动时自动启动服务器
  304. - **调试日志**: 启用详细日志以便开发调试
  305. - **最大连接数**: 允许的最大并发连接数
  306. 3. 点击"启动服务器"开始接受连接
  307. ### 连接 AI 助手
  308. 服务器在 `http://localhost:3000/mcp`(或您配置的端口)上提供 HTTP 端点。
  309. AI 助手可以使用 MCP 协议连接并访问所有可用工具。
  310. ## 开发
  311. ### 项目结构
  312. ```
  313. cocos-mcp-server/
  314. ├── source/ # TypeScript 源文件
  315. │ ├── main.ts # 插件入口点
  316. │ ├── mcp-server.ts # MCP 服务器实现
  317. │ ├── settings.ts # 设置管理
  318. │ ├── types/ # TypeScript 类型定义
  319. │ ├── tools/ # 工具实现
  320. │ │ ├── scene-tools.ts
  321. │ │ ├── node-tools.ts
  322. │ │ ├── component-tools.ts
  323. │ │ ├── prefab-tools.ts
  324. │ │ ├── project-tools.ts
  325. │ │ ├── debug-tools.ts
  326. │ │ ├── preferences-tools.ts
  327. │ │ ├── server-tools.ts
  328. │ │ ├── broadcast-tools.ts
  329. │ │ ├── scene-advanced-tools.ts (已整合到 node-tools.ts 和 scene-tools.ts)
  330. │ │ ├── scene-view-tools.ts
  331. │ │ ├── reference-image-tools.ts
  332. │ │ └── asset-advanced-tools.ts
  333. │ ├── panels/ # UI 面板实现
  334. │ └── test/ # 测试文件
  335. ├── dist/ # 编译后的 JavaScript 输出
  336. ├── static/ # 静态资源(图标等)
  337. ├── i18n/ # 国际化文件
  338. ├── package.json # 插件配置
  339. └── tsconfig.json # TypeScript 配置
  340. ```
  341. ### 从源码构建
  342. ```bash
  343. # 安装依赖
  344. npm install
  345. # 开发构建(监视模式)
  346. npm run watch
  347. # 生产构建
  348. npm run build
  349. ```
  350. ### 添加新工具
  351. 1. 在 `source/tools/` 中创建新的工具类
  352. 2. 实现 `ToolExecutor` 接口
  353. 3. 将工具添加到 `mcp-server.ts` 初始化中
  354. 4. 工具会自动通过 MCP 协议暴露
  355. ### TypeScript 支持
  356. 插件完全使用 TypeScript 编写,具备:
  357. - 启用严格类型检查
  358. - 为所有 API 提供全面的类型定义
  359. - 开发时的 IntelliSense 支持
  360. - 自动编译为 JavaScript
  361. ## 故障排除
  362. ### 常见问题
  363. 1. **服务器无法启动**: 检查端口可用性和防火墙设置
  364. 2. **工具不工作**: 确保场景已加载且 UUID 有效
  365. 3. **构建错误**: 运行 `npm run build` 检查 TypeScript 错误
  366. 4. **连接问题**: 验证 HTTP URL 和服务器状态
  367. ### 调试模式
  368. 在插件面板中启用调试日志以获取详细的操作日志。
  369. ### 使用调试工具
  370. ```json
  371. {
  372. "tool": "debug_get_console_logs",
  373. "arguments": {"limit": 50, "filter": "error"}
  374. }
  375. ```
  376. ```json
  377. {
  378. "tool": "debug_validate_scene",
  379. "arguments": {"checkMissingAssets": true}
  380. }
  381. ```
  382. ## 系统要求
  383. - Cocos Creator 3.8.6 或更高版本
  384. - Node.js(Cocos Creator 自带)
  385. - TypeScript(作为开发依赖安装)
  386. ## 许可证
  387. 本插件供 Cocos Creator 项目使用,并且源代码一并打包,可以用于学习和交流。没有加密。可以支持你自己二次开发优化,任何本项目代码或者衍生代码均不能用于任何商用、转售,如果需要商用,请联系本人。
  388. ## 联系我加入群
  389. <img alt="image" src="https://github.com/user-attachments/assets/a276682c-4586-480c-90e5-6db132e89e0f" width="400" height="400" />

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.