cocos-mcp-server

# Cocos Creator MCP Server Plugin **[📖 English](README.EN.md)** **[📖 中文](README.md)** A comprehensive MCP (Model Context Protocol) server plugin for Cocos Creator 3.8+ that enables AI assistants to interact with the Cocos Creator editor through a standardized protocol. One-click installation and usage, eliminating all cumbersome environments and configurations. It has been tested with Claude client Claude CLI and Cursor, and other editors are theoretically perfectly supported. **🚀 Now offering 50 powerful fusion tools, achieving 99% editor control!** ## Video Demonstration and Tutorial [<img width="503" height="351" alt="image" src="https://github.com/user-attachments/assets/f186ce14-9ffc-4a29-8761-48bdd7c1ea16" />](https://www.bilibili.com/video/BV1mB8dzfEw8?spm_id_from=333.788.recommend_more_video.0&vd_source=6b1ff659dd5f04a92cc6d14061e8bb92) ##Quick Links - **[📖 Complete Feature Guide (English)](FEATURE_GUIDE_EN.md)** - Detailed documentation for all 158 tools（To be supplemented） - **[📖 完整功能指南 (中文)](FEATURE_GUIDE_CN.md)** - 所有158工具的详细文档（To be supplemented） ## Changelog ## 🚀 Major Update v1.5.0 (July 29, 2024) (Already updated in the Cocos Store, the github version will be synchronized in the next version) cocos store：https://store.cocos.com/app/detail/7941 - **Tool Streamlining and Restructuring**: The original 150+ tools have been condensed and organized into 50 highly reusable and high-coverage core tools, removing all invalid and redundant code, greatly improving ease of use and maintainability. - **Opcode Unification**: All tools adopt the "opcode + parameter" mode, which greatly simplifies the AI call process, improves the AI call success rate, reduces the number of AI calls, and reduces token consumption by 50%. - **Prefab Functionality Comprehensive Upgrade**: Thoroughly fix and improve all core functions such as prefab creation, instantiation, synchronization, and referencing, support complex reference relationships, and 100% align with the official format. - **Event Binding and Old Function Completion**: Supplemented and implemented event binding, old functions such as nodes/components/resources, all methods are completely aligned with the official implementation. - **Interface Optimization**: All interface parameters are clearer, the documentation is more complete, and AI is easier to understand and call. - **Plugin Panel Optimization**: The panel UI is more concise and the operation is more intuitive. - **Performance and Compatibility Improvements**: The overall architecture is more efficient and compatible with all versions of Cocos Creator 3.8.6 and above. ## Tool System and Opcodes - All tools are named with "category_operation", parameters adopt a unified Schema, and support multi-opcode (action) switching, which greatly improves flexibility and scalability. - 50 core tools cover all editor operations such as scenes, nodes, components, prefabs, resources, projects, debugging, preferences, servers, and message broadcasting. - Tool call example: ```json { "tool": "node_lifecycle", "arguments": { "action": "create", "name": "MyNode", "parentUuid": "parent-uuid", "nodeType": "2DNode" } } ``` --- ## Main Function Categories (Partial Examples) - **scene_management**: Scene management (get/open/save/new/close scene) - **node_query / node_lifecycle / node_transform**: Node query, create, delete, attribute change - **component_manage / component_script / component_query**: Component add/delete, script mounting, component information - **prefab_browse / prefab_lifecycle / prefab_instance**: Prefab browsing, creation, instantiation, synchronization - **asset_manage / asset_analyze**: Resource import, delete, dependency analysis - **project_manage / project_build_system**: Project run, build, configuration information - **debug_console / debug_logs**: Console and log management - **preferences_manage**: Preference settings - **server_info**: Server information - **broadcast_message**: Message broadcast ### v1.4.0 - July 26, 2025 (Current github version) #### 🎯 Major Function Fixes - **Completely Fixed Prefab Creation Function**: Completely solved the problem of component/node/resource type reference loss during prefab creation - **Correct Reference Handling**: Implemented a reference format that is completely consistent with manual prefab creation - **Internal Reference**: Node and component references inside the prefab are correctly converted to `{"__id__": x}` format - **External Reference**: Node and component references outside the prefab are correctly set to `null` - **Resource Reference**: Resource references such as prefabs, textures, and sprite frames completely retain the UUID format - **Component/Script Removal API Standardization**: Now, when removing components/scripts, you must pass in the component's cid (type field), not the script name or class name. AI and users should first use getComponents to get the type field (cid), and then pass it to removeComponent. This can 100% accurately remove all types of components and scripts, and is compatible with all Cocos Creator versions. #### 🔧 Core Improvements - **Index Order Optimization**: Adjusted the creation order of prefab objects to ensure consistency with the Cocos Creator standard format - **Component Type Support**: Extended component reference detection to support all cc. component types (Label, Button, Sprite, etc.) - **UUID Mapping Mechanism**: Improved the internal UUID to index mapping system to ensure that reference relationships are established correctly - **Attribute Format Standardization**: Fixed component attribute order and format to eliminate engine parsing errors #### 🐛 Bug Fixes - **Fixed Prefab Import Error**: Solved the `Cannot read properties of undefined (reading '_name')` error - **Fixed Engine Compatibility**: Solved the `placeHolder.initDefault is not a function` error - **Fixed Attribute Overwrite**: Prevented key attributes such as `_objFlags` from being overwritten by component data - **Fixed Reference Loss**: Ensured that all types of references can be correctly saved and loaded #### 📈 Feature Enhancements - **Complete Component Attribute Retention**: All component attributes, including private attributes (such as _group, _density, etc.) - **Child Node Structure Support**: Correctly handle the hierarchical structure and child node relationships of prefabs - **Transform Attribute Handling**: Retain node position, rotation, scaling, and hierarchy information - **Debugging Information Optimization**: Added detailed reference handling logs for easy problem tracking #### 💡 Technical Breakthroughs - **Reference Type Identification**: Intelligently distinguish between internal and external references to avoid invalid references - **Format Compatibility**: The generated prefab is 100% compatible with the format of manually created prefabs - **Engine Integration**: The prefab can be mounted into the scene normally without any runtime errors - **Performance Optimization**: Optimized the prefab creation process to improve the processing efficiency of large prefabs **🎉 Now the prefab creation function is fully available, supporting complex component reference relationships and complete prefab structure!** ### v1.3.0 - July 25, 2024 #### 🆕 New Features - **Integrated Tool Management Panel**: Added comprehensive tool management functionality directly within the main control panel - **Tool Configuration System**: Implemented selective tool enabling/disabling with support for persistent configuration - **Dynamic Tool Loading**: Enhanced tool discovery to dynamically load all 158 available tools in the MCP server - **Real-time Tool Status Management**: Added real-time updates for tool counts and status, reflecting immediately when individual tools are toggled - **Configuration Persistence**: Automatically saves and loads tool configurations between editor sessions #### 🔧 Improvements - **Unified Panel Interface**: Merged tool management into the main MCP server panel as a tab, eliminating the need for a separate panel - **Enhanced Server Settings**: Improved server configuration management with better persistence and loading capabilities - **Vue 3 Integration**: Upgraded to Vue 3 Composition API for better reactivity and performance - **Better Error Handling**: Added comprehensive error handling, including rollback mechanisms for failed operations - **Improved UI/UX**: Enhanced visual design with proper separators, distinct block styling, and non-opaque modal backgrounds #### 🐛 Bug Fixes - **Fixed Tool State Persistence**: Resolved issues with tool states resetting on tab switches or panel reopens - **Fixed Configuration Loading**: Corrected server settings loading issues and message registration problems - **Fixed Checkbox Interaction**: Addressed checkbox unchecking issues and improved responsiveness - **Fixed Panel Scrolling**: Ensured proper scrolling functionality within the tool management panel - **Fixed IPC Communication**: Resolved various IPC communication issues between the frontend and backend #### 🏗️ Technical Improvements - **Simplified Architecture**: Removed multi-configuration complexity, focusing on single configuration management - **Better Type Safety**: Enhanced TypeScript type definitions and interfaces - **Improved Data Synchronization**: Better synchronization between frontend UI state and backend tool manager - **Enhanced Debugging**: Added comprehensive logging and debugging capabilities #### 📊 Statistics - **Total Tools**: Increased from 151 to 158 tools - **Categories**: 13 tool categories, comprehensively covered - **Editor Control**: Achieved 98% editor functionality coverage ### v1.2.0 - Previous Versions - Initial release with 151 tools - Basic MCP server functionality - Scene, node, component, and prefab operations - Project control and debugging tools ## Quick Start **Claude cli configuration:** ``` claude mcp add --transport http cocos-creator http://127.0.0.1:3000/mcp（Use your own configured port number） ``` **Claude client configuration:** ``` { "mcpServers": { "cocos-creator": { "type": "http", "url": "http://127.0.0.1:3000/mcp" } } } ``` **Cursor or VS Class MCP Configuration** ``` { "mcpServers": { "cocos-creator": { "url": "http://localhost:3000/mcp" } } } ``` ## Features ### 🎯 Scene Operations (scene_*) - **scene_management**: Scene Management - Get current scene, open/save/create/close scene, support scene list query - **scene_hierarchy**: Scene Hierarchy - Get complete scene structure, support component information included - **scene_execution_control**: Execution Control - Execute component methods, scene scripts, prefab synchronization ### 🎮 Node Operations (node_*) - **node_query**: Node Query - Find nodes by name/pattern, get node information, detect 2D/3D types - **node_lifecycle**: Node Lifecycle - Create/delete nodes, support component pre-installation, prefab instantiation - **node_transform**: Node Transform - Modify node name, position, rotation, scaling, visibility, and other attributes - **node_hierarchy**: Node Hierarchy - Move, copy, paste nodes, support hierarchical structure operations - **node_clipboard**: Node Clipboard - Copy/paste/cut node operations - **node_property_management**: Property Management - Reset node properties, component properties, transform properties ### 🔧 Component Operations (component_*) - **component_manage**: Component Management - Add/delete engine components (cc.Sprite, cc.Button, etc.) - **component_script**: Script Component - Mount/remove custom script components - **component_query**: Component Query - Get component list, detailed information, available component types - **set_component_property**: Property Setting - Set single or multiple component property values ### 📦 Prefab Operations (prefab_*) - **prefab_browse**: Prefab Browse - List prefabs, view information, verify files - **prefab_lifecycle**: Prefab Lifecycle - Create prefab from node, delete prefab - **prefab_instance**: Prefab Instance - Instantiate to scene, unlink, apply changes, restore original - **prefab_edit**: Prefab Edit - Enter/exit edit mode, save prefab, test changes ### 🚀 Project Control (project_*) - **project_manage**: Project Management - Run project, build project, get project information and settings - **project_build_system**: Build System - Control build panel, check build status, preview server management ### 🔍 Debugging Tools (debug_*) - **debug_console**: Console Management - Get/clear console logs, support filtering and limiting - **debug_logs**: Log Analysis - Read/search/analyze project log files, support pattern matching - **debug_system**: System Debugging - Get editor information, performance statistics, environment information ### 📁 Asset Management (asset_*) - **asset_manage**: Asset Management - Batch import/delete assets, save metadata, generate URL - **asset_analyze**: Asset Analysis - Get dependencies, export asset manifest - **asset_system**: Asset System - Refresh assets, query asset database status - **asset_query**: Asset Query - Query assets by type/folder, get detailed information - **asset_operations**: Asset Operations - Create/copy/move/delete/save/re-import assets ### ⚙️ Preferences (preferences_*) - **preferences_manage**: Preference Management - Get/set editor preferences - **preferences_global**: Global Settings - Manage global configurations and system settings ### 🌐 Server and Broadcast (server_* / broadcast_*) - **server_info**: Server Information - Get server status, project details, environment information - **broadcast_message**: Message Broadcast - Listen and broadcast custom messages ### 🖼️ Reference Image (referenceImage_*) - **reference_image_manage**: Reference Image Management - Add/delete/manage reference images in the scene view - **reference_image_view**: Reference Image View - Control the display and editing of reference images ### 🎨 Scene View (sceneView_*) - **scene_view_control**: Scene View Control - Control Gizmo tools, coordinate system, view mode - **scene_view_tools**: Scene View Tools - Manage various tools and options for the scene view ### ✅ Validation Tools (validation_*) - **validation_scene**: Scene Validation - Validate scene integrity, check for missing resources - **validation_asset**: Asset Validation - Validate asset references, check asset integrity ### 🛠️ Tool Management - **Tool Configuration System**: Selectively enable/disable tools, support multiple sets of configurations - **Configuration Persistence**: Automatically save and load tool configurations - **Configuration Import/Export**: Support import and export of tool configurations - **Real-time Status Management**: Real-time update and synchronization of tool status ### 🚀 Core Advantages - **Unified Opcodes**: All tools are named with "category_operation", and the parameter Schema is unified - **High Reusability**: 50 core tools cover 99% of editor functions - **AI Friendly**: Clear parameters, complete documentation, simple calls - **Performance Optimization**: Reduce token consumption by 50%, improve AI call success rate - **Fully Compatible**: 100% aligned with Cocos Creator official API ## Installation Instructions ### 1. Copy Plugin Files Copy the entire `cocos-mcp-server` folder to the `extensions` directory of your Cocos Creator project. You can also directly import the project in the extension manager: ``` Your Project/ ├── assets/ ├── extensions/ │ └── cocos-mcp-server/ <- Put the plugin here │ ├── source/ │ ├── dist/ │ ├── package.json │ └── ... ├── settings/ └── ... ``` ### 2. Install Dependencies ```bash cd extensions/cocos-mcp-server npm install ``` ### 3. Build Plugin ```bash npm run build ``` ### 4. Enable Plugin 1. Restart Cocos Creator or refresh the extension 2. The plugin will appear in the extension menu 3. Click `Extensions > Cocos MCP Server` to open the control panel ## Usage ### Start Server 1. Open the MCP server panel from `Extensions > Cocos MCP Server` 2. Configure settings: - **Port**: HTTP server port (default: 3000) - **Auto Start**: Automatically start the server when the editor starts - **Debug Logs**: Enable detailed logs for development debugging - **Max Connections**: Maximum number of concurrent connections allowed 3. Click "Start Server" to start accepting connections ### Connect AI Assistant The server provides an HTTP endpoint at `http://localhost:3000/mcp` (or the port you configured). The AI assistant can connect using the MCP protocol and access all available tools. ## Development ### Project Structure ``` cocos-mcp-server/ ├── source/ # TypeScript source files │ ├── main.ts # Plugin entry point │ ├── mcp-server.ts # MCP server implementation │ ├── settings.ts # Settings management │ ├── types/ # TypeScript type definitions │ ├── tools/ # Tool implementation │ │ ├── scene-tools.ts │ │ ├── node-tools.ts │ │ ├── component-tools.ts │ │ ├── prefab-tools.ts │ │ ├── project-tools.ts │ │ ├── debug-tools.ts │ │ ├── preferences-tools.ts │ │ ├── server-tools.ts │ │ ├── broadcast-tools.ts │ │ ├── scene-advanced-tools.ts (Integrated into node-tools.ts and scene-tools.ts) │ │ ├── scene-view-tools.ts │ │ ├── reference-image-tools.ts │ │ └── asset-advanced-tools.ts │ ├── panels/ # UI panel implementation │ └── test/ # Test files ├── dist/ # Compiled JavaScript output ├── static/ # Static resources (icons, etc.) ├── i18n/ # Internationalization files ├── package.json # Plugin configuration └── tsconfig.json # TypeScript configuration ``` ### Build from Source ```bash # Install Dependencies npm install # Development Build (Watch Mode) npm run watch # Production Build npm run build ``` ### Add New Tool 1. Create a new tool class in `source/tools/` 2. Implement the `ToolExecutor` interface 3. Add the tool to the `mcp-server.ts` initialization 4. The tool will be automatically exposed via the MCP protocol ### TypeScript Support The plugin is written entirely in TypeScript and features: * Strict type checking enabled * Comprehensive type definitions for all APIs * IntelliSense support during development * Automatic compilation to JavaScript ## Troubleshooting ### Common Issues 1. **Server fails to start**: Check port availability and firewall settings 2. **Tool doesn't work**: Ensure the scene is loaded and the UUID is valid 3. **Build errors**: Run `npm run build` to check for TypeScript errors 4. **Connection issues**: Verify the HTTP URL and server status ### Debug Mode Enable debug logs in the plugin panel for detailed operation logs. ### Using Debug Tools ```json { "tool": "debug_get_console_logs", "arguments": {"limit": 50, "filter": "error"} } ``` ```json { "tool": "debug_validate_scene", "arguments": {"checkMissingAssets": true} } ``` ## System Requirements * Cocos Creator 3.8.6 or later * Node.js (included with Cocos Creator) * TypeScript (installed as a development dependency) ## License This plugin is for Cocos Creator projects, and the source code is packaged together for learning and communication. There is no encryption. You can support your own secondary development and optimization, and any code or derivative code of this project shall not be used for any commercial or resale purposes. If you need to use it for commercial purposes, please contact me. ## Contact Me to Join the Group <img alt="image" src="https://github.com/user-attachments/assets/a276682c-4586-480c-90e5-6db132e89e0f" width="400" height="400" />