com.gamelovers.mcp-unity

Imported from kevcoutellier/T-VIR-902-Journey-Through-XR (STOP-IT/Packages/com.gamelovers.mcp-unity/AGENTS.md). Install upstream with npx skills add kevcoutellier/T-VIR-902-Journey-Through-XR --skill com.gamelovers.mcp-unity. Copyright stays with the author.

MCP Unity — AI Agent Guide (MCP Package)

Purpose (what this repo is)

MCP Unity exposes Unity Editor capabilities to MCP-enabled clients by running:

• Unity-side “client” (C# Editor scripts): a WebSocket server inside the Unity Editor that executes tools/resources.
• Node-side “server” (TypeScript): an MCP stdio server that registers MCP tools/resources and forwards requests to Unity over WebSocket.

How it works (high-level data flow)

• MCP client ⇄ (stdio / MCP SDK) ⇄ Node server (Server~/src/index.ts)
• Node server ⇄ (WebSocket JSON-RPC-ish) ⇄ Unity Editor (Editor/UnityBridge/McpUnityServer.cs + McpUnitySocketHandler.cs)
• Tool/Resource names must match exactly across Node and Unity (typically lower_snake_case).

Key defaults & invariants

• Unity WebSocket endpoint: ws://localhost:8090/McpUnity by default.
• Config file: ProjectSettings/McpUnitySettings.json (written/read by Unity; read opportunistically by Node).
• Execution thread: Tool/resource execution is dispatched via EditorCoroutineUtility and runs on the Unity main thread. Keep synchronous work short; use async patterns for long work.

Repo layout (where to change what)

/
├── Editor/                       # Unity Editor package code (C#)
│   ├── Tools/                    # Tools (inherit McpToolBase)
│   ├── Resources/                # Resources (inherit McpResourceBase)
│   ├── UnityBridge/              # WebSocket server + message routing
│   ├── Services/                 # Test/log services used by tools/resources
│   └── Utils/                    # Shared helpers (config, logging, workspace integration)
├── Server~/                      # Node MCP server (TypeScript, ESM)
│   ├── src/index.ts              # Registers tools/resources/prompts with MCP SDK
│   ├── src/tools/                # MCP tool definitions (zod schema + handler)
│   ├── src/resources/            # MCP resource definitions
│   └── src/unity/mcpUnity.ts      # WebSocket client that talks to Unity
└── server.json                   # MCP registry metadata (name/version/package)

Quickstart (local dev)

• Unity side

  • Open the Unity project that has this package installed.
  • Ensure the server is running (auto-start is controlled by McpUnitySettings.AutoStartServer).
  • Settings persist in ProjectSettings/McpUnitySettings.json.

• Node side (build)

  • cd Server~ && npm run build
  • The MCP entrypoint is Server~/build/index.js (published as an MCP stdio server).

• Node side (debug/inspect)

  • cd Server~ && npm run inspector to use the MCP Inspector.

Configuration (Unity ↔ Node bridge)

The Unity settings file is the shared contract:

• Path: ProjectSettings/McpUnitySettings.json
• Fields
  • Port (default 8090): Unity WebSocket server port.
  • RequestTimeoutSeconds (default 10): Node request timeout (Node reads this if the settings file is discoverable).
  • AllowRemoteConnections (default false): Unity binds to 0.0.0.0 when enabled; otherwise localhost.
  • EnableInfoLogs: Unity console logging verbosity.
  • NpmExecutablePath: optional npm path for Unity-driven install/build.

Node reads config from ../ProjectSettings/McpUnitySettings.json relative to its current working directory. If not found, Node falls back to:

• host: localhost
• port: 8090
• timeout: 10s

Remote connection note:

• If Unity is on another machine, set AllowRemoteConnections=true in Unity and set UNITY_HOST=<unity_machine_ip_or_hostname> for the Node process.

Adding a new capability

Add a tool

1. Unity (C#)

   • Add Editor/Tools/<YourTool>Tool.cs inheriting McpToolBase.
   • Set Name to the MCP tool name (recommended: lower_snake_case).
   • Implement:
     • Execute(JObject parameters) for synchronous work, or
     • set IsAsync = true and implement ExecuteAsync(JObject parameters, TaskCompletionSource<JObject> tcs) for long-running operations.
   • Register it in Editor/UnityBridge/McpUnityServer.cs (RegisterTools()).

2. Node (TypeScript)

   • Add Server~/src/tools/<yourTool>Tool.ts.
   • Register the tool in Server~/src/index.ts.
   • Use a zod schema for params; forward to Unity using the same method string:
     • mcpUnity.sendRequest({ method: toolName, params: {...} })

3. Build

   • cd Server~ && npm run build

Add a resource

1. Unity (C#)

   • Add Editor/Resources/<YourResource>Resource.cs inheriting McpResourceBase.
   • Set Name (method string) and Uri (e.g. unity://...).
   • Implement Fetch(...) or FetchAsync(...).
   • Register in Editor/UnityBridge/McpUnityServer.cs (RegisterResources()).

2. Node (TypeScript)

   • Add Server~/src/resources/<yourResource>.ts, register in Server~/src/index.ts.
   • Forward to Unity via mcpUnity.sendRequest({ method: resourceName, params: {} }).

Logging & debugging

• Unity

  • Uses McpUnity.Utils.McpLogger (info logs gated by EnableInfoLogs).
  • Connection lifecycle is managed in Editor/UnityBridge/McpUnityServer.cs (domain reload & playmode transitions stop/restart the server).

• Node

  • Logging is controlled by env vars:
    • LOGGING=true enables console logging.
    • LOGGING_FILE=true writes log.txt in the Node process working directory.

Common pitfalls

• Port mismatch: Unity default is 8090; update docs/config if you change it.
• Name mismatch: Node toolName/resourceName must equal Unity Name exactly, or Unity responds unknown_method.
• Long main-thread work: synchronous Execute() blocks the Unity editor; use async patterns for heavy operations.
• Remote connections: Unity must bind 0.0.0.0 (AllowRemoteConnections=true) and Node must target the correct host (UNITY_HOST).
• Unity domain reload: the server stops during script reloads and may restart; avoid relying on persistent in-memory state across reloads.
• Multiplayer Play Mode: Clone instances automatically skip server startup; only the main editor hosts the MCP server.
• Schema compatibility across clients: avoid reusing the same nested Zod object instance for multiple sibling fields (for example position, rotation, scale). Some MCP clients fail on local refs like #/properties/position; prefer creating a fresh nested schema per field.

Release/version bump checklist

• Update versions consistently:
  • Unity package package.json (version)
  • Node server Server~/package.json (version)
  • MCP registry server.json (version + npm identifier/version)
• Rebuild Node output: cd Server~ && npm run build

Available tools (current)

• execute_menu_item — Execute Unity menu items
• select_gameobject — Select GameObjects in hierarchy
• update_gameobject — Update or create GameObject properties
• update_component — Update or add components on GameObjects
• add_package — Install packages via Package Manager
• run_tests — Run Unity Test Runner tests
• send_console_log — Send logs to Unity console
• add_asset_to_scene — Add assets to scene
• create_prefab — Create prefabs with optional scripts
• create_scene — Create and save new scenes
• load_scene — Load scenes (single or additive)
• delete_scene — Delete scenes and remove from Build Settings
• save_scene — Save current scene (with optional Save As)
• get_scene_info — Get active scene info and loaded scenes list
• unload_scene — Unload scene from hierarchy
• get_gameobject — Get detailed GameObject info
• get_console_logs — Retrieve Unity console logs
• recompile_scripts — Recompile all project scripts
• duplicate_gameobject — Duplicate GameObjects with optional rename/reparent
• delete_gameobject — Delete GameObjects from scene
• reparent_gameobject — Change GameObject parent in hierarchy
• create_material — Create materials with specified shader
• assign_material — Assign materials to Renderer components
• modify_material — Modify material properties (colors, floats, textures)
• get_material_info — Get material details including all properties

Available resources (current)

• unity://menu-items — List of available menu items
• unity://scenes-hierarchy — Current scene hierarchy
• unity://gameobject/{id} — GameObject details by ID or path
• unity://logs — Unity console logs
• unity://packages — Installed and available packages
• unity://assets — Asset database information
• unity://tests/{testMode} — Test Runner test information

Update policy (for agents)

• Update this file when:
  • tools/resources/prompts are added/removed/renamed,
  • config shape or default ports/paths change,
  • the bridge protocol changes (request/response contract).
• Keep it high-signal: where to edit code, how to run/build/debug, and the invariants that prevent subtle breakage.