Cocos MCP Server

🚀 Cocos Creator MCP Server插件

Cocos Creator MCP Server插件是一款全面的MCP（模型上下文協議）服務器插件，適用於Cocos Creator 3.8+版本。它允許AI助手通過標準化協議與Cocos Creator編輯器進行交互，支持一鍵安裝和使用，無需複雜的環境配置。該插件已在Claude客戶端Claude CLI和Cursor上進行了測試，理論上也能完美支持其他編輯器。

🚀 目前提供13大類共151種工具，實現了98%的編輯器控制！（預製體實例化存在已知的子節點恢復問題）

🚀 快速開始

鏈接導航

• 📖 完整功能指南（英文） - 所有151個工具的詳細文檔（待完成）
• 📖 完整功能指南（中文） - 所有151個工具的詳細文檔（待完成）

不同客戶端配置示例

Claude cli配置

claude mcp add --transport http cocos-creator http://127.0.0.1:3000/mcp (使用您自己配置的端口號)

Claude客戶端配置

{
    "mcpServers": {
        "cocos-creator": {
            "type": "http",
            "url": "http://127.0.0.1:3000/mcp"
        }
    }
}

Cursor或VS類MCP配置

{
    "mcpServers": {
        "cocos-creator": {
            "url": "http://localhost:3000/mcp"
        }
    }
}

✨ 主要特性

🎯 場景操作

• 獲取當前場景信息和完整的場景列表
• 通過路徑打開場景並保存當前場景
• 創建具有自定義名稱的新場景
• 獲取包含組件信息的完整場景層次結構

🎮 節點操作

• 創建不同類型的節點（Node、2DNode、3DNode）
• 通過UUID獲取節點信息並按名稱模式查找節點
• 設置節點屬性（位置、旋轉、縮放、激活狀態）
• 刪除、移動和複製節點，支持完整的層次結構

🔧 組件操作

• 從節點添加/移除組件
• 獲取節點的所有組件及其屬性
• 動態設置組件屬性
• 從資源路徑附加腳本組件
• 按類別列出可用的組件類型

📦 預製體操作

• 列出項目中按文件夾組織的所有預製體
• 加載、實例化和創建預製體
• 更新現有預製體並還原預製體實例
• 獲取包括依賴項在內的詳細預製體信息
• ⚠️ 已知問題：由於Cocos Creator API的限制，預製體實例化可能無法正確恢復子節點。

🚀 項目控制

• 在預覽模式下運行項目（瀏覽器/模擬器）
• 為不同平臺（Web、移動、桌面）構建項目
• 獲取項目信息和設置
• 刷新資源數據庫並導入新資源
• 獲取詳細的資源信息

🔍 調試工具

• 獲取經過過濾的編輯器控制檯日誌
• 清除控制檯並在場景上下文中執行JavaScript
• 獲取用於調試的詳細節點樹
• 性能統計和場景驗證
• 獲取編輯器和環境信息

⚙️ 附加功能

• 偏好設置管理：獲取/設置編輯器偏好和全局設置
• 服務器控制：服務器信息、項目詳細信息和編輯器控制
• 消息廣播：監聽和廣播自定義消息
• 資源管理：創建、複製、移動、刪除和查詢資源
• 構建系統：項目構建和預覽服務器控制
• 參考圖像管理：在場景視圖中添加、移除和管理參考圖像
• 場景視圖控制：控制小控件工具、座標系和視圖模式
• 高級場景操作：撤銷/重做、快照和高級節點操作

📦 安裝指南

1. 複製插件文件

將整個 cocos-mcp-server 文件夾複製到您的Cocos Creator項目的 extensions 目錄中：

YourProject/
├── assets/
├── extensions/
│   └── cocos-mcp-server/          <- 將插件放置在此處
│       ├── source/
│       ├── dist/
│       ├── package.json
│       └── ...
├── settings/
└── ...

2. 安裝依賴項

cd extensions/cocos-mcp-server
npm install

3. 構建插件

npm run build

4. 啟用插件

1. 重啟Cocos Creator或刷新擴展。
2. 插件將出現在擴展菜單中。
3. 點擊 擴展 > Cocos MCP Server 打開控制面板。

💻 使用示例

基礎用法

創建新的精靈節點

{
    "tool": "node_create_node",
    "arguments": {
        "name": "MySprite",
        "nodeType": "2DNode",
        "parentUuid": "parent-node-uuid"
    }
}

添加精靈組件

{
    "tool": "component_add_component",
    "arguments": {
        "nodeUuid": "node-uuid",
        "componentType": "cc.Sprite"
    }
}

實例化預製體

{
    "tool": "prefab_instantiate_prefab",
    "arguments": {
        "prefabPath": "db://assets/prefabs/Enemy.prefab",
        "position": { "x": 100, "y": 200, "z": 0 }
    }
}

⚠️ 重要提示

由於Cocos Creator API的限制，帶有子節點的複雜預製體可能無法正確實例化，實例化的預製體中可能會缺少子節點。

在瀏覽器中運行項目

{
    "tool": "project_run_project",
    "arguments": {
        "platform": "browser"
    }
}

📚 詳細文檔

工具配置

設置存儲在 YourProject/settings/mcp-server.json 中：

{
    "port": 3000,
    "autoStart": false,
    "enableDebugLog": true,
    "allowedOrigins": ["*"],
    "maxConnections": 10
}

圖標設置

要為插件面板添加圖標：

1. 創建一個PNG圖標文件（推薦尺寸：32x32或64x64）。
2. 將其放置在 static/ 目錄中：static/icon.png。
3. 圖標路徑已在 package.json 中配置。

🔧 技術細節

項目結構

cocos-mcp-server/
├── source/                    # TypeScript源文件
│   ├── main.ts               # 插件入口點
│   ├── mcp-server.ts         # MCP服務器實現
│   ├── settings.ts           # 設置管理
│   ├── types/                # TypeScript類型定義
│   ├── tools/                # 工具實現
│   │   ├── 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
│   │   ├── scene-view-tools.ts
│   │   ├── reference-image-tools.ts
│   │   └── asset-advanced-tools.ts
│   ├── panels/               # UI面板實現
│   └── test/                 # 測試文件
├── dist/                     # 編譯後的JavaScript輸出
├── static/                   # 靜態資產（圖標等）
├── i18n/                     # 國際化文件
├── package.json              # 插件配置
└── tsconfig.json             # TypeScript配置

從源代碼構建

# 安裝依賴項
npm install

# 在開發模式下進行構建並開啟監聽
npm run watch

# 進行生產環境構建
npm run build

添加新工具

1. 在 source/tools/ 中創建一個新的工具類。
2. 實現 ToolExecutor 接口。
3. 將工具添加到 mcp-server.ts 的初始化中。
4. 工具將通過MCP協議自動公開。

TypeScript支持

該插件完全用TypeScript編寫，具有以下特點：

• 啟用嚴格的類型檢查
• 為所有API提供全面的類型定義
• 開發時支持智能感知
• 自動編譯為JavaScript

運行測試

# 運行綜合測試套件
node comprehensive-test.js

# 運行特定功能測試
./test-all-features.sh

# 運行Node.js測試腳本
node test-mcp-server.js

故障排除

常見問題

1. 服務器無法啟動：檢查端口可用性和防火牆設置。
2. 工具無法正常工作：確保場景已加載且UUID有效。
3. 構建錯誤：運行 npm run build 檢查TypeScript錯誤。
4. 連接問題：驗證HTTP URL和服務器狀態。

調試模式

在插件面板中啟用調試日誌以獲取詳細的操作日誌。

使用調試工具

{
    "tool": "debug_get_console_logs",
    "arguments": {"limit": 50, "filter": "error"}
}

{
    "tool": "debug_validate_scene",
    "arguments": {"checkMissingAssets": true}
}

系統要求

• Cocos Creator 3.8.6或更高版本
• Node.js（隨Cocos Creator捆綁）
• TypeScript（作為開發依賴項安裝）

架構說明

此插件使用簡化的MCP協議實現，與Cocos Creator的CommonJS環境兼容。HTTP服務器為AI助手提供了一個JSON-RPC接口，用於與編輯器進行交互。

協議支持

• HTTP連接：http://localhost:3000/mcp（端口可配置）
• JSON-RPC 2.0：標準請求/響應格式
• 工具發現：tools/list 方法返回可用工具
• 工具執行：tools/call 方法執行特定工具

📄 許可證

本插件用於Cocos Creator項目，源代碼未加密且打包在一起，可用於學習和交流。支持您進行二次開發和優化，但本項目的任何代碼或其衍生代碼不得用於任何商業目的或轉售。如需商業使用，請與我聯繫。