# https://github.com/IvanMurzak/Unity-MCP 项目说明书 生成时间：2026-06-22 09:32:16 UTC ## 目录 - [项目概述与安装 (Overview & Installation)](#page-overview) - [系统架构与 MCP Server 管理 (Architecture & Server Lifecycle)](#page-architecture) - [内置工具、API 与自定义扩展 (Built-in Tools, API & Extensibility)](#page-tools) - [UI、依赖解析、部署与常见故障排查 (UI, Dependency Resolver, Deployment & Known Issues)](#page-troubleshooting) ## 项目概述与安装 (Overview & Installation) ### 相关页面 相关主题：[系统架构与 MCP Server 管理 (Architecture & Server Lifecycle)](#page-architecture), [UI、依赖解析、部署与常见故障排查 (UI, Dependency Resolver, Deployment & Known Issues)](#page-troubleshooting)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/IvanMurzak/Unity-MCP/blob/main/README.md) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json) - [cli/package.json](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/package.json) - [cli/src/index.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/index.ts) - [cli/src/utils/agents.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/agents.ts) - [cli/src/utils/manifest.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/manifest.ts) - [cli/src/lib/validation.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/validation.ts) - [cli/src/utils/unity-editor.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/unity-editor.ts) - [cli/src/lib/types.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/types.ts) - [cli/src/commands/open.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/open.ts) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/CHANGELOG.md](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/CHANGELOG.md)
# 项目概述与安装 (Overview & Installation) ## 项目定位与核心组成 Unity-MCP（AI Game Developer）是一套面向 Unity 引擎的 AI 集成方案，提供 AI Skills、MCP Tools 与跨平台 CLI，目标是让任意 AI 编码助手（Claude Code、Gemini、Copilot、Cursor 等）都能直接读写 Unity Editor 中的场景、资产与 C# 代码，从而闭环 AI → 工具 → 编辑器 → 运行游戏 的开发测试链路。 仓库内项目由三个核心组件构成： - **Unity 插件包** `com.ivanmurzak.unity.mcp` 资料来源：[Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json:1-30]()，以 UPM / OpenUPM 形式分发，最低兼容 Unity 2022.3，并声明依赖 `com.unity.test-framework` 1.1.33、`com.unity.modules.uielements`、`extensions.unity.playerprefsex` 2.1.5。 - **跨平台 CLI 工具** `unity-mcp-cli` 资料来源：[cli/package.json:1-50]()，TypeScript 实现，要求 Node.js `^20.19.0 || >=22.12.0`，封装了项目创建、插件安装、AI 客户端配置、HTTP 状态探测等完整流程。 - **共享 MCP Server 二进制** `gamedev-mcp-server` 资料来源：[Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/CHANGELOG.md]()，自 v0.81.0 起插件会在首次启动时自动从 [IvanMurzak/GameDev-MCP-Server](https://github.com/IvanMurzak/GameDev-MCP-Server) 仓库下载与本插件版本绑定的 server zip，解压到 `Library/mcp-server//` 目录。 CLI 入口程序在 `cli/src/index.ts` 中通过 Commander 注册 15 个子命令 资料来源：[cli/src/index.ts:1-45]()：`bootstrap-local`、`close`、`configure`、`create-project`、`install-plugin`、`install-unity`、`open`、`remove-plugin`、`run-tool`、`run-system-tool`、`setup-mcp`、`setup-skills`、`status`、`update`、`wait-for-ready`。库级 API（`runTool`、`runSystemTool`、`createProject` 等）面向 TypeScript 集成方，CLI 仅作为薄封装 资料来源：[cli/src/lib/types.ts:1-50]()。 ## 系统架构 下面给出一次典型连接的组件关系图： ```mermaid flowchart LR A[AI Agent
Claude Code / Cursor / Copilot] -->|stdio or HTTP| B[gamedev-mcp-server
Library/mcp-server/<rid>/] B -->|HTTP + token| C[Unity Editor
com.ivanmurzak.unity.mcp] C -->|ReflectorNet| D[User C# / Scenes / Assets] A -.->|unity-mcp-cli
configure / setup-mcp| B A -.->|skills| E[.github/skills
.cursor/skills ...] ``` AI Agent 通过 stdio 或 HTTP 两种 transport 中的一种连接 MCP Server，Server 内部代理调用 Unity Editor 暴露的工具；CLI 工具 `unity-mcp-cli` 负责生成各 AI 客户端的配置文件（位置在 `cli/src/utils/agents.ts` 中枚举），如 `~/.codex/config.toml`、`.vscode/mcp.json`、`.junie/mcp/mcp.json`、`~/.gemini/config/mcp_config.json` 等 资料来源：[cli/src/utils/agents.ts:1-80]()。每个 agent 都维护独立的 `stdioRemoveKeys` / `httpRemoveKeys` 列表，用于在切换 transport 时清理冗余字段，避免 `type`、`url`、`command` 等键相互污染。 ## 安装与快速开始 ### 1. 安装 Unity 插件 通过 OpenUPM scoped registry 安装（推荐方式）： 1. 在 Unity 项目的 `Packages/manifest.json` 中追加 scoped registry 与 `com.ivanmurzak.unity.mcp` 依赖。CLI 工具 `install-plugin` 会自动完成此步骤 资料来源：[cli/src/utils/manifest.ts:1-50]()：当 `force=false`（自动解析版本）时不会自动降级已存在的更高版本，但当用户显式传入 `--plugin-version` 时允许降级；同时跳过 `file:`、`git+`、`http(s):` 这类非 semver 规范。 2. 也可以手动编辑 `manifest.json` 添加依赖；本包最低兼容 Unity 2022.3 资料来源：[Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json:1-30]()。 安装后首次启动 Unity Editor，插件会根据 `ServerVersion` 自动从 GitHub Release 下载 `gamedev-mcp-server-.zip` 并解压到 `Library/mcp-server//` 资料来源：[Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/CHANGELOG.md]()。若本地版本文件与预期不一致，会强制重新下载以保持 server 与插件一致。 ### 2. 安装 CLI `unity-mcp-cli` 既可全局安装，也可通过 `npx` 临时运行 资料来源：[cli/src/index.ts:1-45]()： ```bash npm install -g unity-mcp-cli # 或一次性使用 npx unity-mcp-cli@latest setup-mcp --project /path/to/UnityProject ``` CLI 默认按 `unityProjectPath` → `url + token` 解析策略定位 Editor 资料来源：[cli/src/lib/types.ts:1-50]()，缺失配置时回退到本地确定性端口，并提供 `run-tool` / `run-system-tool` 子命令在 CI 或脚本中直接调用 MCP 工具。 ### 3. 项目合法性校验 CLI 强制要求被操作的目录为合法 Unity 项目（必须存在 `Packages/manifest.json`） 资料来源：[cli/src/lib/validation.ts:1-50]()；`open` 子命令额外校验 `Assets/` 与 `ProjectSettings/ProjectVersion.txt` 是否存在 资料来源：[cli/src/commands/open.ts:1-50]()。`install-unity` 则按平台默认 Hub 路径（如 `%PROGRAMFILES%\Unity\Hub\Editor`）与 `secondaryInstallPath.json` 扫描已安装的 Editor 资料来源：[cli/src/utils/unity-editor.ts:1-50]()，保证在 100ms 内完成缓存命中。路径比较时会进行 `path.normalize` + 去尾分隔符（Windows 上额外小写化）等归一化处理，以避免 `C:\…` 与 `c:\…` 被误判为不同根。 ### 4. 关联 AI 客户端 执行 `unity-mcp-cli setup-mcp` 会把 stdio / HTTP 配置写入对应 agent 的配置文件 资料来源：[cli/src/utils/agents.ts:1-80]()。已支持的客户端包括：Claude Code、Codex、Cursor、Kilo Code、VS Code (Copilot)、Visual Studio (Copilot)、Rider (Junie)、Antigravity、Cline、Gemini 等。每个 agent 配置都包含 `getStdioProps` 与 `getHttpProps` 两组生成逻辑，切换 transport 时 CLI 会按 `stdioRemoveKeys` / `httpRemoveKeys` 自动删除对方字段，避免遗留键污染。 ## 常见问题与故障排除 依据社区反馈，0.82.x 升级过程中集中出现了以下问题： - **Linux 上 server binary 未下载**（[issue #845](https://github.com/IvanMurzak/Unity-MCP/issues/845)）：从旧版本升级到 0.82.1 后 `Library/mcp-server/linux-x64/` 目录为空。建议清空旧 `Library/mcp-server/` 并重新启动 Editor 触发自动重下载逻辑 资料来源：[Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/CHANGELOG.md]()。 - **下载 zip 缺少完整性校验**（[issue #841](https://github.com/IvanMurzak/Unity-MCP/issues/841)）：当前实现直接解压执行未校验 GitHub Release 附带的 `SHA256SUMS`，存在供应链风险；规避方案是先在浏览器中下载并比对校验和。 - **macOS arm64 自动下载失败**（[issue #829](https://github.com/IvanMurzak/Unity-MCP/issues/829)）与 **下载超时导致安装残破**（[issue #832](https://github.com/IvanMurzak/Unity-MCP/issues/832)）：若网络受限，请先手动下载 `gamedev-mcp-server-osx-arm64.zip` 并放入 `Library/mcp-server/osx-arm64/`，或配置代理后重启 Editor。 - **同一机器两个 Editor 互踢**（[issue #830](https://github.com/IvanMurzak/Unity-MCP/issues/830)）：插件使用共享 `EditorPrefs` PID 键，导致多实例互斥。可通过为不同项目分配不同端口 + 自定义 token 暂时缓解。 - **缺少 ReflectorNet 依赖**（[issue #839](https://github.com/IvanMurzak/Unity-MCP/issues/839)）：安装后报 `CS0246`，需手动在 `manifest.json` 中补齐 `com.IvanMurzak.ReflectorNet` 依赖。 - **`tests-run` 工具死锁**（[issue #840](https://github.com/IvanMurzak/Unity-MCP/issues/840)）：0.81.1 的回归问题，建议升级到 0.82.1（已包含相关修复）或临时回退到 0.81.0。 - **UPM 升级 DLL 命名冲突**（[issue #745](https://github.com/IvanMurzak/Unity-MCP/issues/745)）：在 Unity 6.4 上 NuGet flat-layout 名称可能与 BCL/Burst 程序集冲突，安装后需重新导入程序集。 ## See Also - [MCP 工具与 AI Skills 体系](Tools-and-Skills.md) - [CLI 命令参考](CLI-Reference.md) - [共享 MCP Server 二进制分发](Server-Binary-Distribution.md) - [已知问题与发布说明](Release-Notes.md) --- ## 系统架构与 MCP Server 管理 (Architecture & Server Lifecycle) ### 相关页面 相关主题：[项目概述与安装 (Overview & Installation)](#page-overview), [内置工具、API 与自定义扩展 (Built-in Tools, API & Extensibility)](#page-tools), [UI、依赖解析、部署与常见故障排查 (UI, Dependency Resolver, Deployment & Known Issues)](#page-troubleshooting)
相关源码文件 以下源码文件用于生成本页说明： - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/McpServerManager.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/McpServerManager.cs) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/McpServerChecksum.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/McpServerChecksum.cs) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/Startup.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/Startup.cs) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/Startup.Editor.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/Startup.Editor.cs) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/DevControl/Startup.DevControl.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/DevControl/Startup.DevControl.cs) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/DevControl/DevControlServer.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/DevControl/DevControlServer.cs) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json) - [cli/package.json](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/package.json) - [cli/src/index.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/index.ts) - [cli/src/lib.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib.ts) - [cli/src/lib/types.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib.ts) - [cli/src/utils/agents.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/agents.ts) - [cli/src/commands/setup-mcp.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/setup-mcp.ts) - [cli/src/utils/manifest.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/manifest.ts) - [cli/src/commands/run-tool.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/run-tool.ts) - [cli/src/commands/run-system-tool.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/run-system-tool.ts)
# 系统架构与 MCP Server 管理 (Architecture & Server Lifecycle) ## 概述 Unity-MCP 是一个面向 Unity 编辑器的 Model Context Protocol (MCP) 集成方案,由两个互补的工件组成:Unity 侧的 Editor 插件包 `com.ivanmurzak.unity.mcp`(版本 0.82.1,Unity 2022.3+)与跨平台 Node.js CLI 工具 `unity-mcp-cli`(同样 0.82.1,要求 Node ≥ 20.19 或 ≥ 22.12)。Editor 插件负责在编辑器进程内托管 MCP 工具注册表、桥接 C# 反射调用并自动管理本地 `gamedev-mcp-server` 二进制;CLI 承担编辑器引导、OpenUPM 清单改写、为多个 AI Agent 写入 MCP 配置等一次性任务。两者协同构成"AI Agent ↔ MCP Server ↔ Unity Editor"的三段式架构。 资料来源:[package.json:1-30](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json),[cli/package.json:1-50](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/package.json) ## 组件架构 ```mermaid flowchart LR AI[AI Agent
Claude/Codex/Cursor/...] CLI[unity-mcp-cli
Node.js] Plugin[Unity Editor Plugin
com.ivanmurzak.unity.mcp] Srv[GameDev MCP Server
gamedev-mcp-server] Editor[Unity Editor
C# 反射 + Tools] AI -- stdio / http --> Srv CLI -- 配置写入 --> AI CLI -- 启动 / 等待就绪 --> Plugin Srv -- streamableHttp / stdio --> Plugin Plugin -- 工具调用 --> Editor Editor -- 资产 / 场景状态 --> Srv ``` AI Agent 直接通过 MCP 协议与本地 `gamedev-mcp-server` 通信;服务器作为代理将工具调用转发到 Unity 内暴露的 HTTP 端点。CLI 是独立进程,专注于一次性编排(安装、配置、引导),不常驻。 资料来源:[cli/src/index.ts:1-50](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/index.ts),[cli/src/commands/setup-mcp.ts:1-30](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/setup-mcp.ts) ## 服务器生命周期管理 ### 二进制分发与完整性校验 自 0.81.0 起,Editor 插件按 Runtime Identifier (RID) 从 `IvanMurzak/GameDev-MCP-Server` 的固定 `v` GitHub Release 下载 `gamedev-mcp-server-.zip`,解压到 `/Library/mcp-server//`。`McpServerManager.DownloadAndUnpackBinary` 负责下载与解压;`McpServerChecksum` 在执行前对照 Release 同时发布的 `SHA256SUMS` 做 fail-closed 校验。版本号固定于插件清单,首次启动或版本不匹配时自动重下。0.82.1 已更新该 server pin。 资料来源:[McpServerManager.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/McpServerManager.cs),[McpServerChecksum.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/McpServerChecksum.cs),[Issue #841](https://github.com/IvanMurzak/Unity-MCP/issues/841) ### 传输模式 CLI 与 Editor 之间支持 `stdio` 与 `http`(streamableHttp)两种传输;Agent 配置由 `SetupMcpOptions.transport` 切换,默认走 `http`。`OpenProjectTransport` 类型(`'streamableHttp' | 'stdio'`)通过环境变量 `UNITY_MCP_TRANSPORT` 透传给 Editor,后者由 `Startup.cs` 解析后决定是否拉起 DevControlServer 与 HTTP 端点。 资料来源:[cli/src/lib/types.ts:1-50](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib.ts),[Startup.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/Startup.cs) ### 多 Editor 实例与状态隔离 `Startup.Editor.cs` 与 `DevControlServer` 协同负责进程握手:每个 Editor 通过 EditorPrefs 记录"当前活跃连接的 PID"用于检测本机是否已有接管中的实例。同机两个 Unity 项目同时启用插件时,共享 PID 键会导致互斥——一端重连/重编会断开另一端,这是 Issue #830 描述的故障模式。 资料来源:[Startup.Editor.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/Startup.Editor.cs),[DevControlServer.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Editor/Scripts/DevControl/DevControlServer.cs),[Issue #830](https://github.com/IvanMurzak/Unity-MCP/issues/830) ## CLI 与库接口 `unity-mcp-cli` 同时提供可执行 CLI 与零副作用的库入口。CLI 注册的命令包括 `bootstrap-local`、`setup-mcp`、`setup-skills`、`install-plugin`、`remove-plugin`、`open`、`create-project`、`run-tool`、`run-system-tool`、`status`、`wait-for-ready`、`close`、`configure`、`create-update` 等。`cli/src/lib.ts` 导出同名纯函数(由 `package.json#exports` 暴露),所有结果以判别联合 `{ kind: 'success' | 'failure', success: boolean, ... }` 返回,进度通过可选 `onProgress` 回调对外暴露——这一约束保证 CLI 可被 IDE/SDK 安全嵌入而无副作用。 资料来源:[cli/src/index.ts:1-50](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/index.ts),[cli/src/lib.ts:1-40](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib.ts),[cli/src/utils/manifest.ts:1-30](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/manifest.ts) 工具执行通过 HTTP 路由 `/api/tools`(对外暴露给 MCP 客户端)与 `/api/system-tools`(保留给宿主进程)调用,二者共享 `run-tool-builder.ts` 的构建逻辑。`agents.ts` 维护 Agent 注册表(`claude-code`、`cursor`、`codex`、`rider-junie`、`github-copilot-cli`、`vscode-copilot`、`vs-copilot`、`kilo-code`、`unity-ai` 等),为每个 Agent 指定配置路径、skills 目录、JSON/TOML 格式与传输序列化形式。 资料来源:[cli/src/commands/run-tool.ts:1-10](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/run-tool.ts),[cli/src/commands/run-system-tool.ts:1-10](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/run-system-tool.ts),[cli/src/utils/agents.ts:1-40](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/agents.ts) ## 已知问题与缓解 | 现象 | 触发条件 | 缓解路径 | |------|----------|----------| | 二进制下载超时,安装处于半残状态 | GitHub 限流或网络中断 | 启用 SHA256SUMS 校验并清理 `Library/mcp-server` 后重试 | | 多 Editor 互踢 | 共享 EditorPrefs PID 键 | 隔离 `UserSettings/` 或为不同项目绑定独立端口 | | `tests-run` 在 0.81.1 死锁编辑器主线程 | 主线程同步等待 NUnit 结果 | 升级至 0.82.x 修复版本 | | macOS arm64 启动报"binary missing" | RID 不匹配或 zip 解压失败 | 删除缓存目录后重启 Editor(参见 #829、#832、#845) | | `Assets_Modify` 不落盘 | 缺少 `EditorUtility.SetDirty` 调用 | 在工具实现中显式标记脏并 `AssetDatabase.SaveAssets()` | ## See Also - [README & 快速上手](https://github.com/IvanMurzak/Unity-MCP/blob/main/README.md) - [CHANGELOG (0.82.x)](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/CHANGELOG.md) - [GameDev-MCP-Server Releases](https://github.com/IvanMurzak/GameDev-MCP-Server/releases) - [Issue #841 — SHA256SUMS 校验提案](https://github.com/IvanMurzak/Unity-MCP/issues/841) - [Issue #830 — 多 Editor 实例冲突](https://github.com/IvanMurzak/Unity-MCP/issues/830) --- ## 内置工具、API 与自定义扩展 (Built-in Tools, API & Extensibility) ### 相关页面 相关主题：[系统架构与 MCP Server 管理 (Architecture & Server Lifecycle)](#page-architecture), [UI、依赖解析、部署与常见故障排查 (UI, Dependency Resolver, Deployment & Known Issues)](#page-troubleshooting)
相关源码文件 以下源码文件用于生成本页说明： - [cli/src/index.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/index.ts) - [cli/src/utils/agents.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/agents.ts) - [cli/src/commands/run-system-tool.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/run-system-tool.ts) - [cli/src/lib/types.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/types.ts) - [cli/src/utils/manifest.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/manifest.ts) - [cli/src/commands/bootstrap-local.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/bootstrap-local.ts) - [commands/tools/validate_mcp_openai.py](https://github.com/IvanMurzak/Unity-MCP/blob/main/commands/tools/validate_mcp_openai.py) - [commands/tools/validate_json_schema.py](https://github.com/IvanMurzak/Unity-MCP/blob/main/commands/tools/validate_json_schema.py) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json)
# 内置工具、API 与自定义扩展 (Built-in Tools, API & Extensibility) ## 总览 Unity-MCP（包名 `com.ivanmurzak.unity.mcp`，当前版本 `0.82.1`）通过三条互补的渠道向 AI Agent 暴露 Unity Editor 的能力：(1) 一组由 Unity 插件内置的 MCP 工具（scene / game-object / assets / screenshot / tests-run 等）；(2) 一条独立的 HTTP API 路由 `/api/system-tools`，供 CLI 直接调用而不向 MCP 客户端暴露；(3) 一个跨平台的 CLI 工具 `unity-mcp-cli`，负责安装、配置、连接管理与工具调用。其核心扩展理念在 `package.json` 的描述中被概括为 "Any C# method may be turned into a tool by a single line"，即通过 ReflectorNet 将任意 C# 方法反射为 MCP 工具 资料来源：[Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json:14]()。社区 issue #839 进一步确认了 ReflectorNet 是该机制所必需的运行时依赖，缺失时会出现 CS0246 编译错误 资料来源：[issue #839](https://github.com/IvanMurzak/Unity-MCP/issues/839)。 ```mermaid flowchart LR A[AI Agent
Codex/Copilot/Cursor/...] -->|MCP stdio / HTTP| B[GameDev-MCP-Server
v8.0.0] B -->|HTTP JSON-RPC| C[Unity Editor Plugin
com.ivanmurzak.unity.mcp] C -->|ReflectorNet| D[Built-in Tools
Scene/GameObject/Assets/Screenshot/Tests] C -->|User-defined C# methods| E[Custom Tools] F[unity-mcp-cli] -->|/api/system-tools| C F -->|configure / setup-mcp| G[Agent Config Files
.vscode/mcp.json 等] ``` ## CLI 子命令工具集 `unity-mcp-cli` 通过 Commander 注册了 15 个一级子命令，统一管理从 Unity 安装、项目创建、插件安装到 MCP 连接与工具调度的全部流程 资料来源：[cli/src/index.ts:11-29]()。其中直接面向"工具调用"的子命令是 `run-tool` 与 `run-system-tool`，前者对应暴露给 MCP 客户端的常规工具，后者对应 Unity 插件 `/api/system-tools` 路由下的系统级工具（不暴露给 AI Agent），返回结构统一由 `RunToolSuccess` / `RunToolFailure` 区分 资料来源：[cli/src/commands/run-system-tool.ts:1-13]()、资料来源：[cli/src/lib/types.ts:1-100]()。 其余 CLI 工具按职责可分为三组（见下表）： | 子命令 | 职责 | 资料来源 | |---|---|---| | `create-project` / `install-unity` | 创建 Unity 工程并通过 Unity Hub 安装 Editor | [cli/src/commands/create-project.ts:1-50]() | | `install-plugin` / `remove-plugin` / `setup-mcp` / `setup-skills` | 在 `Packages/manifest.json` 写入依赖并生成 Agent 配置文件 | [cli/src/utils/manifest.ts:1-100]() | | `bootstrap-local` / `open` / `close` / `status` / `wait-for-ready` / `login` / `configure` | 切换连接模式（Custom / Cloud）并监控 Editor 状态 | [cli/src/commands/bootstrap-local.ts:1-50]() | ## 内置 MCP 工具与扩展机制 插件以"反射"为核心暴露工具：`Assets_Modify`、`Assets_Read`、`GameObject_*`、`Scene_*`、`Script_*`、`screenshot-*`、`tests-run` 等均通过 `McpServerManager` 注册，AI Agent 调用时 Unity 端按 JSON Schema 反序列化参数并经 ReflectorNet 派发到对应 C# 方法。社区中曾报告 `Assets_Modify` 改动 ScriptableObject 后未调用 `EditorUtility.SetDirty` 导致不落盘 资料来源：[issue #334](https://github.com/IvanMurzak/Unity-MCP/issues/334)，以及 `tests-run` 在 v0.81.1 中导致 Editor 主线程死锁的回归 资料来源：[issue #840](https://github.com/IvanMurzak/Unity-MCP/issues/840)；v0.81.1 还曾因打包脚本未携带 ReflectorNet 依赖而出现 CS0246 错误，提示内置工具链的稳定性高度依赖 ReflectorNet 的正确发布 资料来源：[issue #839](https://github.com/IvanMurzak/Unity-MCP/issues/839)。 扩展自定义工具的标准做法是：在工程任意程序集中以 C# 方法形式编写业务逻辑，并使用插件提供的 `McpTool` 特性标注，由 ReflectorNet 自动生成 JSON Schema 并注册到 MCP 服务端。命令行侧则可通过 `validate_mcp_openai.py` 把工具定义注入 OpenAI API 进行端到端校验 资料来源：[commands/tools/validate_mcp_openai.py:1-200]()，或使用 `validate_json_schema.py` 在离线环境下校验 `inputSchema` 是否符合 JSON Schema Draft 4/6/7/2020-12 规范 资料来源：[commands/tools/validate_json_schema.py:1-80]()。对于"截图工具看不到 ScreenSpaceOverlay UI"等覆盖盲区，社区已提出 `UGUI_Element_State` 类内置工具的诉求 资料来源：[issue #837](https://github.com/IvanMurzak/Unity-MCP/issues/837)，可作为新增内置工具的典型用例。 ## 多 AI Agent 集成 `unity-mcp-cli` 通过 `agents.ts` 中预定义的 Agent 描述符统一处理配置文件的路径、格式（`json` / `toml`）与字段映射（`mcpServers` / `servers` / `mcp_servers` 等），目前已覆盖以下主流 AI Agent 资料来源：[cli/src/utils/agents.ts:1-300]()： | Agent | 配置文件 | 格式 | 字段键 | |---|---|---|---| | VS Code (Copilot) | `.vscode/mcp.json` | json | `servers` | | Visual Studio (Copilot) | `.vs/mcp.json` | json | `servers` | | Codex | `.codex/config.toml` | toml | `mcp_servers` | | Kilo Code | `.kilocode/mcp.json` | json | `mcpServers` | | Rider (Junie) | `.junie/mcp/mcp.json` | json | `mcpServers` | | Antigravity | `~/.gemini/config/mcp_config.json` | json | `mcpServers` | | Cline | `~/Code/globalStorage/.../cline_mcp_settings.json` | json | `mcpServers` | 每个描述符都提供 `getStdioProps` 与 `getHttpProps` 两组配置生成函数，分别注入 `command`/`args` 或 `url`/`headers`，并由 `stdioRemoveKeys` / `httpRemoveKeys` 控制互斥字段的清理。CLI 在 `setup-mcp` 时会根据目标 Agent 自动选用对应描述符，从而保证 `run-tool` 与 MCP 服务端的连接配置在所有 Agent 中保持一致；同一机器同时运行两个 Unity 工程时，共享的 EditorPrefs PID 键会导致连接互斥，需通过 `bootstrap-local` 显式切换本地模式来隔离 资料来源：[cli/src/commands/bootstrap-local.ts:1-50]()、资料来源：[issue #830](https://github.com/IvanMurzak/Unity-MCP/issues/830)。 ## 常见失败模式 - **构建链回归**：自 0.71.0 引入 NuGet flat-layout DLL 命名后，Burst 与 BCL 兼容 DLL 在 Unity 6.4 中解析失败，需关注 `extensions.unity.playerprefsex` 等传递依赖 资料来源：[issue #745](https://github.com/IvanMurzak/Unity-MCP/issues/745)。 - **二进制下载残留**：从 GitHub Release 拉取 `gamedev-mcp-server-.zip` 时若超时或中断，会留下半解压目录，下次启动需要手动清理 `Library/mcp-server//` 资料来源：[issue #832](https://github.com/IvanMurzak/Unity-MCP/issues/832)。 - **扩展 API 缺位**：当某个 AI Agent 不在 `agents.ts` 预定义列表中时，CLI 会回退到通用 JSON 写入逻辑，需手动核对字段键是否正确。 ## See Also - [架构与连接 (Architecture & Connection)](./architecture.md) - [安装与升级指南 (Installation & Upgrade)](./installation.md) - [故障排查 (Troubleshooting)](./troubleshooting.md) --- ## UI、依赖解析、部署与常见故障排查 (UI, Dependency Resolver, Deployment & Known Issues) ### 相关页面 相关主题：[项目概述与安装 (Overview & Installation)](#page-overview), [系统架构与 MCP Server 管理 (Architecture & Server Lifecycle)](#page-architecture), [内置工具、API 与自定义扩展 (Built-in Tools, API & Extensibility)](#page-tools)
相关源码文件 以下源码文件用于生成本页说明： - [cli/src/index.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/index.ts) - [cli/package.json](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/package.json) - [cli/src/utils/agents.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/agents.ts) - [cli/src/utils/manifest.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/manifest.ts) - [cli/src/commands/install-plugin.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/install-plugin.ts) - [cli/src/commands/create-project.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/create-project.ts) - [cli/src/commands/bootstrap-local.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/bootstrap-local.ts) - [cli/src/commands/open.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/open.ts) - [cli/src/commands/configure.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/configure.ts) - [cli/src/commands/login.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/login.ts) - [cli/src/lib/validation.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/validation.ts) - [cli/src/utils/unity-editor.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/unity-editor.ts) - [cli/src/utils/json-parse.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/json-parse.ts) - [cli/src/lib/types.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/types.ts) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json)
# UI、依赖解析、部署与常见故障排查 (UI, Dependency Resolver, Deployment & Known Issues) ## 项目概览与 Unity 插件元数据 AI Game Developer (Unity-MCP) 项目由两个并列的子项目组成：位于 `Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp` 的 Unity 插件包（要求 Unity 2022.3 及以上）和位于 `cli/` 的跨平台命令行工具 `unity-mcp-cli`。最新发布的 0.82.1 版本在 Unity 端显式声明了三项运行时依赖——`com.unity.test-framework@1.1.33`、`com.unity.modules.uielements@1.0.0` 与 `extensions.unity.playerprefsex@2.1.5`——并通过 OpenUPM scoped registry（`package.openupm.com`）解析 `com.ivanmurzak.unity.mcp` 与下游关联包（如 `com.IvanMurzak.ReflectorNet`）。这种声明方式意味着包一旦缺漏 `ReflectorNet` 就会出现社区报告的 `CS0246` 编译错误。 资料来源：[Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json) ## CLI 部署与命令体系 CLI 入口由 Commander.js 在 `cli/src/index.ts` 中构建，所有子命令在该文件按声明顺序注册，并统一接收 `-v / --verbose` 诊断开关；执行前通过 `preAction` hook 提前激活 verbose 通道，命令运行时还会并行触发一次 `checkForUpdate` 后台检查，使 `unity-mcp-cli` 在启动后即可提示用户升级。该工具覆盖完整部署生命周期： - **项目准备**：`create-project`（按需引导安装 Unity Hub）、`install-unity`（安装指定版本 Editor）。 - **插件安装**：`install-plugin`（写入 `Packages/manifest.json` 与 OpenUPM scope）。 - **运行时**：`open`（打开项目并按 `--no-connect` 选择是否连接 MCP）、`close` / `status` / `wait-for-ready`。 - **Agent 适配**：`setup-mcp` 与 `setup-skills` 为外部 AI Agent 生成配置文件。 - **配置管理**：`configure` 在 `AI-Game-Developer-Config.json` 中启用/禁用具体工具、提示词与资源。 - **连接模式**：`bootstrap-local`（锁定 `Custom` 模式与本地 url/token）、`login`（云端认证）。 - **工具调用**：`run-tool` 与 `run-system-tool` 远程触发 MCP 工具。 - **自身维护**：`update`（CLI 升级）。 资料来源：[cli/src/index.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/index.ts)、[cli/package.json](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/package.json) ## 依赖解析：manifest.json 与 OpenUPM 作用域 `cli/src/utils/manifest.ts` 复刻了 C# `Installer.Manifest.cs` 的语义，负责把插件依赖安全地写入 Unity 项目。其关键策略包括：仅当 `Packages/manifest.json` 缺少 OpenUPM scoped registry 时追加 `package.openupm.com` 与必需 scope；通过 `shouldUpdateVersion` 默认阻止降级，但允许 CLI 中显式 `--plugin-version` 触发 force 升级；对 `file:`、`git+`、`http(s):` 这类非 semver 前缀始终跳过自动覆盖，便于本地开发调试；最终返回 `AddPluginResult.modified` 与 `resolvedVersion` 两个标志位，方便上层 UI 渲染差异。 CLI 侧通过 `cli/src/commands/install-plugin.ts` 把上述能力暴露给终端：先调用库函数解析最新版本，再写入 manifest，期间借助 chalk + yocto-spinner 输出阶段性提示（`dependencies-resolved`、`manifest-written` 等）。 资料来源：[cli/src/utils/manifest.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/manifest.ts)、[cli/src/commands/install-plugin.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/install-plugin.ts) ## AI Agent 适配与 MCP 配置生成 `cli/src/utils/agents.ts` 维护一份受支持 AI Agent 的清单，每一项都声明配置文件路径（如 `.vscode/mcp.json`、`.codex/config.toml`、`.junie/mcp/mcp.json`、`.vs/mcp.json`、`.kilocode/mcp.json`）以及 MCP body 字段名（`mcpServers` 或 `servers`）。每条记录实现两组工厂函数：`getStdioProps` 把端口、超时、授权 token 序列化为命令行参数，`getHttpProps` 则把它们序列化为 HTTP URL / Headers；`stdioRemoveKeys` 与 `httpRemoveKeys` 保证两种模式互不污染字段。 当前内置适配的 Agent 包括 Claude Code、Cursor、Codex（TOML 格式，独立 `tool_timeout_sec` / `startup_timeout_sec`）、Kilo Code、VS Code Copilot、Visual Studio Copilot、Rider (Junie) 等。`authHeaders` 辅助函数会在需要鉴权时生成 `Authorization: Bearer `，避免在不需要鉴权的 Agent 里误写敏感头。 资料来源：[cli/src/utils/agents.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/agents.ts) ## 路径校验、连接与本地模式 `cli/src/lib/validation.ts` 提供零副作用的输入校验：`requireProjectPath` 要求非空字符串并 resolve 为绝对路径，`requireUnityProject` 进一步断言 `Packages/manifest.json` 存在。校验结果以 `{ ok: true, ... } | { ok: false, error }` 判别联合返回，库层不抛出跨公共边界的异常——这正是 `cli/src/lib/types.ts` 中 `CreateProjectResult` / `RunToolFailure` 等结果类型的统一约定。 `cli/src/utils/unity-editor.ts` 在定位 Unity Editor 时除了扫描 Hub 默认根目录，还会读取 `secondaryInstallPath.json`，因此即便用户把 Editor 迁到 `C:\UnityEditor\` 也能在百毫秒级被找到；其 `normalizeRootForDedup` 在 Windows 下做大小写无关归一化，Posix 下保留大小写以匹配文件系统语义。 `cli/src/commands/bootstrap-local.ts` 中的 `pinLocalModeConfig` 把 `connectionMode` 规范化为字符串 `"Custom"`（无论传入 `"Cloud"` 还是整数 1），并由 `isAlreadyPinned` 判断当前 url/token 与磁盘值是否一致；一致时跳过写入，实现幂等的本地模式锁定。`cli/src/commands/login.ts` 则负责云端 OAuth 流程：若 `cloudToken` 已存在且未传 `--force`，直接跳过；否则调用 `runCloudLogin` 写入 token。 资料来源：[cli/src/lib/validation.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/validation.ts)、[cli/src/utils/unity-editor.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/unity-editor.ts)、[cli/src/commands/bootstrap-local.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/bootstrap-local.ts)、[cli/src/commands/login.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/login.ts) ## 常见故障排查 ```mermaid flowchart TD A[unity-mcp-cli 启动] --> B{校验项目路径} B -- 失败 --> X[返回 ValidationFailure] B -- 成功 --> C[解析 OpenUPM scope 与版本] C --> D[写入 Packages/manifest.json] D --> E[setup-mcp 生成 Agent 配置] E --> F[open 启动 Unity Editor] F --> G{连接模式} G -- Local --> H[bootstrap-local 写入 Custom + url/token] G -- Cloud --> I[login 获取 cloudToken] H --> J[run-tool 调用 MCP 工具] I --> J J --> K{出错?} K -- 二进制缺失 --> L[触发 DownloadAndUnpackBinary] K -- 鉴权失败 --> M[重跑 login --force] K -- 测试死锁 --> N[降级或加超时] ``` 社区报告的典型故障与排查方向可归纳如下表： | 现象 | 触发版本 | 排查方向 | | --- | --- | --- | | MCP 服务器二进制未下载 / 启动失败 | 0.80–0.82.1 | 检查 `Library/mcp-server//` 是否被 GitHub 超时中断；社区已建议在 `DownloadAndUnpackBinary` 中引入 SHA256SUMS 校验（issue #841、#845） | | 升级后立刻 `CS0246` 编译错误 | 0.81.1 | 确认 `com.IvanMurzak.ReflectorNet` 已通过 OpenUPM scope 解析（issue #839） | | `tests-run` 工具导致 Editor 主线程死锁 | 0.81.1 | 回退至 0.81.0 或在调用方加上超时 / 取消传播（issue #840） | | macOS arm64 二进制缺失 | 0.80.0 | 重新触发自动下载；检查 `osx-arm64` 子目录权限（issue #829） | | 同机两个 Editor 互踢 | 多版本 | `EditorPrefs` 中 PID 键共享造成，需要为每个项目使用独立端口（issue #830） | | `Assets_Modify` 未持久化 | 长期 | 调用方需自行调用 `EditorUtility.SetDirty`（issue #334） | | NuGet flat-layout DLL 名称冲突 | 0.71.0+ | Unity 6.4 触发 Burst 程序集解析失败（issue #745） | | VS Code Copilot 偶发 `request failed` | 持续 | 重启 VS Code 与 Unity 后重试，必要时删除 `.vscode/mcp.json` 并重新 `setup-mcp`（issue #666） | 排查流程上的统一做法：先用 `unity-mcp-cli status` 核对 CLI / 插件 / 服务器版本，再用 `install-plugin .` 强制按当前版本重写 manifest，最后用 `open . --no-connect` 仅打开 Editor 而不发起 MCP 连接，以隔离网络与认证问题。`json-parse.ts` 中带位置指针的 `JsonParseError` 会在写入 `AI-Game-Developer-Config.json` 时给出精确到字符的报错，便于修复 `configure` 命令产生的损坏文件。 资料来源：[cli/src/index.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/index.ts)、[cli/src/commands/install-plugin.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/install-plugin.ts)、[cli/src/commands/open.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/open.ts)、[cli/src/commands/configure.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/configure.ts)、[cli/src/utils/json-parse.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/json-parse.ts) ## See Also - [CLI 总览与命令参考](cli-overview.md) - [MCP 工具与运行循环](mcp-tools-and-runtime.md) - [AI Agent 接入指南](ai-agent-integration.md) - [Release Notes 0.82.1](https://github.com/IvanMurzak/Unity-MCP/releases/tag/0.82.1) --- --- ## Doramagic 踩坑日志 项目：IvanMurzak/Unity-MCP 摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：MCP server binary download can leave install in broken state when GitHub。 ## 1. 安装坑 · 来源证据：MCP server binary download can leave install in broken state when GitHub - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP server binary download can leave install in broken state when GitHub - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/832 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：Missing ReflectorNet dependency causes CS0246 compilation error - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Missing ReflectorNet dependency causes CS0246 compilation error - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/839 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。 ## 3. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/IvanMurzak/Unity-MCP | host_targets=mcp_host, claude_code, claude, cursor, chatgpt ## 4. 配置坑 · 来源证据：After updating to 0.82.1, server binary not downloaded on Linux - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：After updating to 0.82.1, server binary not downloaded on Linux - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/845 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。 ## 5. 配置坑 · 来源证据：Two Editors on the same machine can't both hold an MCP connection (shared EditorPrefs PID key) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Two Editors on the same machine can't both hold an MCP connection (shared EditorPrefs PID key) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/830 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 6. 配置坑 · 来源证据：tests-run tool causes Unity Editor deadlock in v0.81.1 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：tests-run tool causes Unity Editor deadlock in v0.81.1 - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/840 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 7. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/IvanMurzak/Unity-MCP | README/documentation is current enough for a first validation pass. ## 8. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/IvanMurzak/Unity-MCP | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/IvanMurzak/Unity-MCP | no_demo; severity=medium ## 10. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/IvanMurzak/Unity-MCP | no_demo; severity=medium ## 11. 安全/权限坑 · 来源证据：Bug: Auto-download failed, MCP server binary missing on macOS arm64 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Bug: Auto-download failed, MCP server binary missing on macOS arm64 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/829 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。 ## 12. 安全/权限坑 · 来源证据：Feature: built-in tool to read UGUI element state (ScreenSpaceOverlay UI is invisible to screenshot tools) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: built-in tool to read UGUI element state (ScreenSpaceOverlay UI is invisible to screenshot tools) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/837 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。 ## 13. 安全/权限坑 · 来源证据：Verify downloaded mcp-server zip against published SHA256SUMS before execute (fail-closed) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Verify downloaded mcp-server zip against published SHA256SUMS before execute (fail-closed) - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/841 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。 ## 14. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/IvanMurzak/Unity-MCP | issue_or_pr_quality=unknown ## 15. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/IvanMurzak/Unity-MCP | release_recency=unknown