Relevant source files

The following files were used as context for generating this wiki page: - [Packages/src/Editor/Server/McpServerController.cs](https://github.com/hatayama/uLoopMCP/blob/main/Packages/src/Editor/Server/McpServerController.cs) - [Packages/src/Editor/Api/McpTools/Core/UnityToolRegistry.cs](https://github.com/hatayama/uLoopMCP/blob/main/Packages/src/Editor/Api/McpTools/Core/UnityToolRegistry.cs) - [Packages/src/Editor/Api/McpTools/Core/IUnityTool.cs](https://github.com/hatayama/uLoopMCP/blob/main/Packages/src/Editor/Api/McpTools/Core/IUnityTool.cs) - [Packages/src/Editor/Execution/CommandRunner.cs](https://github.com/hatayama/uLoopMCP/blob/main/Packages/src/Editor/Execution/CommandRunner.cs) - [Packages/src/Editor/UI/McpEditorWindow.cs](https://github.com/hatayama/uLoopMCP/blob/main/Packages/src/Editor/UI/McpEditorWindow.cs) - [Packages/src/ARCHITECTURE.md](https://github.com/hatayama/uLoopMCP/blob/main/Packages/src/ARCHITECTURE.md) - [Packages/src/README.md](https://github.com/hatayama/uLoopMCP/blob/main/Packages/src/README.md) - [Packages/src/Editor/Compilation/RoslynCompiler.cs](https://github.com/hatayama/uLoopMCP/blob/main/Packages/src/Editor/Compilation/RoslynCompiler.cs) - [Packages/src/Editor/Config/UnityMcpPathResolver.cs](https://github.com/hatayama/uLoopMCP/blob/main/Packages/src/Editor/Config/UnityMcpPathResolver.cs) - [Packages/src/TOOL_REFERENCE.md](https://github.com/hatayama/uLoopMCP/blob/main/Packages/src/TOOL_REFERENCE.md)

# Unity (C#) Backend Architecture The uLoopMCP Unity (C#) Backend is an integrated TCP server that runs within the Unity Editor. Its primary purpose is to expose Unity's core functionalities—such as compilation, testing, scene manipulation, and dynamic code execution—to external Model Context Protocol (MCP) clients, typically a TypeScript server that bridges communication with LLM-powered tools. This allows AI agents to programmatically control the Unity Editor, enabling autonomous development loops. The architecture is designed to be modular and extensible, centered around a "Tool" pattern. It features a robust security model to control access to sensitive Unity APIs, schema-driven communication for type safety, and session management resilient to domain reloads. The system is managed through a dedicated Editor window, which provides controls for server state, port configuration, and security settings. For more high-level context, see the [TypeScript Server Architecture](ARCHITECTURE_TypeScript.md). *Sources: [Packages/src/ARCHITECTURE.md](), [Packages/src/README.md]()* ## System Overview The Unity C# backend is one of the three main components of the uLoopMCP system. It communicates exclusively with the TypeScript server, which in turn communicates with MCP clients like Cursor or Claude Code. This diagram illustrates the high-level interaction between the system components. ```mermaid graph TD subgraph "MCP Clients" Claude[Claude Code, VSCode, etc.] end subgraph "TypeScript Server (Node.js)" TSServer[MCP Protocol Server] end subgraph "Unity Editor (C# Backend)" McpServerController[McpServerController
TCP Server] CommandRunner[CommandRunner] ToolRegistry[UnityToolRegistry] Tools[IUnityTool Implementations] Security[Security Layer] end Claude -.->|MCP Protocol (stdio)| TSServer TSServer -->|TCP/JSON-RPC| McpServerController McpServerController --> CommandRunner CommandRunner --> ToolRegistry CommandRunner --> Security Security --> Tools ToolRegistry --> Tools CommandRunner --> Tools classDef unity fill:#fff3e0,stroke:#e65100,stroke-width:2px class McpServerController,CommandRunner,ToolRegistry,Tools,Security unity ``` The communication flow is as follows: 1. The TypeScript server sends a JSON-RPC request to the Unity C# backend over a TCP socket. 2. The `McpServerController` receives the raw data. 3. The request is passed to the `CommandRunner` for processing. 4. The `CommandRunner` identifies the requested tool, validates it against security policies, and executes it. 5. The tool's response is serialized and sent back to the TypeScript server over the same TCP connection. *Sources: [Packages/src/ARCHITECTURE.md](), [Packages/src/Editor/Server/McpServerController.cs](), [Packages/src/Editor/Execution/CommandRunner.cs]()* ## Core Components The C# backend is composed of several key classes that manage the server lifecycle, UI, and command execution. | Component | Description | Source File | | :--- | :--- | :--- | | **`McpServerController`** | The central orchestrator. Manages the TCP server's lifecycle (start, stop, recovery after domain reload), handles client connections, and dispatches incoming requests. | `Editor/Server/McpServerController.cs` | | **`McpEditorWindow`** | Provides the GUI within the Unity Editor (`Window > uLoopMCP`) for managing the server, configuring settings (port, auto-start), and adjusting security levels. | `Editor/UI/McpEditorWindow.cs` | | **`CommandRunner`** | Receives parsed JSON-RPC requests, finds the corresponding tool via `UnityToolRegistry`, performs security checks, and executes the tool. | `Editor/Execution/CommandRunner.cs` | | **`UnityToolRegistry`** | Discovers and maintains a collection of all available tools (`IUnityTool` implementations) using reflection to find classes marked with the `[McpTool]` attribute. | `Editor/Api/McpTools/Core/UnityToolRegistry.cs` | | **`RoslynCompiler`** | Handles the `execute-dynamic-code` tool. It compiles and executes C# code snippets at runtime, subject to defined security levels. | `Editor/Compilation/RoslynCompiler.cs` | | **`UnityMcpPathResolver`** | A utility class responsible for resolving all necessary file paths, such as LLM tool configuration files (`mcp.json`) and the location of the TypeScript server bundle. | `Editor/Config/UnityMcpPathResolver.cs` | *Sources: [Packages/src/Editor/Server/McpServerController.cs](), [Packages/src/Editor/UI/McpEditorWindow.cs](), [Packages/src/Editor/Execution/CommandRunner.cs](), [Packages/src/Editor/Api/McpTools/Core/UnityToolRegistry.cs](), [Packages/src/Editor/Compilation/RoslynCompiler.cs](), [Packages/src/Editor/Config/UnityMcpPathResolver.cs]()* ## Tool System Architecture The extensibility of the C# backend is built on a "Tool" pattern. Every command exposed to the MCP client is an implementation of the `IUnityTool` interface. ### Tool Definition Tools are defined by implementing the `IUnityTool` interface, typically by inheriting from the generic `AbstractUnityTool` class. This provides a type-safe structure for defining parameters and responses. This class diagram shows the relationship between the core tool interfaces and a concrete implementation. ```mermaid classDiagram direction LR class IUnityTool { <> +string ToolName +Task~object~ ExecuteAsync(string, CancellationToken) } class AbstractUnityTool~TSchema, TResponse~ { <> +string ToolName #Task~TResponse~ ExecuteAsync(TSchema, CancellationToken) } class MyCustomTool { +string ToolName #Task~MyCustomResponse~ ExecuteAsync(MyCustomSchema, CancellationToken) } class UnityToolRegistry { +Dictionary~string, IUnityTool~ _tools +Initialize() +GetTool(string) IUnityTool } IUnityTool <|-- AbstractUnityTool AbstractUnityTool <|-- MyCustomTool UnityToolRegistry o-- "1..*" IUnityTool : manages ``` Key aspects of the tool system: - **`IUnityTool`**: The base interface for all tools, defining the `ToolName` and a generic `ExecuteAsync` method. - **`AbstractUnityTool`**: A base class that simplifies tool creation with strongly-typed, serializable schema and response classes. - **`[McpTool]` Attribute**: A class-level attribute that marks a class as a tool, allowing `UnityToolRegistry` to discover it automatically during startup. - **Execution on Main Thread**: All tools are executed on Unity's main thread, ensuring safe access to Unity APIs. *Sources: [Packages/src/Editor/Api/McpTools/Core/IUnityTool.cs](), [Packages/src/README.md](), [Packages/src/Editor/Api/McpTools/Core/UnityToolRegistry.cs]()* ### Creating a Custom Tool Developers can extend uLoopMCP by creating their own tools. This involves creating schema/response classes and a tool class that inherits from `AbstractUnityTool`. ```csharp // 1. Define parameters public class MyCustomSchema : BaseToolSchema { [Description("Parameter description")] public string MyParameter { get; set; } = "default_value"; } // 2. Define response public class MyCustomResponse : BaseToolResponse { public string Result { get; set; } } // 3. Implement the tool [McpTool(Description = "Description of my custom tool")] public class MyCustomTool : AbstractUnityTool { public override string ToolName => "my-custom-tool"; protected override Task ExecuteAsync(MyCustomSchema parameters, CancellationToken cancellationToken) { // Custom logic here... string result = $"Processed '{parameters.MyParameter}'"; return Task.FromResult(new MyCustomResponse { Result = result }); } } ``` *Sources: [Packages/src/README.md]()* ## Request Execution Flow When a command is sent from an MCP client, it follows a specific sequence within the Unity backend. This sequence diagram shows the lifecycle of a single tool execution request. ```mermaid sequenceDiagram participant TS as TypeScript Server participant TCP as McpServerController (TCP) participant Runner as CommandRunner participant Registry as UnityToolRegistry participant Security as McpSecurityChecker participant Tool as IUnityTool TS->>TCP: Sends JSON-RPC Request TCP->>Runner: HandleRequest(request) Runner->>Registry: GetTool(methodName) Registry-->>Runner: Returns IUnityTool instance Runner->>Security: Validate(tool) Security-->>Runner: Validation Result (Allowed) Runner->>Tool: ExecuteAsync(params) Note right of Tool: Tool executes on Unity's main thread Tool-->>Runner: Returns Task~object~ Runner-->>TCP: Returns JSON-RPC Response TCP-->>TS: Sends Response ``` *Sources: [Packages/src/Editor/Server/McpServerController.cs](), [Packages/src/Editor/Execution/CommandRunner.cs](), [Packages/src/Editor/Api/McpTools/Core/UnityToolRegistry.cs]()* ## Security Architecture Security is a critical aspect, especially for tools like `execute-dynamic-code` that can perform powerful operations. The security model is managed via the **McpEditorWindow** and settings are persisted in `McpEditorSettings`. ### General Tool Security The following tools can be enabled or disabled: - **Allow Tests Execution**: Enables the `run-tests` tool. - **Allow Menu Item Execution**: Enables the `execute-menu-item` tool. - **Allow Third Party Tools**: Enables custom tools developed for a specific project. *Sources: [Packages/src/README.md](), [Packages/src/Editor/UI/McpEditorWindow.cs]()* ### Dynamic Code Execution Security The `execute-dynamic-code` tool has a three-tier security model, implemented by the `RoslynCompiler` and its internal `SecurityValidator`. | Level | Name | Description | | :--- | :--- | :--- | | **0** | **Disabled** | No compilation or execution is allowed. This is the safest setting. | | **1**| **Restricted** | **(Recommended)** Allows use of most Unity APIs and standard libraries but blocks security-critical operations like file deletion (`File.Delete`), network access (`HttpClient`), and process execution (`Process.Start`). | | **2**| **FullAccess** | No restrictions. All assemblies and APIs are accessible. This poses a security risk and should only be used with fully trusted code. | The `RoslynCompiler` initializes its assembly references based on the current security level. In `Restricted` mode, the `SecurityValidator` inspects the compiled code's syntax tree for calls to dangerous APIs before execution is permitted. *Sources: [Packages/src/README.md](), [Packages/src/Editor/Compilation/RoslynCompiler.cs]()* ## Configuration and Path Management The `UnityMcpPathResolver` class is a static utility responsible for locating all relevant configuration files and directories for various LLM tools. This centralization simplifies integration with different development environments. ### Path Resolution Logic The resolver can locate configuration files in different locations depending on the tool and user settings: - **Project-based**: For tools like Cursor (`.cursor/mcp.json`) and VSCode (`.vscode/mcp.json`), it looks in the project root. - **Home Directory-based**: For tools like Windsurf and Codex, it looks in the user's home directory (`~/.codeium/` or `~/.codex/`). - **Git Root vs. Project Root**: The system can be configured to place configuration files at the Git repository root instead of the Unity project root, which is useful for monorepos. The resolver also finds the `server.bundle.js` file for the TypeScript server, searching multiple locations to support both local development and package manager installations. This flowchart shows the logic for resolving a configuration file path. ```mermaid flowchart TD A[GetConfigPath(editorType)] --> B{Use Git Repo Root?}; B -- Yes --> C[Find Git Root]; B -- No --> D[Use Unity Project Root]; C --> E{Git Root Found?}; E -- Yes --> F[Base = Git Root]; E -- No --> D; F --> G[Resolve Path]; D --> G; G --> H{Editor uses Home Dir?}; H -- Yes --> I[Get Home Dir Path]; H -- No --> J[Combine Base + Config Path]; I --> K[Return Final Path]; J --> K; ``` *Sources: [Packages/src/Editor/Config/UnityMcpPathResolver.cs](), [Packages/src/Editor/UI/McpEditorWindow.cs]()* ## Conclusion The uLoopMCP Unity (C#) Backend provides a powerful and secure bridge between AI agents and the Unity Editor. Its architecture, founded on the principles of modularity and extensibility through the Tool pattern, allows developers to easily add custom functionality. The schema-driven, type-safe communication combined with a multi-level security model ensures both reliability and safety. Centralized components like `McpServerController`, `CommandRunner`, and `UnityToolRegistry` work in concert to create a robust system for automating complex development tasks within Unity. *Sources: [Packages/src/ARCHITECTURE.md](), [Packages/src/README.md]()*## FULL FILE CONTEXT SUMMARY The user wants a technical wiki page about the "Unity (C#) Backend Architecture" of the `uLoopMCP` project. I need to provide a detailed breakdown of the C# components that run inside the Unity Editor. Based on the file context, here's a summary of the key architectural points: 1. **High-Level Structure (`ARCHITECTURE.md`, `README.md`)**: * The system has three parts: MCP Clients (LLMs), a TypeScript Server (Node.js), and the Unity Editor Backend (C# TCP Server). * The TypeScript server communicates with the Unity backend via TCP/JSON-RPC on localhost. * The Unity backend is responsible for exposing editor functions as "tools" to the TypeScript server. * Key patterns mentioned are MVP (Model-View-Presenter) for the UI, and a "Tool Pattern" for commands. 2. **Core Components & Flow**: * `McpServerController.cs`: This is the main entry point. It starts, stops, and manages the TCP server. It listens for client connections and receives raw request data. It's responsible for handling domain reloads and restoring the server state. * `McpEditorWindow.cs`: This is the UI layer (the "View" in MVP). It provides buttons and settings in a Unity window to control the `McpServerController`. It allows users to set the port, security levels, and configure different LLM tools. * `CommandRunner.cs`: This class is the request handler. It takes a raw JSON-RPC request, parses it, finds the corresponding tool, checks security permissions, and executes it. It's the central dispatcher for all incoming commands. * `IUnityTool.cs` & `UnityToolRegistry.cs`: This defines the "Tool" pattern. * `IUnityTool` is the interface all command tools must implement. * `UnityToolRegistry` uses reflection to discover all classes that implement `IUnityTool` and have the `[McpTool]` attribute. It acts as a service locator for tools. * The `README.md` shows how to create a custom tool by inheriting from `AbstractUnityTool`, which provides type-safe parameters and responses. 3. **Security (`README.md`, `RoslynCompiler.cs`, `McpEditorWindow.cs`)**: * Security is a major feature. It's configured in `McpEditorWindow`. * There are general toggles for enabling/disabling features like test execution, menu item execution, and custom "third-party" tools. * The most detailed security is around the `execute-dynamic-code` tool, which is handled by `RoslynCompiler.cs`. * `RoslynCompiler` implements a 3-tier security level: * Level 0 (Disabled): No code execution. * Level 1 (Restricted): Recommended. Blocks dangerous APIs like `File.Delete`, `HttpClient`, `Process.Start`. This is enforced by a `SecurityValidator` that analyzes the compiled code. * Level 2 (FullAccess): No restrictions. 4. **Dynamic Code Execution (`RoslynCompiler.cs`, `README.md`)**: * This is a core feature, powered by the `RoslynCompiler` class. * It requires the `Microsoft.CodeAnalysis.CSharp` (Roslyn) package. * It can take a simple C# script, wrap it in a class and an `ExecuteAsync` method, compile it, and run it. * The wrapping logic is smart enough to handle existing `using` statements and top-level code. 5. **Configuration & Path Management (`UnityMcpPathResolver.cs`)**: * The system needs to interact with configuration files for various LLM tools (Cursor, Claude Code, VSCode, etc.). These files (`mcp.json`, `config.toml`) can be in different locations (project root, user home directory). * `UnityMcpPathResolver` is a static utility class that centralizes all this path-finding logic. * It also handles a setting to place configs in the Git repository root instead of the Unity project root, which is useful for monorepos. * It has logic to find the TypeScript server's `server.bundle.js` file, whether the package is in local development mode (`Packages/src`) or installed via the package manager (`Library/PackageCache`). 6. **Request Flow (Synthesized from multiple files)**: 1. TypeScript server sends a JSON-RPC request over TCP. 2. `McpServerController` receives it. 3. The request is passed to `CommandRunner`. 4. `CommandRunner` uses `UnityToolRegistry` to find the `IUnityTool` instance by name. 5. `CommandRunner` checks security settings (e.g., is `run-tests` allowed?). 6. If allowed, `CommandRunner` calls `ExecuteAsync` on the tool instance. 7. The tool runs on the Unity main thread. 8. The result is sent back through `McpServerController`. This information is sufficient to build a comprehensive wiki page with diagrams and tables as requested. I will structure the page logically, starting with the high-level overview and then diving into the core components, the tool system, the execution flow, and finally security and configuration. I will use Mermaid diagrams to visualize the architecture and flows. I will cite all information from the provided source files.

Relevant source files