Files

T

joywayerandClaude Opus 5 02dc5d51ca 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>

2026-09-02 07:36:54 +08:00

4.1 KiB

Raw Blame History

name, description

name	description
cocos-mcp	Use when 要对 YouleNexus 工程做任何 Cocos Creator 编辑器操作（场景/节点/组件/prefab/资源/动画/预览截图），或 mcp__funplay_cocos__* 工具没出现、调用报连接失败、curl 127.0.0.1:8765/health 不通时。

funplay-cocos-mcp 接入与排障

工程 cocoscreator_projects/YouleNexus。编辑器操作走 mcp__funplay_cocos__* 工具（105 个独立工具，不是聚合派发）。

「禁止手改 .scene/.prefab/.anim/.meta」这条规则的唯一来源是 CLAUDE.md，本文件不复述——按仓库第二准则，同一条规则不在两处定义。

工具怎么用：不在本文件

MCP server 连上后会自注入完整说明（每个工具 description 带用法/枚举/示例）。照它的说明用，不要在本文件重复维护一份工具清单——扩展换版本时那份副本必然过期误导。需要查工具清单时调 get_tool_catalog。

当前扩展 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 这种聚合入口，每个操作就是一把独立工具。

前置条件（缺一不可）

Cocos Creator 3.8.8 已打开 YouleNexus 工程；
扩展 Funplay Cocos MCP 已启用（extensions/funplay-cocos-mcp/funplay-cocos-mcp.config.json 里 autostart: true 默认会自动起 sidecar，监听 http://127.0.0.1:8765/mcp）；
Claude Code 侧不需要 .mcp.json —— funplay_cocos 配置在用户级 ~/.claude.json，项目级刻意不维护 MCP 配置（schema 校验也不允许空对象，见 memory cocos-creator-mcp-setup）。

探活

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。

连不上时

提示用户去编辑器里启用扩展 / 等待 autostart 起服务，不要盲目重试，更不要绕开 MCP 去手改序列化文件。服务只在编辑器进程内，外部无法代为启动。

按此顺序排查：编辑器是否开着 → 扩展管理器里 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 会话才生效。

已知坑

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）与配置位置演进全在那里。

4.1 KiB Raw Blame History Unescape Escape