chore(spec): 综合清理 + legacy-layer 迁移 spec/plan/data
主要改动: - 切到 funplay-cocos-mcp v0.5.1 (用户级配置, 项目级 .mcp.json 删除) - 仓库文档/CLAUDE.md/.gitignore 等清理过时 cocos-mcp-server 引用 - memory 文件同步: cocos-mcp-setup/path/blocker/spriteframe-uuid/prefab-persist 等加 funplay 实测警告 - memory 新建 funplay-cocos-mcp-pending-verification.md (后已被实测覆盖) - spec/plan/data: - docs/superpowers/specs/2026-09-02-legacy-layer-migration-design.md - docs/superpowers/plans/2026-09-02-legacy-layer-migration.md - docs/superpowers/data/layer-spirit-summary.json - YouleNexus: profiles.ts / defaults.ts / PlayerInfoView.prefab / scene 改动 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -1,45 +1,51 @@
|
||||
---
|
||||
name: cocos-mcp
|
||||
description: Use when 要对 YouleNexus 工程做任何 Cocos Creator 编辑器操作（场景/节点/组件/prefab/资源/动画/预览截图），或 cocos_* 工具压根没出现、调用报连接失败、curl 127.0.0.1:3000 不通时。
|
||||
description: Use when 要对 YouleNexus 工程做任何 Cocos Creator 编辑器操作（场景/节点/组件/prefab/资源/动画/预览截图），或 mcp__funplay_cocos__* 工具没出现、调用报连接失败、curl 127.0.0.1:8765/health 不通时。
|
||||
---
|
||||
|
||||
# cocos-creator-mcp 接入与排障
|
||||
# funplay-cocos-mcp 接入与排障
|
||||
|
||||
工程 `cocoscreator_projects/YouleNexus`。编辑器操作走 `mcp__cocos-creator-mcp__cocos_*` 工具。
|
||||
工程 `cocoscreator_projects/YouleNexus`。编辑器操作走 `mcp__funplay_cocos__*` 工具（**105 个独立工具**，不是聚合派发）。
|
||||
|
||||
「禁止手改 `.scene`/`.prefab`/`.anim`/`.meta`」这条规则的唯一来源是 CLAUDE.md，本文件不复述——按仓库第二准则，同一条规则不在两处定义。
|
||||
|
||||
## 工具怎么用：不在本文件
|
||||
|
||||
MCP server 连上后会自动注入完整说明（CRITICAL RULES + intent→tool 速查表 + 批量操作），每个工具的 description 也带 action 枚举和示例。**照它的说明用，不要在本文件重复维护一份工具清单**——扩展换版本时那份副本必然过期误导。
|
||||
MCP server 连上后会自注入完整说明（每个工具 description 带用法/枚举/示例）。**照它的说明用，不要在本文件重复维护一份工具清单**——扩展换版本时那份副本必然过期误导。需要查工具清单时调 `get_tool_catalog`。
|
||||
|
||||
当前扩展 `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 再调。
|
||||
当前扩展 `funplay-cocos-mcp` v0.5.1（`extensions/funplay-cocos-mcp/`），工具名形如 `mcp__funplay_cocos__<verb>_<noun>`（如 `create_node` / `inspect_component` / `run_project_preview` / `capture_preview_screenshot`）。**不是** `action:` 参数派发模式——没有 `cocos_scene` / `cocos_node` 这种聚合入口，每个操作就是一把独立工具。
|
||||
|
||||
## 前置条件（缺一不可）
|
||||
|
||||
1. Cocos Creator 3.7+ 已打开 `YouleNexus` 工程；
|
||||
2. 扩展 **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__*` 允许规则）。
|
||||
1. Cocos Creator 3.8.8 已打开 `YouleNexus` 工程；
|
||||
2. 扩展 **Funplay Cocos MCP** 已启用（`extensions/funplay-cocos-mcp/funplay-cocos-mcp.config.json` 里 `autostart: true` 默认会自动起 sidecar，监听 `http://127.0.0.1:8765/mcp`）；
|
||||
3. Claude Code 侧**不需要** `.mcp.json` —— `funplay_cocos` 配置在用户级 `~/.claude.json`，项目级刻意不维护 MCP 配置（schema 校验也不允许空对象，见 memory `cocos-creator-mcp-setup`）。
|
||||
|
||||
## 探活
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:3000/health
|
||||
# 期望：{"status":"ok","tools":16,"transport":"streamable-http"}
|
||||
curl http://127.0.0.1:8765/health
|
||||
# 期望：{"ok":true,"name":"Funplay Cocos MCP - YouleNexus","version":"0.5.1","projectName":"YouleNexus",...}
|
||||
```
|
||||
|
||||
或在会话内直接调 `mcp__funplay_cocos__get_project_info`，期望 `{ok:true, ...}` 包含 `projectName: YouleNexus`、`cocosVersion: 3.8.8`。
|
||||
|
||||
## 连不上时
|
||||
|
||||
**提示用户去编辑器里启动服务，不要盲目重试，更不要绕开 MCP 去手改序列化文件。** 服务只在编辑器进程内，外部无法代为启动。
|
||||
**提示用户去编辑器里启用扩展 / 等待 autostart 起服务**，不要盲目重试，更不要绕开 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 应可自动启动，**未实测**）。
|
||||
按此顺序排查：编辑器是否开着 → 扩展管理器里 `Funplay Cocos MCP` 是否启用 → `~/.claude.json` 里 `mcpServers.funplay_cocos` 条目是否还在（type=http、url=http://127.0.0.1:8765/mcp）→ `/health` 是否通 → 工具列表里是否出现 `mcp__funplay_cocos__*`（用 `get_tool_catalog` 列出来核对）。`~/.claude.json` 改动后**需重启 Claude Code 会话**才生效。
|
||||
|
||||
## 已知坑
|
||||
|
||||
- `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`。
|
||||
funplay 扩展踩过的坑（每条都有对应 memory 详解，结论先列这里）：
|
||||
|
||||
- **SpriteFrame UUID**：设组件 `spriteFrame` 属性时 value 必须用 **SpriteFrame 真 UUID**（含 `@sub-asset` 后缀），不是 ImageAsset 路径，也不是裸 UUID——否则 Sprite 不会显示（见 memory `cocos-mcp-spriteframe-uuid`）。
|
||||
- **挂脚本路径判断**：`framework/` 路径下挂脚本能正常识别；老版本曾误判 `framework/` 为非脚本路径，已修正（见 memory `cocos-mcp-mount-script-path`）。
|
||||
- **mount_script 持久化限制**：MCP 的 mount 系列工具不写 prefab JSON 的 `__type__` / `__scriptAsset`，需要用户在编辑器里手动挂一次；不要绕过去 Edit prefab JSON（UUID 引用会被破坏，见 memory `prefab-persist-mount-script`）。
|
||||
- **library 缓存**：不要 `rm -rf YouleNexus/library`；用 Cocos 编辑器的 reload 重建（见 memory `cocos-mcp-library-cache`）。
|
||||
- **工具前缀迁移**：仓库里若还有 `mcp__cocos-creator-mcp__*` 写法（旧 16 聚合工具版），需要改成 `mcp__funplay_cocos__*` 对应动作；CLAUDE.md 的允许规则已迁好。
|
||||
|
||||
## 安装方式与历史沿革
|
||||
|
||||
项目记忆 `cocos-creator-mcp-setup` —— 历次换装（164 工具 stdio 桥 → 16 聚合 HTTP :3000 → 105 独立 HTTP :8765）与配置位置演进全在那里。
|
||||
|
||||
Reference in New Issue
Block a user