Unity Code MCP

🚀 Unity Code MCP

Unity Code MCP 是一個專注於編碼的模型上下文協議（MCP）服務器，它能讓 AI 代理自主編寫 Unity 代碼。

🚀 快速開始

Unity Code MCP 是一款高性能、專注於編碼的 MCP 服務器，用 Rust 構建而成。它能優雅地處理 Unity 的編譯週期，同時僅提供自主代碼開發所需的基本工具：編譯反饋和測試執行。

此 MCP 服務器能讓 AI 代理以卓越的速度和可靠性自主開發 Unity 代碼 —— 編寫代碼、編譯、修復編譯錯誤、測試、修復 bug，不斷重複，就像人類開發一樣。

✨ 主要特性

• 🤖 編碼優化：為 AI 代理高效編碼工作流程設計的精簡工具。
• ⚡ 輕量級與高性能：採用 Rust 構建，速度極快，內存使用極少，響應時間極短。當工作區不是 Unity 項目時，僅使用 1MB 內存；當工作區是 Unity 項目且 Unity 編輯器為該項目打開時，也僅使用 10MB 內存。此外，與 Unity 編輯器的通信基於 UDP，對系統的負載極小。
• 🎯 高效通信：通過基本操作實現最少的令牌使用，僅返回相關信息。
• 🧪 測試驅動：具備全面的測試執行和報告功能。
• 📦 自包含：單個二進制文件，無運行時依賴（無需 Node.js、Python 或 .NET）。

📦 安裝指南

前提條件

• Unity 6.0 或更高版本
• Rust 工具鏈（用於從源代碼構建）
• CMake 和 C 編譯器（用於構建依賴項）

步驟 1：安裝 Unity 包

在你的 Unity 項目中安裝 Visual Studio Code Editor 包。

步驟 2：獲取二進制文件

選項 A：下載發行版（推薦）（僅適用於 Windows）

• 從發行版頁面下載最新的二進制文件。

選項 B：從源代碼構建

cargo build --release

步驟 3：配置你的 AI 助手

將 MCP 服務器添加到你的 AI 助手配置中：

對於 Cursor/Trae：

{
  "mcpServers": {
    "unity-code": {
      "command": "/path/to/unity-code-mcp",
      "env": {
        "UNITY_PROJECT_PATH": "${workspaceFolder}"
      }
    }
  }
}

對於帶有 MCP 擴展的 VS Code：

{
  "mcp.servers": {
    "unity-code": {
      "command": "/path/to/unity_code_mcp",
      "env": {
        "UNITY_PROJECT_PATH": "${workspaceFolder}"
      }
    }
  }
}

對於 Claude Desktop：

{
  "mcpServers": {
    "unity-code": {
      "command": "/path/to/unity_code_mcp"
    }
  }
}

⚠️ 重要提示

UNITY_PROJECT_PATH 環境變量是一個備用選項。如果你的 IDE 支持 MCP roots 功能，服務器將自動從提供的工作區根目錄檢測 Unity 項目，並優先使用該信息而非環境變量。

💡 使用建議

如果 ${workspaceFolder} 在你的 IDE 中不起作用，嘗試使用絕對路徑，例如 "UNITY_PROJECT_PATH": "/absolute/path/to/your/unity/project"。或者，要求你的 IDE 開發者添加對 MCP roots 功能的支持。

⚠️ 重要提示

二進制命令請使用絕對路徑。

💻 使用示例

基礎用法

配置完成後，AI 代理可以完全自主地開發 Unity 代碼：

用戶：“創建一個玩家控制器，使用 WASD 鍵移動並具備跳躍功能。確保它經過充分測試。”

AI：我將創建一個具備移動和跳躍功能的完整玩家控制器，然後編寫全面的測試。

1. [AI 編寫帶有移動邏輯的 PlayerController.cs]
2. [AI 調用：refresh_asset_database]
   → 結果：“編譯失敗：CS0246：找不到類型或命名空間名稱 'Rigidbody'”
3. [AI 修復缺失的 using UnityEngine; 語句]
4. [AI 調用：refresh_asset_database]
   → 結果：“編譯成功，無錯誤”
5. [AI 編寫帶有移動和跳躍測試的 PlayerControllerTests.cs]
6. [AI 調用：run_tests]
   → 結果：“5 個測試通過，2 個測試失敗：Jump_ShouldApplyUpwardForce 中出現 NullReferenceException，Move_WithInvalidInput 中出現 ArgumentException”
7. [AI 分析失敗原因並修復空引用和輸入驗證錯誤]
8. [AI 調用：refresh_asset_database]
   → 結果：“編譯成功，無錯誤”
9. [AI 調用：run_tests]
   → 結果：“所有 7 個測試均成功通過”

AI：✅ 完成！創建了一個具備 WASD 移動、跳躍機制的完整玩家控制器，並進行了全面測試。所有測試均通過。

這展示了真正的自主開發 —— 從用戶請求到經過充分測試、可正常運行的 Unity 代碼，無需任何人工干預。

高級用法

AI 代理自主修復 Unity 項目編譯錯誤示例：

📚 詳細文檔

🔧 MCP 服務器工具

Unity Code MCP 為自主代碼開發提供了 2 種工具：

1. 資產數據庫刷新

• 觸發 Unity 編譯和資產處理。
• 返回編譯錯誤以及其他非編譯警告和錯誤 僅包括刷新期間的日誌。
• 優雅地處理域重新加載。

資產數據庫刷新工具運行示例：

2. 測試執行

• 運行 Unity 測試並提供全面的報告。
• 為失敗的測試提供詳細的堆棧跟蹤和日誌。
• 支持 EditMode 和 PlayMode 測試。

測試執行工具運行示例：

🔧 技術細節

平臺支持

代碼是跨平臺的，但由於我僅使用 Windows，無法為其他平臺進行構建或測試。如果存在特定平臺的 bug，你需要自行修復。

🧪 開發與測試

運行測試

要運行測試套件：

1. 啟動 Unity 編輯器 並加載嵌入式測試項目：

   # 打開 Unity 編輯器並加載項目：
   # ./UnityProject
   

2. 運行測試（單線程運行以避免與 Unity 衝突）：

   cargo test -- --test-threads=1
   

⚠️ 重要提示

測試需要一個運行中的 Unity 編輯器實例，並加載嵌入式項目。由於與 Unity 編輯器的交互，測試可能需要 30 - 60 秒才能完成。

從源代碼構建

前提條件

• C 編譯器：構建 aws-lc-rs 依賴項所需。
  • Windows：MSVC（Visual Studio 構建工具）
  • macOS：Xcode 命令行工具 (xcode-select --install)
  • Linux：GCC（在 Ubuntu/Debian 上使用 sudo apt-get install build-essential）
• CMake：構建 aws-lc-rs 依賴項所需。
  • Windows：遵循 官方指南
  • macOS：brew install cmake
  • Linux：sudo apt-get install cmake（Ubuntu/Debian）

構建命令

# 調試構建
cargo build

# 發行版構建（推薦用於生產環境）
cargo build --release

🤝 貢獻代碼

歡迎貢獻代碼！請按以下步驟操作：

1. 分叉倉庫。
2. 創建功能分支。
3. 使用 cargo test -- --test-threads=1 運行測試。
4. 提交拉取請求。

📄 許可證

本項目採用 MIT 許可證 —— 詳情請參閱 LICENSE 文件。

🔗 相關項目

• Visual Studio Code Editor for Unity - 必需的 Unity 包
• Model Context Protocol - 協議規範
• Unity Code Pro VS Code Extension - 相關的 VS Code 擴展