HexTrails/wechat/HexTrail/extensions/Cocos MCP Pro - 安全可撤销 AI 场景编辑器/QUICK_START.md

Cocos MCP Pro Quick Start

Version: 0.2.0

中文：第一次连接

1. 安装并打开面板

1. 保留Cocos Store下载的ZIP，不要重新打包或增加外层目录。
2. 在Creator中打开扩展 -> 扩展管理器，切到“项目”或“全局”扩展页并点击“导入”。
3. 直接选择正式ZIP；ZIP根目录已经包含package.json，无需先解压。
4. 确认扩展版本为0.2.0且已启用，等待Creator完成首次资源导入。
5. 从扩展 -> Cocos MCP -> Open MCP Panel打开控制台。

正式包已经包含dist和运行依赖。购买用户不需要执行npm install。

2. 一键检测并配置客户端

1. 确认面板显示MCP服务“运行中”。
2. 点击“一键检测”。Node、Bridge、WebSocket和Creator Scene均通过后再继续。
3. 只配置你实际使用的客户端。v0.2.0支持Cursor、Windsurf、Trae CN、Trae国际版、Zoo Code、Cline、Roo Code和Codex。
4. 完全退出并重新打开AI客户端，使它重新加载MCP配置。
5. 调用cocos_ping和cocos_get_capabilities。两项返回真实结果才算连接成功。

v0.2.0不再让客户端执行临时.cmd或.sh启动器。配置会直接记录Node和bridge-cli.js的绝对路径，并通过--project传入当前工程。写配置前会备份原文件，写完后再次校验；重新点“一键配置”也会迁移旧版启动器配置。

3. 完成第一个闭环任务

打开测试场景后，可以直接让AI执行：

先读取场景，在Canvas下创建一个红色圆形和一个蓝色方形，横向排列。
完成后验证运行态结果并保存场景；如果失败，回滚全部改动，不要让我手动挂脚本。

这个任务应由cocos_apply_ui_spec或对应任务级工具一次完成。成功回执包含status、changed、verified、undoAvailable、diagnostics和nextAction。调用一次cocos_mcp_undo_last应撤销整个任务。

仍建议保持这个节奏：

Inspect -> Mutate -> Verify -> Undo or Continue

4. 调试网页预览或构建错误

• 网页预览：使用cocos_preview_debug_start启动插件托管的Chrome/Edge会话，再用read读取JavaScript异常、Promise异常和失败网络请求，必要时用capture截图，最后stop。
• Creator构建：使用cocos_get_build_diagnostics整理现有构建日志。它只提供证据，不代表Android或iOS构建一定不受影响。

需要帮助

先查看同目录的TROUBLESHOOTING.md。反馈问题时请附：Creator版本、插件版本、系统、AI客户端、一键检测结果和完整错误信息。请勿发送API Key或未脱敏项目资产。

联系邮箱：jimmymjing@gmail.com

English: First connection

1. In Extension Manager, choose Project or Global, import the Store ZIP directly, enable v0.2.0, and open Extensions -> Cocos MCP -> Open MCP Panel. The ZIP already has package.json at its root and does not need to be extracted first.
2. Run the panel self-test. Node, Bridge, WebSocket, and Creator Scene must pass.
3. Auto-configure only the client you use, fully restart it, then call cocos_ping and cocos_get_capabilities.
4. v0.2.0 launches the absolute Node executable with bridge-cli.js --project <project>. It backs up, validates, and atomically replaces client config files; rerunning Auto Config migrates old launcher entries.
5. Try a transactional task such as a red circle and blue square. It must create, verify, save, and undo without requiring a generated script or manual component attachment.

The Store package bundles its runtime dependencies. Store customers do not need to run npm install.