Unity-MCP

一个使用模型上下文协议 (MCP) 的 Unity 与 AI 助手之间的桥梁。

概述

Unity-MCP 是为 Unity 游戏开发实现的 Model Context Protocol (MCP) 的开源版本。它通过标准化接口使 AI 助手能够与 Unity 游戏环境交互，从而支持 AI 辅助游戏开发、自动化测试、场景分析和运行时调试。

架构

架构已经简化，使用 AILogger 进行持久化，不再需要单独的服务器组件：

AI Assistant <-> Unity-MCP STDIO Client <-> Unity Client <-> AILogger

• AI 助手：使用 MCP 协议与 Unity-MCP STDIO 客户端通信
• Unity-MCP STDIO 客户端：将命令转发给 Unity 客户端并将结果存储在 AILogger 中
• Unity 客户端：在 Unity 中执行命令并返回结果
• AILogger：存储日志和结果以供后续检索

Unity-MCP STDIO 客户端直接与 Unity 客户端通信，后者提供了代码执行和查询的端点。查询工具通过将查询包裹在 return 语句中来将其转换为代码执行。

特性

• 在 Unity 运行时环境中执行 C# 代码
• 检查游戏对象及其组件
• 分析场景层次结构和结构
• 运行测试并接收结果
• 调用游戏对象和组件上的方法
• 在运行时修改游戏状态

部署选项

• Unity 编辑器扩展：一个超越游戏执行周期的编辑器扩展
• Docker 容器：一个可以通过网络与 Unity 通信的容器化版本
• NPX 包：一个可以通过 NPX 安装和运行的 Node.js 包

文档

• MCP 架构：MCP 架构和命名空间的概述
• MCP STDIO 客户端：关于 MCP STDIO 客户端及其日志记录能力的信息
• 查询工具：关于查询工具及其工作原理的详细信息
• AILogger 集成：关于 AILogger 集成的详细信息
• API 参考：关于 API 端点的详细信息
• 安装指南：安装和设置 Unity-MCP 的逐步说明
• 开发指南：关于开发环境和工作流程的信息
• 热重载指南：关于开发环境中热重载的详细信息
• 热重载快速参考：热重载命令和技巧的快速参考指南
• 贡献指南：为项目贡献的指南

开始使用

要开始使用 Unity-MCP，请按照以下步骤操作：

1. 克隆仓库：

   git clone https://github.com/TSavo/Unity-MCP.git
   cd Unity-MCP
   

2. 安装依赖项：

   npm install
   

3. 构建项目：

   npm run build
   

4. 启动 MCP STDIO 客户端：

   npm start
   

   这将启动与 Unity 通信并使用 AILogger 进行持久化的 MCP STDIO 客户端。

   注意：确保 AILogger 在 http://localhost:3030 上运行，或者设置 AI_LOGGER_URL 环境变量指向您的 AILogger 实例。

5. 运行测试：

   # 运行所有测试
   npm test
   
   # 仅运行单元测试
   npm run test:unit
   
   # 仅运行端到端测试
   npm run test:e2e
   
   # 使用特定模式运行测试
   npm test -- --testNamePattern="should return the server manifest"
   npm run test:unit -- --testNamePattern="should return the server manifest"
   npm run test:e2e -- --testNamePattern="should discover the test server"
   

有关更详细的说明，请参阅 安装指南。

连接到 AI 助手

要将 Unity-MCP 桥连接到 AI 助手，您需要创建一个 MCP 配置文件：

{
  "mcpServers": {
    "unity-ai-bridge": {
      "url": "http://localhost:8080/sse"
    }
  }
}

将此文件放置在适合您的 AI 助手的位置。对于 Claude，通常会放在 Claude Desktop 应用程序的配置目录中。

可用工具

Unity-MCP 桥提供了以下工具：

1. execute_code：直接在 Unity 中执行 C# 代码。
2. query：使用点表示法执行查询以访问对象、属性和方法。
3. get_logs：从 AILogger 获取日志。
4. get_log_by_name：从 AILogger 获取特定日志。

使用示例

在 Unity 中执行代码

您可以使用 execute_code 工具在 Unity 中执行 C# 代码。代码将在 Unity 运行时环境中执行，并且结果将存储在 AILogger 中以便稍后检索。

JSON-RPC 请求

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
      "code": "Debug.Log(\"Hello from Unity!\"); return GameObject.FindObjectsOfType<GameObject>().Length;",
      "timeout": 5000
    }
  }
}

JSON-RPC 响应

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"success\",\"logName\":\"unity-execute-1712534400000\",\"result\":{\"success\":true,\"result\":42,\"logs\":[\"Hello from Unity!\"],\"executionTime\":123}}"
      }
    ]
  }
}

查询 Unity 对象

您可以使用 query 工具查询 Unity 对象。这允许您使用点表示法访问对象、属性和方法。

JSON-RPC 请求

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "query": "Camera.main.transform.position",
      "timeout": 5000
    }
  }
}

JSON-RPC 响应

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"success\",\"logName\":\"unity-query-1712534400000\",\"result\":{\"success\":true,\"result\":{\"x\":0,\"y\":1,\"z\":-10},\"executionTime\":45}}"
      }
    ]
  }
}

从 AILogger 检索结果

您可以使用 get_log_by_name 工具从 AILogger 检索先前操作的结果。

JSON-RPC 请求

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_log_by_name",
    "arguments": {
      "log_name": "unity-execute-1712534400000",
      "limit": 1
    }
  }
}

JSON-RPC 响应

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"success\",\"name\":\"unity-execute-1712534400000\",\"entries\":[{\"id\":\"123e4567-e89b-12d3-a456-426614174000\",\"name\":\"unity-execute-1712534400000\",\"data\":{\"result\":{\"success\":true,\"result\":42,\"logs\":[\"Hello from Unity!\"],\"executionTime\":123},\"timestamp\":\"2025-04-08T00:00:00.000Z\"},\"timestamp\":\"2025-04-08T00:00:00.000Z\"}]}"
      }
    ]
  }
}

示例用法

一旦 AI 助手可以访问 Unity 工具，您可以要求它执行诸如以下任务：

Can you execute the following C# code in Unity?

GameObject.Find("Player").transform.position = new Vector3(0, 1, 0);

许可证

MIT

作者

T Savo (@TSavo)