mcp-bridge

# MCP Bridge Plugin This is an MCP (Model Context Protocol) bridge plugin designed for Cocos Creator, used to connect external AI tools with the Cocos Creator editor to automate operations on scenes, nodes, and other resources. ## Applicable Versions This plugin is applicable to Cocos Creator 2.4.x versions. 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, allowing external tools to call Cocos Creator editor functions through the MCP protocol. - **Scene Node Operations**: Get, create, and modify nodes in the scene. - **Resource Management**: Create scenes and prefabs, and open specified resources. - **Component Management**: Add, delete, and get 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, and get resource information. - **Real-time Logging**: Provides detailed operation log recording and display. - **Automatic Startup**: Supports automatically starting the service when the editor starts. - **Editor Management**: Get and set selected objects, and refresh the editor. - **Game Object Search**: Find 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 Validation**: Verify script syntax correctness. - **Global Search**: Search for text content in the project. - **Undo/Redo**: Manage the editor's undo stack. - **Effect Management**: Create and modify particle systems. - **Tool Description**: The test panel provides detailed tool descriptions and parameter explanations. ## Installation and Usage ### Installation Copy this plugin to the `packages` directory of your Cocos Creator project. ### Startup 1. Open the Cocos Creator editor. 2. In the menu bar, select `MCP Bridge/Open Panel` to open the test panel. 3. In the panel, click the "Start" button 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 on, which defaults to 3456. - **Automatic Startup**: You can set the service to start automatically when the editor starts. ## Connecting to AI Editor ### Configure in AI Editor (e.g., Cursor / VS Code) If your AI editor provides Type: command or Stdio options: ``` Command: node Args: [Absolute path of Cocos Creator project]/packages/mcp-bridge/mcp-proxy.js ``` For example, in your project, the full path should be: ``` Args: [Your drive letter]:/[Project path]/packages/mcp-bridge/mcp-proxy.js ``` ### Or add JSON configuration: ```json { "mcpServers": { "cocos-creator": { "command": "node", "args": ["[Absolute path of Cocos Creator project]/packages/mcp-bridge/mcp-proxy.js"] } } } ``` Note: Please replace the path in the above configuration with the actual absolute path of the `mcp-proxy.js` file in your project. ## 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`: The UUID of the node. - `newName`: The new node name. ### 3. save_scene - **Description**: Save the changes to the current scene. - **Parameters**: None ### 4. get_scene_hierarchy - **Description**: Get the complete node tree structure of the current scene (including UUID, name, and hierarchy). - **Parameters**: None ### 5. update_node_transform - **Description**: Modify the coordinates, scale, or color of the node. - **Parameters**: - `id`: Node UUID - `x`, `y`: Coordinates - `width`, `height`: Node width and height (newly supported) - `scaleX`, `scaleY`: Scale values - `color`: HEX color code (e.g., #FF0000) - **Important Note**: You must call `get_scene_hierarchy` before execution to ensure that the `id` is valid to prevent operating on a non-existent node. ### 6. open_scene - **Description**: Open the specified scene file in the editor. This is an asynchronous and time-consuming operation. Please wait a few seconds after opening. **Important Note**: If it is a newly created or empty scene, be sure to create and initialize the basic nodes (Canvas/Camera) first. - **Parameters**: - `url`: The scene resource path, such as `db://assets/NewScene.fire` ### 7. create_node - **Description**: Create a new node in the current scene. - **Important Notes**: 1. If `parentId` is specified, you must first confirm that the parent node corresponding to the UUID still exists through `get_scene_hierarchy`. 2. **Preset Type Differences**: - `empty`: Pure empty node, no components, no textures. - `sprite`: Automatically adds a Sprite component, default size 100x100, with the engine's default texture placeholder. - `button`: Automatically adds Sprite and Button components, default size **150x50**, background color set to dark for clear text visibility, with default texture. - `label`: Automatically adds a Label component, default size 120x40. - **Parameters**: - `name`: Node name - `parentId`: Parent node UUID (optional) - `type`: Node preset type (`empty`, `sprite`, `label`, `button`) ### 8. manage_components - **Description**: Manage node components. - **Important Best Practices**: 1. **Reference Validation**: Before operating, you must call `get_scene_hierarchy` to confirm that the node corresponding to `nodeId` actually exists (to prevent reference invalidation due to scene reset or node deletion). 2. Before performing an `add` operation, it is recommended to check whether a similar component already exists through the `get` operation. 3. After adding `cc.Sprite`, be sure to set its `spriteFrame` property, otherwise the node will not be displayed. 4. When creating a button, make sure the target node has a positive size (`width`/`height`) as the click area. - **Parameters**: - `nodeId`: Node UUID - `action`: Operation type (`add`, `remove`, `get`, `update`) - `componentType`: Component type, such as `cc.Sprite` (for `add`/`update` operations) - `componentId`: Component ID (for `remove`/`update` operations) - `properties`: Component properties (for `add`/`update` operations). - **Smart Features**: 1. If the property expects a component type but a node UUID is passed in, the plugin will automatically find the matching component. 2. For resource-type properties (such as `cc.Prefab`, `cc.Material`), pass in the UUID of the resource, and the plugin will automatically handle asynchronous loading and serialization. 3. **Asset Array Support**: For array properties such as `materials`, support passing in an array of UUIDs, and the plugin will automatically concurrently load all resources and synchronously update the editor UI. - **Operation Rules (Subject Validation Rule)**: Before assigning or updating, you must ensure that the target property actually exists on the component. ### 9. manage_script - **Description**: Manage script files, default create TypeScript script - **Parameters**: - `action`: Operation type (`create`, `delete`, `read`, `write`) - `path`: Script path, such as `db://assets/scripts/NewScript.ts` - `content`: Script content (for `create` and `write` operations) - `name`: Script name (for `create` operation) - **Default Template**: When content is not provided, a default template in TypeScript format will be used ### 10. batch_execute - **Description**: Batch execute multiple operations - **Parameters**: - `operations`: List of operations - `tool`: Tool name - `params`: Tool parameters ### 11. manage_asset - **Description**: Manage assets - **Parameters**: - `action`: Operation type (`create`, `delete`, `move`, `get_info`) - `path`: Asset path, such as `db://assets/textures` - `targetPath`: Target path (for `move` operation) - `content`: Asset content (for `create` operation) ### 12. scene_management - **Description**: Scene management. After creating and opening through `open_scene`, be sure to initialize the basic nodes (such as Canvas and Camera). - **Parameters**: - `action`: Operation type (`create`, `delete`, `duplicate`, `get_info`) - `path`: Scene path, such as `db://assets/scenes/NewScene.fire` - `targetPath`: Target path (for `duplicate` operation) - `name`: Scene name (for `create` operation) ### 13. prefab_management - **Description**: Prefab management - **Parameters**: - `action`: Operation type (`create`, `update`, `instantiate`, `get_info`) - `path`: Prefab path, such as `db://assets/prefabs/NewPrefab.prefab` - `nodeId`: Node ID (for `create` and `update` operations) - `parentId`: Parent node ID (for `instantiate` operation) ### 14. manage_editor - **Description**: Manage editor - **Parameters**: - `action`: Operation type (`get_selection`, `set_selection`, `refresh_editor`) - `target`: Target type (`node`, `asset`) (for `set_selection` operation) - `properties`: Operation properties - `nodes`: Array of node UUIDs (for `set_selection` operation) - `assets`: Array of asset UUIDs (for `set_selection` operation) ### 15. find_gameobjects - **Description**: Find game objects - **Parameters**: - `conditions`: Search conditions - `name`: Node name (contains match) - `tag`: Node tag - `component`: Component type - `active`: Active state - `recursive`: Whether to search recursively (default: true) ### 16. manage_material - **Description**: Manage material resources. Supports adapting the `_effectAsset` and `_techniqueData` structures of Cocos Creator 2.4.x. - **Parameters**: - `action`: Operation type (`create`, `delete`, `update`, `get_info`) - `path`: Material path, such as `db://assets/materials/NewMaterial.mat` - `properties`: Material properties (for `create` and `update` operations) - `shaderUuid`: Specifies the UUID of the shader to use - `defines`: Macro definition object (will be merged with existing values for `update`) - `uniforms`: Uniform parameter object (will be merged with existing values for `update`, corresponding to `props` in the engine) ### 17. manage_shader - **Description**: Manage shader (Effect) resources. - **Parameters**: - `action`: Operation type (`create`, `read`, `write`, `delete`, `get_info`) - `path`: Shader path, such as `db://assets/effects/MyShader.effect` - `content`: Text content (for `create` and `write` operations) ### 18. manage_texture - **Description**: Manage texture - **Parameters**: - `action`: Operation type (`create`, `delete`, `get_info`, `update`) - `path`: Texture path, such as `db://assets/textures/NewTexture.png` - `properties`: Texture properties (for `create`/`update` operations) - `type`: Texture type (e.g., `sprite`, `texture`, `raw`) (for `update`) - `border`: Nine-slice border array `[top, bottom, left, right]` (for `update`, only valid when type is sprite) - `subMetas`: (Internal use) - `width`: Width (for `create` to generate placeholder image) - `height`: Height (for `create` to generate placeholder image) - `native`: Native path ### 18. execute_menu_item - **Description**: Execute menu item - **Parameters**: - `menuPath`: Menu item path, such as `Assets/Create/Folder`. Supports mapping common commands: `File/New Scene`, `File/Save Scene`, `Edit/Undo`, `Edit/Redo`, `Project/Build`, etc. ### 19. apply_text_edits - **Description**: Apply text edits - **Parameters**: - `filePath`: File path, such as `db://assets/scripts/TestScript.ts` - `edits`: List of edit operations - `type`: Operation type (`insert`, `delete`, `replace`) - `position`: Insertion position (for `insert` operation) - `start`: Start position (for `delete` and `replace` operations) - `end`: End position (for `delete` and `replace` operations) - `text`: Text content (for `insert` and `replace` operations) ### 20. read_console - **Description**: Read console - **Parameters**: - `limit`: Output limit (optional) - `type`: Output type (`log`, `error`, `warn`) (optional) ### 21. validate_script - **Description**: Validate script - **Parameters**: - `filePath`: Script path, such as `db://assets/scripts/TestScript.ts` - **Note**: For TypeScript files, only basic syntax structure checks are performed, not complete compilation validation. ### 22. find_in_file - **Description**: Global file search - **Parameters**: - `query`: Search keyword - `extensions`: File extension list (optional, default `['.js', '.ts', '.json', '.fire', '.prefab', '.xml', '.txt', '.md']`) - `includeSubpackages`: Whether to search subpackages (optional, default true) ### 23. manage_undo - **Description**: Undo/redo management - **Parameters**: - `action`: Operation type (`undo`, `redo`, `begin_group`, `end_group`, `cancel_group`) - `description`: Undo group description (for `begin_group`) ### 24. manage_vfx - **Description**: Effect (particle) management. Important note: Before operating, you must confirm the validity of the parent node or target node. - **Parameters**: - `action`: Operation type (`create`, `update`, `get_info`) - `nodeId`: Node UUID (for `update`, `get_info`) - `name`: Node name (for `create`) - `parentId`: Parent node UUID (for `create`) - `properties`: Particle properties object - `duration`, `emissionRate`, `life`, `lifeVar`, `startColor`, `endColor` - `startSize`, `endSize`, `speed`, `angle`, `gravity`, `file` (plist/texture) ### 25. manage_animation - **Description**: Manage the animation component of a node - **Parameters**: - `action`: Operation type (`get_list`, `get_info`, `play`, `stop`, `pause`, `resume`) - `nodeId`: Node UUID - `clipName`: Animation clip name (for `play` operation, optional, default plays defaultClip) ### 26. get_sha - **Description**: Get the SHA-256 hash value of the specified file - **Parameters**: - `path`: File path, such as `db://assets/scripts/Test.ts` ## Technical Implementation ### Architecture Design The plugin adopts a typical Cocos Creator extension architecture, including the following parts: - **main.js**: The main entry point of the plugin, responsible for starting the HTTP service and processing MCP requests. - **scene-script.js**: Scene script, responsible for actually performing node operations. - **panel/**: Panel interface, providing a user interaction interface. - `index.html`: Panel UI structure - `index.js`: Panel interaction logic ### HTTP Service The plugin has a built-in HTTP server that provides two main interfaces: - `GET /list-tools`: Returns all available MCP tool definitions - `POST /call-tool`: Executes a specific tool operation ### MCP Protocol Integration The plugin follows the MCP (Model Context Protocol) standard, allowing external AI tools to understand and call Cocos Creator's functions. ### Data Flow 1. An external tool sends an MCP request to the plugin's HTTP interface 2. main.js receives the request and parses the parameters 3. The request is forwarded to scene-script.js via Editor.Scene.callSceneScript 4. scene-script.js executes the specific operation in the scene thread 5. The result is returned to the external tool ## Development Guide ### Adding New Features To add a new MCP tool to the plugin, you need to: 1. Add the tool definition to the `/list-tools` response in main.js 2. Add the corresponding processing logic in the handleMcpCall function 3. If you need to execute in the scene thread, you need to add the corresponding function in scene-script.js ### Log Management The plugin logs all operations, including: - Service start/stop - MCP request reception - Operation success/failure status - Error messages ## Precautions - The plugin needs to be run in the Cocos Creator environment - The HTTP service will occupy the specified port, please ensure that the port is not occupied by other programs - The plugin will automatically mark the scene as "modified", please pay attention to saving the scene - Different versions of Cocos Creator may have API differences, please adjust according to the actual situation ## AI Operation Safety Rules (Subject Validation Rule) In order to ensure the stability of automated operations, AI must follow the following rules when using this plugin tool: 1. **Certainty First**: Any operation on nodes, components, or attributes must be based on the premise that "the subject has been confirmed to exist". 2. **Verification Process**: * **Node Verification**: Before the operation, you must use `get_scene_hierarchy` to confirm the node. * **Component Verification**: Before operating a component, you must use `get` (through `manage_components`) to confirm that the component exists. * **Attribute Verification**: Before updating an attribute, you must confirm that the attribute name is accurate. 3. **Prohibit Assumptions**: It is forbidden to blindly attempt to modify non-existent objects or attributes. ## Contribution Welcome to submit Issues and Pull Requests to improve this plugin! ## License GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 Anyone is allowed to obtain, use, modify, and distribute this software, but must comply with the following conditions: 1. When distributing modified versions, the source code must be made public under the same license 2. When providing services over the network, the source code must also be provided to users 3. Any derivative works must also follow the same license terms The complete license text can be found in the LICENSE file in the project root directory.