Skip to content

AGENTS.md

Latest commit

 

History

History
195 lines (166 loc) · 11.4 KB

AGENTS.md

File metadata and controls

195 lines (166 loc) · 11.4 KB
Raw

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).
  • Authentication token: Library/McpUnity/bridge-token (256-bit hex secret; never commit or copy into project settings).
  • Handshake security: clients authenticate as mcp-unity:<token> with HTTP Basic and must omit Origin; every supplied Origin is rejected.
  • 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

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.
    • AllowBatchModeServer (default false): permits a persistent MCP host in Unity -batchmode; package installation remains disabled in batch mode.
    • AllowRemoteConnections (default false): Unity binds to 0.0.0.0 when enabled; otherwise localhost.
    • AllowPackageInstallation (default false): permits add_package; keep disabled unless both client and package source are trusted.
    • EnableInfoLogs: Unity console logging verbosity.
    • NpmExecutablePath: optional npm path for Unity-driven install/build.

Node resolves bridge configuration in this order:

  • explicit environment values: UNITY_PORT, UNITY_HOST, UNITY_REQUEST_TIMEOUT;
  • MCP_UNITY_SETTINGS_PATH when set;
  • ProjectSettings/McpUnitySettings.json discovered above the installed Node module, then above the current working directory.

Node resolves authentication separately and fails closed in this order:

  • MCP_UNITY_AUTH_TOKEN;
  • the file named by MCP_UNITY_AUTH_TOKEN_PATH;
  • Library/McpUnity/bridge-token beside the discovered Unity project.

An explicitly configured missing, empty, or malformed token never falls back. Generated client configs set both MCP_UNITY_SETTINGS_PATH and MCP_UNITY_AUTH_TOKEN_PATH.

If no valid setting is 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.
  • Remote transport is plaintext ws://; restrict it to a trusted network, VPN, or SSH tunnel. Use MCP_UNITY_AUTH_TOKEN when the remote bridge cannot read the project token file.

Persistent headless host note:

  • Batch mode is disabled by default. Enable AllowBatchModeServer or launch Unity with MCP_UNITY_ALLOW_BATCH_MODE=true for a long-lived headless MCP host; npm installation/build remains skipped in batch mode.

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)
    • Node lockfile, MCP protocol metadata, dashboard metadata, and McpUnitySettings.ServerVersion
  • 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 (disabled by default; requires AllowPackageInstallation=true)
  • 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
  • get_play_mode_status — Get Unity play mode status (isPlaying, isPaused)
  • set_play_mode_status — Control Unity play mode (play, pause, stop, step)
  • 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 apps (current)

  • show_unity_dashboard — Open the Unity dashboard MCP App in VS Code

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
  • ui://unity-dashboard — Unity dashboard MCP App UI

Available prompts (current)

  • unity_dashboard — Opens Unity dashboard MCP app with guided information about features
  • gameobject_handling_strategy — Provides structured workflow for GameObject operations

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.
  • AGENTS.md is the single source of project guidance. Its sibling CLAUDE.md must contain the exact bytes @AGENTS.md\n; never duplicate these rules there.
  • If project skills are added, keep their content only in .agents/skills/<skill>/ and expose each to Claude Code through a relative .claude/skills/<skill> symlink targeting ../../.agents/skills/<skill>. Never use copied content or absolute links, so clones and worktrees remain self-contained.