mcp-bridge

This is a MCP (Model Context Protocol) bridge plugin designed for Cocos Creator to connect external AI tools Cocos Creator editor, operations on scenes, nodes other resources. ## ApplicableThis plugin is compatible with Creator version 2.4.x. Due to the use of specific editor APIs, it may not be compatible with newer or older versions. ## Features - **HTTP Service Interface**: Provides a standard for external tools to call Cocos Creator editor functions via the. - **Scene Node Operations**: Obtain, create, and modify nodes in the scene. - **Resource Management**: Create scenes, prefabs, and open scenes or prefabs to enter edit mode. - **Component Management**: Add, remove, and retrieve node components. - **Script Management**: Create, delete, read, and write script files. - **Batch Execution**: Execute multiple MCP tool operations in batches to improve efficiency. - **Asset Management**: Create, delete, move retrieve resource information. - **Offline Prefab/Scene Modification fast and secure offline editor engine. Automatically identifies prefab (`.prefab`) and scene (`.fire`) physical skeleton differences. Supports creating resource skeletons from scratch, deep copying and cloning references, sorting rendering levels, nested array reference binding (`clickEvents[0].target`), attribute reference binding, and physical deletion + deep recursive reference update anti-crash mechanism. Editor private serialization fields (`_N$`) are automatically synchronized, thoroughly eliminating deserialization deadlocks and Watcher blocking. - **Real-time Logging**: Provides log records and display, supporting persistent writing to project log files. - **Automatic Startup automatic service startup when the editor starts. - **Editor Management**: Get and set selected objects, refresh the editor. - **Game Object Search**: Search for nodes in the scene based on conditions. - **Material Management**: Create and manage material resources. - **Texture Management**: Create and manage texture resources. - **Menu Item Execution**: Execute Cocos Creator editor menu items. - **Code Editing Enhancement**: Apply text editing operations to files. - **Console Reading**: Read editor console output. - **Script Verification**: Verify script syntax correctness. - **Global Search**: Search for text content in the project. - **Undo/Redo**: Manage the editor's undo stack. - **Special Effects Management**: Create and modify particle systems. - **Concurrency Safety**: The instruction queue is executed serially, with a queue 100 (returning HTTP 429 if exceeded), preventing the editor from freezing. - **Timeout Protection**: IPC communication and instruction queues have a timeout fallback mechanism. - **Attribute Protection**: A blacklist mechanism for component core attributes, preventing AI tampering with `node`/`uuid` and other could cause crashes. - Fault Tolerance**: Parameter alias mapping (`operation`→`action`, `save`→`update`/`write`), compatible with hallucinations. - **Reference Lookup**: Find all positions in the scene that reference a specified node or resource, supporting automatic parsing of sub-resources like Texture2D → SpriteFrame. - **Project Building**: One-click trigger Cocos native `Editor.Builder` to (with built-in intelligent anti-crash fallback mechanism). - **Project Information**: Used to pull the current active editor-level status (version number, root directory, currently open scene UUID). - **Claude Code Skills**: Built-in 6 Claude Code skills (`/mcp-define` → `/-architect` → `/mcp-execute` → `/mcp-verify`), covering the complete development workflow from demand analysis to verification. ### Claude Code Skills The project `.claude/skills/` directory provides the following skills, which can be directly called in Claude Code: | Skill | Purpose | |------|------| | `/mcp-rules` | Load MCP Bridge development specifications (language, architecture, naming, submission) | | `/mcp-define` | Create function Spec (in-depth code research + 6 delivery standards) | | `/mcp-architect` | Create implementation Plan (file list + step-by-step checkboxes + code snippets) | | `/mcp-execute` | Execute the plan step-by-step (mandatory compilation verification + state synchronization) | | `/mcp-refactor` | Code audit and cleanup (list issues first, user confirmation before modification) | | `/mcp-verify` | Function verification (visual audit + boundary testing + regression check) | Complete workflow: `/mcp-define` → `/mcp-architect` → `/mcp-execute` → `/mcp-verify` ## Installation and Usage ### Installation Copy this plugin to the `packages` directory of your Cocos Creator project. ### Build ```bash npm install npm run build ``` > **Note**: The build uses esbuild and specifies `--target=es2018` to ensure compatibility with the Electron 9.x runtime built into Cocos Creator 2.4.x. ### Startup 1. Open the Cocos Creator editor. 2. Select `MCP Bridge/MCP Settings Panel` from the menu bar to open the settings panel. 3. Click the "Start" button in the panel to start the service. 4. The service runs on port 8200 by default. ### Configuration Options - **Port**: You can customize the port that the HTTP service listens on, defaulting to 8200. - **Automatic Startup**: You can set the service to start automatically when the editor starts. - **Multi-instance Support**: If the default port (8200) is occupied or within the system's excluded range, the plugin will automatically try to use the next available port (e.g., 8201) until it finds one. - **Port Binding**: The service binds to `127.0.0.1` (localhost), avoiding conflicts with Hyper-V/WSL port reservation mechanisms. - **Project Activation**: Before the project is activated via `set_active_instance`, only the `get_active_instances` and `set_active_instance` basic tools are available, preventing unauthorized access. - **Configuration Isolation**: Plugin configurations (auto-start, last used port) are now stored in the project directory (`settings/mcp-bridge.json`), with different projects' configurations being independent. ## Connecting AI Editors ### Automated One-click Configuration (Recommended) The current version supports automated configuration detection and writing for the following AI clients: - **Claude Desktop** (global) - **Cline** (VSCode workspace/global) - **Roo Code** (VSCode workspace/global) - **Trae** (global) 1. In the Cocos Creator menu bar, select `MCP Bridge/Open MCP Settings Panel` to open the settings panel. 2. Switch to the **「MCP Configuration」** tab at the top. 3. If the system successfully scans, select the corresponding host AI client from the dropdown menu. 4. Click **「One-click Configure Current Platform」**. The plugin will securely complete the automatic writing of MCP Server definition registration information. Restart the corresponding AI to seamlessly launch. ### Manual Configuration in AI Editors If your AI editor provides a Type: command or Stdio option: ``` Command: node Args: [plugin installation path]/dist/mcp-proxy.js ``` ### Or Add JSON Configuration: ```json { "mcpServers": { "mcp-bridge": { "command": "node", "args": ["[plugin installation path]/dist/mcp-proxy.js"] } } } ``` Note: Please replace the path in the above configuration with the actual absolute path of the `dist/mcp-proxy.js` file in your project. ## Project Architecture ``` mcp-bridge/ ├── src/ # TypeScript source code │ ├── main.ts # Plugin main entry (load/unload, IPC registration) │ ├── scene-script.ts # Scene script (rendering process, operating cc.* engine API) │ ├── mcp-proxy.ts # MCP stdio proxy (AI client ↔ HTTP bridge) │ ├── IpcManager.ts # IPC message manager │ ├── McpConfigurator.ts # AI client configuration automatic injection │ ├── core/ # Core infrastructure │ │ ├── Logger.ts # Centralized logging (buffering + panel synchronization + file landing) │ │ ├── CommandQueue.ts # Instruction queue (serialization + timeout protection) │ │ ├── HttpServer.ts # HTTP server lifecycle management │ │ ├── McpRouter.ts # HTTP request routing distribution │ │ └── McpWrappers.ts # Independent resource tools (search/undo/sha/animation) │ ├── tools/ # MCP tool layer │ │ ├── ToolRegistry.ts # Tool definition registry (name/description/schema) │ │ └── ToolDispatcher.ts # Tool scheduling center (handleMcpCall → scene script) │ ├── utils/ # General tools │ │ └── AssetPatcher.ts # Atomic resource creation + Prefab repair tool │ └── panel/ # Settings panel │ └── index.ts # Panel interaction logic ├── panel/ │ └── index.html # Panel HTML template ├── dist/ # Compilation output (esbuild bundle) │ ├── main.js # Main process entry │ ├── scene-script.js # Scene script │ ├── panel/index.js # Panel script │ └── mcp-proxy.js # MCP proxy ├── package.json # Plugin manifest (Cocos Creator 2.x format) └── tsconfig.json # TypeScript compilation configuration ``` ### Process Architecture ``` Main Process (main.ts) Rendering Process (scene-script.ts) │ │ ├─ 1. Receive HTTP request │ │ HttpServer → McpRouter │ ├─ 2. Route to tool dispatcher │ │ ToolDispatcher.handleMcpCall() │ ├─ 3. Call scene script ──────────────────────┤ │ CommandQueue → callSceneScript │ │ ├─ 4. Operate nodes/components │ │ cc.engine / cc.director │ ├─ 5. Notify scene dirty │ │ Editor.Ipc → scene:dirty └─ 6. Return JSON result ◀──────────────────┘ ``` ## API Interface The service provides the following MCP tool interfaces: ### 1. get_selected_node - **Description**: Get the ID of the currently selected node in the editor. - **Parameters**: None ### 2. set_node_name - **Description**: Modify the name of a specified node. - **Parameters**: - `id`: Node's UUID - `newName`: New node name ### 3. save_scene / save_prefab / close_prefab - **Description**: Save/close operations for scenes and prefabs. - **Parameters**: None (`save_scene` saves the scene, `save_prefab` saves the current prefab, `close_prefab` exits prefab edit mode) ### 4. get_scene_hierarchy - **Description**: Get the complete node tree structure of the current scene. If you want to query specific component properties, please use manage_components. - **Parameters**: - `nodeId`: Specified root node UUID (optional) - `depth`: Traversal depth limit, defaults to 2 (optional) - `includeDetails`: Whether to include details like coordinates, scaling, etc., defaults to false (optional) ### 5. update_node_transform - **Description**: Modify a node's coordinates, scaling, color, or visibility. - **Parameters**: `id`(required), `x`, `y`, `width`, `height`, `scaleX`, `scaleY`, `rotation`, `color`, `opacity`, `active`, `anchorX`, `anchorY`, `skewX`, `skewY` ### 6. open_scene / open_prefab - **Description**: Open a scene/prefab to enter edit mode (asynchronous operation, may take a few seconds). - **Parameters**: `url` — Resource path (e.g., `db://assets/NewScene.fire`) ### 7. create_node - **Description**: Create a new node in the current scene. - **Parameters**: `name`(required), `parentId`, `type`(empty/sprite/label/button), `layout`(center/top/bottom/full, etc.) ### 8. manage_components - **Description**: Manage node components (add/remove/modify/query). - **Parameters**: `nodeId`(required), `action`(add/remove/update/get), `componentType`, `componentId`, `properties` ### 9. manage_script - **Description**: Manage script files. - **Parameters**: `action`(create/delete/read/write), `path`, `content`, `name` ### 10. batch_execute - **Description**: Execute multiple operations in batches. - **Parameters**: `operations` — Operation list (including `tool` and `params`) ### 11. manage_asset - **Description**: Manage resources (create/delete/move/query information). - **Parameters**: `action`, `path`, `targetPath`, `content` ### 12. scene_management / prefab_management - **Description**: Scene and prefab management. - **Parameters**: `action`(create/delete/duplicate/get_infopath`, `nodeId`, `parentId` 13. manage_editor - **Description**: Manage the editor (get/set selection, refresh editor). - **Parameters**: `action`(get_selection/set_selection/refresh_editor), `target`, `properties` - **Note**: `refresh_editor` only accepts single file paths (with extensions), directory paths and `db://assets` global paths are strictly rejected by the code layer. ### 14. find_gameobjects - **Description**: Search for game objects in the scene based on conditions. - **Parameters**: `conditions`(name/component/active), `recursive` ### 15. manage_material / manage_texture / manage_shader - **Description**: Manage material, texture, and shader resources. - **Parameters**: `action`, `path`, `properties`/`content` ### 16. execute_menu_item - **Description**: Execute menu items (support `delete-node:UUID` to directly delete a node). - **Parameters**: `menuPath` ### 17. apply_text_edits **Description**: Apply text edits to files (insert/delete/replace). - **Parameters**: `filePath`, `edits` ### 18. read_console - **Description**: Read plugin console logs. - **Parameters**: `limit`, `type` ### 19. validate_script - **Description**: Verify script syntax correctness. - **Parameters**: `file### 20. - **Description**: Search project files (support file name, directory name). - **Parameters**: `query`, `useRegex`, `path`(defaults to `db://assets`, passing `db://` will automatically correct to `db://assets`), `matchType`, `extensions`, `includeSubpackages` ### 21. manage_undo - **Description**: Undo/redo management. - **Parameters**: `action`(undo/redo/begin_group/end_group/cancel_group), `description`, `id` ### 22. manage_vfx - **Description**: Special effects (particle system) management. - **Parameters**: `action`(create/update/get_info), `nodeId`, `name`, `parentId`, `properties` ### 23. manage_animation - **Description**: Manage node animation components. - **Parameters**: `action`(get_list/get_info/play/stop/pause/resume), `nodeId`, `clipName` ###. get_sha - **Description**: Get the SHA-256 hash value of file. - ** `path` ### 25. find_references - **Description**: Find all positions in the scene that reference a specified node or resource. - **ParameterstargetId`, `targetType`(node/asset/auto) ### 26. / create_prefab - **Description**: Create a scene file / save scene nodes as a prefab. - **Parameters**: `sceneName` / `nodeId` + `prefabName` ### 27. build_project - **Description**: Trigger the editor's built-in packaging and construction pipeline (with empty scene fault tolerance and engine module whitelist synchronization protection) - **Parameters**: `platform` (e.g., web-mobile), `debug` ### 28. get_project_info - **Description**: Get the currently activated editor environment data - **Parameters**: None (returns `path`, `version`, `openScene` status) ### 29. get_active_instances - **Description**: Scan and obtain all running `mcp-bridge` instances (port range 8200–8210) locally, returning their respective ports and project root paths. - **Parameters**: None ### 30. set_active_instance - **Description**: Activate and bind the target Cocos Creator project instance. After calling, all tools (including offline editing and editor tools) can be obtained. If not activated, only basic management tools are returned. - **Parameters**: `port` (target port number) ### 31. modify_prefab_offline - **Description**: Offline modification prefab tool. No need to open a window in the editor, directly parse and modify prefabs at the physical file level, execute a series of declarative operations, and safely write back to the physical disk. - **Parameters**: - `prefabUrl` (required): The db:// path of the prefab resource, e.g., `db://assets/prefabs/MyPrefab.prefab`. For non-existent files, if the first operation is `add_node` and the path is empty, it triggers automatic creation from scratch. - `operations` (required): List of operations. Supported atomic operations `action` include: - `update_property`: Update node/component properties (properties pass property key-value pairs. Supports array index syntax like `clickEvents[0].handler`. Component properties automatically synchronize `_N$` private serialization fields) - `add_component`: Mount a new component (componentType specifies the class name. Component properties automatically synchronize `_N$` fields) - `remove_component`: Unload component (automatically physically splice and delete and recursively update references) - `add_node`: Add a new child node under `targetPath` (automatically complete 6 native properties) - `remove_node`: Physically delete the node tree (physically splice and depth recursively remap all `__id__` to null to prevent out-of-bounds crashes) - `clone_node`: Deep copy node subtree (use `indexMap` to rearrange and copy subtree internal relative `__id__` references) - `reorder_child`: Adjust child node rendering order (childOrder passes name array, safely merge missing items) - `set_reference`: Bind component property references (through `referenceValue` property association external UUID or internal node/component index. Supports array index syntax like `clickEvents[0].target`, can automatically create nested array elements via `elementType: "cc.ClickEvent"`) ### 32. modify_scene_offline - **Description**: Offline modification scene file tool. Directly parse and modify scene (.fire) resources at the physical file level and physically parse and refresh AssetDB after operation. Supports the same 8 atomic operations as `modify_prefab_offline`. - **Parameters**: - `sceneUrl` (required): The db:// path of the scene resource, e.g., `db://assets/scene/FormalScene.fire`. For non-existent files, if the first operation is `add_node` and `targetPath` is empty, it automatically initializes a minimal empty scene skeleton. - `operations` (required): Shares the same operation structure as `modify_prefab_offline`. ## Offline Editor Engine Principles (Prefabs and Scenes) Cocos Creator 2.x prefab physical files are flat JSON object arrays (starting with `cc.Prefab` as the first element, dependent on `{"__id__": index}` mutual reference). Due to this special flat topology, direct addition or deletion can easily lead to index confusion or null pointer crashes. To ensure 100% robustness of offline atomic modifications, this plugin designs and implements the following core principles: ### 1. Depth Recursive Reference Update (`remapAllIdRefs` Algorithm) When deleting nodes or unloading components, using `null` logic placeholders can cause engine deserialization constructor crashes (Cocos fatal zone). Therefore, it must use physical `splice` to actually delete flat items and shorten the array. To prevent physical deletion causing all greater than deleted index `__id__` references from getting confused, this engine introduces a depth recursive traversal recalculation algorithm. It scans all fields of the entire JSON object, whether it's a normal flat property or deeply nested in arrays or objects (like `clickEvents` event `target`): * If `oldId` belongs to the physically deleted range, it elegantly resets it to `null` and automatically executes `filter(item => item !== null)` filtering for component or child node reference arrays (`_children`/`_components`). * If `oldId` is greater than the deletion item index, it automatically subtracts the number of deleted items `k` ahead of it (`newId = oldId - k`), making the reference relationship perfectly reset in the new physical array. ### 2. Non-Displacement Subtree Cloning Algorithm (`clone_node`) During cloning operations, the engine recursively extracts all objects contained in the source node subtree (child nodes, bound components, and associated `cc.PrefabInfo`), deep copies and appends them at the end of the flat JSON. To ensure the independence of the cloned subtree, the engine establishes a temporary mapping table `Map<oldIndex, newIndex>` in memory and traverses the cloned new object: * If it finds its `__id__` reference pointing to the original subtree's old index, it uses the Map to recalculate and replace it with the corresponding cloned new index to ensure the correctness of the relative reference. * If it finds its reference pointing to a public node outside the subtree, it retains it as is to prevent incorrect modifications. ### 3. Root Node Prefix Filtering and Path Fault Tolerance Offline prefabs may have different positioning prefixes in different tools. This engine implements intelligent cutting in the `findNodeByPath` method: if the first level of the addressing path segment equals the current prefab root node's name and there are no child nodes with the same name under the root node, it automatically peels off the prefix and addresses downward. This perfectly adapts to addressing requests "with root name prefix" and "directly referring to the root". ### 4. Offline "From Scratch" Automatic Creation If the modified prefab does not exist, the distributor automatically creates a physical directory and writes a minimal empty skeleton JSON format file containing all 2.4.x required native properties (like `_eulerAngles`, `_skewX`/`_skewY`, `_is3DNode`, `groupIndex`, etc.). To avoid the multi-layer nesting structure generated during creation, after writing the skeleton, the distributor automatically `shift()` removes the redundant `add_node` operation used to create the root node, directly making subsequent component and property operations seamlessly locate to the skeleton's built-in root node. ### 5. Non-Blocking Asynchronous Reload Mechanism (Prevent Watcher Deadlock) When offline prefabs are written to disk, physical file writing completes within 1~3 milliseconds. To prevent Cocos editor file Watcher from competing for file locks with the main thread, causing microsecond-level race condition deadlocks, the main process immediately callbacks and releases the queue after writing successfully, while using `setTimeout` to delay 200 milliseconds to asynchronously wake up and refresh `Editor.assetdb.refresh`. This thoroughly avoids MCP queue blocking due to lock contention leading to 60-second timeouts and editor "checking file updates" spinning and getting stuck. ### 6. Custom Script UUID Automatic Compression When Cocos Creator serializes custom script components, the physical prefab's `__type__` field needs to fill in a 23-bit compressed UUID (converted via r=5 algorithm, like `1f9d8d0d-d79c-45ff-8ed7-e0f1e651fe26` compressed to `1f9d80N15xF/47X4PHmUf4m`). This engine implements a pure offline Hex/Base64 UUID mutual conversion and compression algorithm, automatically executing compression in the background when adding, removing, and retrieving custom components. This thoroughly solves the problem of offline direct mounting of raw 36-bit UUIDs being reported by the editor as `cc.MissingScript` and the connected properties failing. ### 7. Complex Component Property (like `cc.ClickEvent`) Flattening and Promotion (Lift) Cocos 2.x `cc.ClickEvent` inherits from `cc.Object`. The engine deserialization specification restricts it from being **directly inline** in the component's property structure. It must be flattened as an independent item in a flat array and referenced via `{ "__id__": index }`, and its `component` property should be empty `""` in the physical file and set with a special `_componentId` as the compressed UUID of the corresponding script. For this, this engine implements an automatic promotion and flattening (Lift) mechanism for properties. When writing `clickEvents` and other event properties, it automatically identifies and creates independent flattened event nodes, recursively calculates relative dependency references, and executes reference recalculations, perfectly fitting the engine's deserialization binding specification. ### 9. Nested Array Reference Binding and Automatic Element Creation (`clickEvents[0].target`) This engine now supports directly accessing and modifying properties of nested arrays within components via array index syntax. When `set_reference` or `update_property`'s `propertyName` contains paths like `clickEvents[0].target`: 1. **Parse Path**: Automatically identify array field names `clickEvents`, index `0`, and child property `target`. 2. **Access Array**: Obtain the array from the component's properties (compatible with `_N$` prefix serialization version). 3. **Automatic Creation**: If the array or specified index element does not exist, automatically create it using the `elementType` parameter (like `cc.ClickEvent`), initialize default values, and fill in the flat array. 4. **Dereference**: Automatically handle the conversion of Cocos flat format `{ __id__: N }` to actual objects. This allows scenarios like binding button click events, setting custom script array references, etc., to be completed in offline editing without post-processing scripts manually calculating index mappings. ### 10. Component Property `_N$` Private Serialization Field Automatic Synchronization Cocos Creator 2.x engine serializes certain component properties internally using both public fields and private serialization fields starting with `_N$`. When the editor detects script updates and triggers reconstruction, it relies on `_N$` fields to read deserialized data. If missing, the editor resets to default values, covering data written offline. This engine, in `update_property`, `add_component`, and `set_reference` operations, for each written component property `K` (not starting with `_` or `_N$`), **automatically synchronizes and writes `_N$K`**. Ensure the editor can correctly read offline written data after any triggered redraws, thoroughly ending the swallow problem. ### 11. MCP Proxy Embedded Offline Engine (Project Activation Required) `mcp-proxy.js` has embedded the OfflinePrefabEditor compilation package. When AI clients (like Antigravity, Claude Code) connect via stdio, they need to activate the project via `set_active_instance` to obtain offline editing tools. - **Cocos Online Mode**: The proxy forwards calls to the Cocos Creator plugin HTTP service, obtaining complete AssetDB refresh and editor synchronization capabilities. - **Pure Proxy Offline Mode**: If activated but the editor is not running, the proxy directly executes offline modifications within this process. The project path is obtained by scanning surviving instances or the `MCP_BRIDGE_PROJECT_PATH` environment variable. ### 12. Scene and Prefab Skeleton Generalization and Difference Handling This engine supports physical modification of both prefabs (`.prefab`) and scenes (`.fire`). By automatically identifying the first `cc.Prefab` or `cc.SceneAsset` type in `findNodeByPath`, it dynamically sets the root positioning starting point (prefab is `data.__id__`, scene is virtual root `scene.__id__`). Additionally, when adding nodes, the engine automatically filters out `cc.PrefabInfo` data block creation in scene mode, ensuring the purity of the scene file structure and perfect backward compatibility. ## Development Guide ### Adding New MCP Tools 1. Add tool definitions (name, description, inputSchema) in `src/tools/ToolRegistry.ts` 2. Add corresponding processing methods in `src/tools/ToolDispatcher.ts` 3. If you need to operate scene nodes, add corresponding scene script processors in `src/scene-script.ts` ### Building and Debugging ```bash # Type checking (no file generation) npx tsc --noEmit # Complete build npm run build # Reload plugin in Cocos Creator # Menu → Developer → Reload ``` ### Log Management The plugin uniformly records all operation logs through the `Logger` service: - Real-time display on the panel (via IPC `sendToPanel`) - Persistent writing to `settings/mcp-bridge.log` (automatic rotation, up to 2MB limit) - In-memory buffer limit of 2000 entries, automatically truncated if exceeded ## AI Operation Safety Rules 1. **Determinism First**: Any operations on nodes, components, and properties must be based on confirming the existence of the subject. 2. **Verification Process**: Before operation, must use `get_scene_hierarchy` / `manage_components(get)` to confirm the target exists. 3. **No Assumptions**: Prohibited from blindly attempting to modify non-existent objects or properties. ## Update Log Please refer to [UPDATE_LOG.md](./UPDATE_LOG.md) for detailed version update history. ## Contact If you have questions or suggestions, please contact: firekula@foxmail.com ## License GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 Complete license text can be found in the LICENSE file in the project root directory.