项目定位与核心组成

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 仓库下载与本插件版本绑定的 server zip，解压到 Library/mcp-server/<rid>/ 目录。

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。

系统架构

下面给出一次典型连接的组件关系图：

flowchart LR
    A[AI Agent<br/>Claude Code / Cursor / Copilot] -->|stdio or HTTP| B[gamedev-mcp-server<br/>Library/mcp-server/&lt;rid&gt;/]
    B -->|HTTP + token| C[Unity Editor<br/>com.ivanmurzak.unity.mcp]
    C -->|ReflectorNet| D[User C# / Scenes / Assets]
    A -.->|unity-mcp-cli<br/>configure / setup-mcp| B
    A -.->|skills| E[.github/skills<br/>.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-<rid>.zip 并解压到 Library/mcp-server/<rid>/ 资料来源：Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/CHANGELOG.md。若本地版本文件与预期不一致，会强制重新下载以保持 server 与插件一致。

2. 安装 CLI

unity-mcp-cli 既可全局安装，也可通过 npx 临时运行 资料来源：cli/src/index.ts:1-45：

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）：从旧版本升级到 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）：当前实现直接解压执行未校验 GitHub Release 附带的 SHA256SUMS，存在供应链风险；规避方案是先在浏览器中下载并比对校验和。
• macOS arm64 自动下载失败（issue #829）与 下载超时导致安装残破（issue #832）：若网络受限，请先手动下载 gamedev-mcp-server-osx-arm64.zip 并放入 Library/mcp-server/osx-arm64/，或配置代理后重启 Editor。
• 同一机器两个 Editor 互踢（issue #830）：插件使用共享 EditorPrefs PID 键，导致多实例互斥。可通过为不同项目分配不同端口 + 自定义 token 暂时缓解。
• 缺少 ReflectorNet 依赖（issue #839）：安装后报 CS0246，需手动在 manifest.json 中补齐 com.IvanMurzak.ReflectorNet 依赖。
• tests-run 工具死锁（issue #840）：0.81.1 的回归问题，建议升级到 0.82.1（已包含相关修复）或临时回退到 0.81.0。
• UPM 升级 DLL 命名冲突（issue #745）：在 Unity 6.4 上 NuGet flat-layout 名称可能与 BCL/Burst 程序集冲突，安装后需重新导入程序集。

See Also

• MCP 工具与 AI Skills 体系
• CLI 命令参考
• 共享 MCP Server 二进制分发
• 已知问题与发布说明

概述

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,cli/package.json:1-50

组件架构

flowchart LR
    AI[AI Agent<br/>Claude/Codex/Cursor/...]
    CLI[unity-mcp-cli<br/>Node.js]
    Plugin[Unity Editor Plugin<br/>com.ivanmurzak.unity.mcp]
    Srv[GameDev MCP Server<br/>gamedev-mcp-server]
    Editor[Unity Editor<br/>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,cli/src/commands/setup-mcp.ts:1-30

服务器生命周期管理

二进制分发与完整性校验

自 0.81.0 起,Editor 插件按 Runtime Identifier (RID) 从 IvanMurzak/GameDev-MCP-Server 的固定 v<ServerVersion> GitHub Release 下载 gamedev-mcp-server-<rid>.zip,解压到 <Project>/Library/mcp-server/<platform>/。McpServerManager.DownloadAndUnpackBinary 负责下载与解压;McpServerChecksum 在执行前对照 Release 同时发布的 SHA256SUMS 做 fail-closed 校验。版本号固定于插件清单,首次启动或版本不匹配时自动重下。0.82.1 已更新该 server pin。

资料来源:McpServerManager.cs,McpServerChecksum.cs,Issue #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,Startup.cs

多 Editor 实例与状态隔离

Startup.Editor.cs 与 DevControlServer 协同负责进程握手:每个 Editor 通过 EditorPrefs 记录"当前活跃连接的 PID"用于检测本机是否已有接管中的实例。同机两个 Unity 项目同时启用插件时,共享 PID 键会导致互斥——一端重连/重编会断开另一端,这是 Issue #830 描述的故障模式。

资料来源:Startup.Editor.cs,DevControlServer.cs,Issue #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,cli/src/lib.ts:1-40,cli/src/utils/manifest.ts:1-30

工具执行通过 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,cli/src/commands/run-system-tool.ts:1-10,cli/src/utils/agents.ts:1-40

已知问题与缓解

See Also

• README & 快速上手
• CHANGELOG (0.82.x)
• GameDev-MCP-Server Releases
• Issue #841 — SHA256SUMS 校验提案
• Issue #830 — 多 Editor 实例冲突

总览

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。

flowchart LR
    A[AI Agent<br/>Codex/Copilot/Cursor/...] -->|MCP stdio / HTTP| B[GameDev-MCP-Server<br/>v8.0.0]
    B -->|HTTP JSON-RPC| C[Unity Editor Plugin<br/>com.ivanmurzak.unity.mcp]
    C -->|ReflectorNet| D[Built-in Tools<br/>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<br/>.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 工具按职责可分为三组（见下表）：

内置 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，以及 tests-run 在 v0.81.1 中导致 Editor 主线程死锁的回归 资料来源：issue #840；v0.81.1 还曾因打包脚本未携带 ReflectorNet 依赖而出现 CS0246 错误，提示内置工具链的稳定性高度依赖 ReflectorNet 的正确发布 资料来源：issue #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，可作为新增内置工具的典型用例。

多 AI Agent 集成

unity-mcp-cli 通过 agents.ts 中预定义的 Agent 描述符统一处理配置文件的路径、格式（json / toml）与字段映射（mcpServers / servers / mcp_servers 等），目前已覆盖以下主流 AI Agent 资料来源：cli/src/utils/agents.ts:1-300：

每个描述符都提供 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。

常见失败模式

• 构建链回归：自 0.71.0 引入 NuGet flat-layout DLL 命名后，Burst 与 BCL 兼容 DLL 在 Unity 6.4 中解析失败，需关注 extensions.unity.playerprefsex 等传递依赖 资料来源：issue #745。
• 二进制下载残留：从 GitHub Release 拉取 gamedev-mcp-server-<rid>.zip 时若超时或中断，会留下半解压目录，下次启动需要手动清理 Library/mcp-server/<platform>/ 资料来源：issue #832。
• 扩展 API 缺位：当某个 AI Agent 不在 agents.ts 预定义列表中时，CLI 会回退到通用 JSON 写入逻辑，需手动核对字段键是否正确。

See Also

• 架构与连接 (Architecture & Connection)
• 安装与升级指南 (Installation & Upgrade)
• 故障排查 (Troubleshooting)

项目概览与 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 端显式声明了三项运行时依赖——[email protected]、[email protected] 与 [email protected]——并通过 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

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、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、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 <token>，避免在不需要鉴权的 Agent 里误写敏感头。

资料来源：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、cli/src/utils/unity-editor.ts、cli/src/commands/bootstrap-local.ts、cli/src/commands/login.ts

常见故障排查

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[降级或加超时]

社区报告的典型故障与排查方向可归纳如下表：

排查流程上的统一做法：先用 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、cli/src/commands/install-plugin.ts、cli/src/commands/open.ts、cli/src/commands/configure.ts、cli/src/utils/json-parse.ts

See Also

• CLI 总览与命令参考
• MCP 工具与运行循环
• AI Agent 接入指南
• Release Notes 0.82.1

Pitfall Log / 踩坑日志

项目：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