# https://github.com/IvanMurzak/Unity-MCP Project Manual Generated at: 2026-06-22 09:46:52 UTC ## Table of Contents - [Repository Overview & System Architecture](#page-1) - [Unity Plugin: Runtime, Editor, Tools, UI & Conversion](#page-2) - [MCP Server, CLI Tool, Installer & Deployment](#page-3) - [Customization, Extensibility, Operations & Known Issues](#page-4) ## Repository Overview & System Architecture ### Related Pages Related topics: [Unity Plugin: Runtime, Editor, Tools, UI & Conversion](#page-2), [MCP Server, CLI Tool, Installer & Deployment](#page-3)
Related Source Files The following source files were used to generate this page: - [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/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/open.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/open.ts) - [cli/src/lib/types.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/types.ts) - [cli/src/lib/validation.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/validation.ts) - [cli/src/lib/create-project.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/create-project.ts) - [cli/src/utils/json-parse.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/json-parse.ts)
# Repository Overview & System Architecture ## Purpose and Scope Unity-MCP — distributed under the npm/Unity package name **`com.ivanmurzak.unity.mcp`** and the CLI name **`unity-mcp-cli`** — is an open-source bridge that lets any MCP-compatible AI agent (Claude Code, Codex, Gemini, Copilot, Cursor, Kilo Code, Cline, Antigravity, Rider/Junie, and so on) read, edit, and run code inside a live Unity Editor. The Unity package manifest describes it as *"AI Skills, MCP Tools, and CLI for Unity Engine. Full AI develop and test loop... Any C# method may be turned into a tool by a single line"* ([Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json:6-7]()). The repository is split into two independently-versioned artifacts that ship in lockstep: | Artifact | Type | Version (0.82.1) | Entry point | |---|---|---|---| | `com.ivanmurzak.unity.mcp` | UPM/Unity package | `0.82.1`, requires `unity 2022.3` | Editor window + HTTP/stdio MCP server | | `unity-mcp-cli` | npm CLI (ESM) | `0.82.1`, requires `node ^20.19.0 || >=22.12.0` | `bin/unity-mcp-cli.js` | The Unity package declares runtime dependencies on `com.unity.test-framework@1.1.33`, `com.unity.modules.uielements@1.0.0`, and `extensions.unity.playerprefsex@2.1.5` ([Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json:18-22]()). The CLI declares `commander@^13.1.0` for argument parsing, `chalk@^5.6.2` for styled output, and `yocto-spinner@^1.1.0` for progress indication ([cli/package.json:30-34]()). ## Repository Layout & Components The two artifacts live in different subtrees: - **`Unity-MCP-Plugin/`** — the Editor-side package. It hosts the C# MCP server that runs in-process with Unity, the Editor window, the ReflectorNet-backed dynamic-method bridge, and the auto-downloader for the shared `gamedev-mcp-server` binary that ships in `Library/mcp-server//` (introduced in 0.81.0). - **`cli/`** — a Node.js/TypeScript ESM project that automates Unity installation, project bootstrap, plugin manifest patching, MCP-config generation for many AI agents, and an HTTP client for running tools remotely. Its top-level `program` registers fifteen subcommands — `bootstrap-local`, `close`, `configure`, `create-project`, `install-plugin`, `install-unity`, `login`, `open`, `remove-plugin`, `run-tool`, `run-system-tool`, `setup-mcp`, `setup-skills`, `status`, `update`, and `wait-for-ready` ([cli/src/index.ts:18-30]()). Library code under `cli/src/lib/` is deliberately side-effect-free so that third parties can import the same logic the CLI uses. The discriminated-union return types `CreateProjectResult`, `RunToolResult`, and the helpers in `validation.ts` (e.g. `requireUnityProject`) keep public callers from having to catch exceptions across the boundary ([cli/src/lib/types.ts:55-145](), [cli/src/lib/validation.ts:18-33]()). ## Runtime Architecture & Data Flow The runtime is a three-tier pipeline. The AI agent speaks MCP (JSON-RPC over stdio or HTTP) to the standalone `gamedev-mcp-server`, which speaks the same protocol over an authenticated HTTP/stdio channel to the in-process C# MCP server hosted by the Unity Editor. The Editor server uses the ReflectorNet runtime to bind arbitrary C# methods to MCP tools at startup. ```mermaid flowchart LR A[AI Agent
Claude/Codex/Copilot/Cursor/...] -->|stdio or HTTP + token| B[gamedev-mcp-server
Library/mcp-server/<rid>/] B -->|HTTP localhost:port + token| C[Unity Editor
C# MCP server] C --> D[ReflectorNet
dynamic method binding] D --> E[Project assemblies
any C# method = tool] CLI[unity-mcp-cli] -->|bootstrap, open, run-tool| B CLI -->|manifest.json edit, setup-mcp| F[AI-agent config files
.vscode/mcp.json, .cursor/mcp.json, ...] ``` The CLI’s `run-tool` / `run-system-tool` commands consume the same `RunToolResult` union, where success returns `{ kind: 'success', data }` and failure is categorized as `invalid-input | connection-refused | connection-reset | network-error | timeout | http-error | unknown` ([cli/src/lib/types.ts:73-145]()). Connection parameters (URL + token) are read from the project's `UserSettings/AI-Game-Developer-Config.json`; when the file is missing the CLI falls back to a deterministic localhost port ([cli/src/lib/types.ts:127-135]()). ## Supported AI Agents & Configuration `cli/src/utils/agents.ts` is a single declarative registry that maps agent IDs to: - **skills path** (where the CLI copies skill files, e.g. `.claude/skills`, `.cursor/skills`, `.junie/skills`, `.kilocode/skills`), - **config path & format** (JSON or TOML, e.g. `.vscode/mcp.json`, `.codex/config.toml`, `~/.gemini/config/mcp_config.json`, `.cursor/mcp.json`, `.junie/mcp/mcp.json`), - **`getStdioProps` / `getHttpProps`** builders that produce the per-agent schema (some use `mcpServers`, others use `servers`), including authorization headers derived from `authHeaders(token, authRequired)` and a default `tool_timeout_sec: 300` for Codex ([cli/src/utils/agents.ts:25-220]()). The supported roster currently includes Claude Code, Codex, Kilo Code, Rider (Junie), Visual Studio (Copilot), VS Code (Copilot), Cursor, Cline, and Antigravity. The `setup-mcp` command walks this registry to write the correct file for whichever agent the user selects. ## Operational Concerns Drawn from Community Issues Several recurring failure modes in the issue tracker trace directly to the architecture above and are worth noting on this overview page: - **Server binary download (issues #829, #832, #845)** — the in-Editor `DownloadAndUnpackBinary` flow (called from `McpServerManager`) pulls `gamedev-mcp-server-.zip` from the pinned GitHub release and extracts it to `Library/mcp-server//`. Network failures during this step can leave the install in a broken state; a SHA256SUMS verification step has been proposed (issue #841) to fail-closed. - **Shared EditorPrefs PID key (issue #830)** — running two Editor instances on the same machine causes mutual exclusion because both writers race for the same connection state. - **ReflectorNet dependency (issue #839)** — the package must declare `com.IvanMurzak.ReflectorNet`; if a UPM downgrade drops it, every dependent `.cs` file fails to compile with `CS0246`. - **Editor deadlock on `tests-run` (issue #840)** — a regression in 0.81.1 where the test-runner tool blocked Unity's main thread. These issues are not yet fixed in 0.82.1, so operators running the CLI in CI or multi-Editor environments should pin to a known-good version and pre-warm `Library/mcp-server//` before starting the Editor. ## See Also - [Installation & Setup Guide](Installation.md) - [CLI Command Reference](CLI-Commands.md) - [MCP Protocol & Tool Authoring](MCP-Protocol.md) - [Troubleshooting & Known Issues](Troubleshooting.md) --- ## Unity Plugin: Runtime, Editor, Tools, UI & Conversion ### Related Pages Related topics: [Repository Overview & System Architecture](#page-1), [MCP Server, CLI Tool, Installer & Deployment](#page-3), [Customization, Extensibility, Operations & Known Issues](#page-4)
Related Source Files The following source files were used to generate this page: - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Runtime/UnityMcpPlugin.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Runtime/UnityMcpPlugin.cs) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Runtime/UnityMcpPluginBuilder.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Runtime/UnityMcpPluginBuilder.cs) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Runtime/UnityMcpPlugin.Converters.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Runtime/UnityMcpPlugin.Converters.cs) - [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Runtime/UnityMcpPlugin.Config.cs](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/Runtime/UnityMcpPlugin.Config.cs) - [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/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/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/lib/types.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/types.ts) - [cli/src/lib/run-tool.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/run-tool.ts) - [commands/tools/1.json](https://github.com/IvanMurzak/Unity-MCP/blob/main/commands/tools/1.json) - [cli/src/utils/agents.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/agents.ts)
# Unity Plugin: Runtime, Editor, Tools, UI & Conversion The Unity package `com.ivanmurzak.unity.mcp` is the in-engine side of the AI Game Developer stack. It hosts the runtime entry point, the editor-side MCP server lifecycle, the configurable tool surface, the bridge to the shared `gamedev-mcp-server` binary, and the converters that marshal between CLR objects and the Model Context Protocol (MCP) wire format. This page documents how those pieces fit together based on the public source tree. ## 1. Package Layout and Runtime Entry Point The package is a standard UPM distribution targeting Unity 2022.3 and above. Its `package.json` declares the display name "AI Game Developer — MCP", the test-framework and UI-elements module dependencies, and an `extensions.unity.playerprefsex` scoped dependency. Source: [Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json]() The runtime is split into focused files rather than one monolith: | File | Responsibility | |------|----------------| | `Runtime/UnityMcpPlugin.cs` | Top-level static facade; access point for tools and lifecycle. | | `Runtime/UnityMcpPluginBuilder.cs` | Fluent builder used to compose the plugin instance and register tools. | | `Runtime/UnityMcpPlugin.Config.cs` | Holds connection configuration (host, port, transport, token). | | `Runtime/UnityMcpPlugin.Converters.cs` | Maps CLR types to MCP type schemas; the only file dealing with type-conversion policy. | This split keeps the public surface small: the builder assembles state, the config file is the single source of truth for connection parameters, and converters are isolated so type-system changes do not leak into the rest of the runtime. Source: [Runtime/UnityMcpPlugin.cs](), [Runtime/UnityMcpPluginBuilder.cs](), [Runtime/UnityMcpPlugin.Config.cs](), [Runtime/UnityMcpPlugin.Converters.cs]() ## 2. Editor Side: Server Lifecycle and Binary Download The editor side is anchored by `Editor/Scripts/McpServerManager.cs` and `Editor/Scripts/Startup.cs`. The startup hook runs on Editor load, while the manager owns the lifecycle of the shared `gamedev-mcp-server` process. ### 2.1 Binary Acquisition Since v0.81.0 the plugin no longer ships a bundled server. Instead, `McpServerManager.DownloadAndUnpackBinary` resolves the current runtime identifier (`win-x64`, `osx-arm64`, `linux-x64`, …), downloads `gamedev-mcp-server-.zip` from the pinned `v` GitHub release over HTTPS, and extracts it into `Library/mcp-server//`. Source: [Editor/Scripts/McpServerManager.cs]() A version sentinel is written next to the binary; on subsequent runs, a mismatch between the sentinel and the pinned `ServerVersion` triggers a forced re-download. This is the mechanism referenced in the 0.81.0 release notes ("existing installs re-download automatically on first use (version-file mismatch)"). Source: [Editor/Scripts/McpServerManager.cs]() ### 2.2 Common Failure Modes Community reports cluster around the download path and are worth surfacing here: - **macOS arm64 / Linux auto-download failures** ([#829](https://github.com/IvanMurzak/Unity-MCP/issues/829), [#845](https://github.com/IvanMurzak/Unity-MCP/issues/845)): a half-extracted zip or a failed HTTPS fetch can leave `Library/mcp-server//` in a broken state. GitHub-side timeouts were specifically called out in [#832](https://github.com/IvanMurzak/Unity-MCP/issues/832). - **No integrity check** ([#841](https://github.com/IvanMurzak/Unity-MCP/issues/841)): the download is not verified against the published `SHA256SUMS` before extraction, so a corrupted or substituted archive would currently be executed without detection. The `DownloadAndUnpackBinary` path is the recommended place to add a fail-closed hash check. - **Single-Editor mutex via shared EditorPrefs PID key** ([#830](https://github.com/IvanMurzak/Unity-MCP/issues/830)): two Editors on the same machine both write to the same `EditorPrefs` key, so the most recently started instance claims the MCP socket and drops the other. Users running parallel projects need a per-project PID key. - **Missing ReflectorNet dependency** ([#839](https://github.com/IvanMurzak/Unity-MCP/issues/839)): in 0.81.1 the `com.IvanMurzak.ReflectorNet` package was not declared in `package.json`, causing `CS0246` until it was added manually. The current `package.json` reflects the corrected dependency set. ## 3. Tool Surface and Conversion The plugin exposes MCP tools via the shared server's `runTool` / `runSystemTool` HTTP endpoints. The CLI's `runTool` helper posts to `/api/tools/{name}` and the system variant to `/api/system-tools/{name}`, both of which the Unity plugin serves from the same HTTP listener. Source: [cli/src/lib/run-tool.ts]() A representative tool schema lives under `commands/tools/*.json`; for example, the asset-modify schema accepts an `assetRef` (path or GUID) and a `content` payload expressed as a `SerializedMember` — a tree of CLR-shaped values that the runtime converters flatten and rehydrate. Source: [commands/tools/1.json]() `UnityMcpPlugin.Converters.cs` is the policy layer for that round-trip: it decides which CLR types are serialisable, how generics and reference loops are handled, and how schema annotations are emitted. Because every tool argument passes through the same converter chain, a regression in this file is felt uniformly across all tools. Source: [Runtime/UnityMcpPlugin.Converters.cs]() The CLI's `RunToolResult` type documents the on-the-wire response shape: `{ status: "success", structured?: , content?: }`. Tools that need rich data should return `structured`; tools that primarily render text use `content`. Consumers narrow on `kind === 'success' | 'failure'`. Source: [cli/src/lib/types.ts]() ## 4. UI, Configuration, and Agent Wiring The editor UI is provided by the `Startup` and `McpServerManager` pair: a window with start/stop controls, a connection-mode selector (Cloud, Custom), and tool/prompt/resource filters persisted into `AI-Game-Developer-Config.json` under `UserSettings/`. Source: [Editor/Scripts/Startup.cs](), [Editor/Scripts/McpServerManager.cs]() The CLI mirrors that config schema in `cli/src/utils/config.ts` (`createDefaultConfig`, `readConfig`, `writeConfig`, `getOrCreateConfig`) so that the two sides stay in lockstep. Source: [cli/src/utils/config.ts]() Agent configuration is written per agent by the `setupMcp` command, which uses a registry of known agents (Claude Code, Gemini, Copilot, Cursor, Codex, Kilo Code, Rider/Junie, VS, VS Code). Each entry defines the config path, the stdio argument list, and the HTTP variant with optional auth headers. Source: [cli/src/utils/agents.ts]() A known regression: the `tests-run` tool caused an Editor deadlock in v0.81.1, reportedly because it ran synchronously on the main thread ([#840](https://github.com/IvanMurzak/Unity-MCP/issues/840)). Likewise, `Assets_Modify` against ScriptableObject assets was reported to mutate in memory without `EditorUtility.SetDirty` being called, so changes did not persist ([#334](https://github.com/IvanMurzak/Unity-MCP/issues/334)). Both are illustrative of why conversion + dirty-flag policy is part of the plugin contract, not an internal detail. ```mermaid flowchart LR A[AI Agent / CLI] -->|HTTP /api/tools/name| B[Unity Editor] B --> C[McpServerManager] C --> D[Download gamedev-mcp-server] D --> E[Library/mcp-server/rid/] C --> F[Converters] F --> G[UnityMcpPlugin tools] G --> H[Scene / Assets / Editor APIs] ``` ## See Also - CLI Library API and project bootstrap: `cli/src/lib/create-project.ts`, `cli/src/lib/types.ts` - Agent configuration registry: `cli/src/utils/agents.ts` - Shared MCP server source: [IvanMurzak/GameDev-MCP-Server](https://github.com/IvanMurzak/GameDev-MCP-Server) - Release notes for v0.81.0 (shared server migration), v0.82.0, v0.82.1 --- ## MCP Server, CLI Tool, Installer & Deployment ### Related Pages Related topics: [Repository Overview & System Architecture](#page-1), [Unity Plugin: Runtime, Editor, Tools, UI & Conversion](#page-2), [Customization, Extensibility, Operations & Known Issues](#page-4)
Related Source Files The following source files were used to generate this page: - [cli/src/index.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/index.ts) - [cli/src/cli.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/cli.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/types.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/commands/setup-mcp.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/setup-mcp.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) - [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) - [commands/tools/validate_mcp_openai.py](https://github.com/IvanMurzak/Unity-MCP/blob/main/commands/tools/validate_mcp_openai.py) Community references consulted: - [Issue #845 — Linux 0.82.1 server binary not downloaded](https://github.com/IvanMurzak/Unity-MCP/issues/845) - [Issue #841 — SHA256SUMS verification for the downloaded zip](https://github.com/IvanMurzak/Unity-MCP/issues/841) - [Issue #832 — Install left broken on GitHub download timeout](https://github.com/IvanMurzak/Unity-MCP/issues/832) - [Issue #829 — Auto-download failed on macOS arm64](https://github.com/IvanMurzak/Unity-MCP/issues/829) - [Release 0.81.0 — migration to shared GameDev-MCP-Server](https://github.com/IvanMurzak/Unity-MCP/releases/tag/0.81.0)
# MCP Server, CLI Tool, Installer & Deployment ## Overview The Unity-MCP project ships a coordinated deployment system with three moving parts: a Unity Editor package (`com.ivanmurzak.unity.mcp`) that auto-downloads and runs a native MCP server, a cross-platform Node.js CLI (`unity-mcp-cli`) that bootstraps projects and configures AI agents, and a public library surface that lets other tools embed the same workflows without spawning a subprocess. The 0.81.x release line migrated the server from a plugin-internal binary to a **shared `GameDev-MCP-Server`** fetched from `IvanMurzak/GameDev-MCP-Server` into the Unity project's `Library/mcp-server//` folder. As of 0.82.1 the CLI package version is `0.82.1` and matches the plugin pin (see [cli/package.json](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/package.json) and [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)). ## High-Level Architecture ```mermaid flowchart LR A[AI Agent
Claude / Cursor / Codex / Copilot] -->|MCP stdio or http| B[unity-mcp-cli
binary] B -->|HTTPS download| GH[GameDev-MCP-Server
GitHub Release vX.Y.Z] GH --> C[Library/mcp-server/<rid>/
gamedev-mcp-server] C -->|stdio/JSON-RPC| D[Unity Editor plugin
com.ivanmurzak.unity.mcp] D -->|HTTP listener| B A -.configure.-> E[setup-mcp
writes .vscode/mcp.json etc.] E --> B ``` The CLI is split into two export points (see [cli/src/lib.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib.ts) and [cli/src/cli.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/cli.ts)). Importing `unity-mcp-cli` (the package root) returns a side-effect-free library whose functions return discriminated `Result` unions keyed on `kind: 'success' | 'failure'`. Importing `unity-mcp-cli/cli` (or invoking the `unity-mcp-cli` binary) runs Commander, parses argv, and exits. This separation lets agents embed install/configure flows without leaking spinners or stdout writes ([cli/src/lib.ts:7-19](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib.ts)). ## Unity Package & Server Auto-Download The plugin package declares Unity 2022.3+ compatibility and pulls in the test framework, UIElements module, and `extensions.unity.playerprefsex` as hard dependencies ([Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json:24-28](https://github.com/IvanMurzak/Unity-MCP/blob/main/Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json)). On first start the editor downloads `gamedev-mcp-server-.zip` from a pinned GitHub release into `Library/mcp-server//`, extracts it, and launches the binary. The download path is governed by `McpServerManager.DownloadAndUnpackBinary`. The auto-download path has been a recurring source of community pain. Issue [#829](https://github.com/IvanMurzak/Unity-MCP/issues/829) reports the macOS arm64 fetch leaving no binary on disk, issue [#832](https://github.com/IvanMurzak/Unity-MCP/issues/832) reports a half-extracted install when GitHub's HTTPS transfer is interrupted, issue [#845](https://github.com/IvanMurzak/Unity-MCP/issues/845) reports the same on Linux after the 0.82.1 bump, and issue [#841](https://github.com/IvanMurzak/Unity-MCP/issues/841) calls out the lack of a SHA256SUMS check on the zip before extraction (a fail-closed verification is requested). When the binary is missing the typical recovery is to delete `Library/mcp-server/` and let the editor re-download, or to fetch the matching release manually from [IvanMurzak/GameDev-MCP-Server](https://github.com/IvanMurzak/GameDev-MCP-Server). ## CLI Tool: Commands & Library API The CLI registers 14 subcommands under the `unity-mcp-cli` program ([cli/src/index.ts:9-37](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/index.ts)): | Command | Purpose | |---|---| | `install-plugin` / `remove-plugin` | Add or remove `com.ivanmurzak.unity.mcp` from a project's `manifest.json` | | `configure` | Edit `AI-Game-Developer-Config.json` (host, transport, auth, tool/prompt/resource toggles) | | `setup-mcp` | Write per-agent MCP client configuration | | `setup-skills` | Stage the shared `Skills` folder for an agent | | `bootstrap-local` | One-shot local bring-up | | `open` / `create-project` | Locate and launch a Unity Editor against a project | | `install-unity` | Install a Unity Editor version via the Hub | | `run-tool` / `run-system-tool` | Invoke an MCP tool over the HTTP API | | `login`, `status`, `close`, `update`, `wait-for-ready` | Session and lifecycle helpers | `run-tool` and `run-system-tool` share a common builder pattern. `runToolCommand` ([cli/src/commands/run-tool.ts:1-13](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/run-tool.ts)) and `runSystemToolCommand` ([cli/src/commands/run-system-tool.ts:1-13](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/run-system-tool.ts)) both delegate to `buildRunToolCommand` with different `routePrefix` and verb labels (`/api/tools` vs `/api/system-tools`). System tools are explicitly **not** exposed to MCP clients — only to operators using the CLI. The library surface mirrors those commands as `installPlugin`, `removePlugin`, `configure`, `setupMcp`, `openProject`, `createProject`, `runTool`, and `runSystemTool` ([cli/src/lib.ts:21-31](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib.ts)). Every public result is a discriminated union — for example `SetupMcpSuccess` vs `SetupMcpFailure` and `InstallSuccess` vs `InstallFailure` ([cli/src/lib/types.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/types.ts)) — and progress is delivered through an optional `onProgress` callback typed as a `ProgressEvent` union, never through globals. ## Agent Configuration Registry `setup-mcp` discovers agents through the registry in [cli/src/utils/agents.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/agents.ts). Each `AgentDefinition` knows its `id`, display `name`, `skillsPath`, the config file location (via `configPathDisplay` and `getConfigPath`), the file format (`'json' | 'toml'`), the JSON/TOML body key (`bodyPath`), and two serializers: `getStdioProps` and `getHttpProps`. Helpers `getAgentById`, `getAgentIds`, and `listAgentTable` provide lookup and CLI printing. The registry covers Claude Code, Cursor, Codex, Cline, Kilo Code, Rider (Junie), Visual Studio (Copilot), VS Code (Copilot), Unity (Copilot), and the GitHub Copilot CLI. Per-agent quirks are encoded in the entry — for example, Codex writes TOML under `mcp_servers` and sets `tool_timeout_sec: 300` plus `startup_timeout_sec: 30` for the HTTP variant, while Cline's config path is OS-dependent (Windows uses `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings`, macOS uses `~/Library/Application Support/Code/User/globalStorage`, Linux uses `~/.config/Code/User/globalStorage`) and its HTTP transport is `streamableHttp` rather than `http`. `setup-mcp` exposes `--transport`, `--url`, and `--token` overrides plus `--list` to enumerate agents ([cli/src/commands/setup-mcp.ts:19-26](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/setup-mcp.ts)). ## Validation & Tooling `commands/tools/validate_mcp_openai.py` provides a way to dry-run a generated MCP tool manifest against the OpenAI function-calling endpoint, surfacing schema errors and missing descriptions before the tool reaches a model. Combined with the CLI's `run-tool` helper, this closes a small feedback loop: author a tool description, run `validate_mcp_openai` to confirm the schema is acceptable, then `run-tool` to exercise it against a live Unity instance. ## See Also - [MCP Tools Reference](MCP-Tools-Reference.md) — built-in and user-defined tools exposed to agents - [Configuration](Configuration.md) — `AI-Game-Developer-Config.json` schema and Editor settings - [Authentication & Transports](Authentication-Transports.md) — stdio vs http, token-based auth, and per-agent quirks - [Troubleshooting](Troubleshooting.md) — recovery steps for the auto-download, PID, and checksum issues cited above --- ## Customization, Extensibility, Operations & Known Issues ### Related Pages Related topics: [Unity Plugin: Runtime, Editor, Tools, UI & Conversion](#page-2), [MCP Server, CLI Tool, Installer & Deployment](#page-3)
Related Source Files The following source files were used to generate this page: - [cli/src/utils/agents.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/agents.ts) - [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) - [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/src/utils/manifest.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/manifest.ts) - [cli/src/utils/unity-editor.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/unity-editor.ts) - [cli/src/lib/run-tool.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/run-tool.ts) - [cli/src/lib/validation.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/validation.ts) - [cli/src/commands/bootstrap-local.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/bootstrap-local.ts) - [cli/src/lib/types.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/types.ts) - [cli/src/lib/create-project.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/create-project.ts) - [cli/src/utils/ui.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/ui.ts) - [cli/src/utils/json-parse.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/json-parse.ts)
# Customization, Extensibility, Operations & Known Issues This page documents how Unity-MCP is customized per agent, extended with new tools, operated through the CLI, and the known limitations reported by the community. It is written against plugin version **0.82.1** (June 21, 2026). ## Customization — AI Agent Integration Unity-MCP ships a multi-agent configuration registry that wires the local MCP server into each supported AI client. The registry lives in `cli/src/utils/agents.ts` and currently supports Codex, Kilo Code, VS Code (Copilot), Visual Studio (Copilot), Rider (Junie), Antigravity, and Cline. Each entry defines three things: the on-disk config path, the serialization format (`json` or `toml`), and a pair of transport serializers (`getStdioProps`, `getHttpProps`) so the same entry can produce either an stdio or HTTP configuration. Source: [cli/src/utils/agents.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/agents.ts). | Agent | Config Path | Body Key | Skills Path | |---|---|---|---| | Codex | `.codex/config.toml` | `mcp_servers` | `.agents/skills` | | VS Code (Copilot) | `.vscode/mcp.json` | `servers` | `.github/skills` | | Visual Studio (Copilot) | `.vs/mcp.json` | `servers` | `.github/skills` | | Rider (Junie) | `.junie/mcp/mcp.json` | `mcpServers` | `.junie/skills` | | Antigravity | `~/.gemini/config/mcp_config.json` | `mcpServers` | `.agent/skills` | | Cline | `~/Code/globalStorage/.../cline_mcp_settings.json` | `mcpServers` | `.cline/skills` | Each entry filters incompatible keys per transport (`stdioRemoveKeys`, `httpRemoveKeys`) so an HTTP-only field such as `url` is never written into an stdio block, preventing client-side parse failures. Source: [cli/src/utils/agents.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/agents.ts). ### Bootstrap Local Mode For headless or scripted runs, `bootstrap-local.ts` exposes `pinLocalModeConfig(current, url, token)`, which normalizes the connection mode to `"Custom"` and pins host/token onto the saved config. The helper `isAlreadyPinned` keeps the operation idempotent so re-running the command does not churn the file. Source: [cli/src/commands/bootstrap-local.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/commands/bootstrap-local.ts). ## Extensibility — Adding and Validating Tools The Unity package follows a "one-line attribute" extension model: any C# method may be turned into an MCP tool with a single attribute. The package metadata at `Unity-MCP-Plugin/Packages/com.ivanmurzak.unity.mcp/package.json` lists runtime dependencies (`com.unity.test-framework`, `com.unity.modules.uielements`, `extensions.unity.playerprefsex`) and pins Unity **2022.3** as the minimum supported version. Source: [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). Tool invocation over HTTP is handled by the library API in `cli/src/lib/run-tool.ts`. Both `runTool` and `runSystemTool` POST to `/api/tools/{name}` and `/api/system-tools/{name}` respectively, resolving URL/token via explicit override → project config → deterministic localhost port. The default timeout is **60 s** (`DEFAULT_TIMEOUT_MS`). Source: [cli/src/lib/run-tool.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/run-tool.ts). ### Validation Helpers The CLI ships side-effect-free validators under `cli/src/lib/validation.ts`. `requireProjectPath` and `requireUnityProject` return a discriminated union (`{ ok: true } | { ok: false, error }`) so library callers stay exception-free across the public boundary. Source: [cli/src/lib/validation.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/validation.ts). Robust JSON parsing is provided by `json-parse.ts`, which tries a raw parse first, falls back to auto-stringify, and reports exact byte positions on failure. Source: [cli/src/utils/json-parse.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/json-parse.ts). Library-facing option shapes are exported from `cli/src/lib/types.ts`, including `SetupMcpOptions`, `OpenProjectOptions`, and the `OpenProjectAuthOption` union (`'none' | 'required'`). Source: [cli/src/lib/types.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/types.ts). ## Operations — CLI Subcommands `unity-mcp-cli` (v0.82.1) registers fifteen subcommands in `cli/src/index.ts`: `bootstrapLocal`, `close`, `configure`, `createProject`, `installPlugin`, `installUnity`, `login`, `open`, `removePlugin`, `runTool`, `runSystemTool`, `setupMcp`, `setupSkills`, `status`, `waitForReady`, plus a non-blocking `createUpdate` checker. Source: [cli/src/index.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/index.ts). The CLI requires Node.js `^20.19.0 || >=22.12.0`. Source: [cli/package.json](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/package.json). A progress bar helper (`createProgressBar`) automatically switches to plain text when stdout is not a TTY, so CI and non-interactive shells still get observable status output. Source: [cli/src/utils/ui.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/ui.ts). ### Project Creation & Editor Discovery `create-project.ts` orchestrates Unity Editor launches with timeout handling and warning aggregation. Editor resolution in `unity-editor.ts` first scans the platform default Hub root, then reads Unity Hub's `secondaryInstallPath.json` for user-moved installs. Comparison keys are normalized per-OS (`path.normalize` plus lowercasing on Windows only) so paths differing only by case or trailing separator are correctly deduped while preserving Posix case sensitivity. Source: [cli/src/utils/unity-editor.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/unity-editor.ts). Source: [cli/src/lib/create-project.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/lib/create-project.ts). ### Package Manifest Updates `manifest.ts` ports the C# `Installer.Manifest` logic to TypeScript: it adds the OpenUPM scoped registry, inserts or updates the plugin entry, and prevents silent downgrades when auto-resolving versions. Non-semver specs (`file:`, `git+`, `http:`, `https:`) skip auto-update to avoid breaking local development references. Source: [cli/src/utils/manifest.ts](https://github.com/IvanMurzak/Unity-MCP/blob/main/cli/src/utils/manifest.ts). ## Known Issues (Community-Reported) The community thread has surfaced several operational caveats worth tracking: - **Binary download races on Linux (0.82.1)** — [#845](https://github.com/IvanMurzak/Unity-MCP/issues/845): server binary fails to download after upgrade on Linux x64. - **No SHA256 verification on downloaded server** — [#841](https://github.com/IvanMurzak/Unity-MCP/issues/841): the plugin extracts and executes the zip without checking the published SHA256SUMS; a fail-closed check is requested. - **`tests-run` deadlock in 0.81.1** — [#840](https://github.com/IvanMurzak/Unity-MCP/issues/840): regression where the tool blocks the Editor main thread (previously returned timeout-only). - **Missing ReflectorNet dependency (0.81.1)** — [#839](https://github.com/IvanMurzak/Unity-MCP/issues/839): `com.IvanMurzak.ReflectorNet` is not declared, causing `CS0246` on first install. - **Broken install on GitHub timeout (0.81.0)** — [#832](https://github.com/IvanMurzak/Unity-MCP/issues/832): a partial download can leave `Library/mcp-server//` in an unusable state. - **Two Editors can't share an MCP connection** — [#830](https://github.com/IvanMurzak/Unity-MCP/issues/830): a shared EditorPrefs PID key forces mutual exclusion between two simultaneous Unity projects on the same host. - **macOS arm64 auto-download failure (0.80.0)** — [#829](https://github.com/IvanMurzak/Unity-MCP/issues/829): missing binary in `osx-arm64/` after Start Server. - **`Assets_Modify` doesn't persist** — [#334](https://github.com/IvanMurzak/Unity-MCP/issues/334): ScriptableObject edits are not saved because `EditorUtility.SetDirty` is not called. - **Particle System extension breakage (0.68.0+)** — [#717](https://github.com/IvanMurzak/Unity-MCP/issues/717). - **NuGet flat-layout DLL names (0.71.0)** — [#745](https://github.com/IvanMurzak/Unity-MCP/issues/745): BCL compatibility DLLs break Editor compilation and Burst resolution on Unity 6.4. - **ScreenSpaceOverlay UI invisible to screenshots** — [#837](https://github.com/IvanMurzak/Unity-MCP/issues/837): requests a built-in UGUI element-state tool. - **VS Code Copilot transient MCP errors** — [#666](https://github.com/IvanMurzak/Unity-MCP/issues/666): intermittent "Sorry, your request failed" responses despite the server being reachable. The latest published release is **0.82.1** (June 21, 2026). Source: [releases/tag/0.82.1](https://github.com/IvanMurzak/Unity-MCP/releases/tag/0.82.1). ## See Also - [Repository README](https://github.com/IvanMurzak/Unity-MCP) - [CLI Reference](https://github.com/IvanMurzak/Unity-MCP/tree/main/cli) - [Plugin Source](https://github.com/IvanMurzak/Unity-MCP/tree/main/Unity-MCP-Plugin) - [Release Notes](https://github.com/IvanMurzak/Unity-MCP/releases) --- --- ## Pitfall Log Project: IvanMurzak/Unity-MCP Summary: Found 15 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/832 ## 2. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/839 ## 3. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/IvanMurzak/Unity-MCP ## 4. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/845 ## 5. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/830 ## 6. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/840 ## 7. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/IvanMurzak/Unity-MCP ## 8. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/IvanMurzak/Unity-MCP ## 9. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/IvanMurzak/Unity-MCP ## 10. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/IvanMurzak/Unity-MCP ## 11. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/829 ## 12. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/837 ## 13. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/IvanMurzak/Unity-MCP/issues/841 ## 14. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/IvanMurzak/Unity-MCP ## 15. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/IvanMurzak/Unity-MCP