# codergamester/mcp-unity architecture

> Architecture diagram of the GitHub repository codergamester/mcp-unity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codergamester/mcp-unity
- Repository: https://github.com/codergamester/mcp-unity

## Overview

##### Main Components
- Editor Component:
- This folder (Editor/) contains all Unity Editor-specific code.
- Subcomponents include:
▪ Resources (e.g., GetAssetsResource, GetConsoleLogsResource, GetGameObjectResource, etc.) that provide Unity’s data.
▪ Tools (e.g., AddAssetToSceneTool, AddPackageTool, RunTestsTool, etc.) that perform actions in the editor.
▪ UnityBridge that establishes communication channels between Unity and the server.
▪ Services (e.g., TestRunnerService) supporting backend interactions.
▪ Utility classes for configuration and workspace (McpConfigUtils, VsCodeWorkspaceUtils).

- Server Component:
- The Server/ directory houses the Node.js backend.
- Contains:
▪ src folder with TypeScript sources for resources and tools mirroring the Editor functionality.
▪ Build folder with compiled JavaScript and type definitions.
▪ Package management artifacts (package.json) and Docker configuration for container deployment.
▪ Utility modules for error handling and logging.

- External AI/LLM Clients:
- Represented by connected AI coding assistants (Claude, Windsurf, Cursor) that interact via the WebSocket.

- Communication Infrastructure:
- WebSocket Server that facilitates real-time, bidirectional communications between the Editor and Node.js Server.
- Environment configuration (e.g., UNITY_PORT) helps establish the proper ports and settings.

##### Relationships and Interactions
- The Unity Editor component (with its Tools, Resources, Services, and UnityBridge) communicates via a WebSocket to the Node.js server.
- The Node.js Server acts as the central MCP server, handling incoming commands (e.g., execute_menu_item, select_gameobject):
- It processes these requests (using resources and tools modules) and may perform operations back in the Unity Editor.
- External AI clients connect to the Node.js server, sending instructions that are translated into actions within Unity.
- Integration with IDEs (like VSCode) is enabled via configuration and package cache access.

##### Architectural Patterns and Technologies
- The separation of concerns is clear: Unity Editor (client-side functionality) and Node.js Server (backend communication layer) form a loosely coupled, distributed architecture.
- The design employs a bridge pattern (visible in the UnityBridge module) to interact between Unity’s internal APIs and the external MCP protocol.
- Technologies include Unity Editor’s C# environment and Node.js with TypeScript.
- Communication patterns rely on real-time WebSocket data flows.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Unity Editor (Client) Components
    subgraph "Unity Editor (Client)"
        UE_Resources["Resources"]:::editor
        UE_Tools["Tools"]:::editor
        UE_Services["Services"]:::editor
        UE_UnityBridge["UnityBridge"]:::editor
        UE_Utils["Utils"]:::editor
    end

    %% Node.js MCP Server Components
    subgraph "Node.js MCP Server"
        NS_Source["Source Code"]:::server
        NS_WebSocket["MCP WebSocket Endpoint"]:::server
        NS_Build["Build Artifacts"]:::server
        NS_Config["Config & Deployment"]:::server
    end

    %% External AI Clients
    subgraph "External AI Clients"
        AI_Claude["Claude"]:::external
        AI_Windsurf["Windsurf"]:::external
        AI_Cursor["Cursor"]:::external
    end

    %% Communication Infrastructure
    WS["WebSocket Channel"]:::ws

    %% Connections between components
    AI_Claude -->|"send_command"| NS_Source
    AI_Windsurf -->|"send_command"| NS_Source
    AI_Cursor -->|"send_command"| NS_Source

    UE_UnityBridge <-->|"WS_comm"| WS
    WS -->|"WS_link"| NS_WebSocket
    NS_WebSocket -->|"process_cmd"| NS_Source

    %% Internal Unity Editor interactions
    UE_Resources -->|"provides_data"| UE_UnityBridge
    UE_Tools -->|"triggers_actions"| UE_UnityBridge
    UE_Services -->|"supports"| UE_UnityBridge

    %% Internal Server interactions
    NS_Source -->|"executes_logic"| NS_Build
    NS_Source -->|"reads_settings"| NS_Config

    %% Click Events for Unity Editor
    click UE_Resources "https://github.com/codergamester/mcp-unity/tree/main/Editor/Resources"
    click UE_Tools "https://github.com/codergamester/mcp-unity/tree/main/Editor/Tools"
    click UE_UnityBridge "https://github.com/codergamester/mcp-unity/tree/main/Editor/UnityBridge"
    click UE_Services "https://github.com/codergamester/mcp-unity/tree/main/Editor/Services"
    click UE_Utils "https://github.com/codergamester/mcp-unity/tree/main/Editor/Utils"
    
    %% Click Events for Node.js MCP Server
    click NS_Source "https://github.com/codergamester/mcp-unity/tree/main/Server/src"
    click NS_Build "https://github.com/codergamester/mcp-unity/tree/main/Server/build"
    click NS_Config "https://github.com/codergamester/mcp-unity/blob/main/Server/package.json"
    click NS_WebSocket "https://github.com/codergamester/mcp-unity/blob/main/Server/src/unity/mcpUnity.ts"
    
    %% Click Event for WebSocket Handler in Unity Editor
    click WS "https://github.com/codergamester/mcp-unity/blob/main/Editor/UnityBridge/McpUnitySocketHandler.cs"

    %% Styles
    classDef editor fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef server fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef ws fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
```
