PHXH
/
unity-mcp
51
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
unity-mcp/MCPForUnity
History
dsarno 075d68dba3
Material tools: support direct shader property keys + add EditMode coverage (#344) 
* 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

* feat(material): support direct shader property keys and texture paths; add EditMode tests

* chore(tests): track required .meta files; remove ephemeral Assets/Editor test helper

* fix(manage_gameobject): validate parsed component_properties is a dict; return clear error
 		2025-10-23 18:25:29 -07:00
..
Editor Material tools: support direct shader property keys + add EditMode coverage (#344) 2025-10-23 18:25:29 -07:00
Runtime Rename plugin folder to MCPForUnity (#303) 2025-10-03 20:23:28 -04:00
UnityMcpServer~/src Material tools: support direct shader property keys + add EditMode coverage (#344) 2025-10-23 18:25:29 -07:00
Editor.meta Rename plugin folder to MCPForUnity (#303) 2025-10-03 20:23:28 -04:00
README.md Rename plugin folder to MCPForUnity (#303) 2025-10-03 20:23:28 -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 6.2.4 2025-10-23 01:43:22 +00:00
package.json.meta Rename plugin folder to MCPForUnity (#303) 2025-10-03 20:23:28 -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 server folder that contains server.py (UnityMcpServer~/src).
    • Install Python and/or uv if missing.
    • 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”.

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 uv Install 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.
    • 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

  • Enable “Show Debug Logs” in the header for more details in the Console when diagnosing issues.