Unity MCP 统合框架

英文版本

这是一个可扩展的框架，用于将 Unity 和 Model Context Protocol (MCP) 进行整合。通过这个框架，AI语言模型如Claude可以通过一个可扩展的处理器架构直接与Unity编辑器进行交互。

🌟 特征

• 可扩展插件架构：创建并注册自定义处理器以扩展功能
• 完整的MCP整合：支持MCP的所有基本功能，包括命令、资源和提示
• TypeScript & C# 支持：服务器组件使用TypeScript，Unity组件使用C#
• 编辑器整合：作为具有可定制设置的编辑器工具运行
• 自动检测：自动检测并注册各种处理器
• 通信：基于TCP/IP的Unity与外部AI服务之间的通信

📋 必要条件

• Unity 2022.3.22f1 及以上版本（兼容Unity6.1）
  • 已测试版本：2022.3.22f1, 2023.2.19f1, 6000.0.35f1, 6000.1.0f1
• .NET/C# 9.0
• Node.js 18.0.0 及以上版本及npm（用于TypeScript服务器）
  • 请从Node.js 官方网站下载安装

🚀 开始使用

安装方法

1. 使用Unity包管理器进行安装：
   • 打开包管理器 (Window > Package Manager)
   • 点击“+”按钮
   • 选择“从git URL添加包...”
   • 输入：https://github.com/isuzu-shiranui/UnityMCP.git?path=jp.shiranui-isuzu.unity-mcp

快速设置

1. 打开Unity，进入 Edit > Preferences > Unity MCP
2. 配置连接设置（主机和端口）
3. 点击“Connect”按钮开始等待连接

与Claude Desktop集成

使用安装程序

Unity MCP包含了一个简单的安装和配置TypeScript客户端的工具。

1. 在Unity编辑器中，进入“Edit > Preferences > Unity MCP”
2. 点击“Open Installer Window”按钮打开TypeScript客户端安装器
3. 按照安装器的指示操作：
   • 确认已安装Node.js（未安装时会显示下载链接）
   • 点击“Latest”按钮获取最新版本
   • 选择安装文件夹，并点击“Download and Install TypeScript Client”按钮
   • 安装完成后，打开“Configuration Preview”部分，复制设置JSON到剪贴板
4. 设置Claude Desktop：
   • 打开Claude Desktop
   • 点击“Claude”菜单，选择“Settings...”
   • 点击“Developer”标签，然后点击“Edit Config”按钮
   • 将复制的设置粘贴并保存
5. 重启Claude Desktop以应用设置

这样，Claude Desktop将自动连接到Unity MCP客户端，实现与Unity编辑器的无缝集成。

手动安装

1. 从发布页面下载最新的ZIP文件并解压
2. 记录build/index.js文件的完整路径
3. 打开Claude Desktop的配置文件claude_desktop_config.json
4. 添加以下内容并保存：

{
   "mcpServers": {
      "unity-mcp": {
         "command": "node",
         "args": [
            "path/to/index.js"
         ]
      }
   }
}

※ 请将path/to/index.js替换为实际路径（在Windows上，请使用双反斜杠"\\"或正斜杠"/"）

🔌 架构

Unity MCP框架主要由两个组件构成：

1. Unity C# 插件

• McpServer：监听TCP连接并路由命令的核心服务器
• IMcpCommandHandler：创建自定义命令处理器的接口
• IMcpResourceHandler：创建数据提供资源的接口
• McpSettings：管理插件设置
• McpServiceManager：依赖注入系统，用于服务管理
• McpHandlerDiscovery：自动检测并注册各种处理器

2. TypeScript MCP 客户端

• HandlerAdapter：使各种处理器适应MCP SDK
• HandlerDiscovery：检测并注册处理器实现
• UnityConnection：管理与Unity的TCP/IP通信
• BaseCommandHandler：命令处理器实现的基础类
• BaseResourceHandler：资源处理器实现的基础类
• BasePromptHandler：提示处理器实现的基础类

📄 MCP处理器类型

Unity MCP基于Model Context Protocol (MCP)支持以下三种处理器类型：

1. 命令处理器（工具）

• 用途：执行动作的工具（在Unity侧执行某些操作）
• 控制：模型控制型 - AI模型可以自动调用
• 实现：实现IMcpCommandHandler接口

2. 资源处理器（资源）

• 用途：访问Unity内数据的资源（提供信息）
• 控制：应用程序控制型 - 客户端应用程序决定使用
• 实现：实现IMcpResourceHandler接口

3. 提示处理器（提示）

• 用途：可重用的提示模板或工作流程
• 控制：用户控制型 - 用户明确选择并使用
• 实现：仅在TypeScript侧实现IPromptHandler接口

🔬 示例代码

该包包含以下示例：

1. Unity MCP处理器示例

   • C#实现的示例代码
   • 可直接导入项目中使用

2. Unity MCP处理器示例JavaScript

   • JavaScript实现的示例代码
   • 请将此中的JS文件复制到build/handlers目录中使用

⚠️ 注意：示例代码包含任意代码执行功能。在生产环境中使用时请注意安全。

示例导入方法：

1. 在Unity包管理器中选择本包
2. 点击“Samples”标签
3. 点击需要的示例的“Import”按钮

🛠️ 创建自定义处理器

命令处理器 (C#)

创建一个新的实现IMcpCommandHandler的类：

using Newtonsoft.Json.Linq;
using UnityMCP.Editor.Core;

namespace YourNamespace.Handlers
{
    internal sealed class YourCommandHandler : IMcpCommandHandler
    {
        public string CommandPrefix => "yourprefix";
        public string Description => "处理器描述";

        public JObject Execute(string action, JObject parameters)
        {
            // 实现命令逻辑
            if (action == "yourAction")
            {
                // 使用参数执行某些操作
                return new JObject
                {
                    ["success"] = true,
                    ["result"] = "结果数据"
                };
            }

            return new JObject
            {
                ["success"]_ = false,
                ["error"] = $"未知动作: {action}"
            };
        }
    }
}

资源处理器 (C#)

创建一个新的实现IMcpResourceHandler的类：

using Newtonsoft.Json.Linq;
using UnityMCP.Editor.Resources;

namespace YourNamespace.Resources
{
    internal sealed class YourResourceHandler : IMcpResourceHandler
    {
        public string ResourceName => "yourresource";
        public string Description => "资源描述";
        public string ResourceUri => "unity://yourresource";

        public JObject FetchResource(JObject parameters)
        {
            // 实现获取资源数据的处理
            var data = new JArray();
            
            // 获取并处理一些数据，添加到JArray中
            data.Add(new JObject
            {
                ["name"] = "项1",
                ["value"] = "值1"
            });

            return new JObject
            {
                ["success"] = true,
                ["items"] = data
            };
        }
    }
}

命令处理器 (TypeScript)

扩展BaseCommandHandler创建新的处理器：

import { IMcpToolDefinition } from "../core/interfaces/ICommandHandler.js";
import { JObject } from "../types/index.js";
import { z } from "zod";
import { BaseCommandHandler } from "../core/BaseCommandHandler.js";

export class YourCommandHandler extends BaseCommandHandler {
   public get commandPrefix(): string {
      return "yourprefix";
   }

   public get description(): string {
      return "处理器描述";
   }

   public getToolDefinitions(): Map<string, IMcpToolDefinition> {
      const tools = new Map<string, IMcpToolDefinition>();

      // 定义工具
      tools.set("yourprefix_yourAction", {
         description: "动作描述",
         parameterSchema: {
            param1: z.string().describe("参数描述"),
            param2: z.number().optional().describe("可选参数")
         },
         annotations: {
            title: "工具标题",
            readOnlyHint: true,
            openWorldHint: false
         }
      });

      return tools;
   }

   protected async executeCommand(action: string, parameters: JObject): Promise<JObject> {
      // 实现命令逻辑
      // 将请求转发给Unity
      return await this.sendUnityRequest(
              `${this.commandPrefix}.${action}`,
              parameters
      );
   }
}

资源处理器 (TypeScript)

扩展BaseResourceHandler创建新的资源处理器：

import { BaseResourceHandler } from "../core/BaseResourceHandler.js";
import { JObject } from "../types/index.js";
import { URL } from "url";

export class YourResourceHandler extends BaseResourceHandler {
   public get resourceName(): string {
      return "yourresource";
   }

   public get description(): string {
      return "资源描述";
   }

   public get resourceUriTemplate(): string {
      return "unity://yourresource";
   }

   protected async fetchResourceData(uri: URL, parameters?: JObject): Promise<JObject> {
      // 处理请求参数
      const param1 = parameters?.param1 as string;

      // 向Unity发送请求
      const response = await this.sendUnityRequest("yourresource.get", {
         param1: param1
      });

      if (!response.success) {
         throw new Error(response.error as string || "获取资源失败");
      }

      // 整理响应数据并返回
      return {
         items: response.items || []
      };
   }
}

提示处理器 (TypeScript)

扩展BasePromptHandler创建新的提示处理器：

import { BasePromptHandler } from "../core/BasePromptHandler.js";
import { IMcpPromptDefinition } from "../core/interfaces/IPromptHandler.js";
import { z } from "zod";

export class YourPromptHandler extends BasePromptHandler {
   public get promptName(): string {
      return "yourprompt";
   }

   public get description(): string {
      return "提示描述";
   }

   public getPromptDefinitions(): Map<string, IMcpPromptDefinition> {
      const prompts = new Map<string, IMcpPromptDefinition>();

      // 注册提示定义
      prompts.set("analyze-component", {
         description: "分析Unity组件",
         template: "详细分析以下Unity组件，并提出改进建议:\n\n```csharp\n{code}\n```",
         additionalProperties: {
            code: z.string().describe("待分析的C#代码")
         }
      });

      return prompts;
   }
}

注意：C#侧实现IMcpCommandHandler或IMcpResourceHandler的类可以在项目中的任何位置放置，通过程序集搜索会被自动检测并注册。同样地，在TypeScript侧，只要将类放在handlers目录中，也会被自动检测。

🔄 通信流程

1. Claude（或其他AI）调用MCP的某个功能（工具/资源/提示）
2. TypeScript服务器通过TCP将请求转发给Unity
3. Unity的McpServer接收请求并找到合适的处理器
4. 处理器在Unity的主线程中处理请求
5. 结果通过TCP连接返回给TypeScript服务器
6. TypeScript服务器格式化结果并返回给Claude

⚙️ 设置

Unity设置

通过Edit > Preferences > Unity MCP访问设置：

• Host：绑定服务器的IP地址（默认：127.0.0.1）
• Port：监听的端口（默认：27182）
• UDP Discovery：启用TypeScript服务器的自动检测
• Auto-start on Launch：Unity启动时自动启动服务器
• Auto-restart on Play Mode Change：在播放模式开始/结束时重新启动服务器
• Detailed Logs：启用调试用的详细日志

TypeScript设置

TypeScript服务器的环境变量：

• MCP_HOST：Unity服务器主机（默认：127.0.0.1）
• MCP_PORT：Unity服务器端口（默认：27182）

🔍 故障排除

常见问题

1. 连接错误

   • 检查Unity侧的防火墙设置
   • 确认端口号正确设置
   • 确认没有其他进程占用同一端口

2. 处理器未注册

   • 确认处理器类实现了正确的接口
   • 确认C#处理器是public或internal访问级别
   • 在Unity侧检查日志，确认注册过程中没有出现错误

3. 资源未找到

   • 确认资源名称和URI一致
   • 确认资源处理器已被正确激活

查看日志

• Unity控制台：查看来自McpServer的日志消息
• TypeScript服务器：使用MCP Inspector等工具检查通信错误

📚 内置处理器

Unity (C#)

• MenuItemCommandHandler：执行Unity编辑器的菜单项
• ConsoleCommandHandler：操作Unity控制台日志
• AssembliesResourceHandler：获取程序集信息
• PackagesResourceHandler：获取包信息

TypeScript

• MenuItemCommandHandler：执行菜单项
• ConsoleCommandHandler：操作控制台日志
• AssemblyResourceHandler：获取程序集信息
• PackageResourceHandler：获取包信息

📖 外部资源

• Model Context Protocol (MCP) 规范

⚠️ 安全注意事项

1. 不要执行不可信的处理器：第三方创建的处理器代码应在使用前进行安全审查。
2. 限制代码执行权限：特别是包含code_execute命令的处理器，由于其任意代码执行能力，在生产环境中应考虑禁用。

📄 许可证

本项目在MIT许可证下提供 - 详情请参阅许可证文件。

---

Shiranui-Isuzu いすず