MCP2UNITY
by MusafirEx
README.md
# MCP2UNITY
**Version: 0.5.2 (experimental backport)** | **Unity: 2022.3 LTS (validated on 2022.3.62f3)** | **Windows PowerShell companion**
> **Latest validation (2026-11-10, PR #4):** Unity EditMode suite **160/160 passed** (0 failed, skipped or inconclusive; 55.21 seconds) after the target-scene EventSystem fix merged into `main`. Reviewed action `c0a81ff40d63`; no console errors, scene saved/clean. See [CHANGELOG](CHANGELOG.md).
MCP2UNITY restarts the original Wasim Unity MCP Bridge from its **v0.5.1** source instead of upgrading the transport to v0.6.0. The v0.5.1 standalone PowerShell companion and its Unity Editor file-IPC architecture are retained; 17 optional tools from v0.6.0 are backported into separate Editor modules. This rebuild has 21 original tool entries + 17 backported entries + 1 reviewed Transform tool + 8 uGUI tools = **47 advertised MCP tools**.
> **Verification status:** All **73/73 EditMode tests (Phases 1–3)** passed in Unity 2022.3.62f3 with the connected MCP bridge advertising 47 tools and no reported compilation/Console errors. Canvas/Panel/Button/Styling/Layout creation was exercised end-to-end in the MuOnBaAr test scene, which was restored to five original root objects. **Phase 4 PlayMode interactions passed 13/13**, bringing the measured total to **120/120 Unity tests** (107 EditMode + 13 PlayMode) on 2026-11-10, including 10/10 Phase 5 UI serialization and persistence tests. Direct live MCP-created UI Hide/Show interaction was also verified in Game View (target `activeSelf` changed false/true) and the temporary Canvas/EventSystem were removed; the original five scene roots were verified. Unity compilation and Console were clean after UPM update. No standalone Windows companion/player-build certification is implied.
## Why this build?
- Keep the v0.5.1 companion process, ngrok lifecycle, script-inspection tools, and existing script-change approval workflow.
- Isolate v0.6.0 runtime inspection, rollback, scene/view diagnostics, profiler and Editor/Test Framework actions behind modular handlers.
- Add only narrow communication patches for MCP image envelopes, JSON array preservation, request expiry, and no replay of interrupted operations.
- Require local review for scene/script change sets and Editor actions. Neither can be approved remotely.
## Install from GitHub (UPM)
1. Back up the project. Remove the old `com.wasimdevelopment.unity-mcp-bridge` package if it is installed; both packages retain the same Editor assembly name and must **not** be installed together.
2. In Unity 2022.3, open **Window > Package Manager > + > Add package from git URL**.
3. Enter:
```text
https://github.com/MusafirEx/MCP2UNITY.git
```
4. Allow Newtonsoft JSON 3.2.1 and Unity Test Framework 1.1.33 dependencies to resolve. Check the Console for compile errors before starting anything.
5. Open **Window > Wasim Development > Unity MCP Bridge**, configure the Windows PowerShell executable and ngrok. Close any companion from an earlier installation before starting this one.
6. Click **Start Companion** and run **Local MCP Self-Test**. It should advertise 47 tools and complete a `unity_get_status` round trip. Use the private MCP endpoint generated by the bridge, not an unauthenticated public URL.
This URL installs from the repository's default branch, **`main`**. To explicitly select it, append `#main` to the URL. To keep a reproducible package version, pin a specific commit using `#<commit-sha>` instead. Unity Package Manager resolves Git revisions when the package is installed or updated; it does not automatically fetch every new commit. The former `#rebuild/v051-backports` install link is no longer recommended.
The tool catalog is visible only when the companion and Unity IPC are running. If requests fail during compilation, wait until Unity finishes importing before trying them again. A request that times out or is interrupted is intentionally not replayed.
## Capability groups
| Group | Tools |
| --- | ---: |
| v0.5.1 project, scripts, assets, hierarchy, animator, console and script proposals | 21 |
| v0.6.0 runtime, capture, trace, change sets, diagnostics, references, profiler, editor/test actions | 17 |
| Reviewed Transform position / Euler rotation / scale tool | 1 |
| uGUI Canvas, element creation, RectTransform editing and hierarchy inspection (phase 1) | 4 |
| Reviewed uGUI styling / LayoutGroup configuration (phase 2) | 2 |
| Advanced uGUI controls, guarded GameObject deletion and Button event binding (phase 3) | 2 |
| **Advertised total** | **47** |
See [the 17 backported tool specifications](Documentation~/TOOLS_V060.md) and [the backport matrix](Documentation~/BACKPORT_MATRIX.md).
### Change sets and Editor actions
The `unity_set_transform` tool prepares local/world Position, Euler Rotation and Scale changes (absolute or relative) as **reviewed change sets**. It does not modify the scene until approved locally. World scale on nonuniformly scaled parents is rejected; [details and examples](Documentation~/TOOLS_V060.md#transform-tool-mcp2unity-extension).
Enable the specific permissions in the bridge window, then review local proposals through **Window > Wasim Development > Change Sets and Actions**. Approval and rollback are local actions, not public MCP endpoints. Review every proposed operation; Unity callbacks and project tests may execute project-defined code.
### Unity uGUI Phases 1–4
The following eight uGUI MCP tools are included in the catalog:
- `unity_create_canvas` — queue creation of a Canvas, CanvasScaler, GraphicRaycaster and optional EventSystem.
- `unity_create_ui` — queue Panel, Image, Button, legacy Text, TextMeshProUGUI, Slider, Toggle, InputField or ScrollView creation under an existing Canvas; each element uses RectTransform.
- `unity_set_rect_transform` — queue Anchor Min/Max, Pivot, Size Delta or Anchored Position edits.
- `unity_inspect_ui` — read a bounded uGUI hierarchy, including RectTransform, text, colors, button interactability and LayoutGroup details.
- `unity_set_ui_property` — submit reviewed edits of text, font size, graphic color, interactable, raycastTarget, Image fill and sprite asset reference.
- `unity_set_ui_layout` — submit reviewed Horizontal/Vertical/Grid LayoutGroup configuration including spacing, padding, cell size and column/row constraints.
- `unity_bind_button_event` — only binds a persistent Button.onClick → GameObject.SetActive(bool) targeting a UI object under the same Canvas; arbitrary event targets/methods are rejected.
- `unity_delete_gameobject` — propose deletion of a saved scene GameObject with exact-name confirmation, a maximum subtree size (≤100), Unity Undo, local approval, and scene-file backup. Prefab instances/assets are protected.
Write tools only propose locally reviewed changes, so the Unity Review window must approve them. No remote approval endpoint is added. Creation operations support aliases (including `$createdCanvas` and `$createdUi` for dedicated calls) and retain scene-backup rollback.
See [Unity uGUI MCP tools](Documentation~/UNITY_UI_TOOLS.md) for schemas and test scope. UI Toolkit/UXML, arbitrary runtime callback method bindings, and advanced Button events beyond allowlisted SetActive(bool) are **not supported**. All 73 Phase 1–3 EditMode tests passed in Unity 2022.3.62f3, and the direct Canvas/Panel/Button/Styling/Layout MCP integration test succeeded. Phase 4 adds 13 separate PlayMode tests of actual UI event dispatch and input behavior. All **13/13 PlayMode tests passed** through the reviewed Unity Test Runner action on 2026-11-10; PlayMode fixture tests do not by themselves demonstrate serialized MCP event persistence or clicks in every target game scene. The rollback guard correctly blocked an unsafe restore when scene files diverged; temporary UI was removed manually, and the original five root objects were verified.
### Phase 6 — security and recovery tests (verified)
`Tests/Editor/SafetyRecoveryIntegrationTests.cs` adds **12 new EditMode safety regressions** covering path constraints, stale/deferred scene write protection, deletion hierarchy guards, rollback divergence, and interrupted IPC request handling. **All 12/12 passed** on 2026-11-10 in Unity 2022.3.62f3, action `abef18ce2b4b`, run `4bfd294e-6c1e-48a6-9a34-839891d3c8bd` (4.28s; no failed, skipped or inconclusive tests). **Cumulative verified result: 108/108** automated tests (95 EditMode + 13 PlayMode). Live Phase 5 Hide/Show Game View clicks separately passed and are not included in this automated count.
### Phase 7 — final MCP contract suite (verified)
`Tests/Editor/FinalContractIntegrationTests.cs` adds **12 EditMode tests** for the 47-tool catalog, schema strictness and bounds, permission hints, stable read-only MCP responses, and invalid-input rejection. **All 12 Phase 7 tests PASSED** on 2026-11-10 using the refreshed UPM package and the corrected hierarchy test (action `5be3bb8c8c20`, run `58d6361f-d8ec-4086-a42c-fd66d9bd12ea`, 3.44s, zero failed/skipped/inconclusive). **Cumulative automated result: 120/120** (107 EditMode + 13 PlayMode). Unity Editor tests alone do not certify an end-to-end external MCP client, Windows companion process survival, ngrok reconnection or player builds.
### Windows Companion and ngrok transport validation (in progress)
The **120/120 Unity automated regression tests remain verified**. A separate short live ChatGPT-to-Unity read-only burst passed **12/12 MCP calls** (401–1096 ms per call, 626 ms mean) with stable Companion PID, ngrok reporting Ready, and an unchanged five-root gameplay scene. A reviewed Unity Editor script compile/domain reload was also verified (`27efd2959d84`): Editor.log confirms the reload and the running Companion retained PID 20996, ngrok reported `Ready`, and Unity IPC resumed. Those earlier domain-reload observations were separate from the later verified Windows public HTTPS and restart checks described below.
A targeted PowerShell reliability patch in `Companion~/wdmcp-companion.ps1` replaces the prior delete-then-move JSON writer with atomic `File.Replace`/`File.Move` and bounded retries. The **offline PowerShell function regression has now passed on Windows** (all reported assertions, including 18 held-reader JSON replacements, cleanup, JSON `null` and image responses, and heartbeat recovery). The `Tests~/test-companion-stability.ps1` local/ngrok/restart observer has now **passed live Windows execution** for a 12/12 local soak and a controlled Companion restart. The script never prints private endpoints or performs automatic restarts.
**Controlled Windows Companion restart now PASSED (2026-11-10):** 3/3 pre-restart local MCP handshakes, followed by direct local and public ngrok HTTPS JSON-RPC success (47 tools) after a user-initiated restart. Companion PID changed **24496 → 10260**; no status-file read recoveries occurred. Unity scene and console stayed clean. These results verify a controlled restart, **not** unattended crash or prolonged-network-outage recovery.
**Direct Windows transport soak now PASSED:** 12/12 local MCP handshakes (mean 290 ms, maximum 352 ms), actual public HTTPS ngrok MCP handshake (47 tools), and zero observed status-read recoveries/retries in that run. Prior transient status-file failures are documented; manual Companion restart/reconnect remains pending.
See [the Windows/ngrok stability validation plan](Documentation~/STABILITY_VALIDATION.md) for commands, manual approval points and acceptance criteria.
### Verification on your Windows workstation
Run the PowerShell regression tests from the package root:
```powershell
& '.\Tests~\test-companion-functions.ps1'
```
For Unity Edit Mode tests, add the **installed** package name to your test project's `Packages/manifest.json`:
```json
"testables": ["com.musafirex.mcp2unity"]
```
Then run **Window > General > Test Runner > EditMode > BridgeIntegrationTests** or:
```powershell
& '.\Tests~\run-unity-tests.ps1' -UnityEditor 'C:\Program Files\Unity\Hub\Editor\2022.3.22f1\Editor\Unity.exe' -ProjectPath 'C:\YourTestProject'
```
Tests require a disposable project with a backup. Also verify Console reading, script inspection, camera image transport, tracing, change-set rollback, compile/reload continuity, and ngrok reconnection using the actual Windows setup. VRChat behavior still needs testing in VRChat clients; Unity/ClientSim inspection is not authoritative network verification.
## Architecture
```text
MCP Client -> ngrok HTTPS -> PowerShell companion (v0.5.1 base)
|
Library/ file IPC
|
Unity Editor dispatcher
| |
21 legacy tools 17 modular tools
```
- No model API key is embedded.
- Editor-only assembly; no runtime/player build bridge.
- Paths and user-approved changes are restricted to the permitted project locations.
- Keep private capability URLs and ngrok tokens out of public Git commits and issue logs.
## Source and license
Original source: [wasim-development/wasim-unity-mcp-bridge v0.5.1](https://github.com/wasim-development/wasim-unity-mcp-bridge/tree/v0.5.1) (commit `9061958a372df692daf056ba03b5aff283b6d99d`). Feature reference: [v0.6.0](https://github.com/wasim-development/wasim-unity-mcp-bridge/tree/v0.6.0) (commit `bd4f758e7fde2a76c9b4c032e6882675b3e934df`). Original paths and Unity .meta GUIDs are preserved. The upstream restrictive LICENSE.md is retained: publication/redistribution requires permission from Wasim Development.
### Unity uGUI Phase 4 — PlayMode interaction tests (verified)
`Tests/PlayMode/WasimUnityMcpBridge.PlayMode.Tests.asmdef` and `UiRuntimePlayModeTests.cs` add **13 Unity PlayMode tests** for Button pointer clicks, `SetActive` callbacks, disabled Buttons, `GraphicRaycaster` hit tests, Slider value/range/whole-numbers and silent updates, Toggle pointer clicks and interactability, legacy InputField text/limits/callbacks, and ScrollRect normalized movement and drag. They use transient Canvas/EventSystem fixtures and destroy them after each test; no gameplay scene assets are saved. These tests exercise the Unity runtime interaction layer; the MCP-created hierarchy and persistent Button listener are separately checked by the 73 EditMode tests. A live end-to-end MCP UI PlayMode test is still recommended. **13/13 tests passed** on 2026-11-10 in Unity 2022.3.62f3 (reviewed action `f197a999ff82`, 0 failed/skipped/inconclusive); combined EditMode and PlayMode automated results are **86/86 passed**.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues