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+, enabling AI assistants to interact with the Cocos Creator editor through a standardized protocol. It offers one-click installation and usage, eliminating all cumbersome environment setup and configuration. It has been tested with the Claude client, Claude CLI, and Cursor, and theoretically supports other editors perfectly. **🚀 Now offering 50 powerful fusion tools, achieving 99% editor control!** ## Video Demonstration and Tutorials [<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 updated) - **[📖 完整功能指南 (中文)](FEATURE_GUIDE_CN.md)** - 所有158工具的详细文档（待补充） ## Changelog ## 🚀 Major Update v1.5.0 (July 29, 2024) (Already updated in Cocos Store, GitHub version will be updated in the next release) Cocos Store: https://store.cocos.com/app/detail/7941 If you prefer not to purchase, you can join the communication group, and I can send you the latest version directly! - **Tool Streamlining and Refactoring**: Condensed the original 150+ tools into 50 core tools with high reusability and coverage, removing all ineffective redundant code, greatly enhancing usability and maintainability. - **Unified Operation Code**: All tools adopt the "operation code + parameters" model, significantly simplifying the AI calling process, increasing the success rate of AI calls, reducing the number of AI calls, and lowering token consumption by 50%. - **Comprehensive Upgrade of Prefab Functionality**: Thoroughly fixed and improved all core functionalities related to prefab creation, instantiation, synchronization, and referencing, supporting complex reference relationships, and aligning 100% with the official format. - **Event Binding and Legacy Functionality Completion**: Supplemented and implemented event binding, node/component/resource, and other legacy functionalities, with all methods fully aligned with the official implementation. - **Interface Optimization**: All interface parameters are clearer, documentation is more complete, making it easier for AI to understand and call. - **Plugin Panel Optimization**: The panel UI is more concise, and operations are more intuitive. - **Performance and Compatibility Enhancements**: Overall architecture is more efficient, compatible with all versions of Cocos Creator 3.8.6 and above. ## Tool System and Operation Codes - All tools are named in the format "category_operation", with parameters following a unified schema, supporting multi-operation code (action) switching, greatly enhancing flexibility and scalability. - The 50 core tools cover all editor operations including scenes, nodes, components, prefabs, resources, projects, debugging, preferences, servers, and message broadcasting. - Example of tool invocation: ```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/create/close scenes) - **node_query / node_lifecycle / node_transform**: Node querying, creation, deletion, property changes - **component_manage / component_script / component_query**: Component addition/removal, script mounting, component information - **prefab_browse / prefab_lifecycle / prefab_instance**: Prefab browsing, creation, instantiation, synchronization - **asset_manage / asset_analyze**: Resource import, deletion, dependency analysis - **project_manage / project_build_system**: Project running, building, configuration information - **debug_console / debug_logs**: Console and log management - **preferences_manage**: Preferences management - **server_info**: Server information - **broadcast_message**: Message broadcasting ### v1.4.0 - July 26, 2025 (Current GitHub Version) #### 🎯 Major Function Fixes - **Complete Fix for Prefab Creation Functionality**: Thoroughly resolved the issue of component/node/resource type references being lost during prefab creation. - **Correct Reference Handling**: Achieved a reference format that is completely consistent with manually created prefabs. - **Internal References**: Node and component references within the prefab are correctly converted to `{"__id__": x}` format. - **External References**: Node and component references outside the prefab are correctly set to `null`. - **Resource References**: Prefab, texture, sprite frame, and other resource references fully retain UUID format. - **Component/Script Removal API Standardization**: When removing components/scripts, the component's cid (type field) must now be passed; script names or class names cannot be used. AI and users should first use getComponents to obtain the type field (cid) and then pass it to removeComponent. This ensures 100% accurate removal of all types of components and scripts, compatible with all versions of Cocos Creator. #### 🔧 Core Improvements - **Index Order Optimization**: Adjusted the order of prefab object creation to ensure consistency with Cocos Creator's standard format. - **Component Type Support**: Expanded component reference detection to support all cc.-prefixed component types (Label, Button, Sprite, etc.). - **UUID Mapping Mechanism**: Improved the internal UUID to index mapping system to ensure correct establishment of reference relationships. - **Property Format Standardization**: Fixed the order and format of component properties to eliminate engine parsing errors. #### 🐛 Bug Fixes - **Fixed Prefab Import Error**: Resolved the `Cannot read properties of undefined (reading '_name')` error. - **Fixed Engine Compatibility**: Resolved the `placeHolder.initDefault is not a function` error. - **Fixed Property Overwrites**: Prevented critical properties like `_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 Property Retention**: All component properties, including private properties (like _group, _density, etc.), are retained. - **Child Node Structure Support**: Correctly handles the hierarchy structure and child node relationships of prefabs. - **Transform Property Handling**: Retains node position, rotation, scale, and hierarchy information. - **Debug Information Optimization**: Added detailed reference handling logs for easier issue tracking. #### 💡 Technical Breakthroughs - **Reference Type Identification**: Smartly distinguishes between internal and external references to avoid invalid references. - **Format Compatibility**: The generated prefabs are 100% compatible with manually created prefab formats. - **Engine Integration**: Prefabs can be mounted to scenes without any runtime errors. - **Performance Optimization**: Optimized the prefab creation process to improve the handling efficiency of large prefabs. **🎉 The prefab creation functionality is now fully available, supporting complex component reference relationships and complete prefab structures!** ### v1.3.0 - July 25, 2024 #### 🆕 New Features - **Integrated Tool Management Panel**: Added comprehensive tool management functionality directly in the main control panel. - **Tool Configuration System**: Implemented selective tool enabling/disabling, supporting persistent configuration. - **Dynamic Tool Loading**: Enhanced tool discovery functionality, capable of dynamically loading all 158 available tools from the MCP server. - **Real-time Tool Status Management**: Added real-time updates for tool counts and statuses, reflecting changes immediately when a single tool is 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 responsiveness and performance. - **Better Error Handling**: Added comprehensive error handling, including rollback mechanisms for failed operations. - **Improved UI/UX**: Enhanced visual design, including appropriate separators, unique block styles, and non-transparent modal backgrounds. #### 🐛 Bug Fixes - **Fixed Tool Status Persistence**: Resolved the issue of tool statuses resetting when switching tabs or reopening panels. - **Fixed Configuration Loading**: Corrected server settings loading issues and message registration problems. - **Fixed Checkbox Interaction**: Resolved checkbox deselection issues and improved responsiveness. - **Fixed Panel Scrolling**: Ensured correct scrolling functionality in 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 states and backend tool managers. - **Enhanced Debugging**: Added comprehensive logging and debugging capabilities. #### 📊 Statistics - **Total Tools**: Increased from 151 to 158 tools. - **Categories**: 13 tool categories, providing comprehensive coverage. - **Editor Control**: Achieved 98% coverage of editor functionalities. ### 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 configured port number) ``` **Claude Client Configuration:** ``` { "mcpServers": { "cocos-creator": { "type": "http", "url": "http://127.0.0.1:3000/mcp" } } } ``` **Cursor or VS-like MCP Configuration:** ``` { "mcpServers": { "cocos-creator": { "url": "http://localhost:3000/mcp" } } } ``` ## Feature Characteristics ### 🎯 Scene Operations (scene_*) - **scene_management**: Scene management - Get current scene, open/save/create/close scenes, supports scene list queries. - **scene_hierarchy**: Scene hierarchy - Get complete scene structure, supports component information inclusion. - **scene_execution_control**: Execution control - Execute component methods, scene scripts, prefab synchronization. ### 🎮 Node Operations (node_*) - **node_query**: Node querying - Find nodes by name/pattern, get node information, detect 2D/3D types. - **node_lifecycle**: Node lifecycle - Create/delete nodes, supports component pre-installation, prefab instantiation. - **node_transform**: Node transformation - Modify node name, position, rotation, scale, visibility, and other properties. - **node_hierarchy**: Node hierarchy - Move, copy, paste nodes, supports hierarchical structure operations. - **node_clipboard**: Node clipboard - Copy/paste/cut node operations. - **node_property_management**: Property management - Reset node properties, component properties, transformation properties. ### 🔧 Component Operations (component_*) - **component_manage**: Component management - Add/remove engine components (cc.Sprite, cc.Button, etc.). - **component_script**: Script component - Mount/remove custom script components. - **component_query**: Component querying - Get component lists, detailed information, available component types. - **set_component_property**: Property setting - Set single or multiple component property values. ### 📦 Prefab Operations (prefab_*) - **prefab_browse**: Prefab browsing - List prefabs, view information, validate files. - **prefab_lifecycle**: Prefab lifecycle - Create prefabs from nodes, delete prefabs. - **prefab_instance**: Prefab instance - Instantiate into scenes, unlink, apply changes, restore original. - **prefab_edit**: Prefab editing - Enter/exit edit mode, save prefabs, test changes. ### 🚀 Project Control (project_*) - **project_manage**: Project management - Run projects, build projects, 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, supports filtering and limiting. - **debug_logs**: Log analysis - Read/search/analyze project log files, supports pattern matching. - **debug_system**: System debugging - Get editor information, performance statistics, environment information. ### 📁 Resource Management (asset_*) - **asset_manage**: Resource management - Batch import/delete resources, save metadata, generate URLs. - **asset_analyze**: Resource analysis - Get dependencies, export resource lists. - **asset_system**: Resource system - Refresh resources, query resource database status. - **asset_query**: Resource querying - Query resources by type/folder, get detailed information. - **asset_operations**: Resource operations - Create/copy/move/delete/save/re-import resources. ### ⚙️ Preferences (preferences_*) - **preferences_manage**: Preferences management - Get/set editor preferences. - **preferences_global**: Global settings - Manage global configurations and system settings. ### 🌐 Server and Broadcasting (server_* / broadcast_*) - **server_info**: Server information - Get server status, project details, environment information. - **broadcast_message**: Message broadcasting - Listen to and broadcast custom messages. ### 🖼️ Reference Images (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 systems, view modes. - **scene_view_tools**: Scene view tools - Manage various tools and options in the scene view. ### ✅ Validation Tools (validation_*) - **validation_scene**: Scene validation - Validate scene integrity, check for missing resources. - **validation_asset**: Asset validation - Validate resource references, check resource integrity. ### 🛠️ Tool Management - **Tool Configuration System**: Selectively enable/disable tools, supporting multiple configurations. - **Configuration Persistence**: Automatically save and load tool configurations. - **Configuration Import/Export**: Support for importing and exporting tool configurations. - **Real-time Status Management**: Real-time updates and synchronization of tool statuses. ### 🚀 Core Advantages - **Unified Operation Code**: All tools use "category_operation" naming, with a unified parameter schema. - **High Reusability**: 50 core tools cover 99% of editor functionalities. - **AI Friendly**: Clear parameters, complete documentation, and simple calls. - **Performance Optimization**: Reduces token consumption by 50%, improving AI call success rates. - **Fully Compatible**: 100% aligned with Cocos Creator's official API. ## Installation Instructions ### 1. Copy Plugin Files Copy the entire `cocos-mcp-server` folder into 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/ <- Place the plugin here │ ├── source/ │ ├── dist/ │ ├── package.json │ └── ... ├── settings/ └── ... ``` ### 2. Install Dependencies ```bash cd extensions/cocos-mcp-server npm install ``` ### 3. Build the Plugin ```bash npm run build ``` ### 4. Enable the Plugin 1. Restart Cocos Creator or refresh the extension. 2. The plugin will appear in the extension menu. 3. Click `Extension > Cocos MCP Server` to open the control panel. ## Usage Instructions ### Start the Server 1. Open the MCP server panel from `Extension > 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 begin accepting connections. ### Connect AI Assistant The server provides an HTTP endpoint at `http://localhost:3000/mcp` (or your configured port). AI assistants 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 implementations │ │ ├── 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 (merged into node-tools.ts and scene-tools.ts) │ │ ├── scene-view-tools.ts │ │ ├── reference-image-tools.ts │ │ └── asset-advanced-tools.ts │ ├── panels/ # UI panel implementations │ └── 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 Tools 1. Create a new tool class in `source/tools/`. 2. Implement the `ToolExecutor` interface. 3. Add the tool to the initialization in `mcp-server.ts`. 4. The tool will be automatically exposed via the MCP protocol. ### TypeScript Support The plugin is fully written in TypeScript, featuring: - Strict type checking enabled. - Comprehensive type definitions for all APIs. - IntelliSense support during development. - Automatic compilation to JavaScript. ## Troubleshooting ### Common Issues 1. **Server Won't Start**: Check port availability and firewall settings. 2. **Tools Not Working**: Ensure the scene is loaded and UUIDs are valid. 3. **Build Errors**: Run `npm run build` to check for TypeScript errors. 4. **Connection Issues**: Verify 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 higher. - Node.js (included with Cocos Creator). - TypeScript (installed as a development dependency). ## License This plugin is for use in Cocos Creator projects, and the source code is included for learning and communication purposes. It is not encrypted. You can support your own secondary development and optimization, but any code from this project or derived code cannot be used for commercial purposes or resale. For commercial use, please contact me. ## Contact Me to Join the Group <img src="https://github.com/user-attachments/assets/2e3f043a-0b03-4b27-a175-e9c31fbed981" width="400" height="400"/> <img src="https://github.com/user-attachments/assets/5ef6172c-2968-499e-9edf-7da133016cd2" width="400" height="400"/>