chore: 纳入项目全部源码进根仓库统一管理

删除 YouleNexus 内嵌 .git，统一由根仓库唯一管理。提交： - projects/ 旧 H5 模板 Game_Surface_3 与各子游戏源码 - cocoscreator_projects/YouleNexus 工程 + cocos-creator-mcp 扩展源码 - CLAUDE.md、.mcp.json 等配置 library/temp/node_modules/dist 等缓存由 .gitignore 排除。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-28 11:55:13 +08:00
parent f5673c33c8
commit 7ab748919a
7317 changed files with 2810014 additions and 0 deletions
@@ -0,0 +1,539 @@
+# Cocos Creator MCP
+
+[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server extension for Cocos Creator 3.8+.
+
+AI assistants like Claude can control Cocos Creator editor through this extension — creating nodes, editing scenes, managing prefabs, building projects, and more.
+
+## Features
+
+- **164 Tools** across 13 categories — comprehensive editor automation
+- **Streamable HTTP (SSE)** — Native support for MCP's Streamable HTTP transport
+- **JSON-RPC 2.0** — Standard MCP protocol compliance
+- **Prefab Property Persistence** — Component properties are correctly preserved when saving prefabs
+- **Preview in Editor** — Start editor preview programmatically (no manual button click needed)
+- **Screenshot Capture** — Capture editor window and game preview screenshots (WebP / PNG)
+- **Video Recording** — Record game preview canvas to video (MP4 / WebM) via Preview Recorder panel
+- **Game Command Control** — Send commands to running game preview (screenshot, click, navigate, state, inspect)
+- **Client Scripts** — Drop-in TypeScript files for game preview integration (`client/`)
+- **Auto Start** — Server starts automatically when the extension loads
+- **Tool Call Logging** — All tool invocations logged with timing for debugging
+- **UUID Validation** — Input validation helpers for better error messages
+- **i18n** — English, Japanese, Chinese
+- **Regression Tests** — 200+ assertions covering core tool flows
+
+## Quick Start
+
+### 1. Install
+
+Copy or symlink this extension into your Cocos Creator project's `extensions/` directory:
+
+```bash
+# Windows (Junction — no admin required)
+mklink /J "your-project\extensions\cocos-creator-mcp" "path\to\cocos-creator-mcp"
+
+# macOS / Linux
+ln -s /path/to/cocos-creator-mcp your-project/extensions/cocos-creator-mcp
+```
+
+### 2. Build
+
+```bash
+cd cocos-creator-mcp
+npm install
+npm run build
+```
+
+### 3. Enable in Cocos Creator
+
+1. Open your project in Cocos Creator
+2. Go to **Extension > Extension Manager**
+3. Enable **Cocos Creator MCP**
+4. Open the panel: **Extension > Cocos Creator MCP > Open Panel**
+5. Click **Start Server** (or set `autoStart: true` in config)
+
+### 4. Connect from Claude Code
+
+Pick one of the two transports below.
+
+#### Option A — stdio bridge (recommended for Claude Code VSCode extension)
+
+The Claude Code VSCode extension currently has a bug where it unconditionally
+tries OAuth Dynamic Client Registration for HTTP-type MCP servers and fails
+with `SDK auth failed` (see upstream issues
+[#26917](https://github.com/anthropics/claude-code/issues/26917),
+[#38102](https://github.com/anthropics/claude-code/issues/38102),
+[#29697](https://github.com/anthropics/claude-code/issues/29697)).
+To avoid it entirely, use the bundled stdio bridge. It speaks JSON-RPC on
+stdin/stdout and forwards to the HTTP server internally.
+
+```json
+{
+  "mcpServers": {
+    "cocos-creator-mcp": {
+      "command": "node",
+      "args": [
+        "<ABSOLUTE_PATH_TO>/cocos-creator-mcp/client/stdio-bridge.js"
+      ]
+    }
+  }
+}
+```
+
+Optional env var: `COCOS_MCP_URL` (default `http://127.0.0.1:3000/mcp`).
+
+#### Option B — direct HTTP
+
+Works with Claude Code CLI, Cursor, Cline, and other clients that don't force
+OAuth on HTTP MCP. The server ships minimal dummy OAuth endpoints
+(`/.well-known/oauth-*`, `/oauth/register|authorize|token`) so OAuth-requiring
+clients can still complete a pro-forma flow on localhost.
+
+```json
+{
+  "mcpServers": {
+    "cocos-creator-mcp": {
+      "type": "http",
+      "url": "http://127.0.0.1:3000/mcp"
+    }
+  }
+}
+```
+
+> The dummy OAuth endpoints will be removed once upstream issues
+> ([#26917](https://github.com/anthropics/claude-code/issues/26917),
+> [#38102](https://github.com/anthropics/claude-code/issues/38102))
+> are resolved or real authentication is introduced.
+
+### 5. Verify
+
+```bash
+curl http://127.0.0.1:3000/health
+# {"status":"ok","tools":164}
+```
+
+## Available Tools (164)
+
+<details>
+<summary><strong>Scene (6)</strong> — Scene lifecycle and hierarchy</summary>
+
+| Tool | Description |
+|------|-------------|
+| `scene_get_hierarchy` | Get the node tree (with optional component info) |
+| `scene_open` | Open a scene by UUID or db:// path |
+| `scene_save` | Save the current scene |
+| `scene_get_list` | List all .scene files |
+| `scene_close` | Close the current scene |
+| `scene_get_current` | Get name and UUID of the current scene |
+</details>
+
+<details>
+<summary><strong>Scene Advanced (30)</strong> — Undo, clipboard, queries, property manipulation</summary>
+
+| Tool | Description |
+|------|-------------|
+| `scene_execute_script` | Execute a custom scene script method |
+| `scene_snapshot` | Take a snapshot for undo |
+| `scene_snapshot_abort` | Abort the current undo snapshot |
+| `scene_begin_undo` | Begin recording undo operations |
+| `scene_end_undo` | End undo recording |
+| `scene_cancel_undo` | Cancel undo recording |
+| `scene_query_dirty` | Check if scene has unsaved changes |
+| `scene_query_ready` | Check if scene is fully loaded |
+| `scene_query_classes` | List all available component classes |
+| `scene_query_components` | Query components for a node |
+| `scene_query_component_has_script` | Check if a component has a script file |
+| `scene_query_node_tree` | Get raw node tree from editor |
+| `scene_query_node` | Get full property dump of a node |
+| `scene_query_component` | Get full property dump of a component |
+| `scene_query_nodes_by_asset` | Find nodes referencing an asset |
+| `scene_query_scene_bounds` | Get scene bounding rect |
+| `scene_soft_reload` | Soft reload scene |
+| `scene_reset_node_transform` | Reset transform to default |
+| `scene_reset_property` | Reset a specific property to default |
+| `scene_reset_component` | Reset a component to defaults |
+| `scene_copy_node` | Copy node to clipboard |
+| `scene_paste_node` | Paste node from clipboard |
+| `scene_cut_node` | Cut node to clipboard |
+| `scene_create` | Create a new empty scene |
+| `scene_save_as` | Save scene to a new file |
+| `scene_set_parent` | Reparent node(s) with official API |
+| `scene_restore_prefab` | Restore prefab node to original state |
+| `scene_execute_component_method` | Call a method on a component |
+| `scene_move_array_element` | Reorder array property element |
+| `scene_remove_array_element` | Remove array property element |
+</details>
+
+<details>
+<summary><strong>Scene View (19)</strong> — Gizmo, camera, grid, viewport</summary>
+
+| Tool | Description |
+|------|-------------|
+| `view_change_gizmo_tool` | Switch gizmo tool (move/rotate/scale/rect) |
+| `view_query_gizmo_tool` | Get current gizmo tool |
+| `view_change_gizmo_pivot` | Change pivot mode (center/pivot) |
+| `view_query_gizmo_pivot` | Get current pivot mode |
+| `view_change_gizmo_coordinate` | Change coordinate system (local/global) |
+| `view_query_gizmo_coordinate` | Get current coordinate system |
+| `view_change_mode_2d_3d` | Switch 2D/3D view |
+| `view_query_mode_2d_3d` | Get current view mode |
+| `view_set_grid_visible` | Show/hide grid |
+| `view_query_grid_visible` | Check grid visibility |
+| `view_set_icon_gizmo_3d` | Toggle 3D icon gizmos |
+| `view_query_icon_gizmo_3d` | Check 3D icon gizmo state |
+| `view_set_icon_gizmo_size` | Set icon gizmo size |
+| `view_query_icon_gizmo_size` | Get icon gizmo size |
+| `view_focus_on_node` | Focus camera on node(s) |
+| `view_align_with_view` | Align node with camera view |
+| `view_align_view_with_node` | Align camera with node |
+| `view_get_status` | Get all view settings at once |
+| `view_reset` | Reset scene view to default |
+</details>
+
+<details>
+<summary><strong>Node (14)</strong> — Create, edit, move, delete nodes</summary>
+
+| Tool | Description |
+|------|-------------|
+| `node_create` | Create node (with optional components) |
+| `node_get_info` | Get node details (position, scale, components) |
+| `node_find_by_name` | Find nodes by name |
+| `node_set_property` | Set node property |
+| `node_set_transform` | Set position/rotation/scale at once |
+| `node_set_active` | Set node visibility |
+| `node_set_layer` | Set node layer |
+| `node_delete` | Delete node |
+| `node_move` | Move node to new parent |
+| `node_duplicate` | Duplicate node |
+| `node_get_all` | List all nodes |
+| `node_detect_type` | Detect node type (2D/3D/Node) |
+| `node_create_tree` | Create a node hierarchy in one call (v1.6) |
+| `node_set_layout` | Set UITransform + Widget + color/opacity at once (v1.13) |
+</details>
+
+<details>
+<summary><strong>Component (8)</strong> — Add, remove, configure components</summary>
+
+| Tool | Description |
+|------|-------------|
+| `component_add` | Add component (e.g. `cc.Label`, `cc.Sprite`) |
+| `component_remove` | Remove component |
+| `component_get_components` | List components on node |
+| `component_set_property` | Set component property (Label.string, fontSize, etc.) |
+| `component_get_info` | Get full component dump by UUID |
+| `component_get_available` | List all available component classes |
+| `component_auto_bind` | Auto-match `@property` fields to nodes by name (v1.12) |
+| `component_query_enum` | Query enum values of a component property (v1.6) |
+</details>
+
+<details>
+<summary><strong>Prefab (12)</strong> — Prefab lifecycle and validation</summary>
+
+| Tool | Description |
+|------|-------------|
+| `prefab_list` | List all prefabs |
+| `prefab_create` | Create prefab from node (properties preserved) |
+| `prefab_instantiate` | Instantiate prefab into scene |
+| `prefab_get_info` | Get prefab asset info |
+| `prefab_update` | Apply prefab changes |
+| `prefab_revert` | Revert prefab instance to original |
+| `prefab_duplicate` | Copy prefab to new path |
+| `prefab_validate` | Validate prefab for broken references |
+| `prefab_open` | Open prefab for editing (v1.5) |
+| `prefab_close` | Close prefab editing mode and return to scene (v1.5) |
+| `prefab_create_and_replace` | Create prefab and replace instance in one call (v1.5) |
+| `prefab_create_from_spec` | Create node tree + auto-bind + prefab_create in one call (v1.12) |
+</details>
+
+<details>
+<summary><strong>Asset (18)</strong> — CRUD, queries, metadata, dependencies</summary>
+
+| Tool | Description |
+|------|-------------|
+| `asset_create` | Create new asset |
+| `asset_delete` | Delete asset |
+| `asset_move` | Move/rename asset |
+| `asset_copy` | Copy asset |
+| `asset_save` | Save asset |
+| `asset_reimport` | Re-import asset |
+| `asset_import` | Import external file into project |
+| `asset_query_path` | Get file path for UUID |
+| `asset_query_uuid` | Get UUID for path |
+| `asset_query_url` | Get URL for UUID |
+| `asset_get_details` | Get asset metadata |
+| `asset_get_dependencies` | Get asset dependencies |
+| `asset_open_external` | Open in external editor |
+| `asset_save_meta` | Save asset meta/importer settings |
+| `asset_generate_available_url` | Generate non-conflicting asset path |
+| `asset_query_ready` | Check if asset DB is ready |
+| `asset_query_users` | Find assets that reference this asset |
+| `asset_query_missing` | Check for missing references |
+</details>
+
+<details>
+<summary><strong>Project (8)</strong> — Project info, settings, engine</summary>
+
+| Tool | Description |
+|------|-------------|
+| `project_get_info` | Get project name and path |
+| `project_refresh_assets` | Refresh asset database |
+| `project_get_asset_info` | Get asset info by UUID |
+| `project_find_asset` | Find assets by glob pattern |
+| `project_get_settings` | Get project settings |
+| `project_set_settings` | Set a project setting |
+| `project_get_engine_info` | Get engine version and paths |
+| `project_query_scripts` | Query all script plugins |
+</details>
+
+<details>
+<summary><strong>Preferences (4)</strong> — Editor preferences</summary>
+
+| Tool | Description |
+|------|-------------|
+| `preferences_get` | Get preference value |
+| `preferences_set` | Set preference value |
+| `preferences_get_all` | Get all preferences for a protocol |
+| `preferences_reset` | Reset preference to default |
+</details>
+
+<details>
+<summary><strong>Debug (22)</strong> — Editor info, logs, preview, screenshots, recording, game control</summary>
+
+| Tool | Description |
+|------|-------------|
+| `debug_get_editor_info` | Get editor version and environment |
+| `debug_list_messages` | List available Editor messages |
+| `debug_execute_script` | Execute scene script method |
+| `debug_get_console_logs` | Get console log entries (scene + game preview) |
+| `debug_clear_console` | Clear editor console and log buffers |
+| `debug_preview` | Start Preview in Editor (play button) |
+| `debug_clear_code_cache` | Clear code cache (Developer > Cache) |
+| `debug_screenshot` | Capture editor window screenshot |
+| `debug_game_command` | Send command to game preview (screenshot/click/navigate/state/inspect) |
+| `debug_batch_screenshot` | Navigate to multiple pages and screenshot each |
+| `debug_record_start` | Start recording game preview canvas (webm/mp4) |
+| `debug_record_stop` | Stop recording and save video file |
+| `debug_reload_extension` | Reload this MCP extension (after build) |
+| `debug_list_extensions` | List installed extensions |
+| `debug_get_extension_info` | Get extension details |
+| `debug_get_project_logs` | Read project log entries |
+| `debug_search_project_logs` | Search patterns in project logs |
+| `debug_get_log_file_info` | Get log file metadata |
+| `debug_validate_scene` | Validate scene for common issues |
+| `debug_query_devices` | List connected devices |
+| `debug_open_url` | Open URL in system browser |
+| `debug_wait_compile` | Wait for TypeScript compile to finish (v1.12) |
+</details>
+
+<details>
+<summary><strong>Server (7)</strong> — Editor server and network</summary>
+
+| Tool | Description |
+|------|-------------|
+| `server_query_ip_list` | Get editor server IPs |
+| `server_query_port` | Get editor server port |
+| `server_get_status` | Get full server status |
+| `server_check_connectivity` | Check if editor server is reachable |
+| `server_get_network_interfaces` | Get network interface details |
+| `server_get_build_hash` | Get build hash of MCP dist files (v1.6) |
+| `server_check_code_sync` | Check if runtime matches dist hash (v1.6) |
+</details>
+
+<details>
+<summary><strong>Builder (5)</strong> — Build and preview</summary>
+
+| Tool | Description |
+|------|-------------|
+| `builder_open_panel` | Open Build panel |
+| `builder_get_settings` | Get build configuration |
+| `builder_query_tasks` | Query active build tasks |
+| `builder_run_preview` | Start preview server |
+| `builder_stop_preview` | Stop preview server |
+</details>
+
+<details>
+<summary><strong>Reference Image (11)</strong> — Scene overlay images</summary>
+
+| Tool | Description |
+|------|-------------|
+| `refimage_add` | Add a reference image |
+| `refimage_remove` | Remove a reference image |
+| `refimage_list` | List all reference images |
+| `refimage_clear_all` | Remove all reference images |
+| `refimage_switch` | Switch active reference image |
+| `refimage_set_position` | Set image position |
+| `refimage_set_scale` | Set image scale |
+| `refimage_set_opacity` | Set image opacity |
+| `refimage_query_config` | Get reference image config |
+| `refimage_query_current` | Get current active image info |
+| `refimage_refresh` | Refresh image display |
+</details>
+
+## Client Scripts
+
+The `client/` directory contains TypeScript files for runtime communication between the game preview and the MCP server. Since the extension is installed in `extensions/`, these files can be imported directly — no copying needed.
+
+### McpConsoleCapture
+
+Captures `console.log/warn/error` from the game preview and sends them to the MCP server.
+
+```typescript
+// Import from extensions/ (adjust relative path as needed)
+import { initMcpConsoleCapture } from "../../extensions/cocos-creator-mcp/client/McpConsoleCapture";
+initMcpConsoleCapture();
+```
+
+### McpDebugClient
+
+Enables AI-driven game control: screenshots, node clicking, and custom commands.
+
+```typescript
+import { initMcpDebugClient } from "../../extensions/cocos-creator-mcp/client/McpDebugClient";
+
+initMcpDebugClient({
+    customCommands: {
+        // Add project-specific commands
+        state: () => ({ success: true, data: { dump: MyDb.dump() } }),
+        navigate: async (args) => {
+            await MyRouter.goTo(args.page);
+            return { success: true };
+        },
+    },
+});
+```
+
+**Built-in commands** (no setup needed):
+- `screenshot` — Capture game screen via RenderTexture
+- `click` — Click a node by name
+
+**Custom commands** (project-specific):
+- Register any handler via `customCommands` option
+- Called via `debug_game_command` MCP tool
+
+Both scripts silently ignore when the MCP server is not running, so they are safe to leave in development builds.
+
+## Console Log Capture (Details)
+
+`debug_get_console_logs` captures logs from two sources:
+
+### Scene Process Logs (automatic)
+
+Console output from scene scripts (`console.log/warn/error` in the scene renderer process) is automatically captured. No setup required.
+
+### Game Preview Logs (opt-in)
+
+Game code runs in a browser during preview, which is a separate process. To capture game preview logs, your game code needs to send logs to the MCP server's `/log` endpoint.
+
+**Setup:**
+
+Add a console capture script to your game project:
+
+```typescript
+const MCP_LOG_URL = "http://127.0.0.1:3000/log";
+const FLUSH_INTERVAL = 500;
+
+let buffer: Array<{ timestamp: string; level: string; message: string }> = [];
+
+function hook(level: string, original: (...args: any[]) => void) {
+    return function (...args: any[]) {
+        original.apply(console, args);
+        buffer.push({
+            timestamp: new Date().toISOString(),
+            level,
+            message: args.map(a => typeof a === "string" ? a : JSON.stringify(a)).join(" "),
+        });
+    };
+}
+
+console.log = hook("log", console.log);
+console.warn = hook("warn", console.warn);
+console.error = hook("error", console.error);
+
+setInterval(() => {
+    if (buffer.length === 0) return;
+    const entries = buffer.splice(0, 50);
+    fetch(MCP_LOG_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(entries),
+    }).catch(() => {}); // silently ignore if MCP server is not running
+}, FLUSH_INTERVAL);
+```
+
+**`POST /log` format:**
+
+```json
+[
+  { "timestamp": "2026-03-26T12:00:00.000Z", "level": "log", "message": "Hello" },
+  { "timestamp": "2026-03-26T12:00:01.000Z", "level": "error", "message": "Something failed" }
+]
+```
+
+Both scene and game logs are merged chronologically when retrieved via `debug_get_console_logs`. Each log entry includes a `source` field (`"scene"` or `"game"`) to distinguish the origin.
+
+## Configuration
+
+Settings are stored in `{project}/settings/cocos-creator-mcp.json`:
+
+```json
+{
+  "port": 3000,
+  "autoStart": true
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `port` | `3000` | HTTP server port |
+| `autoStart` | `false` | Start server automatically when extension loads |
+
+## Testing
+
+```bash
+node test/regression.mjs         # default port 3000
+node test/regression.mjs 3001    # custom port
+```
+
+## Version History
+
+- **v0.1** — MCP server + scene/node tools (13 tools)
+- **v0.5** — Component, prefab, project, debug tools (27 tools)
+- **v1.0** — Full tool coverage (145 tools, 13 categories, 224 test assertions)
+- **v1.1** — Console log capture (scene process auto-capture + game preview via `/log` endpoint)
+- **v1.2** — AI autonomous development: Preview in Editor, screenshot capture, game command control, code cache clear, scene save fix. Client scripts for game preview integration (`client/`)
+- **v1.3** — `scene:set-property` for prefab save support, prefab_create overwrite guard, param alias (`component` → `componentType`)
+- **v1.5** — `prefab_create_and_replace`, batch `set_property`, `prefab_open`
+- **v1.6** — `debug_batch_screenshot`, widget support in `create_tree`, `component_query_enum`, `server_check_code_sync`
+- **v1.8.0** — Preview Recorder panel: `debug_record_start` / `debug_record_stop` (MediaRecorder via canvas.captureStream, MP4/WebM, quality presets)
+- **v1.8.1** — Fix: `component_set_property` cc.Asset references (cc.Font etc.) falling back to cc.Node when type is unspecified
+- **v1.8.2** — Preview Recorder: screenshot button (webp/png toggle, max width), section-based UI layout
+- **v1.9.0** — Preview Recorder auto-archive of old recordings + preflight "preview not running" check
+- **v1.10.0** — `scene_create` asset-db fallback, stringified args preventive validation, test coverage expansion
+- **v1.11.0** — HTTP MCP OAuth workaround (stdio bridge + dummy OAuth endpoints for Claude Code VSCode upstream bug) + dialog prevention for scene switching tools (`force` param, `ensureSceneSafeToSwitch`, `safeSaveScene`) + regression tests for both
+- **v1.12.0** — Prefab authoring efficiency: `component_auto_bind` (auto-match `@property` fields to node names), `debug_wait_compile` (wait for TS compile to finish), `prefab_create_from_spec` (create node tree + auto-bind + prefab_create in one call)
+- **v1.13.0** — `nodeName` parameter on component/get_components/auto_bind (no UUID required), `screenshot` auto-return option on `component_set_property` / `node_set_layout`, `node_set_layout` unified tool (UITransform + Widget + color/opacity in one call), dialog auto-response for untitled+dirty scenes, shared screenshot / node-resolve utilities
+- **v1.14.0** — Widget `_alignFlags` auto-recalc bug fix: `setProperty` / `setProperties` / `node_set_layout` now re-query `isAlign*` values from scene and rebuild `_alignFlags` bitmask after isAlign updates (Editor bug where bitmask was not updated automatically, causing prefabs to save with `_alignFlags: 45` stuck state). Also `node_create` component addition now waits for editor reflection (`waitForComponent`) to fix flaky tests
+
+## Development
+
+```bash
+npm run watch   # Watch mode
+npm run build   # One-time build
+```
+
+After building, reload the extension in Cocos Creator:
+- **Extension Manager** — disable then re-enable
+- **Developer > Reload** — reloads main process
+- **Full restart** — required for scene script or new category changes
+
+## Requirements
+
+- Cocos Creator 3.8+
+- Node.js 18+
+
+## Known Limitations
+
+- **`scene_create`**: Does not work on Cocos Creator 3.8.x because the underlying `scene:new-scene` Editor message is not exposed on that version. As a workaround, create the `.scene` JSON file directly under `db://assets/` and call `project_refresh_assets` so the editor picks it up. See [#13](https://github.com/harady/cocos-creator-mcp/issues/13) for details.
+
+## License
+
+MIT