🚀 Advacned Unity MCP Integration

🚀 高级 Unity MCP 集成

此软件包可将 Model Context Protocol (MCP) 与 Unity Editor 无缝集成，让 AI 助手能够实时了解并操作你的 Unity 项目。通过此集成，AI 助手可以访问场景层级、项目设置等信息，并直接在 Unity Editor 环境中执行代码。

📚 功能

• 直接浏览和操作项目文件
• 实时访问 Unity 项目信息
• 了解场景层级和游戏对象
• 直接在 Unity Editor 中执行 C# 代码
• 监控日志和错误
• 控制 Editor 的播放模式
• 等待代码执行

🚀 开始使用

先决条件

• Unity 2021.3 或更高版本
• Node.js 18+（用于运行 MCP 服务）

安装

1. 安装 Unity 软件包

你可以通过以下几种方式安装 Unity 软件包：

选项 A：Package Manager（Git URL）

1. 打开 Unity Package Manager（Window > Package Manager）
2. 点击 + 按钮并选择 Add package from git URL...
3. 输入仓库 URL：https://github.com/quazaai/UnityMCPIntegration.git
4. 点击 Add

选项 B：导入自定义软件包

1. 克隆此仓库，或下载 unityPackage
2. 在 Unity 中，前往 Assets > Import Package > Custom Package
3. 选择 UnityMCPIntegration.unitypackage 文件

2. 设置 MCP 服务

你可以通过以下两种方式运行 MCP 服务：

选项 A：直接运行服务

1. 前往 mcpServer (likely <path-to-project>\Library\PackageCache\com.quaza.unitymcp@d2b8f1260bca\mcpServer\) 目录
2. 安装依赖项：

   npm install
   

3. 运行服务：

   node build/index.js
   

选项 B：添加到 MCP Host 配置

将服务添加到 Claude Desktop、自定义实现等的 MCP Host 配置中

{
  "mcpServers": {
    "unity-mcp-server": {
      "command": "node",
      "args": [
        "path-to-project>\\Library\\PackageCache\\com.quaza.unitymcp@d2b8f1260bca\\mcpServer\\mcpServer\\build\\index.js"
      ],
      "env": {
        "MCP_WEBSOCKET_PORT": "5010"
      }
    }
  }
}

演示视频

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Unity MCP Integration：

npx -y @smithery/cli install @quazaai/unitymcpintegration --client claude

🔧 使用方法

调试和监控

你可以在 Unity 中打开 MCP 调试窗口，以监控连接并测试功能：

1. 前往 Window > MCP Debug
2. 使用调试窗口进行以下操作：
   • 检查连接状态
   • 测试代码执行
   • 查看日志
   • 监控事件

可用工具

Unity MCP 集成为 AI 助手提供了多种工具：

Unity 编辑器工具

• get_editor_state: 获取关于 Unity 项目和编辑器状态的全面信息
• get_current_scene_info: 获取有关当前场景的详细信息
• get_game_objects_info: 获取场景中特定 GameObject 的信息
• execute_editor_command: 直接在 Unity 编辑器中执行 C# 代码
• get_logs: 检索和筛选 Unity 控制台日志
• verify_connection: 检查是否有与 Unity 编辑器的活跃连接

文件系统工具

• read_file: 读取 Unity 项目中文件的内容
• read_multiple_files: 一次读取多个文件
• write_file: 使用新内容创建或覆盖文件
• edit_file: 对现有文件进行针对性编辑，带差异预览
• list_directory: 获取目录中的文件和文件夹列表
• directory_tree: 获取目录和文件的层级视图
• search_files: 查找与搜索模式匹配的文件
• get_file_info: 获取特定文件或目录的元数据
• find_assets_by_type: 查找特定类型的所有资源（例如 Material、Prefab）
• list_scripts: 获取项目中所有 C# 脚本的列表

文件路径可以是绝对路径或相对于 Unity 项目 Assets 文件夹的相对路径。例如，"Scenes/MyScene.unity" 指的是 <project>/Assets/Scenes/MyScene.unity。

架构

该集成由两个主要组件组成：

1. Unity 插件 (C#): 位于 Unity 编辑器中，提供对编辑器 API 的访问
2. MCP 服务 (TypeScript/Node.js): 实现 MCP 协议并与 Unity 插件通信

它们之间的通信通过 WebSocket 进行，传输 JSON 消息用于命令和数据交换。

文件系统访问

Unity MCP 集成现在包括强大的文件系统工具，允许 AI 助手：

• 浏览、读取和编辑 Unity 项目中的文件
• 创建新文件和目录
• 搜索特定文件或资源类型
• 分析项目结构
• 通过差异预览进行针对性代码更改

所有文件操作都限制在 Unity 项目目录内以确保安全。该系统智能地处理绝对路径和相对路径，始终相对于项目的 Assets 文件夹解析以方便使用。

示例用法：

• 获取目录列表：list_directory(path: "Scenes")
• 读取脚本文件：read_file(path: "Scripts/Player.cs")
• 编辑配置文件：edit_file(path: "Resources/config.json", edits: [{oldText: "value: 10", newText: "value: 20"}], dryRun: true)
• 查找所有材质：find_assets_by_type(assetType: "Material")

贡献

欢迎贡献！以下是您如何贡献的方式：

1. Fork 该仓库
2. 创建特性分支（git checkout -b feature/amazing-feature）
3. 进行更改
4. 提交更改（git commit -m 'Add some amazing feature'）
5. 推送到分支（git push origin feature/amazing-feature）
6. 开启 Pull Request

开发设置

Unity 端：

• 在 Unity 中打开项目
• 修改 UnityMCPConnection/Editor 目录中的 C# 脚本

服务端：

• 导航到 mcpServer 目录
• 安装依赖：npm install
• 修改 src 目录中的 TypeScript 文件
• 构建服务：npm run build
• 运行服务：node build/index.js

许可证

该项目在 MIT 许可证下获得许可 - 详见 LICENSE 文件。

支持

如果您遇到任何问题或有疑问，请在 GitHub 仓库上提交 issue。