The Autonomous Development Loop
Relevant source files
The following files were used as context for generating this wiki page:The uLoopMCP project is designed to enable an AI agent to drive a Unity project's development forward with minimal human intervention. It achieves this by exposing tasks that are typically handled manually—such as compiling, running tests, checking logs, and editing scenes—as tools that Large Language Models (LLMs) can orchestrate. This creates a "self-hosted development loop" where an AI can repeatedly compile, test, analyze, and fix issues autonomously.
The system is built on two core principles: providing a toolset for a complete development cycle (compile → test → log analysis → fix) and allowing the AI to directly operate the Unity Editor for complex automation tasks. This enables use cases like having an AI fix a project until all tests pass, refactor code and verify the results, or even manipulate scene objects based on high-level instructions.
Sources: README.md:16-25, Packages/src/README.md:16-25
System Architecture
The uLoopMCP system comprises three main components that facilitate the autonomous loop: MCP Clients (LLM tools), a TypeScript Server acting as the MCP protocol server, and the Unity Editor which runs a C# TCP server for tool execution.
Sources: Packages/src/ARCHITECTURE.md:9-15
This diagram illustrates the high-level communication flow between the components.
The communication flow is layered:
- MCP Protocol Layer: LLM clients communicate with the TypeScript server using the Model Context Protocol over stdio.
- Service Layer: The TypeScript server, built with a Domain-Driven Design, orchestrates workflows.
- TCP Layer: The TypeScript server communicates with the Unity Editor via TCP/JSON-RPC on localhost to execute commands.
Sources: Packages/src/ARCHITECTURE.md:47-53
The Loop in Action
The core of the autonomous loop is a cycle of actions an AI can perform to iteratively improve the codebase. This cycle is enabled by a suite of specialized tools.
This flowchart shows a typical autonomous development workflow.
Sources: README.md:20-22, README.md:73-76, README.md:98-101
Core Development Loop Tools
These tools form the backbone of the autonomous development cycle, allowing the AI to compile, test, and debug.
| Tool | Description | Key Use Case in the Loop |
|---|---|---|
compile | Executes AssetDatabase.Refresh() and then compiles the project. Returns detailed error and warning information. | Verify: Checks if code changes have resolved compilation issues. |
get-logs | Retrieves logs from the Unity Console with advanced filtering (LogType, regex, stack trace inclusion). | Analyze: Inspects error messages or debug output to identify the root cause of a problem. |
run-tests | Executes EditMode or PlayMode tests via the Unity Test Runner and returns results. | Test: Validates that code changes have fixed a bug and not introduced regressions. |
clear-console | Clears all logs from the Unity console. | Reset: Provides a clean slate before a new debug session to avoid analyzing stale logs. |
Sources: README.md:71-105, Packages/src/TOOL_REFERENCE.md:12-78
Editor Automation & Discovery Tools
Beyond the basic loop, uLoopMCP provides tools that allow an AI to directly interact with and modify the Unity Editor and project assets. The execute-dynamic-code tool is central to this capability.
| Tool | Description |
|---|---|
execute-dynamic-code | Dynamically executes C# code within the Unity Editor. This is the most powerful automation tool. |
get-hierarchy | Retrieves the structure of the current scene hierarchy as a nested JSON, saved to a file to conserve tokens. |
find-game-objects | Searches for GameObjects in the scene based on name, components, tags, or layers. |
unity-search | Uses the powerful UnitySearch API to find any asset or object in the project. |
execute-menu-item | Executes any MenuItem available in the editor, enabling project-specific scripted actions. |
control-play-mode | Starts, stops, or pauses the Unity Editor's Play Mode. |
capture-window | Captures any EditorWindow as a PNG image, providing visual feedback to the AI. |
Sources: README.md:107-183, Packages/src/TOOL_REFERENCE.md:80-264
The execute-dynamic-code Tool
This tool is a cornerstone of advanced automation, allowing the AI to perform actions not covered by other tools. To mitigate risks, it operates under a tiered security model.
| Level | Name | Description |
|---|---|---|
| 0 | Disabled | No code execution is allowed. This is the safest setting. |
| 1 | Restricted | (Recommended) Allows use of most Unity APIs and user assemblies but blocks security-critical operations like file deletion, network access, and process execution. |
| 2 | FullAccess | No restrictions. All APIs are accessible. This poses a security risk and should only be used with trusted code. |
The security level is configured in the uLoopMCP window within Unity.
Sources: README.md:154-183, SECURITY.md:25-26
Access Methods: MCP vs. CLI/Skills
LLM agents can interact with the uLoopMCP tools through two primary mechanisms: the MCP server or the uloop CLI tool combined with "Skills".
- MCP Server: The LLM tool communicates directly with the TypeScript MCP server, which then forwards requests to Unity. This requires MCP configuration in the LLM tool.
uloopCLI & Skills: The LLM tool invokes theuloopcommand-line tool. "Skills" are definitions (SKILL.mdfiles) that tell the LLM how and when to use the CLI commands. This method requires no MCP configuration and is more context-efficient. The project provides 14 bundled skills for all its tools.
Sources: README.md:255-285, Packages/src/Cli~/scripts/generate-bundled-skills.ts:2-6
This diagram shows the sequence of a tool call using the CLI/Skills approach.
Security Considerations
Given the autonomous nature of the loop, security is a critical concern. uLoopMCP implements several measures that are disabled by default and must be explicitly enabled by the user.
- Tool Permissions: Execution of potentially sensitive tools like
run-tests,execute-menu-item, and any custom third-party tools must be explicitly allowed in the "Security Settings" of the uLoopMCP window. - Dynamic Code Security: The
execute-dynamic-codetool is governed by a strict, user-configurable security level (Disabled, Restricted, FullAccess). The recommended setting is "Restricted". - Sandboxing: It is strongly recommended to run AI-driven development sessions in a sandboxed environment (e.g., containers) to mitigate risks from unexpected behavior.
Sources: README.md:187-203, SECURITY.md:41-45