a0287afbbc
* Add TDD tests for MCP material management issues - MCPMaterialTests.cs: Tests for material creation, assignment, and data reading - MCPParameterHandlingTests.cs: Tests for JSON parameter parsing issues - SphereMaterialWorkflowTests.cs: Tests for complete sphere material workflow These tests document the current issues with: - JSON parameter parsing in manage_asset and manage_gameobject tools - Material creation with properties - Material assignment to GameObjects - Material component data reading All tests currently fail (Red phase of TDD) and serve as specifications for what needs to be fixed in the MCP system. * Refine TDD tests to focus on actual MCP tool parameter parsing issues - Removed redundant tests that verify working functionality (GameObjectSerializer, Unity APIs) - Kept focused tests that document the real issue: MCP tool parameter validation - Tests now clearly identify the root cause: JSON string parsing in MCP tools - Tests specify exactly what needs to be fixed: parameter type flexibility The issue is NOT in Unity APIs or serialization (which work fine), but in MCP tool parameter validation being too strict. * Fix port discovery protocol mismatch - Update _try_probe_unity_mcp to recognize Unity bridge welcome message - Unity bridge sends 'WELCOME UNITY-MCP' instead of JSON pong response - Maintains backward compatibility with JSON pong format - Fixes MCP server connection to Unity Editor * Resolve merge: unify manage_gameobject param coercion and schema widening * Tests: add MaterialParameterToolTests; merge port probe fix; widen tool schemas for JSON-string params * refactor: extract JSON coercion helper; docs + exception narrowing\nfix: fail fast on bad component_properties JSON\ntest: unify setup, avoid test-to-test calls\nchore: use relative MCP package path * chore(tests): track MCPToolParameterTests.cs.meta to keep GUID stable * test: decouple MaterialParameterToolTests with helpers (no inter-test calls) |
||
|---|---|---|
| .. | ||
| Editor | ||
| Runtime | ||
| UnityMcpServer~/src | ||
| 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 server folder that contains
server.py(UnityMcpServer~/src). - Install Python and/or uv if missing.
- For Claude Code, ensure the
claudeCLI is installed.
- Select the server folder that contains
- 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”.
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 uv:
- Command: uv
- Args: run --directory server.py
- Manual Setup: Opens a window with a pre-filled JSON snippet to copy/paste into your client config.
- Choose
uvInstall Location: If uv isn’t on PATH, select the uv binary. - 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 uv:
- 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
- Enable “Show Debug Logs” in the header for more details in the Console when diagnosing issues.