mcp-bridge

# Tool List This is a MCP (Model Context Protocol) bridge plugin designed for Cocos Creator, used to connect external AI tools with the Cocos Creator editor, and realize automated operations on scenes, nodes, and other resources. ## Applicable Version This plugin is suitable for Cocos Creator 2.4.x version. 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 HTTP interface, and external tools can call Cocos Creator editor functions through the MCP protocol. - **Scene Node Operation**: Get, create, and modify nodes in the scene. - **Resource Management**: Create scenes, prefabs, open scenes or prefabs into editing mode. - **Component Management**: Add, delete, get node components. - **Script Management**: Create, delete, read, and write script files. - **Batch Execution**: Batch execute multiple MCP tool operations to improve efficiency. - **Asset Management**: Create, delete, move, and get resource information. - **Real-time Log**: Provides detailed operation log records and display, supports persistent writing to the project log file. - **Automatic Startup**: Supports automatic startup of the service when the editor starts. - **Editor Management**: Get and set the selected object, refresh the editor. - **Game Object Search**: Search for nodes in the scene according to 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 the editor console output. - **Script Verification**: Verify the syntax correctness of scripts. - **Global Search**: Search for text content in the project. - **Undo/Redo**: Manage the editor's undo stack. - **Special Effect Management**: Create and modify particle systems. - **Concurrent Safety**: The instruction queue is executed in series, and the queue has an upper limit of 100 (return HTTP 429 if exceeded), to prevent the editor from getting stuck. - **Timeout Protection**: IPC communication and instruction queue have a timeout bottom-line mechanism. - **Attribute Protection**: The component core attribute blacklist mechanism prevents AI from tampering with `node`/`uuid` and other references that lead to crashes. - **AI Fault Tolerance**: Parameter alias mapping (`operation`→`action`, `save`→`update`/`write`), compatible with large model hallucinations. - **Reference Lookup**: Find all locations in the scene that reference the specified node or resource, and support Texture2D → SpriteFrame sub-resource automatic parsing. - **Project Construction**: One-click trigger Cocos native `Editor.Builder` to build products (built-in intelligent anti-crash bottom-line mechanism). - **Project Information**: Used to pull the currently active editor-level state (version number, root directory, currently open scene UUID). ## Installation and Use ### Installation Copy this plugin to the `packages` directory of the Cocos Creator project. ### Build ```bash npm install npm run build ``` > **Note**: The build uses esbuild and specifies `--target=es2018` to ensure compatibility with Cocos Creator 2.4.x built-in Electron 9.x runtime. ### Start 1. Open the Cocos Creator editor. 2. Select `MCP Bridge/MCP Settings Panel` in 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 3456 by default. ### Configuration Options - **Port**: You can customize the port that the HTTP service listens to, the default is 3456. - **Automatic Startup**: You can set the editor to automatically start the service when it starts. - **Multi-instance Support**: If the default port (3456) is occupied, the plugin will automatically try port +1 (such as 3457), until it finds an available port. - **Configuration Isolation**: The plugin configuration (whether to automatically start, the last used port) is now stored in the project directory (`settings/mcp-bridge.json`), and the configuration of different projects does not interfere with each other. ## Connect AI Editor ### Automated One-click Configuration (Recommended) The current version supports automatic configuration detection and writing for the following AI clients: - **Claude Desktop** (global) - **Cline** (VSCode workspace/global) - **Roo Code** (VSCode workspace/global) - **Trae** (global) 1. Select `MCP Bridge/MCP Settings Panel` in the Cocos Creator menu bar to open the settings panel. 2. Switch to the top **"MCP Configuration"** tab. 3. If the system scans successfully, select the corresponding host AI client from the drop-down menu. 4. Click **"One-click Configure Current Platform"**. The plugin will safely complete the automatic writing of MCP Server definition registration information. Restart the corresponding AI to start seamlessly. ### Manual Configuration in AI Editor If your AI editor provides 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 `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, operation 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 log (buffer + panel synchronization + file landing) │ │ ├── CommandQueue.ts # Instruction queue (serialization + timeout protection) │ │ ├── HttpServer.ts # HTTP server life cycle 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 list (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 distributor │ │ 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 the specified node. - **Parameters**: - `id`: Node's UUID - `newName`: New node name ### 3. save_scene / save_prefab / close_prefab - **Description**: Scene and prefab save/close operation. - **Parameters**: None (`save_scene` saves the scene, `save_prefab` saves the current prefab, `close_prefab` exits prefab editing 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 cooperate with manage_components. - **Parameters**: - `nodeId`: Specified root node UUID (optional) - `depth`: Traversal depth limit, default is 2 (optional) - `includeDetails`: Whether to include details such as coordinates and scaling, default is false (optional) ### 5. update_node_transform - **Description**: Modify the 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 scene/prefab into editing mode (asynchronous operation, need to wait a few seconds). - **Parameters**: `url` — Resource path (such as `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/delete/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**: Batch execute multiple operations. - **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_info), `path`, `nodeId`, `parentId` ### 13. manage_editor - **Description**: Manage the editor (get/set selection, refresh editor). - **Parameters**: `action`(get_selection/set_selection/refresh_editor), `target`, `properties` ### 14. find_gameobjects - **Description**: Search for game objects in the scene according to 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` directly delete node). - **Parameters**: `menuPath` ### 17. apply_text_edits - **Description**: Apply text editing to files (insert/delete/replace). - **Parameters**: `filePath`, `edits` ### 18. read_console - **Description**: Read plugin console log. - **Parameters**: `limit`, `type` ### 19. validate_script - **Description**: Verify script syntax correctness. - **Parameters**: `filePath` ### 20. search_project - **Description**: Search project files (support regular expressions, file names, directory names). - **Parameters**: `query`, `useRegex`, `path`, `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 effect (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` ### 24. get_sha - **Description**: Get the SHA-256 hash value of the specified file. - **Parameters**: `path` ### 25. find_references - **Description**: Find all locations in the scene that reference the specified node or resource. - **Parameters**: `targetId`, `targetType`(node/asset/auto) ### 26. create_scene / create_prefab - **Description**: Create a scene file / save scene node as prefab. - **Parameters**: `sceneName` / `nodeId` + `prefabName` ### 27. build_project - **Description**: Trigger the editor's built-in packaging and construction pipeline (with empty scene fault tolerance, exclusion of engine module whitelist synchronization protection). - **Parameters**: `platform` (such as web-mobile), `debug` ### 28. get_project_info - **Description**: Get the currently active editor environment data. - **Parameters**: None (return `path`, `version`, `openScene` status) ### 29. get_active_instances - **Description**: Scan and get all running `mcp-bridge` instances, and return their corresponding ports and project root paths. - **Parameters**: None ### 30. set_active_instance - **Description**: When multiple running instances exist, explicitly specify the AI tool flow routing to a specific port's project binding. - **Parameters**: `port` (target port number) ## Development Guide ### Add New MCP Tool 1. Add tool definition in `src/tools/ToolRegistry.ts` (name, description, inputSchema). 2. Add corresponding processing method in `src/tools/ToolDispatcher.ts`. 3. If you need to operate scene nodes, add corresponding scene script processor in `src/scene-script.ts`. ### Build and Debug ```bash # Type check (no file generation) npx tsc --noEmit # Complete build npm run build # Reload plugin in Cocos Creator # Menu → Developer → Reload ``` ### Log Management The plugin uses `Logger` service to record all operation logs: - Panel real-time display (through IPC `sendToPanel`). - Persistent writing to `settings/mcp-bridge.log` (automatic rotation, upper limit 2MB). - Memory buffer upper limit 2000, automatic truncation if exceeded. ## AI Operation Safety Rules 1. **Determinism priority**: Any operation on nodes, components, and attributes must be based on "the subject has been confirmed to exist". 2. **Verification process**: Use `get_scene_hierarchy` / `manage_components(get)` to confirm the target exists before operation. 3. **Prohibit assumptions**: Prohibit blind attempts to modify non-existent objects or attributes. ## Update Log Please check [UPDATE_LOG.md](./UPDATE_LOG.md) for detailed version update history. ## License GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 The full text of the license can be found in the LICENSE file in the project root directory.