291 lines
7.7 KiB
Markdown
291 lines
7.7 KiB
Markdown
# Funplay Cocos MCP
|
||
|
||
一个嵌入在 `Cocos Creator 3.x` 扩展里的 MCP Server，对齐了你现有 `unity-mcp` 的核心思路：
|
||
|
||
- 编辑器内嵌 HTTP MCP 服务
|
||
- `execute_javascript` 作为统一主工具
|
||
- `tools / resources / prompts` 三层能力
|
||
- 场景树、节点、文件系统、项目上下文的统一访问
|
||
|
||
当前实现更偏向 Unity MCP 的 `core` 能力集，而不是一次性把全部 Unity 工具逐个照搬。
|
||
|
||
## 已实现能力
|
||
|
||
- MCP 协议：
|
||
- `initialize`
|
||
- `tools/list`
|
||
- `tools/call`
|
||
- `resources/list`
|
||
- `resources/read`
|
||
- `resources/templates/list`
|
||
- `prompts/list`
|
||
- `prompts/get`
|
||
- 核心工具：
|
||
- `execute_javascript`
|
||
- `execute_scene_script`
|
||
- `execute_editor_script`
|
||
- `get_scene_info`
|
||
- `get_hierarchy`
|
||
- `find_nodes`
|
||
- `inspect_node`
|
||
- `list_components`
|
||
- `inspect_component`
|
||
- `list_cameras`
|
||
- `list_animations`
|
||
- `play_animation`
|
||
- `stop_animation`
|
||
- `get_project_info`
|
||
- `list_scenes`
|
||
- `open_scene`
|
||
- `list_prefabs`
|
||
- `list_assets`
|
||
- `inspect_asset`
|
||
- `open_asset`
|
||
- `select_asset`
|
||
- `get_editor_selection`
|
||
- `read_file`
|
||
- `get_file_snippet`
|
||
- `write_file`
|
||
- `replace_in_file`
|
||
- `search_files`
|
||
- `list_directory`
|
||
- `exists`
|
||
- `refresh_assets`
|
||
- `run_script_diagnostics`
|
||
- `get_script_diagnostic_context`
|
||
- `capture_desktop_screenshot`
|
||
- `capture_editor_screenshot`
|
||
- `capture_scene_screenshot`
|
||
- `capture_game_screenshot`
|
||
- `capture_preview_screenshot`
|
||
- `list_editor_windows`
|
||
- `get_runtime_state`
|
||
- `pause_runtime`
|
||
- `resume_runtime`
|
||
- `set_time_scale`
|
||
- `emit_node_event`
|
||
- `simulate_button_click`
|
||
- `invoke_component_method`
|
||
- `simulate_mouse_click`
|
||
- `simulate_mouse_drag`
|
||
- `simulate_key_press`
|
||
- `simulate_key_combo`
|
||
- `simulate_preview_input`
|
||
- `full` 模式附加工具：
|
||
- `create_node`
|
||
- `delete_node`
|
||
- `set_node_transform`
|
||
- `add_component`
|
||
- `remove_component`
|
||
- `set_component_property`
|
||
- `reset_component_property`
|
||
- `create_canvas`
|
||
- `create_label`
|
||
- `create_button`
|
||
- `create_sprite`
|
||
- `create_camera`
|
||
- `set_camera_properties`
|
||
- `add_animation_clip`
|
||
- `instantiate_prefab`
|
||
- `run_scene_asset`
|
||
- `delete_asset`
|
||
- 资源：
|
||
- `cocos://project/context`
|
||
- `cocos://project/summary`
|
||
- `cocos://scene/active`
|
||
- `cocos://scene/current`
|
||
- `cocos://selection/current`
|
||
- `cocos://selection/asset`
|
||
- `cocos://errors/scripts`
|
||
- `cocos://mcp/interactions`
|
||
|
||
## 安装方式
|
||
|
||
把当前目录作为 Cocos Creator 扩展放到：
|
||
|
||
- 项目级：`<你的项目>/extensions/funplay-cocos-mcp`
|
||
- 全局级：`<Cocos Creator 用户扩展目录>/funplay-cocos-mcp`
|
||
|
||
然后重启 Cocos Creator，扩展会默认自动启动 MCP 服务。
|
||
|
||
默认地址：
|
||
|
||
- `http://127.0.0.1:8765/`
|
||
|
||
## 图形化面板
|
||
|
||
扩展启用后，可以在 Cocos Creator 顶部菜单打开：
|
||
|
||
- `Funplay -> MCP Server`
|
||
|
||
面板里可以直接完成：
|
||
|
||
- 启动 / 停止 / 重启 MCP Server
|
||
- 查看当前 URL、端口、Profile、项目名
|
||
- 保存 `host / port / toolProfile / autostart` 配置
|
||
- 一键写入 MCP Client 配置
|
||
- 复制 Codex TOML 或 JSON MCP Client 配置
|
||
- 查看工具列表、资源列表、最近交互日志
|
||
- 直接从 Cocos 里调用工具并填写 JSON 参数
|
||
- Quick Actions 优先给出 `execute_javascript`
|
||
- 一键测试 `execute_javascript`、`get_project_info`、`get_scene_info`、`get_hierarchy`、截图、诊断等常用工具
|
||
|
||
一键配置当前支持：
|
||
|
||
- Claude Code / Claude Desktop：`~/.claude.json`
|
||
- Cursor：`~/.cursor/mcp.json`
|
||
- VS Code：`~/.vscode/mcp.json`
|
||
- Trae：`~/.trae/mcp.json`
|
||
- Kiro：`~/.kiro/settings/mcp.json`
|
||
- Codex：`~/.codex/config.toml`
|
||
|
||
面板会使用当前端口写入 `funplay_cocos` MCP server。写入后请重启对应客户端。
|
||
|
||
## 可选配置
|
||
|
||
在 Cocos 项目根目录放一个 `funplay-cocos-mcp.config.json`：
|
||
|
||
```json
|
||
{
|
||
"host": "127.0.0.1",
|
||
"port": 8765,
|
||
"toolProfile": "core",
|
||
"autostart": true,
|
||
"maxInteractionLogEntries": 50
|
||
}
|
||
```
|
||
|
||
也支持环境变量：
|
||
|
||
- `COCOS_MCP_HOST`
|
||
- `COCOS_MCP_PORT`
|
||
- `COCOS_MCP_PROFILE`
|
||
|
||
## MCP Client 示例
|
||
|
||
### Codex
|
||
|
||
```toml
|
||
[mcp_servers.funplay_cocos]
|
||
url = "http://127.0.0.1:8765/"
|
||
```
|
||
|
||
### Claude / Cursor
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"funplay_cocos": {
|
||
"url": "http://127.0.0.1:8765/"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 推荐首测
|
||
|
||
先在 MCP Client 里调用：
|
||
|
||
1. `get_project_info`
|
||
2. `get_scene_info`
|
||
3. `get_hierarchy`
|
||
4. `resources/read` with `cocos://project/context`
|
||
5. `execute_javascript`（`context: "scene"`）
|
||
6. `execute_javascript`（`context: "editor"`）
|
||
7. `run_script_diagnostics`
|
||
8. `capture_desktop_screenshot`
|
||
9. `list_components`
|
||
10. `get_script_diagnostic_context`
|
||
11. `get_runtime_state`
|
||
12. `capture_editor_screenshot`
|
||
13. `list_editor_windows`
|
||
14. `capture_scene_screenshot`
|
||
15. `simulate_mouse_click`
|
||
|
||
其中 `execute_javascript` 是统一主工具，`execute_scene_script` / `execute_editor_script` 主要保留给兼容调用。
|
||
|
||
`execute_javascript` 示例，场景上下文：
|
||
|
||
```json
|
||
{
|
||
"context": "scene",
|
||
"code": "return { sceneName: scene.name, rootCount: scene.children.length };"
|
||
}
|
||
```
|
||
|
||
`execute_javascript` 示例，编辑器上下文：
|
||
|
||
```json
|
||
{
|
||
"context": "editor",
|
||
"code": "return { projectPath: context.projectPath, toolCount: helpers.listTools().length };"
|
||
}
|
||
```
|
||
|
||
`execute_scene_script.code` 兼容示例：
|
||
|
||
```js
|
||
return {
|
||
sceneName: scene.name,
|
||
rootChildren: scene.children.map((node) => node.name),
|
||
};
|
||
```
|
||
|
||
## 和 Unity MCP 的对应关系
|
||
|
||
- Unity `execute_code` → Cocos `execute_javascript`
|
||
- Unity `execute_code` 的场景/编辑器兼容拆分入口 → `execute_scene_script` / `execute_editor_script`
|
||
- Unity `get_scene_info` → Cocos `get_scene_info`
|
||
- Unity `get_hierarchy` → Cocos `get_hierarchy`
|
||
- Unity `read_file/write_file/search_files` → 同名 Cocos 文件工具
|
||
- Unity `resources/prompts` → 同结构的 Cocos 资源与提示词
|
||
- Unity `core/full` → Cocos `toolProfile=core|full`
|
||
|
||
## 当前边界
|
||
|
||
这版已经进入第二阶段，补上了：
|
||
|
||
- 资产查询 / 打开 / 删除 / 选中
|
||
- TypeScript 脚本诊断
|
||
- 本机桌面截图回传 MCP image
|
||
|
||
现在第三段也补上了：
|
||
|
||
- 组件增删查改
|
||
- Scene / Prefab 资产工具
|
||
- 脚本修复辅助链路：`get_script_diagnostic_context` + `replace_in_file`
|
||
|
||
第四段继续补上了：
|
||
|
||
- UI 专用工具：Canvas / Label / Button / Sprite 创建
|
||
- Camera 专用工具：列出、创建、属性设置
|
||
- Animation 专用工具：列出、添加 Clip、播放、停止
|
||
- 运行态控制：暂停、恢复、时间缩放、状态查询
|
||
- 输入/交互模拟：按钮点击、节点事件、组件方法调用
|
||
- 截图增强：桌面截图、Editor 窗口截图、场景截图别名
|
||
|
||
这次把之前两块缺口也补了：
|
||
|
||
- `capture_scene_screenshot` 现在优先按 Editor 内部面板区域裁剪，不再只是整窗截图别名
|
||
- 新增 `capture_game_screenshot` / `capture_preview_screenshot`
|
||
- 新增 `list_editor_windows` 方便先看 Cocos/Electron 当前有哪些窗口
|
||
- 新增基于 Electron `webContents.sendInputEvent` 的底层输入注入：
|
||
- `simulate_mouse_click`
|
||
- `simulate_mouse_drag`
|
||
- `simulate_key_press`
|
||
- `simulate_key_combo`
|
||
- `simulate_preview_input`
|
||
|
||
暂时还没有直接补齐 Unity MCP 里的这些能力：
|
||
|
||
- 对 Scene/Game 面板做“语义级”识别仍然是 best-effort，依赖当前 Cocos 面板 DOM 结构
|
||
- Preview/Simulator 底层输入已经支持，但不同窗口标题和焦点状态可能需要先用 `list_editor_windows` 确认目标
|
||
- 动画曲线/状态机深度编辑
|
||
|
||
如果你要，我下一步可以继续补下一阶段，专门给你做：
|
||
|
||
1. `SceneView/GameView 精确截图裁剪`
|
||
2. `Preview/Simulator 键鼠事件注入`
|
||
3. `动画曲线和状态机编辑`
|
||
4. `更像 unity-mcp 的完整工具分层`
|