joywayerandClaude Opus 5
0ba37c7212
原文档写着"164 个工具"并复述了一份按前缀分的工具清单, 对应的是已删除的旧扩展, 照着写会调不到工具。 改为不再复述工具用法: cocos-mcp-server 连上后会自注入 5.5K 字符的完整说明 (CRITICAL RULES + intent→tool 速查表 + 批量操作), 16 个工具的 description 也 各带 action 枚举与示例, 仓库里再维护一份副本必然随扩展版本腐化。 文档只保留 MCP 给不了的部分——服务离线时它的自带说明也一并消失, 而那正是最需要 "去编辑器点 Start Server"和"不要转而手改序列化文件"的时刻: - 前置条件、curl /health 探活、连不上时的排查顺序 - settings/mcp-server.json 的 autoStart:false, ECONNREFUSED 的常见成因 - 已知坑: cocos_asset.search 的 type 过滤失效; cocos_scene.hierarchy 的 includeComponents 失效; 编辑器里的 scene-2d 是 Creator 内置模板而非工程资产 (assets/ 下 0 个 .scene), 不必去仓库里找 技能里原本重复的"禁止手改 .scene/.prefab"规则改为引用 CLAUDE.md 单一来源, 依据 是仓库第二准则; 基线测试也表明未读该技能的 agent 仅凭 CLAUDE.md 即拒绝手改。 CLAUDE.md 里"动手前先读技能"改为条件式(正常操作不必读, 故障时才读), 此前该指令 与技能的排障定位冲突, 实测中不同 agent 对它的解读并不一致。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.3 KiB
name, description
| name | description |
|---|---|
| cocos-mcp | Use when 要对 YouleNexus 工程做任何 Cocos Creator 编辑器操作（场景/节点/组件/prefab/资源/动画/预览截图），或 cocos_* 工具压根没出现、调用报连接失败、curl 127.0.0.1:3000 不通时。 |
cocos-creator-mcp 接入与排障
工程 cocoscreator_projects/YouleNexus。编辑器操作走 mcp__cocos-creator-mcp__cocos_* 工具。
「禁止手改 .scene/.prefab/.anim/.meta」这条规则的唯一来源是 CLAUDE.md，本文件不复述——按仓库第二准则，同一条规则不在两处定义。
工具怎么用：不在本文件
MCP server 连上后会自动注入完整说明（CRITICAL RULES + intent→tool 速查表 + 批量操作），每个工具的 description 也带 action 枚举和示例。照它的说明用，不要在本文件重复维护一份工具清单——扩展换版本时那份副本必然过期误导。
当前扩展 cocos-mcp-server（extensions/cocos-mcp-server/），暴露 16 个聚合工具（cocos_scene / node / component / prefab / asset / editor / view / composite / knowledge / validate / template / capture / builder / animation / spine / label），每个靠 action 参数分派。工具默认是 deferred，先 ToolSearch 加载 schema 再调。
前置条件（缺一不可）
- Cocos Creator 3.7+ 已打开
YouleNexus工程； - 扩展 Cocos MCP Server 已启用，且在其面板里点了 Start Server（监听
http://127.0.0.1:3000/mcp）。
Claude Code 侧配置在仓库根 .mcp.json，HTTP 直连，服务器名 cocos-creator-mcp（改名会同时打断 .claude/settings.local.json 里的 mcp__cocos-creator-mcp__* 允许规则）。
探活
curl http://127.0.0.1:3000/health
# 期望：{"status":"ok","tools":16,"transport":"streamable-http"}
连不上时
提示用户去编辑器里启动服务，不要盲目重试，更不要绕开 MCP 去手改序列化文件。 服务只在编辑器进程内，外部无法代为启动。
按此顺序排查：编辑器是否开着 → 扩展是否启用 → 面板是否点过 Start Server → /health 是否通 → .mcp.json 是否仍指向 http://127.0.0.1:3000/mcp（历史上曾指向已删除的 stdio-bridge 路径）。改完 .mcp.json 需重启会话才生效。
settings/mcp-server.json 里 autoStart: false，所以每次开编辑器都得手动点 Start Server；这大概率就是 ECONNREFUSED 的常见成因（改 true 应可自动启动，未实测）。
已知坑
cocos_asset{action:"search"}的type过滤不生效：传cc.SceneAsset照样返回脚本和目录，返回消息还谎称「of type 'cc.SceneAsset'」。自己按结果里的type字段过滤。cocos_scene{action:"hierarchy"}的includeComponents: true不生效，返回树里没有组件信息。要拿组件得对每个节点追加cocos_node{action:"info"}。- 工程当前没有任何场景资源（
assets/下 0 个.scene，只有framework/的.ts）。编辑器里那个scene-2d是 Creator 内置模板（db://internal/default_file_content/scene/scene-2d.scene）新建出来的未保存场景，不是工程资产——别浪费时间去仓库里找它。 - 安装方式与历史沿革记在项目记忆
cocos-creator-mcp-setup。