Overall Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• Packages/src/ARCHITECTURE.md
• Packages/src/README.md
• README.md
• Packages/src/TypeScriptServer~/README.md
• Packages/src/TOOL_REFERENCE.md
• Packages/src/Cli~/scripts/generate-bundled-skills.ts
• SECURITY.md
• Packages/src/Editor/Config/CodexTomlConfigService.cs
• Packages/src/Cli~/src/tests/skills-manager.test.ts

The uLoopMCP system is designed to allow AI agents and LLM-powered development tools to interact with and operate Unity projects. Its core purpose is to enable an autonomous "self-hosted development loop" where an AI can compile, test, analyze logs, and even manipulate the Unity Editor to progress a project with minimal human intervention. This is achieved by exposing Unity Editor functionalities as a set of tools that LLMs can orchestrate.

The architecture is composed of three primary components: external MCP Clients (like Cursor or Claude Code), a TypeScript-based MCP server that acts as a bridge, and a C# server integrated within the Unity Editor. This layered design facilitates communication, tool management, and security. An alternative interaction model is provided through a standalone CLI tool (uloop) and a "Skills" system, which abstracts direct MCP communication for compatible LLM tools.

Sources: Packages/src/ARCHITECTURE.md:11-17, Packages/src/README.md:16-23, Packages/src/README.md:279-285

System Overview

The uLoopMCP system is a tripartite architecture consisting of MCP Clients, a TypeScript Server, and the Unity Editor. These components work in concert to translate high-level requests from an LLM into concrete actions within a Unity project.

This diagram shows the high-level relationship between the three main components of the uLoopMCP system.

Components

Component	Technology	Role
MCP Clients	Various (e.g., VSCode extensions)	LLM-powered development tools that consume the Model Context Protocol (MCP) to interact with the development environment.
TypeScript Server	Node.js	An MCP protocol server that acts as a bridge. It receives requests from MCP clients, processes them through a Domain-Driven Design (DDD) architecture, and forwards them to the Unity Editor.
Unity Editor Integration	C#	A TCP server running inside the Unity Editor. It exposes project and editor functionalities as tools, manages security, and executes commands received from the TypeScript server.
CLI Tool (uloop)	Node.js	A standalone command-line interface that provides the same functionality as the MCP server but is designed to be invoked by "Skills-compatible" LLM tools, bypassing direct MCP configuration.

Sources: Packages/src/ARCHITECTURE.md:11-17, Packages/src/README.md:279-281

Communication Flow

Communication follows a three-layer approach, ensuring a clean separation of concerns between the LLM client, the bridging server, and the Unity Editor.

1. MCP Protocol Layer: LLM clients communicate with the TypeScript server via stdio using the Model Context Protocol.
2. Service Layer: The TypeScript server uses a Domain-Driven Design (DDD) approach, where Use Cases orchestrate business logic.
3. TCP Layer: The TypeScript server communicates with the C# server in the Unity Editor over a local TCP socket using JSON-RPC.

Sources: Packages/src/ARCHITECTURE.md:55-61

The following sequence diagram illustrates a typical request flow, from an MCP client to the execution of a tool in Unity.

Key Architectural Features

TypeScript Server (DDD Architecture)

The TypeScript server is built with a clean, Domain-Driven Design architecture.

• Domain-Driven Design: Follows a clean architecture with a Domain Layer for pure business logic, an Application Layer for service contracts, and an Infrastructure Layer for external integrations.
• Dynamic Tool Management: It dynamically discovers and exposes tools available from the connected Unity Editor to the MCP clients.
• Connection Resilience: Features automatic reconnection and discovery mechanisms to handle events like Unity domain reloads, providing graceful degradation of service.

Sources: Packages/src/ARCHITECTURE.md:65-71, Packages/src/TypeScriptServer~/README.md:32-36

Unity Editor Integration

The C# component within Unity is responsible for exposing and executing tools securely.

• UseCase + Tool Pattern: Combines DDD principles with a Tool Pattern. Tools are defined by implementing the IUnityTool interface and are automatically registered using the [McpTool] attribute. This allows for easy extension with project-specific functionality.
• Schema-Driven Communication: Communication is type-safe, with JSON-RPC requests and responses automatically generated and validated against C# schema classes.
• Security: All tools are subject to security validation via McpSecurityChecker. Dangerous operations are disabled by default and can be enabled through the uLoopMCP settings window.

Sources: Packages/src/ARCHITECTURE.md:73-83, Packages/src/README.md:410-418

CLI and Skills System

As an alternative to direct MCP integration, uLoopMCP provides a CLI and a "Skills" system.

• uloop CLI: A standalone CLI tool that can execute all the same tools as the MCP server. This allows LLM tools that can call shell commands (via a "Skill") to operate Unity without any MCP-specific configuration.
• Skills: Skills are defined in SKILL.md files, which contain metadata and documentation about a tool. These files make tools discoverable to LLM agents. A build script (generate-bundled-skills.ts) collects SKILL.md files from the project and bundles them for the CLI to use.

This diagram shows how a C# tool is exposed as a "Skill" for an LLM agent via the CLI.

Security Architecture

Security is a critical aspect of the architecture, especially for tools like execute-dynamic-code that can run arbitrary code.

• Default-Deny Policy: Potentially dangerous tools like run-tests, execute-menu-item, and custom third-party tools are disabled by default. They must be explicitly enabled in the uLoopMCP window's "Security Settings".
• Dynamic Code Security Levels: The execute-dynamic-code tool has a multi-level security model to control its capabilities.

Level	Name	Description
0	Disabled	Code execution is completely disabled. This is the safest setting.
1	Restricted	(Recommended) Allows most Unity APIs and standard libraries but blocks security-critical operations like file deletion, network access, and process execution.
2	FullAccess	No restrictions. All assemblies and APIs are accessible. This poses a security risk and should only be used with trusted code.

• Sandbox Recommendation: The documentation strongly recommends running AI-driven development in sandboxed environments (e.g., containers) to mitigate risks from unexpected behavior.

Sources: SECURITY.md:27-31, Packages/src/README.md:200-244

Extensibility

The system is designed to be extensible, allowing developers to add project-specific tools.

1. Create Schema/Response Classes: Define C# classes for the tool's parameters (BaseToolSchema) and return data (BaseToolResponse).
2. Create Tool Class: Create a class that inherits from AbstractUnityTool<TSchema, TResponse>.
3. Add [McpTool] Attribute: Decorate the class with the [McpTool] attribute to make it auto-discoverable by the system.
4. (Optional) Create SKILL.md: Add a SKILL.md file in the same directory to make the tool available to the uloop CLI and Skills-compatible LLMs.

The following snippet shows the basic structure for creating a custom tool.

// 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. Create tool class
[McpTool(Description = "Description of my custom tool")]
public class MyCustomTool : AbstractUnityTool<MyCustomSchema, MyCustomResponse>
{
    public override string ToolName => "my-custom-tool";
    
    protected override Task<MyCustomResponse> ExecuteAsync(MyCustomSchema parameters, CancellationToken cancellationToken)
    {
        // Implement custom logic here
        string result = $"Processed '{parameters.MyParameter}'";
        return Task.FromResult(new MyCustomResponse { Result = result });
    }
}

Sources: Packages/src/README.md:410-469

Configuration

Configuration for LLM tools like Cursor and Codex is managed automatically via the uLoopMCP window in Unity. The system generates or updates the necessary configuration files (e.g., ~/.codex/config.toml or .cursor/mcp.json) to point to the running TypeScript server and set the correct port. The CodexTomlConfigService.cs file, for example, handles reading and writing the TOML configuration for Codex, demonstrating how the system abstracts away manual setup.

Sources: Packages/src/README.md:250-256, Packages/src/Editor/Config/CodexTomlConfigService.cs