4d969419d4
* Add server-side ping/pong heartbeat to detect dead WebSocket connections On Windows, WebSocket connections can die silently (OSError 64) without either side being notified. This causes commands to fail with "Unity session not available" until Unity eventually detects the dead connection. Changes: - Add PingMessage model for server->client pings - Add ping loop in PluginHub that sends pings every 10 seconds - Track last pong time per session; close connection if no pong within 20s - Include session_id in pong messages from Unity for server-side tracking - Clean up debug/timing logs from Issue #654 investigation The server will now proactively detect dead connections within 20 seconds instead of waiting indefinitely for the next command to fail. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Fix connection recovery after Unity domain reloads (#654) When Unity performs a domain reload (after script changes, test runs, or large payload transfers), the MCP connection drops and needs to reconnect. The previous reconnection timeout (2s) was too short for domain reloads which can take 10-30s. Changes: - Increase UNITY_MCP_RELOAD_MAX_WAIT_S default from 2s to 30s - Increase backoff cap when reloading from 0.8s to 5.0s - Skip PluginHub session resolution for stdio transport (was causing unnecessary waits on every command) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Fix ping/pong heartbeat, reduce timeout to 20s, fix test flakiness - Add server-side ping loop to detect dead WebSocket connections - Include session_id in pong messages for tracking - Reduce domain reload timeout from 30s to 20s - Add ClassVar annotations for mutable class attributes - Add lock protection for _last_pong access - Change debug stack trace log from Warn to Debug level - Remove unused TIMING-STDIO variable - Fix flaky async duration test (allow 20% timer variance) - Fix Python test that cleared HOME env var on Windows - Skip Unix-path test on Windows (path separator difference) - Add LogAssert.Expect to PropertyConversion tests Fixes #654, #643 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| 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 local
Serverfolder (dev only; usually not needed when using uvx). - 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.