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 扩展