# arodoid/unitymcp architecture

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

- Interactive diagram: https://gitdiagram.com/arodoid/unitymcp
- Repository: https://github.com/arodoid/unitymcp

## Overview

##### Main Components
- Unity Plugin (UnityMCPPlugin):
- Represents the Unity Editor integration, which includes:
- A Debug window (accessible through Unity’s top menu)
- A WebSocket client to establish real-time communication with the server
- A command execution engine to run C# code in the editor context
- Editor state tracking and logging components
- MCP Server (unity-mcp-server):
- A TypeScript-based backend exposing a set of tools:
- get_editor_state, execute_editor_command, and get_logs functionalities
- WebSocket server listening (default port 8080), receiving, processing, and responding to commands
- Additional support features like error and timeout management

##### Relationships and Interactions
- The Unity plugin acts as a client connecting to the MCP Server via WebSocket.
- The data flow is bidirectional:
- Outbound: The plugin sends real-time status, log messages, and command execution requests to the server.
- Inbound: The server provides data responses (like editor state, command confirmations, or error logs) back to the plugin.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Frontend (Unity plugin) and backend (MCP server) are clearly separated.
- Real-Time Communication: Leverages WebSockets for low latency, bidirectional data transfers.
- Modular and Extensible Design: The server is built with TypeScript (and includes a Dockerfile, package configuration, TypeScript config, etc.), suggesting that maintainability and ease of updates are vital.
- Command Execution and Error Handling: The system has built-in measures (such as command timeout, logging, error handling) to ensure robust interactions.

##### Technologies, Frameworks, or Libraries
- Unity & C#: The plugin uses Unity Editor’s API (UnityEngine, UnityEditor) for real-time state monitoring and command execution.
- TypeScript & Node.js: The MCP server is built in TypeScript running on Node.js (with an accompanying Dockerfile for deployment, which suggests containerization is supported).
- WebSockets: The communication between the plugin and server is established over WebSocket on port 8080.
- JSON: The standard format for message exchange.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Unity Plugin Subgraph
    subgraph "Unity Plugin (UnityMCPPlugin)"
        direction TB
        DebugWindow["Debug Window (Unity Editor)"]:::unity
        WebSocketClient["WebSocket Client & Command Execution"]:::unity
        EditorState["Editor State Tracking & Logging"]:::unity
        PluginManifest["Manifest Configuration"]:::config
        PluginPackage["Package Configuration"]:::config
    end

    %% MCP Server Subgraph
    subgraph "MCP Server (unity-mcp-server)"
        direction TB
        ServerWebSocket["WebSocket Server (Port 8080)"]:::server
        ServerCore["Core Tools (get_editor_state,execute_editor_command,get_logs)"]:::server
        ServerError["Security & Error Handling"]:::server
        subgraph "Deployment & Build Tools"
            direction TB
            ServerDockerfile["Dockerfile"]:::deploy
            ServerPkg["Package Configuration"]:::deploy
            ServerTsconfig["TypeScript Config"]:::deploy
        end
    end

    %% Internal Unity Plugin Connections
    DebugWindow -->|"sends commands"| WebSocketClient
    EditorState -->|"sends status/logs"| WebSocketClient

    %% Unity Plugin Config Integration (informational)
    PluginManifest --- PluginPackage

    %% Internal MCP Server Connections
    ServerWebSocket -->|"routes requests"| ServerCore
    ServerCore -->|"handles errors"| ServerError

    %% Cross-communication between Unity Plugin and MCP Server over WebSocket
    WebSocketClient <-->|"WebSocket(JSON)"| ServerWebSocket

    %% Click Events for Unity Plugin Components
    click DebugWindow "https://github.com/arodoid/unitymcp/blob/main/UnityMCPPlugin/Editor/UnityMCPWindow.cs"
    click WebSocketClient "https://github.com/arodoid/unitymcp/blob/main/UnityMCPPlugin/Editor/UnityMCPConnection.cs"
    click PluginManifest "https://github.com/arodoid/unitymcp/blob/main/UnityMCPPlugin/manifest.json"
    click PluginPackage "https://github.com/arodoid/unitymcp/blob/main/UnityMCPPlugin/package.json"

    %% Click Events for MCP Server Components
    click ServerCore "https://github.com/arodoid/unitymcp/blob/main/unity-mcp-server/src/index.ts"
    click ServerDockerfile "https://github.com/arodoid/unitymcp/tree/main/unity-mcp-server/Dockerfile"
    click ServerPkg "https://github.com/arodoid/unitymcp/blob/main/unity-mcp-server/package.json"
    click ServerTsconfig "https://github.com/arodoid/unitymcp/blob/main/unity-mcp-server/tsconfig.json"

    %% Styles
    classDef unity fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef server fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef deploy fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
