c2a6b0ac7a
* Avoid blocking Claude CLI status checks on focus
* Fix Claude Code registration to remove existing server before re-registering
When registering with Claude Code, if a UnityMCP server already exists,
remove it first before adding the new registration. This ensures the
transport mode (HTTP vs stdio) is always updated to match the current
UseHttpTransport EditorPref setting.
Previously, if a stdio registration existed and the user tried to register
with HTTP, the command would fail with 'already exists' and the old stdio
configuration would remain unchanged.
* Fix Claude Code transport validation to parse CLI output format correctly
The validation code was incorrectly parsing the output of 'claude mcp get UnityMCP' by looking for JSON format ("transport": "http"), but the CLI actually returns human-readable text format ("Type: http"). This caused the transport mismatch detection to never trigger, allowing stdio to be selected in the UI while HTTP was registered with Claude Code.
Changes:
- Fix parsing logic to check for "Type: http" or "Type: stdio" in CLI output
- Add OnTransportChanged event to refresh client status when transport changes
- Wire up event handler to trigger client status refresh on transport dropdown change
This ensures that when the transport mode in Unity doesn't match what's registered with Claude Code, the UI will correctly show an error status with instructions to re-register.
* Fix Claude Code registration UI blocking and thread safety issues
This commit resolves three issues with Claude Code registration:
1. UI blocking: Removed synchronous CheckStatus() call after registration
that was blocking the editor. Status is now set immediately with async
verification happening in the background.
2. Thread safety: Fixed "can only be called from the main thread" errors
by capturing Application.dataPath and EditorPrefs.GetBool() on the main
thread before spawning async status check tasks.
3. Transport mismatch detection: Transport mode changes now trigger immediate
status checks to detect HTTP/stdio mismatches, instead of waiting for the
45-second refresh interval.
The registration button now turns green immediately after successful
registration without blocking, and properly detects transport mismatches
when switching between HTTP and stdio modes.
* Enforce thread safety for Claude Code status checks at compile time
Address code review feedback by making CheckStatusWithProjectDir thread-safe
by design rather than by convention:
1. Made projectDir and useHttpTransport parameters non-nullable to prevent
accidental background thread calls without captured values
2. Removed nullable fallback to EditorPrefs.GetBool() which would cause
thread safety violations if called from background threads
3. Added ArgumentNullException for null projectDir instead of falling back
to Application.dataPath (which is main-thread only)
4. Added XML documentation clearly stating threading contracts:
- CheckStatus() must be called from main thread
- CheckStatusWithProjectDir() is safe for background threads
5. Removed unreachable else branch in async status check code
These changes make it impossible to misuse the API from background threads,
with compile-time enforcement instead of runtime errors.
* Consolidate local HTTP Start/Stop and auto-start session
* HTTP improvements: Unity-owned server lifecycle + UI polish
* Deterministic HTTP stop via pidfile+token; spawn server in terminal
* Fix review feedback: token validation, host normalization, safer casts
* Fix stop heuristics edge cases; remove dead pid capture
* Fix unity substring guard in stop heuristics
* Fix local server cleanup and connection checks
* Fix read_console default limits; cleanup Unity-managed server vestiges
* Fix unfocused reconnect stalls; fast-fail retryable Unity commands
* Simplify PluginHub reload handling; honor run_tests timeout
* Fix Windows Claude CLI status check threading
|
||
|---|---|---|
| .. | ||
| Editor | ||
| Runtime | ||
| Editor.meta | ||
| README.md | ||
| README.md.meta | ||
| Runtime.meta | ||
| package.json | ||
| package.json.meta | ||
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
- Open Window > MCP for Unity.
- Click “Auto-Setup”.
- 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
claudeCLI is installed.
- Select the packaged server folder (
- Click “Start Bridge” if the Unity Bridge shows “Stopped”.
- 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
uvxcommand Unity will run. - Includes a copy button and the “Start Local HTTP Server” action so you can launch or reuse the command elsewhere.
- Expands to display the exact
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
uvxwith 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.
- Auto Configure: Writes/updates your config to launch the server via
- 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.
- Cursor / VS Code / Windsurf:
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
- Python or
uvnot found: - Claude CLI not found:
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.