diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..3dcac79
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Funplay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
index 514ceef..ca2f670 100644
--- a/README.md
+++ b/README.md
@@ -1,176 +1,108 @@
-# Funplay Cocos MCP
+
+
Funplay MCP for Cocos
+
+ An Embedded MCP Server for Cocos Creator Editor
+
+
+ 
+ 
+ 
+ 
+
+
+ 中文 | English
+
+
-一个嵌入在 `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`
-- 全局级：`/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.
+
+
+Claude Code / Claude Desktop
```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/"
+ }
+ }
}
```
-也支持环境变量：
+
-- `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
+
+Cursor
```json
{
@@ -182,109 +114,238 @@ url = "http://127.0.0.1:8765/"
}
```
-## 推荐首测
+
-先在 MCP Client 里调用：
+
+VS Code
-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` 主要保留给兼容调用。
+
-`execute_javascript` 示例，场景上下文：
+
+Trae
+
+```json
+{
+ "mcpServers": {
+ "funplay_cocos": {
+ "url": "http://127.0.0.1:8765/"
+ }
+ }
+}
+```
+
+
+
+
+Kiro
+
+```json
+{
+ "mcpServers": {
+ "funplay_cocos": {
+ "type": "http",
+ "url": "http://127.0.0.1:8765/"
+ }
+ }
+}
+```
+
+
+
+
+Codex
+
+```toml
+[mcp_servers.funplay_cocos]
+url = "http://127.0.0.1:8765/"
+```
+
+
+
+### 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).
diff --git a/README_CN.md b/README_CN.md
new file mode 100644
index 0000000..7793ffd
--- /dev/null
+++ b/README_CN.md
@@ -0,0 +1,351 @@
+
+
Funplay MCP for Cocos
+
+ 嵌入 Cocos Creator 编辑器的 MCP Server
+
+
+
+
+
+
+
+
+ 中文 | English
+
+
+
+> 如果这个项目对你有帮助，欢迎顺手点一个 Star。它能帮助更多 Cocos 开发者发现项目，也能支持后续持续维护。
+
+---
+
+Funplay MCP for Cocos 是一个采用 MIT 协议的 Cocos Creator 扩展，它把 HTTP MCP Server 直接嵌入编辑器，让 Claude Code、Cursor、Codex、VS Code Copilot、Trae、Kiro 等 AI 助手可以直接检查和操作正在运行的 Cocos 项目。
+
+这个项目延续 Funplay MCP for Unity 的产品方向：默认工具面保持聚焦，提供一键客户端配置，并围绕一个高灵活度主执行工具组织工作流。
+
+在 Cocos 里，主工具是 `execute_javascript`：
+
+- `context: "scene"` 在当前 Cocos 场景/运行态上下文执行 JavaScript
+- `context: "editor"` 在 Cocos 编辑器/browser 上下文执行 JavaScript
+
+> *“在当前场景里创建一个登录页 UI，包含账号/密码输入框和登录按钮。”*
+>
+> AI 助手可以调用 `execute_javascript`，在当前 Canvas 下生成 UI 层级，挂载 Cocos 组件，检查层级，并截图验证效果。
+
+## 快速开始
+
+如果你只想尽快连上，先做这三步：
+
+- 把这个仓库安装为 Cocos Creator 扩展
+- 打开 `Funplay > MCP Server`
+- 使用内置的一键 MCP 客户端配置
+
+### 1. 安装为 Cocos Creator 扩展
+
+把仓库 clone 或复制到 Cocos 项目的扩展目录：
+
+```bash
+cd /path/to/your-cocos-project
+mkdir -p extensions
+git clone https://github.com/FunplayAI/funplay-cocos-mcp.git extensions/funplay-cocos-mcp
+```
+
+然后重启 Cocos Creator，或在编辑器里重新加载扩展。
+
+你也可以把目录复制到 Cocos Creator 的全局用户扩展目录中。
+
+### 2. 启动 MCP Server
+
+打开编辑器菜单：
+
+```text
+Funplay > MCP Server
+```
+
+服务默认运行在 `http://127.0.0.1:8765/`。
+
+面板刻意保持精简：
+
+- 启用或停用 MCP Server
+- 修改服务端口
+- 在 `core` / `full` 工具暴露模式之间切换
+- 一键配置 AI 客户端
+- 需要时再展开 Debug Output
+
+### 3. 配置 AI 客户端
+
+优先使用 `Funplay > MCP Server` 面板里的 **MCP Client Config** 区域。
+
+选择目标客户端，点击 **One-Click Configure**，扩展会直接写入推荐的 MCP 配置项。
+
+写入客户端的 MCP server 名称是：
+
+```text
+funplay_cocos
+```
+
+如果你更想手动编辑配置文件，再参考下面这些示例。
+
+
+Claude Code / Claude Desktop
+
+```json
+{
+ "mcpServers": {
+ "funplay_cocos": {
+ "type": "http",
+ "url": "http://127.0.0.1:8765/"
+ }
+ }
+}
+```
+
+
+
+
+Cursor
+
+```json
+{
+ "mcpServers": {
+ "funplay_cocos": {
+ "url": "http://127.0.0.1:8765/"
+ }
+ }
+}
+```
+
+
+
+
+VS Code
+
+```json
+{
+ "servers": {
+ "funplay_cocos": {
+ "type": "http",
+ "url": "http://127.0.0.1:8765/"
+ }
+ }
+}
+```
+
+
+
+
+Trae
+
+```json
+{
+ "mcpServers": {
+ "funplay_cocos": {
+ "url": "http://127.0.0.1:8765/"
+ }
+ }
+}
+```
+
+
+
+
+Kiro
+
+```json
+{
+ "mcpServers": {
+ "funplay_cocos": {
+ "type": "http",
+ "url": "http://127.0.0.1:8765/"
+ }
+ }
+}
+```
+
+
+
+
+Codex
+
+```toml
+[mcp_servers.funplay_cocos]
+url = "http://127.0.0.1:8765/"
+```
+
+
+
+### 4. 验证连接
+
+先在 AI 客户端里试几个安全请求：
+
+- “调用 `get_project_info`，总结当前 Cocos 项目。”
+- “读取 `cocos://project/context`，告诉我当前编辑器状态。”
+- “用 `execute_javascript` 的 `context: \"scene\"` 返回当前场景名。”
+- “用 `execute_javascript` 的 `context: \"editor\"` 返回项目路径。”
+
+如果这些都正常返回，说明 MCP server、resources、prompts 和主执行工具已经连通。
+
+### 5. 开始构建
+
+可以在 AI 客户端里尝试：
+
+> 在当前 Cocos 场景里创建一个登录页 UI，包含账号/密码输入框、登录按钮和游客登录按钮。优先使用 `execute_javascript`，创建后检查层级并截图验证。
+
+## 开始前说明
+
+- 这是一个 **仅限 Editor** 的扩展，用于自动化 Cocos Creator，不会给最终游戏包添加运行时依赖。
+- MCP Server 默认监听 `http://127.0.0.1:8765/`。
+- 默认 `core` profile 暴露 50 个高频工具；如果需要完整工具集，可在面板切到 `full`，暴露全部 67 个工具。
+- 所有已暴露的 MCP 工具都会直接执行，Cocos 扩展里没有额外 approval 开关。
+- 推荐工作流是优先使用 `execute_javascript`，再配合截图、诊断、资产、检查类工具。
+- 如果在面板里修改端口或工具暴露模式，扩展会自动保存配置，并在需要时重启服务。
+
+## 为什么做这个项目
+
+- **`execute_javascript` 主工具优先** — 一个高灵活度 JavaScript 工具就能编排场景/运行态和编辑器自动化，避免 AI 客户端被大量细碎工具干扰
+- **嵌入式 Cocos 扩展** — Cocos 侧不需要单独 Python 守护进程或外部 bridge
+- **一键客户端配置** — 在 Cocos Creator 内直接配置 Claude Code、Cursor、VS Code、Trae、Kiro、Codex
+- **内建项目上下文** — 直接暴露项目、场景、选择、脚本诊断和交互历史资源
+- **默认聚焦，必要时全量** — `core` 降低工具列表噪音，需要时切到 `full` 暴露全部工具
+- **可视化验证** — 截图和输入模拟让 AI 能验证 UI 与玩法改动
+
+## 核心特性
+
+- **67 个内置工具** — 覆盖场景层级、资产、UI 创建、组件、文件、脚本诊断、截图、运行态控制和输入模拟
+- **统一主工具** — `execute_javascript` 同时支持 `scene` 和 `editor` 两种上下文
+- **Resources 与 Prompts** — 实时项目资源，以及脚本修复、场景验证、可玩原型等可复用工作流
+- **Cocos 图形面板** — `Funplay > MCP Server` 提供极简服务管理与 MCP 客户端配置
+- **截图与输入支持** — 支持编辑器/场景/Game/Preview 截图，以及 Electron 级鼠标键盘事件
+- **厂商无关** — 兼容任意支持 HTTP JSON-RPC MCP 的 AI 客户端
+
+## 与 Funplay MCP for Unity 的关系
+
+Funplay MCP for Cocos 延续 Funplay MCP for Unity 的设计原则，并针对 Cocos Creator 的 JavaScript/TypeScript 编辑器环境做了适配。
+
+| 维度 | Funplay MCP for Cocos | Funplay MCP for Unity |
+|------|------------------------|------------------------|
+| 编辑器集成 | Cocos Creator 扩展 | Unity Editor 包 |
+| 内置服务 | 内嵌 HTTP MCP Server | 内嵌 HTTP MCP Server |
+| 主执行工具 | `execute_javascript` | `execute_code` |
+| 主语言 | 场景/编辑器上下文中的 JavaScript | Unity 编辑器/运行态中的 C# |
+| 默认工具集 | `core`，50 个工具 | 聚焦版 `core` 工具集 |
+| 完整工具集 | 67 个工具 | 79 个工具 |
+| 客户端配置 | 一键配置面板 | 一键配置窗口 |
+
+## MCP 能力结构
+
+当前包提供四层能力：
+
+- **Tools** — `core` 下 50 个工具，`full` 下 67 个工具
+- **Primary execution** — `execute_javascript` 用于场景/运行态和编辑器/browser 自动化
+- **Prompts** — `fix_script_errors`、`create_playable_prototype`、`scene_validation`、`auto_wire_scene`
+- **Resources** — 项目上下文、场景摘要、当前选择、脚本诊断、资产选择和 MCP 交互历史
+
+## 内置 Resources
+
+| Resource | 说明 |
+|----------|------|
+| `cocos://project/context` | 完整项目与编辑器上下文 |
+| `cocos://project/summary` | 项目摘要 |
+| `cocos://scene/active` | 当前场景快照 |
+| `cocos://scene/current` | 当前场景别名 |
+| `cocos://selection/current` | 当前编辑器选择 |
+| `cocos://selection/asset` | 当前选中资产 |
+| `cocos://errors/scripts` | 脚本诊断信息 |
+| `cocos://mcp/interactions` | 最近 MCP 交互历史 |
+
+## 内置工具
+
+Funplay MCP for Cocos 当前在 `full` profile 下提供 **67 个工具函数**：
+
+| 分类 | 工具 |
+|------|------|
+| **脚本执行** | `execute_javascript`, `execute_scene_script`, `execute_editor_script` |
+| **项目与场景** | `get_project_info`, `get_scene_info`, `get_hierarchy`, `find_nodes`, `inspect_node`, `list_scenes`, `open_scene`, `run_scene_asset` |
+| **节点编辑** | `create_node`, `delete_node`, `set_node_transform` |
+| **资产与 Prefab** | `list_assets`, `inspect_asset`, `open_asset`, `select_asset`, `delete_asset`, `list_prefabs`, `instantiate_prefab`, `get_editor_selection` |
+| **组件** | `list_components`, `inspect_component`, `add_component`, `remove_component`, `set_component_property`, `reset_component_property` |
+| **UI** | `create_canvas`, `create_label`, `create_button`, `create_sprite` |
+| **相机** | `list_cameras`, `create_camera`, `set_camera_properties` |
+| **动画** | `list_animations`, `add_animation_clip`, `play_animation`, `stop_animation` |
+| **文件** | `read_file`, `get_file_snippet`, `write_file`, `replace_in_file`, `search_files`, `list_directory`, `exists`, `refresh_assets` |
+| **诊断** | `run_script_diagnostics`, `get_script_diagnostic_context` |
+| **运行态** | `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` |
+| **截图与窗口** | `capture_desktop_screenshot`, `capture_editor_screenshot`, `capture_scene_screenshot`, `capture_game_screenshot`, `capture_preview_screenshot`, `list_editor_windows` |
+
+## 主工具示例
+
+### Scene 上下文
+
+```json
+{
+ "context": "scene",
+ "code": "return { sceneName: scene.name, rootCount: scene.children.length };",
+ "args": {}
+}
+```
+
+### Editor 上下文
+
+```json
+{
+ "context": "editor",
+ "code": "return { projectPath: context.projectPath, toolCount: helpers.listTools().length };",
+ "args": {}
+}
+```
+
+Editor 上下文脚本可以访问 `Editor`、`fs`、`path`、`os`、`require`、`context`、`args`，以及 `helpers.getStatus()`、`helpers.listTools()`、`helpers.readResource(uri)`、`helpers.callTool(name, args)`、`helpers.configureClient(targetId)` 等辅助函数。
+
+## 可选配置
+
+在 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`
+
+## 架构
+
+```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
+```
+
+服务使用 MCP 风格的 HTTP JSON-RPC 2.0，支持 tools、resources、resource templates、prompts 和 health check。
+
+## 开发
+
+发布改动前可以跑语法检查：
+
+```bash
+npm run check
+```
+
+## 协议
+
+MIT License。详见 [LICENSE](./LICENSE)。