Unity-MCP

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

概述

Unity-MCP 是一个用于 Unity 游戏开发的模型上下文协议的开源实现。它使 AI 助手能够通过标准化接口与 Unity 游戏环境进行交互，从而实现 AI 辅助游戏开发、自动化测试、场景分析和运行时调试。

架构

该架构已简化为使用 AILogger 进行持久化，无需单独的服务器组件：

AI 助手 <-> Unity-MCP STDIO 客户端 <-> Unity 客户端 <-> 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
   
   # 仅运行 e2e 测试
   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 工具，您就可以要求它执行以下任务：

你能否在 Unity 中执行以下 C# 代码？

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

许可证

MIT

作者

T Savo (@TSavo)