Docs: rewrite README and add MIT license

2026-04-15 17:50:17 +08:00
parent efd3330922
commit f7855ea912
3 changed files with 654 additions and 221 deletions
@@ -1,176 +1,108 @@
-# Funplay Cocos MCP
+<p align="center">
+  <h1 align="center">Funplay MCP for Cocos</h1>
+  <p align="center">
+    <strong>An Embedded MCP Server for Cocos Creator Editor</strong>
+  </p>
+  <p align="center">
+    <a href="#"><img src="https://img.shields.io/badge/Cocos%20Creator-3.8%2B-blue" alt="Cocos Creator 3.8+"></a>
+    <a href="#"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+    <a href="#"><img src="https://img.shields.io/badge/MCP-Compatible-green" alt="MCP Compatible"></a>
+    <a href="#"><img src="https://img.shields.io/badge/Platform-Editor%20Only-orange" alt="Editor Only"></a>
+  </p>
+  <p align="center">
+    <a href="./README_CN.md">中文</a> | English
+  </p>
+</p>

-一个嵌入在 `Cocos Creator 3.x` 扩展里的 MCP Server，对齐了你现有 `unity-mcp` 的核心思路：
+> If this project helps your Cocos workflow, please consider giving it a Star. It helps more developers discover the project and supports ongoing development.

- 编辑器内嵌 HTTP MCP 服务
- `execute_javascript` 作为统一主工具
- `tools / resources / prompts` 三层能力
- 场景树、节点、文件系统、项目上下文的统一访问
+---

-当前实现更偏向 Unity MCP 的 `core` 能力集，而不是一次性把全部 Unity 工具逐个照搬。
+Funplay MCP for Cocos is an MIT-licensed Cocos Creator extension that embeds an HTTP MCP server directly inside the editor. It lets AI assistants such as Claude Code, Cursor, Codex, VS Code Copilot, Trae, and Kiro inspect and operate your running Cocos project.

-## 已实现能力
+The package follows the same product direction as Funplay MCP for Unity: keep the default tool surface focused, provide a one-click client configuration window, and make one high-flexibility execution tool the primary workflow.

- 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`
+For Cocos, the primary tool is `execute_javascript`:

-## 安装方式
+- `context: "scene"` runs JavaScript in the active Cocos scene/runtime context
+- `context: "editor"` runs JavaScript in the Cocos editor/browser context

-把当前目录作为 Cocos Creator 扩展放到：
+> *"Create a login page UI with account/password fields and a main login button."*
+>
+> Your AI assistant can call `execute_javascript`, build the UI hierarchy under the active Canvas, attach Cocos components, inspect the result, and capture a screenshot for validation.

- 项目级：`<你的项目>/extensions/funplay-cocos-mcp`
- 全局级：`<Cocos Creator 用户扩展目录>/funplay-cocos-mcp`
+## Quick Start

-然后重启 Cocos Creator，扩展会默认自动启动 MCP 服务。
+If you just want to connect quickly, do these three things:

-默认地址：
+- Install this repository as a Cocos Creator extension
+- Open `Funplay > MCP Server`
+- Use the built-in one-click MCP client configuration

- `http://127.0.0.1:8765/`
+### 1. Install as a Cocos Creator Extension

-## 图形化面板
+Clone or copy this repository into your Cocos project extension directory:

-扩展启用后，可以在 Cocos Creator 顶部菜单打开：
+```bash
+cd /path/to/your-cocos-project
+mkdir -p extensions
+git clone https://github.com/FunplayAI/funplay-cocos-mcp.git extensions/funplay-cocos-mcp
+```

- `Funplay -> MCP Server`
+Then restart Cocos Creator or reload extensions from the editor.

-面板里可以直接完成：
+You can also install it globally by copying the folder into your Cocos Creator user extensions directory.

- 启动 / 停止 / 重启 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`、截图、诊断等常用工具
+### 2. Start the MCP Server

-一键配置当前支持：
+Open the editor menu:

- 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`
+```text
+Funplay > MCP Server
+```

-面板会使用当前端口写入 `funplay_cocos` MCP server。写入后请重启对应客户端。
+The server runs on `http://127.0.0.1:8765/` by default.

-## 可选配置
+The panel is intentionally small:

-在 Cocos 项目根目录放一个 `funplay-cocos-mcp.config.json`：
+- Enable or disable the MCP server
+- Change the server port
+- Switch tool exposure between `core` and `full`
+- Configure AI clients with one click
+- Expand debug output only when needed
+
+### 3. Configure Your AI Client
+
+Use the built-in **MCP Client Config** section in the `Funplay > MCP Server` panel first.
+
+Select your target client, click **One-Click Configure**, and the extension writes the recommended MCP config entry for you.
+
+The MCP server name written to clients is:
+
+```text
+funplay_cocos
+```
+
+If you prefer to edit config files manually, use the examples below as fallback references.
+
+<details>
+<summary>Claude Code / Claude Desktop</summary>

 ```json
 {
-  "host": "127.0.0.1",
-  "port": 8765,
-  "toolProfile": "core",
-  "autostart": true,
-  "maxInteractionLogEntries": 50
+  "mcpServers": {
+    "funplay_cocos": {
+      "type": "http",
+      "url": "http://127.0.0.1:8765/"
+    }
+  }
 }
 ```

-也支持环境变量：
+</details>

- `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
+<details>
+<summary>Cursor</summary>

 ```json
 {
@@ -182,109 +114,238 @@ url = "http://127.0.0.1:8765/"
 }
 ```

-## 推荐首测
+</details>

-先在 MCP Client 里调用：
+<details>
+<summary>VS Code</summary>

-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`
+```json
+{
+  "servers": {
+    "funplay_cocos": {
+      "type": "http",
+      "url": "http://127.0.0.1:8765/"
+    }
+  }
+}
+```

-其中 `execute_javascript` 是统一主工具，`execute_scene_script` / `execute_editor_script` 主要保留给兼容调用。
+</details>

-`execute_javascript` 示例，场景上下文：
+<details>
+<summary>Trae</summary>
+
+```json
+{
+  "mcpServers": {
+    "funplay_cocos": {
+      "url": "http://127.0.0.1:8765/"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Kiro</summary>
+
+```json
+{
+  "mcpServers": {
+    "funplay_cocos": {
+      "type": "http",
+      "url": "http://127.0.0.1:8765/"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Codex</summary>
+
+```toml
+[mcp_servers.funplay_cocos]
+url = "http://127.0.0.1:8765/"
+```
+
+</details>
+
+### 4. Verify the Connection
+
+Open your AI client and try a few safe requests first:
+
+- "Call `get_project_info` and summarize the current Cocos project."
+- "Read `cocos://project/context` and tell me the editor status."
+- "Use `execute_javascript` with `context: \"scene\"` to return the active scene name."
+- "Use `execute_javascript` with `context: \"editor\"` to return the project path."
+
+If these work, the MCP server, resources, prompts, and primary execution tool are connected correctly.
+
+### 5. Start Building
+
+Try a higher-level prompt in your AI client:
+
+> Create a login page UI in the current Cocos scene with account/password fields, a login button, and a guest-login button. Use `execute_javascript` first, inspect the hierarchy, then capture a screenshot.
+
+## Before You Start
+
+- This extension is **Editor-only**. It is meant to automate Cocos Creator, not to add runtime dependencies to your final game build.
+- The MCP server listens on `http://127.0.0.1:8765/` by default.
+- The default `core` profile exposes 50 high-signal tools. Switch to `full` in the panel if you want all 67 tools exposed.
+- All exposed MCP tools execute directly. There is no extra approval toggle inside the Cocos extension.
+- The recommended workflow is `execute_javascript` first, then focused helper tools for screenshots, diagnostics, assets, and inspection.
+- If you change the server port or tool exposure in the panel, the extension saves the config and restarts the server when needed.
+
+## Why This Project
+
+- **`execute_javascript` First** — One high-flexibility JavaScript tool can orchestrate scene/runtime work and editor-side automation without flooding AI clients with too many narrow tool calls
+- **Embedded Cocos Extension** — No separate Python daemon or external bridge process is required for the Cocos-side plugin
+- **One-Click Client Configuration** — Configure Claude Code, Cursor, VS Code, Trae, Kiro, and Codex directly from Cocos Creator
+- **Project Context Built In** — Exposes live project, scene, selection, script diagnostics, and interaction-history resources
+- **Focused by Default, Full When Needed** — `core` reduces tool-list noise; `full` exposes every available tool
+- **Visual Validation** — Scene/editor/preview screenshots and input simulation help AI verify UI and gameplay changes
+
+## Highlights
+
+- **67 Built-in Tools** — Scene hierarchy, assets, UI creation, components, files, script diagnostics, screenshots, runtime control, and input simulation
+- **Primary Unified Tool** — `execute_javascript` supports both `scene` and `editor` contexts
+- **Resources & Prompts** — Live project resources plus reusable workflows like script fixing, scene validation, and playable prototype creation
+- **Cocos Panel UI** — A minimal `Funplay > MCP Server` panel for service management and MCP client setup
+- **Screenshot and Input Support** — Capture editor/scene/game/preview screenshots and send Electron-level mouse/keyboard events
+- **Vendor Agnostic** — Works with any AI client that supports MCP over HTTP JSON-RPC
+
+## Relationship to Funplay MCP for Unity
+
+Funplay MCP for Cocos follows the same design principles as Funplay MCP for Unity, adapted to Cocos Creator's JavaScript/TypeScript editor environment.
+
+| Area | Funplay MCP for Cocos | Funplay MCP for Unity |
+|------|------------------------|------------------------|
+| Editor integration | Cocos Creator extension | Unity Editor package |
+| Embedded server | Built-in HTTP MCP server | Built-in HTTP MCP server |
+| Primary execution tool | `execute_javascript` | `execute_code` |
+| Primary language | JavaScript in scene/editor contexts | C# in Unity editor/runtime contexts |
+| Default profile | `core` with 50 tools | `core` focused tool profile |
+| Full profile | 67 tools | 79 tools |
+| Client setup | One-click config panel | One-click config window |
+
+## MCP Capabilities
+
+The current package exposes four capability layers:
+
+- **Tools** — 50 tools in `core`, 67 tools in `full`
+- **Primary execution** — `execute_javascript` for scene/runtime and editor/browser automation
+- **Prompts** — `fix_script_errors`, `create_playable_prototype`, `scene_validation`, and `auto_wire_scene`
+- **Resources** — project context, scene summaries, current selection, script diagnostics, asset selection, and MCP interaction history
+
+## Built-in Resources
+
+| Resource | Description |
+|----------|-------------|
+| `cocos://project/context` | Full project and editor context |
+| `cocos://project/summary` | Short project summary |
+| `cocos://scene/active` | Active scene snapshot |
+| `cocos://scene/current` | Alias for the current scene |
+| `cocos://selection/current` | Current editor selection |
+| `cocos://selection/asset` | Current selected asset |
+| `cocos://errors/scripts` | Script diagnostics |
+| `cocos://mcp/interactions` | Recent MCP interaction history |
+
+## Built-in Tools
+
+Funplay MCP for Cocos currently ships with **67 tool functions** in the `full` profile:
+
+| Category | Tools |
+|----------|-------|
+| **Script Execution** | `execute_javascript`, `execute_scene_script`, `execute_editor_script` |
+| **Project & Scene** | `get_project_info`, `get_scene_info`, `get_hierarchy`, `find_nodes`, `inspect_node`, `list_scenes`, `open_scene`, `run_scene_asset` |
+| **Node Editing** | `create_node`, `delete_node`, `set_node_transform` |
+| **Assets & Prefabs** | `list_assets`, `inspect_asset`, `open_asset`, `select_asset`, `delete_asset`, `list_prefabs`, `instantiate_prefab`, `get_editor_selection` |
+| **Components** | `list_components`, `inspect_component`, `add_component`, `remove_component`, `set_component_property`, `reset_component_property` |
+| **UI** | `create_canvas`, `create_label`, `create_button`, `create_sprite` |
+| **Camera** | `list_cameras`, `create_camera`, `set_camera_properties` |
+| **Animation** | `list_animations`, `add_animation_clip`, `play_animation`, `stop_animation` |
+| **Files** | `read_file`, `get_file_snippet`, `write_file`, `replace_in_file`, `search_files`, `list_directory`, `exists`, `refresh_assets` |
+| **Diagnostics** | `run_script_diagnostics`, `get_script_diagnostic_context` |
+| **Runtime** | `get_runtime_state`, `pause_runtime`, `resume_runtime`, `set_time_scale` |
+| **Interaction** | `emit_node_event`, `simulate_button_click`, `invoke_component_method`, `simulate_mouse_click`, `simulate_mouse_drag`, `simulate_key_press`, `simulate_key_combo`, `simulate_preview_input` |
+| **Screenshots & Windows** | `capture_desktop_screenshot`, `capture_editor_screenshot`, `capture_scene_screenshot`, `capture_game_screenshot`, `capture_preview_screenshot`, `list_editor_windows` |
+
+## Primary Tool Examples
+
+### Scene Context

 ```json
 {
  "context": "scene",
-  "code": "return { sceneName: scene.name, rootCount: scene.children.length };"
+  "code": "return { sceneName: scene.name, rootCount: scene.children.length };",
+  "args": {}
 }
 ```

-`execute_javascript` 示例，编辑器上下文：
+### Editor Context

 ```json
 {
  "context": "editor",
-  "code": "return { projectPath: context.projectPath, toolCount: helpers.listTools().length };"
+  "code": "return { projectPath: context.projectPath, toolCount: helpers.listTools().length };",
+  "args": {}
 }
 ```

-`execute_scene_script.code` 兼容示例：
+Editor-context scripts receive `Editor`, `fs`, `path`, `os`, `require`, `context`, `args`, and helper functions such as `helpers.getStatus()`, `helpers.listTools()`, `helpers.readResource(uri)`, `helpers.callTool(name, args)`, and `helpers.configureClient(targetId)`.

-```js
-return {
-  sceneName: scene.name,
-  rootChildren: scene.children.map((node) => node.name),
-};
+## Optional Configuration
+
+Place `funplay-cocos-mcp.config.json` in the Cocos project root:
+
+```json
+{
+  "host": "127.0.0.1",
+  "port": 8765,
+  "toolProfile": "core",
+  "autostart": true,
+  "maxInteractionLogEntries": 50
+}
 ```

-## 和 Unity MCP 的对应关系
+Environment variables are also supported:

- 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`
+- `COCOS_MCP_HOST`
+- `COCOS_MCP_PORT`
+- `COCOS_MCP_PROFILE`

-## 当前边界
+## Architecture

-这版已经进入第二阶段，补上了：
+```text
+Cocos Creator Extension
+    ├─ browser.js
+    │   ├─ Embedded HTTP MCP Server
+    │   ├─ Tool Registry
+    │   ├─ Resource Provider
+    │   ├─ Prompt Provider
+    │   └─ One-Click Client Configuration
+    ├─ scene.js
+    │   └─ Scene/runtime execution bridge
+    ├─ panel/index.js
+    │   └─ Minimal MCP Server panel
+    └─ lib/
+        ├─ assets, diagnostics, screenshots, input
+        └─ server, resources, prompts, tool registry
+```

- 资产查询 / 打开 / 删除 / 选中
- TypeScript 脚本诊断
- 本机桌面截图回传 MCP image
+The server speaks MCP-style HTTP JSON-RPC 2.0 and supports tools, resources, resource templates, prompts, and health checks.

-现在第三段也补上了：
+## Development

- 组件增删查改
- Scene / Prefab 资产工具
- 脚本修复辅助链路：`get_script_diagnostic_context` + `replace_in_file`
+Run a syntax check before publishing changes:

-第四段继续补上了：
+```bash
+npm run check
+```

- UI 专用工具：Canvas / Label / Button / Sprite 创建
- Camera 专用工具：列出、创建、属性设置
- Animation 专用工具：列出、添加 Clip、播放、停止
- 运行态控制：暂停、恢复、时间缩放、状态查询
- 输入/交互模拟：按钮点击、节点事件、组件方法调用
- 截图增强：桌面截图、Editor 窗口截图、场景截图别名
+## License

-这次把之前两块缺口也补了：
-
- `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 的完整工具分层`
+MIT License. See [LICENSE](./LICENSE).