Project Structure

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/Cli~/scripts/generate-bundled-skills.ts
• Packages/src/TypeScriptServer~/README.md
• Packages/src/ARCHITECTURE_ja.md
• Packages/src/TOOL_REFERENCE.md
• SECURITY.md
• Packages/src/Cli~/src/tests/skills-manager.test.ts
• Packages/src/TypeScriptServer~/package.json
• Packages/src/Cli~/src/tests/cli-e2e.test.ts
• Packages/src/Editor/Config/UnityMcpPathResolver.cs

The uLoopMCP project is designed to let AI agents compile, test, and operate a Unity project from popular LLM tools. Its structure is a multi-component system that bridges external Model Context Protocol (MCP) clients with the Unity Editor. The core idea is to expose Unity Editor functions—like compiling, running tests, and inspecting scenes—as tools that an LLM can orchestrate to create an autonomous development loop.

The system is composed of three primary components: the Unity Editor integration (a C# TCP server), a TypeScript server (a Node.js process acting as the MCP server), and the external MCP clients (e.g., Cursor, Claude Code). A standalone CLI tool, uloop, is also provided as an alternative, context-efficient way for LLMs to interact with the system via "Skills". This modular structure allows for clear separation of concerns, with each component handling a specific part of the communication and execution pipeline.

Sources: Packages/src/README.md:16-23, Packages/src/ARCHITECTURE.md:10-14

High-Level System Architecture

The uLoopMCP system consists of three main parts that work together: MCP Clients, a TypeScript Server, and the Unity Editor.

1. MCP Clients: LLM-powered development tools like Claude Code, Cursor, and VSCode that consume the MCP protocol.
2. TypeScript Server: A Node.js process that acts as the MCP protocol server. It uses a Domain-Driven Design (DDD) architecture to manage business logic and communicate with the Unity Editor.
3. Unity Editor: A C# TCP server integrated into the Unity Editor. It exposes Unity functionalities as tools and manages security.

The following diagram illustrates the high-level architecture and communication flow between these components.

Communication Flow

The system uses a three-layer communication approach:

1. MCP Protocol Layer: LLM clients communicate with the TypeScript server using the Model Context Protocol over stdio.
2. Service Layer: The TypeScript server uses Domain-Driven Design, where Use Cases orchestrate business workflows.
3. TCP Layer: The TypeScript server communicates with the Unity Editor via TCP/JSON-RPC on localhost.

Sources: Packages/src/ARCHITECTURE.md:46-51

Component Breakdown

The project's source code is primarily organized within the Packages/src/ directory, which contains the C# code for the Unity Editor, the TypeScript server, and the CLI tool.

The diagram below shows the main directories for each component within the package structure.

Unity Editor Integration (C#)

The Unity Editor component is the C# part of the system that runs inside Unity. It acts as a TCP server, listening for commands from the TypeScript server, executing them using Unity APIs, and managing security.

• Location: Packages/src/Editor/
• Architecture: It follows a combination of Domain-Driven Design (DDD), Model-View-Presenter (MVP) for UI, and a Tool Pattern. UseCases orchestrate business workflows, and Application Services implement single functions.
• Key Concepts:
  • Tools: Custom operations are created by implementing the IUnityTool interface and using the [McpTool] attribute for automatic registration.
  • Security: All tools are subject to validation by the McpSecurityChecker. Security settings, such as allowing test execution or dynamic code, are configured through the uLoopMCP window.
  • Path Resolution: The UnityMcpPathResolver class is responsible for locating configuration files and the TypeScript server bundle, handling different environments like local development, package manager installations, and WSL2.

Sources: Packages/src/ARCHITECTURE.md:70-80, Packages/src/README.md:310-336, Packages/src/Editor/Config/UnityMcpPathResolver.cs:9-89, SECURITY.md:25-28

TypeScript Server (Node.js)

The TypeScript server is a Node.js process that serves as the bridge between MCP clients and the Unity Editor. It implements the MCP protocol and translates requests into JSON-RPC calls to the Unity TCP server.

• Location: Packages/src/TypeScriptServer~/

• Architecture: It uses a Domain-Driven Design (DDD) approach with a clean architecture, separating domain logic from infrastructure concerns.

• Build Process: The server is bundled into a single file (dist/server.bundle.js) using esbuild. The build process is triggered automatically on npm install via a postinstall script.

  "scripts": {
    "build": "npm run build:bundle",
    "build:bundle": "esbuild src/server.ts --bundle --platform=node --format=esm --outfile=dist/server.bundle.js --external:fs --external:path --external:net --external:os --sourcemap",
    "postinstall": "npm run build"
  }
  

  Sources: Packages/src/TypeScriptServer~/package.json:8-10, 42

• Directory Structure:

  src/
  ├── types/          # Type definitions for tools
  ├── tools/          # Tool implementations (e.g., compile, get-logs)
  ├── server.ts       # Main class for the MCP server
  └── unity-client.ts # Communication client for the Unity side
  

  Sources: Packages/src/TypeScriptServer~/README.md:25-34

CLI Tool (uloop)

uLoopMCP includes a standalone CLI tool named uloop that offers an alternative way for LLM tools to interact with Unity.

• Location: Packages/src/Cli~/
• Purpose: It provides the same functionality as the MCP tools but is designed to be invoked by "Skills"-compatible LLM agents. This approach is more context-efficient for the LLM, as it doesn't require the tool definitions to be part of the prompt.
• Functionality: The CLI offers commands that mirror the MCP tools, such as uloop compile, uloop get-logs, and uloop run-tests. It communicates with the Unity TCP server directly.
• Installation: The CLI is installed as a global npm package: npm install -g uloop-cli.

Sources: Packages/src/README.md:204-220, Packages/src/Cli~/src/tests/cli-e2e.test.ts

Skills System

The Skills system provides an abstraction layer over the uloop CLI, making it easy for LLM tools to discover and use the available commands.

• Structure: A "Skill" is defined by a SKILL.md file, which contains Markdown frontmatter for metadata and a body for documentation.

  ---
  name: uloop-my-custom-tool
  description: Description of what the tool does and when to use it.
  ---
  
  # uloop my-custom-tool
  
  Detailed documentation for the tool...
  

  Sources: Packages/src/README.md:342-351, Packages/src/Cli~/src/tests/skills-manager.test.ts:10-16

• Discovery: The uloop skills install command scans the project for SKILL.md files in predefined locations (Assets/**/Editor/, Packages/*/Editor/, etc.) and makes them available to the LLM tool.

• Bundling: A script, generate-bundled-skills.ts, collects all SKILL.md files from the McpTools and cli-only directories and bundles them into a single TypeScript file (bundled-skills.ts) for the CLI to use. This automates the process of including built-in skills.

The diagram below shows how skills are generated and bundled.

Configuration and Paths

Properly resolving paths to configuration files and the server bundle is critical for the system to function across different user setups.

Path Resolution

The static class UnityMcpPathResolver in Packages/src/Editor/Config/UnityMcpPathResolver.cs is responsible for all path-related logic.

• TypeScript Server Path: It uses a priority system to find server.bundle.js:
  1. Local development path (Packages/src/).
  2. A fixed path in the Library/ folder.
  3. The path resolved by the Unity Package Manager API.
  4. A fallback search in Library/PackageCache/.
• Configuration Root: It can resolve paths relative to either the Unity project root or the Git repository root, which is configurable in the editor settings. This is useful for monorepos where the Unity project is in a subdirectory.
• WSL2 Support: The resolver includes logic to detect if it's running in a WSL2 environment and converts Windows-style paths to WSL2-style paths (/mnt/c/...) when necessary, particularly for Claude Code.

Sources: Packages/src/Editor/Config/UnityMcpPathResolver.cs:101-105, 298-333, 401-422

Configuration Files

uLoopMCP automatically configures the necessary files for various LLM tools. The location and name of these files differ per tool.

LLM Tool	Configuration File Path	Managed By
Cursor	{root}/.cursor/mcp.json	UnityMcpPathResolver
Claude Code	{root}/.mcp.json	UnityMcpPathResolver
VSCode	{root}/.vscode/mcp.json	UnityMcpPathResolver
Gemini CLI	{root}/.gemini/settings.json	UnityMcpPathResolver
Windsurf	~/.codeium/windsurf/mcp_config.json	UnityMcpPathResolver
Codex	~/.codex/config.toml	UnityMcpPathResolver

{root} refers to the project or repository root. ~ refers to the user's home directory.

Sources: Packages/src/Editor/Config/UnityMcpPathResolver.cs:93-100, 192-232, Packages/src/README.md:183-198

A typical configuration entry in an mcp.json file looks like this:

{
  "mcpServers": {
    "uLoopMCP": {
      "command": "node",
      "args": [
        "[Unity Package Path]/TypeScriptServer~/dist/server.bundle.js"
      ],
      "env": {
        "UNITY_TCP_PORT": "{port}"
      }
    }
  }
}

Sources: Packages/src/README.md:187-198

Security Structure

Security is a key consideration, especially since the tool allows for dynamic code execution. The project implements several security measures.

• Security Settings UI: Many powerful tools are disabled by default and must be explicitly enabled via the Window > uLoopMCP "Security Settings" panel. This includes:
  • run-tests
  • execute-menu-item
  • Custom third-party tools
• Dynamic Code Security Levels: The execute-dynamic-code tool has a 3-tier security model:
  • Level 0 (Disabled): No code execution allowed.
  • Level 1 (Restricted): Recommended setting. Allows most Unity APIs but blocks dangerous operations like file deletion, network access, and process execution.
  • Level 2 (FullAccess): No restrictions.
• Automated Scanning: The project uses GitHub's security scanning features.

Sources: SECURITY.md:25-31, Packages/src/README.md:144-173, 287-304

Conclusion

The uLoopMCP project is built on a robust, multi-component architecture that effectively decouples the LLM client interface from the Unity Editor's execution environment. The TypeScript server acts as a clean, protocol-compliant intermediary, while the C# integration provides direct, powerful access to Unity's core functionalities. The addition of the uloop CLI and the Skills system offers a flexible and efficient alternative for modern AI agents, demonstrating a thoughtful approach to both developer experience and AI interaction. This modular structure not only ensures a clear separation of concerns but also provides a solid foundation for future extensions and integrations.

Sources: Packages/src/ARCHITECTURE.md, Packages/src/README.md