PHXH
/
unity-mcp
51
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
unity-mcp/MCPForUnity
History
dsarno 711768d064
Async Test Infrastructure & Editor Readiness Status + new refresh_unity tool (#507) 
* Add editor readiness v2, refresh tool, and preflight guards

* Detect external package changes and harden refresh retry

* feat: add TestRunnerNoThrottle and async test running with background stall prevention

- Add TestRunnerNoThrottle.cs: Sets editor to 'No Throttling' mode during test runs
  with SessionState persistence across domain reload
- Add run_tests_async and get_test_job tools for non-blocking test execution
- Add TestJobManager for async test job tracking with progress monitoring
- Add ForceSynchronousImport to all AssetDatabase.Refresh() calls to prevent stalls
- Mark DomainReloadResilienceTests as [Explicit] with documentation explaining
  the test infrastructure limitation (internal coroutine waits vs MCP socket polling)
- MCP workflow is unaffected - socket messages provide external stimulus that
  keeps Unity responsive even when backgrounded

* refactor: simplify and clean up code

- Remove unused Newtonsoft.Json.Linq import from TestJobManager
- Add throttling to SessionState persistence (once per second) to reduce overhead
- Critical job state changes (start/finish) still persist immediately
- Fix duplicate XML summary tag in DomainReloadResilienceTests

* docs: add async test tools to README, document domain reload limitation

- Add run_tests_async and get_test_job to main README tools list
- Document background stall limitation for domain reload tests in DEV readme

* ci: add separate job for domain reload tests

Run [Explicit] domain_reload tests in their own job using -testCategory

* ci: run domain reload tests in same job as regular tests

Combines into single job with two test steps to reuse cached Library

* fix: address coderabbit review issues

- Fix TOCTOU race in TestJobManager.StartJob (single lock scope for check-and-set)
- Store TestRunnerApi reference with HideAndDontSave to prevent GC/serialization issues

* docs: update tool descriptions to prefer run_tests_async

- run_tests_async is now marked as preferred for long-running suites
- run_tests description notes it blocks and suggests async alternative

* docs: update README screenshot to v8.6 UI

* docs: add v8.6 UI screenshot

* Update README for MCP version and instructions for v8.7

* fix: handle preflight busy signals and derive job status from test results

- manage_asset, manage_gameobject, manage_scene now check preflight return
  value and propagate busy/retry signals to clients (fixes Sourcery #1)
- TestJobManager.FinalizeCurrentJobFromRunFinished now sets job status to
  Failed when resultPayload.Failed > 0, not always Succeeded (fixes Sourcery #2)

* fix: increase HTTP server startup timeout for dev mode

When 'Force fresh server install' is enabled, uvx uses --no-cache --refresh
which rebuilds the package and takes significantly longer to start.

- Increase timeout from 10s to 45s when dev mode is enabled
- Add informative log message explaining the longer startup time
- Show actual timeout value in warning message

* fix: derive job status from test results in FinalizeFromTask fallback

Apply same logic as FinalizeCurrentJobFromRunFinished: check result.Failed > 0
to correctly mark jobs as Failed when tests fail, even in the fallback path
when RunFinished callback is not delivered.
 		2026-01-03 12:42:32 -08:00
..
Editor Async Test Infrastructure & Editor Readiness Status + new refresh_unity tool (#507) 2026-01-03 12:42:32 -08:00
Runtime Test/478 matrix4x4 serialization crash (#481) 2025-12-23 15:53:14 -08:00
Editor.meta Rename plugin folder to MCPForUnity (#303) 2025-10-03 20:23:28 -04:00
README.md HTTP Server, uvx, C# only custom tools (#375) 2025-11-24 23:21:06 -04:00
README.md.meta Rename plugin folder to MCPForUnity (#303) 2025-10-03 20:23:28 -04:00
Runtime.meta Rename plugin folder to MCPForUnity (#303) 2025-10-03 20:23:28 -04:00
package.json chore: bump version to 8.6.0 2026-01-02 05:53:04 +00:00
package.json.meta Add .meta files (#472) 2025-12-19 18:59:19 -04:00

README.md

MCP for Unity — Editor Plugin Guide

Use this guide to configure and run MCP for Unity inside the Unity Editor. Installation is covered elsewhere; this document focuses on the Editor window, client configuration, and troubleshooting.

Open the window

  • Unity menu: Window > MCP for Unity

The window has four areas: Server Status, Unity Bridge, MCP Client Configuration, and Script Validation.

Quick start

  1. Open Window > MCP for Unity.
  2. Click “Auto-Setup”.
  3. If prompted:
    • Select the packaged server folder (Server) if you want to run the bundled implementation.
    • Install Python and/or uv/uvx if missing so the server can be managed locally.
    • For Claude Code, ensure the claude CLI is installed.
  4. Click “Start Bridge” if the Unity Bridge shows “Stopped”.
  5. Use your MCP client (Cursor, VS Code, Windsurf, Claude Code) to connect.

Server Status

  • Status dot and label:
    • Installed / Installed (Embedded) / Not Installed.
  • Mode and ports:
    • Mode: Auto or Standard.
    • Ports: Unity (varies; shown in UI), MCP 6500.
  • Actions:
    • Auto-Setup: Registers/updates your selected MCP client(s), ensures bridge connectivity. Shows “Connected ✓” after success.
    • Rebuild MCP Server: Rebuilds the Python based MCP server
    • Select server folder…: Choose the folder containing server.py.
    • Verify again: Re-checks server presence.
    • If Python isn’t detected, use “Open Install Instructions”.
  • HTTP Server Command foldout:
    • Expands to display the exact uvx command Unity will run.
    • Includes a copy button and the “Start Local HTTP Server” action so you can launch or reuse the command elsewhere.

Unity Bridge

  • Shows Running or Stopped with a status dot.
  • Start/Stop Bridge button toggles the Unity bridge process used by MCP clients to talk to Unity.
  • Tip: After Auto-Setup, the bridge may auto-start in Auto mode.

MCP Client Configuration

  • Select Client: Choose your target MCP client (e.g., Cursor, VS Code, Windsurf, Claude Code).
  • Per-client actions:
    • Cursor / VS Code / Windsurf:
      • Auto Configure: Writes/updates your config to launch the server via uvx with the current package version:
        • Command: uvx (or your overridden path)
        • Args: --from mcp-for-unity
      • Manual Setup: Opens a window with a pre-filled JSON snippet to copy/paste into your client config.
      • Choose UV Install Location: If uv/uvx isn’t on PATH, select the executable.
      • A compact “Config:” line shows the resolved config file name once uv/server are detected.
    • Claude Code:
      • Register with Claude Code / Unregister MCP for Unity with Claude Code.
      • If the CLI isn’t found, click “Choose Claude Install Location”.
      • The window displays the resolved Claude CLI path when detected.

Notes:

  • The UI shows a status dot and a short status text (e.g., “Configured”, “uv Not Found”, “Claude Not Found”).
  • Use “Auto Configure” for one-click setup; use “Manual Setup” when you prefer to review/copy config.

Script Validation

  • Validation Level options:
    • Basic — Only syntax checks
    • Standard — Syntax + Unity practices
    • Comprehensive — All checks + semantic analysis
    • Strict — Full semantic validation (requires Roslyn)
  • Pick a level based on your project’s needs. A description is shown under the dropdown.

Troubleshooting

Tips

  • Use Cmd+Shift+M (macOS) / Ctrl+Shift+M (Windows, Linux) to toggle the MCP for Unity window.
  • Enable “Show Debug Logs” in the header for more details in the Console when diagnosing issues.