64 lines
3.6 KiB
Markdown
Executable File
64 lines
3.6 KiB
Markdown
Executable File
# 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执行：
|
|
|
|
```text
|
|
先读取场景，在Canvas下创建一个红色圆形和一个蓝色方形，横向排列。
|
|
完成后验证运行态结果并保存场景；如果失败，回滚全部改动，不要让我手动挂脚本。
|
|
```
|
|
|
|
这个任务应由`cocos_apply_ui_spec`或对应任务级工具一次完成。成功回执包含`status`、`changed`、`verified`、`undoAvailable`、`diagnostics`和`nextAction`。调用一次`cocos_mcp_undo_last`应撤销整个任务。
|
|
|
|
仍建议保持这个节奏：
|
|
|
|
```text
|
|
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](./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`.
|