内容
# cc-mvp
`cc-mvp` 是一个 Cocos Creator 3.8 编辑器扩展，它将场景、节点、组件、预制件、预览、构建、资产和调试操作作为 MCP 工具暴露出来。
它旨在为 Codex 和 Claude Code 等 AI 客户端设计：
- Cocos Creator 保持真实的编辑器状态并执行实际操作。
- `cc-mvp` 在 `http://127.0.0.1:17321` 启动本地 HTTP 网桥。
- `dist/mcp-server.js` 是一个stdio MCP适配器，它将MCP工具调用转发到该本地网桥。
## 提供的内容
主要功能组：
- 场景工具：获取当前场景、列出场景、打开场景、保存场景、创建场景、检查层次结构
- 节点工具：创建、读取、查找、移动、复制、删除、更新变换和活动状态
- 组件工具：添加、移除、检查、设置属性、安装自定义脚本组件
- 预制件工具：列出、检查、打开、实例化、创建、将场景节点导出为真实的预制件资产
- 预览工具：浏览器预览、GameView 启动/暂停/步进/停止
- 构建工具：查询平台/任务、触发真实 Creator 构建、AI 友好的构建助手
- 资产/调试/环境工具：资产 CRUD、日志、场景 JS 执行、统计、验证、首选项、服务器信息
面向 AI 的高级工具包括：
- `ai_preview_browser_with_scene`
- `ai_build_web_desktop_default`
- `ai_build_web_mobile_default`
- `ai_build_web_mobile_and_wait`
- `ai_export_selected_nodes_to_prefabs`
- `ai_export_nodes_by_name_to_prefabs`
## 架构
- `source/main.ts`：扩展主进程、HTTP 网桥、MCP 样式的 JSON-RPC 路由、项目/构建/资产/日志工具
- `source/scene.ts`：真实场景/节点/组件/预制件/GameView 操作的场景脚本
- `source/mcp-server.ts`：stdio MCP 服务器，转发到 `http://127.0.0.1:17321`
## 安装
将扩展程序放在您的项目中：
```text
YourProject/
├─ assets/
├─ extensions/
│ └─ cc-mvp/
│ ├─ source/
│ ├─ dist/
│ ├─ package.json
│ └─ ...
└─ ...
```
安装和构建：
```powershell
cd E:\CocosWorkspace\Test33\extensions\cc-mvp
npm install
npm run build
```
然后在 Cocos Creator 中：
1. 打开项目。
2. 启用或刷新 `cc-mvp` 扩展。
3. 在 AI 客户端使用 MCP 时保持 Creator 打开。
## 验证网桥
扩展加载后，网桥应在以下位置可用：
```text
http://127.0.0.1:17321
```
快速健康检查：
```powershell
Invoke-RestMethod `
-Method Get `
-Uri "http://127.0.0.1:17321/health"
```
预期结果：
- HTTP 200
- 包含扩展名称、版本和项目路径的 JSON
## MCP 端点
`cc-mvp` 暴露了三个实用的入口点：
1. Stdio MCP 服务器
```powershell
node E:/CocosWorkspace/Test33/extensions/cc-mvp/dist/mcp-server.js
```
2. HTTP JSON-RPC MCP 端点
```text
POST http://127.0.0.1:17321/mcp
```
3. 简化的 HTTP 工具端点
```text
POST http://127.0.0.1:17321/tool
```
其他有用的路由：
- `GET /health`
- `GET /tools`
- `POST /message`
- `POST /crud`
## 与 Codex 配合使用
Codex CLI 和 Codex IDE 扩展共享相同的 MCP 配置。OpenAI 文档指出，MCP 服务器可以通过 `codex mcp add` 或通过 `~/.codex/config.toml` / 项目 `.codex/config.toml` 添加。参见官方文档： [Model Context Protocol – Codex](https://developers.openai.com/codex/mcp) 和 [Advanced Configuration – Codex](https://developers.openai.com/codex/config-advanced)。
### 选项 A：从 CLI 添加
运行一次：
```powershell
codex mcp add cc-mvp -- node E:/CocosWorkspace/Test33/extensions/cc-mvp/dist/mcp-server.js
```
然后在 Codex 中验证：
- 运行 `codex mcp --help` 获取 MCP 管理命令
- 在 Codex TUI 中运行 `/mcp` 以查看 `cc-mvp` 是否已连接
### 选项 B：添加到 `.codex/config.toml`
对于此项目，创建或编辑：
- `E:\CocosWorkspace\Test33\.codex\config.toml`
示例：
```toml
[mcp_servers.cc-mvp]
command = "node"
args = ["E:/CocosWorkspace/Test33/extensions/cc-mvp/dist/mcp-server.js"]
cwd = "E:/CocosWorkspace/Test33"
startup_timeout_sec = 20
tool_timeout_sec = 600
enabled = true
```
如果您更喜欢用户范围的设置，请将相同的块放在：
- `~/.codex/config.toml`
### 如何提示 Codex
连接服务器后，您可以自然地要求 Codex 调用工具。示例：
- `使用 cc-mvp 获取当前的 Cocos 场景并总结节点层次结构。`
- `使用 cc-mvp 打开 db://assets/scene.scene 并启动浏览器预览。`
- `使用 cc-mvp 将当前选定的节点导出到 db://assets/prefabs/selected。`
- `使用 cc-mvp 运行 web-mobile 构建并等待完成。`
典型工具序列：
1. `scene_get_current_scene`
2. `scene_get_hierarchy`
3. `node_find_nodes_by_name` 或 `node_create_node`
4. `project_preview_start` 或 `ai_preview_browser_with_scene`
5. `project_build` 或 `ai_build_web_mobile_and_wait`
## 与 Claude Code 配合使用
Anthropic 文档介绍了使用 `claude mcp add --transport stdio <name> -- <command> [args...]` 的本地_stdio MCP 服务器。参见官方文档： [Connect Claude Code to tools via MCP](https://docs.anthropic.com/en/docs/claude-code/mcp)。
### 选项 A：本地范围
这是最简单的设置，仅影响您当前项目在您机器上的运行：
```powershell
claude mcp add --transport stdio cc-mvp -- node E:/CocosWorkspace/Test33/extensions/cc-mvp/dist/mcp-server.js
```
### 选项 B：项目范围
如果您想将 MCP 服务器配置写入存储库的 `.mcp.json` 中：
```powershell
claude mcp add --transport stdio cc-mvp --scope project -- node E:/CocosWorkspace/Test33/extensions/cc-mvp/dist/mcp-server.js
```
Anthropic 目前区分这些范围：
- `local`：存储在 `~/.claude.json` 中，仅适用于当前项目
- `project`：存储在存储库 `.mcp.json` 中，适用于团队共享
- `user`：存储在 `~/.claude.json` 中，适用于所有项目
### 等效的 `.mcp.json` 示例
如果您想手动编写项目配置：
```json
{
"mcpServers": {
"cc-mvp": {
"command": "node",
"args": [
"E:/CocosWorkspace/Test33/extensions/cc-mvp/dist/mcp-server.js"
],
"env": {}
}
}
}
```
### 检查服务器状态
有用的 Claude Code 命令：
```powershell
claude mcp list
claude mcp get cc-mvp
```
在 Claude Code 中：
```text
/mcp
```
### 如何提示 Claude Code
示例：
- `使用 cc-mvp MCP 服务器检查当前的 Cocos 场景。`
- `使用 cc-mvp 打开 db://assets/scene.scene 并启动浏览器预览。`
- `使用 cc-mvp 将名为 Enemy 的节点导出到 db://assets/prefabs/enemies。`
- `使用 cc-mvp 构建 web-mobile 并等待完成。`
## 直接 HTTP 使用
如果您正在构建自己的客户端，您可以直接调用网桥。
### 简化的 `/tool` 调用
```json
{
"name": "scene_get_current_scene",
"arguments": {}
}
```
PowerShell：
```powershell
$body = @{
name = "scene_get_current_scene"
arguments = @{}
} | ConvertTo-Json -Depth 20
Invoke-RestMethod `
-Method Post `
-Uri "http://127.0.0.1:17321/tool" `
-ContentType "application/json" `
-Body $body
```
### MCP JSON-RPC 调用
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "scene_get_current_scene",
"arguments": {}
}
}
```
## 推荐的第一个工具调用
连接新的 AI 客户端时，这些是良好的第一次检查：
1. `scene_get_current_scene`
2. `scene_get_scene_list`
3. `scene_get_hierarchy`
4. `project_get_info`
5. `env_get_environment_info`
然后继续执行实际操作：
1. `ai_preview_browser_with_scene`
2. `prefab_export_node_to_prefab`
3. `ai_export_selected_nodes_to_prefabs`
4. `ai_build_web_mobile_and_wait`
## 实用示例
### 打开场景并在浏览器中预览
使用高级助手：
```json
{
"name": "ai_preview_browser_with_scene",
"arguments": {
"scene": "db://assets/scene.scene"
}
}
```
### 触发 web-mobile 构建并等待
```json
{
"name": "ai_build_web_mobile_and_wait",
"arguments": {
"debug": true,
"buildPath": "project://build/web-mobile",
"timeoutMs": 600000,
"pollMs": 1500
}
}
```
### 将场景节点导出为真实的预制资产
```json
{
"name": "prefab_export_node_to_prefab",
"arguments": {
"nodeUuid": "YOUR_NODE_UUID",
"url": "db://assets/prefabs/Enemy.prefab"
}
}
```
## 注意
- stdio MCP 服务器依赖于本地 Creator 网桥，因此 Cocos Creator 必须保持打开状态。
- `dist/mcp-server.js` 不直接操作项目文件。它将请求转发到正在运行的编辑器。
- 浏览器预览通常是自动化预览流程最稳定的路径。
- GameView 控件已实现并测试，但 Creator UI 状态仍会影响时间。
- 构建工具触发真实的 Creator 构建任务，而不仅仅是面板导航。
- 资源路径应尽可能使用 Creator `db://` URL。
## 故障排除
如果 Codex 或 Claude Code 无法使用工具：
1. 使用 `E:\CocosWorkspace\Test33` 确认 Creator 已打开。
2. 确认已启用 `cc-mvp`。
3. 确认 `http://127.0.0.1:17321/health` 返回成功。
4. 重建扩展：
```powershell
cd E:\CocosWorkspace\Test33\extensions\cc-mvp
npm run build
```
5. 刷新或重启 Cocos Creator。
6. 如果客户端仍指向旧路径，请重新运行 `codex mcp add ...` 或 `claude mcp add ...`。
