convez.ai
MCP ServerDesenvolvimento WebAvançado
84rswk6v8n-boopshurongsen

Cocos MCP Server

84rswk6v8n-boopshurongsen/cocos-mcp-server

MCP server para Cocos Creator com 21 ferramentas de editor AI

Ver no GitHub
InicialPluginScore · de 0 a 100

Extensão MCP para Cocos Creator 3.7+ que expõe as capacidades do editor a clientes AI, permitindo leitura e manipulação de projetos, cenas, nós, componentes, recursos e animações. Fornece 21 ferramentas integradas para UI building, edição de nós, consulta de recursos, configuração de animações e debug visual em tempo de execução.

Instalação

$npx convez-ai 84rswk6v8n-boopshurongsen/cocos-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
v1.7.8
Issues abertas
0
Contribuidores
2

Casos de uso

  • Automação de UI building e layout em Cocos Creator
  • Debug visual de física e colisões em tempo de execução
  • Edição assistida de animações e Animation Graph
  • Geração em lote de estruturas de cenas e prefabs
  • Inspeção e validação de projetos (hierarquia, referências, nomeação)

Veredito

Ferramenta madura e bem-documentada para quem trabalha com Cocos Creator e quer automação AI no editor. O conjunto amplo de 21 ferramentas cobre fluxos reais (física, animações, UI), mas requer familiaridade com Cocos e MCP para aproveitar ao máximo.

README

A tradução para o português deste README ainda está na fila.

Cocos MCP Server

Cocos MCP Server 是一个面向 Cocos Creator 3.7+ / 3.8.x 的 MCP 插件,让支持 MCP 的 AI 客户端可以读取和操作 Cocos 工程、场景、节点、组件、资源、动画和预览运行态。

插件提供编辑器面板、MCP 服务启动入口、工具管理和运行可视化能力,适合用 AI 辅助完成 UI 搭建、节点编辑、资源查询、动画配置、场景检查和浏览器预览调试。

主要能力

  • 在 Cocos Creator 内启动 MCP Server,并把编辑器能力暴露给 AI 客户端。
  • 通过工具管理面板查看、启用和配置已注册工具。
  • 支持场景、节点、组件、预制体、资源、编辑器、视图、UI 模板、构建、动画等常用工作流。
  • 支持浏览器预览状态查询和运行态桥接,便于 AI 理解预览页面里的实际节点树。
  • 支持 Animation Mask 和 Animation Graph 等 Cocos Creator 3.8.x 动画资源编辑。

安装

  1. 将 cocos-mcp-server 文件夹放入 Cocos Creator 项目的 extensions/ 目录。
  2. 打开或重启 Cocos Creator。
  3. 在顶部菜单中打开 MCP Server 面板。
  4. 启动 MCP 服务,并按面板生成的配置接入 Claude、Cursor、Codex 等 MCP 客户端。

更多安装说明见 INSTALL.md。

21 个工具简表

工具功能简介
scene场景管理工具,用于打开、保存、创建场景,读取层级,查询场景状态,执行撤销事务,检测场景引用和组件类型。
node节点工具,用于查找、创建、修改、移动、复制、删除节点,设置 Transform,挂载或移除脚本,并支持批量修改。
component组件工具,用于添加、移除、查看和配置组件属性,查询可用组件类型,绑定按钮点击事件并支持批量绑定。
prefab预制体工具,用于查询、创建、实例化、删除、进入编辑、保存编辑、应用或回退预制体变更。
asset资源工具,用于搜索、创建、复制、移动、删除、导入、刷新资源,查询依赖,以及在 UUID、路径和 URL 之间转换。
editor编辑器工具,用于读取项目信息、运行或停止预览、构建项目、打开构建面板、读取日志、管理偏好设置和重载编辑器。
view视图工具,用于切换 Gizmo、2D/3D 模式、网格、图标显示,聚焦节点,对齐相机,并管理参考图。
composite复合 UI 工具,用一次调用创建按钮、文本、图片等完整 UI,也可挂载脚本并完成属性绑定,适合快速搭建界面。
knowledge知识查询工具,用于查询 Cocos 组件属性、UI 规则、布局模式、动画配方、最佳实践和工具使用指南。
validate深度校验工具,用于检查 UI 重叠、越界、资源引用一致性、层级深度和命名问题。
templateUI 模板工具,用于列出并应用内置模板,例如弹窗、滚动列表、导航栏和设置页。
capture场景快照工具,用于导出场景或指定节点子树的结构化 JSON,帮助 AI 理解布局、尺寸、位置和组件信息。
builderJSON 构建工具,用于根据声明式节点树一次性创建复杂层级和组件,适合批量生成 UI 或原型结构。
animation动画工具,用于播放控制、创建和编辑动画剪辑、轨道、关键帧、曲线、事件、预设和批量动画操作。
spineSpine 工具,用于读取 sp.Skeleton 动画和皮肤,设置动画、皮肤、属性、骨骼数据和 socket。
label文本工具,用于管理 cc.Label、cc.RichText、cc.EditBox 的文本、字体、样式、描边、阴影和批量样式。
runtime运行态桥接工具,用于在浏览器预览页中读取运行时场景树、节点、组件、统计信息,并支持修改节点激活和 Transform。
preview浏览器预览工具,用于启动、停止和查询预览状态,返回预览地址、端口、启动时间和服务复用情况。
animation_maskAnimation Mask 工具,用于创建、查询、更新 .animask 资源,批量设置骨骼遮罩,校验骨骼路径。
animation_graphAnimation Graph 工具,用于编辑 .animgraph 资源,管理参数、状态、连线、过渡条件、Layer,并校验动画图。
physics物理配置工具,用于检查和配置刚体、碰撞体、触发区、投射物碰撞、碰撞分组、物理材质和物理调试。

功能图文介绍

运行态物理调试可视化

cocos_physics 支持在 Cocos Web 预览运行后绘制物理调试信息,AI 可以通过 MCP 在外部浏览器自动打开注入预览页,并把射线、命中点和碰撞体线框直接叠加到游戏画面上。

运行态物理调试可视化

这个功能主要用于排查 3D 游戏里的物理检测问题,例如射线是否从正确位置发出、是否被中间碰撞体遮挡、命中的具体节点是谁,以及运行态碰撞体和模型显示是否对齐。调试面板支持开启或关闭显示、单独控制射线和碰撞体显示,并可以清除或恢复当前绘制内容。

常用能力包括:

  • debug_draw_ray:绘制运行态射线,可显示命中点和命中节点名称。
  • debug_draw_collider:绘制指定节点的碰撞体线框。
  • debug_draw_all_colliders:绘制当前运行场景中的全部碰撞体。
  • debug_set_visibility:控制物理调试面板、射线和碰撞体显示状态。
  • debug_clear_drawings:清除当前运行态调试绘制。

射线调试推荐流程:

  1. 使用 cocos_runtime.open_injected_preview 打开外部浏览器自动注入预览页。
  2. 使用 cocos_runtime.wait_until_ready 等待运行态场景就绪。
  3. 使用 cocos_physics.debug_set_visibility 打开物理调试面板。
  4. 使用 cocos_physics.debug_draw_all_colliders 绘制场景碰撞体线框。
  5. 使用 cocos_physics.debug_draw_ray 绘制射线并检查命中结果。

移动中的节点建议给 debug_draw_ray 传 live: true,这样射线每帧会重新采样起点、目标点和命中点。按节点绘制时优先使用 originNode 和 targetNode,工具会优先使用节点碰撞体中心;如果命中物体,返回结果会包含 hitInfo.result.node、hitInfo.result.collider、hitInfo.result.point 和 hitInfo.result.distance,画面中也会显示“命中:节点名”。

示例:

{
  "action": "debug_draw_ray",
  "originNode": "这个是测试的节点-001",
  "targetNode": "这个是测试的节点-003",
  "live": true,
  "raycast": true,
  "maxDistance": 20,
  "label": "射线:001 -> 003",
  "showLabel": true
}

使用建议

  • 修改 3 个以上节点时优先使用 node 的 batch_modify。
  • 批量绑定按钮点击事件时优先使用 component 的 batch_click_event。
  • 构建复杂 UI 层级时优先使用 builder,简单按钮、文本、图片可用 composite。
  • 检查断裂资源引用可用 scene.validate_scene,做布局和层级深度检查可用 validate。
  • 不熟悉某个工具 action 时,可先用 knowledge 查询 tool_guide。

v1.7.7 更新内容

  • 增强 cocos_runtime 运行态桥接,新增按组件查找运行时节点、读取属性路径、调用组件方法和等待运行时控制台日志等能力。
  • 优化运行态日志读取,支持按 sinceIndex、关键字、日志级别和等待时间获取浏览器预览页日志,便于验证运行后效果。
  • 增加运行态私有属性路径保护,默认阻止读取 _ 开头的私有属性路径。
  • 优化 Codex stdio 桥接默认 MCP 地址,默认指向 http://127.0.0.1:3300/mcp,降低端口配置缺失时的连接失败概率。
  • 已验证 bridgeVersion 0.1.4 在 Cocos 浏览器预览页中可正常完成场景 ready、组件查找、属性读取、方法调用和日志回读。

v1.7.6 更新内容

  • 新增 Cocos Web 运行态桥接能力,支持通过浏览器预览页读取运行时场景树、节点、组件和基础统计信息。
  • 新增 cocos_runtime 工具,支持检查运行态连接、等待场景就绪、查找节点、读取节点信息、读取组件信息、切换节点显隐和修改 Transform。
  • 新增运行态代理注入页,可通过 injectedPreviewUrl 自动注入 runtime bridge,减少手动在浏览器控制台执行脚本的步骤。
  • 优化 runtime bridge 客户端管理,清理旧客户端并拒绝过旧 bridge 版本,避免旧页面干扰 active client 选择。
  • 修复预览代理下场景 JSON、socket.io、WASM 和 engine external 资源转发问题,提升 Cocos 预览页运行态读取稳定性。
  • 优化启动 MCP 服务器面板,支持端口配置、启动/停止、重启 Cocos 后自动启动、工具列表查看、MCP 地址获取、插件重新加载和版本信息展示。

联系

如需支持或定制,可联系:

  • QQ: 1799096798
  • 微信: 13272695146
Ver o original no GitHub

Bom para

Relacionados