Tool Reference
Relevant source files
The following files were used as context for generating this wiki page:
- Packages/src/TOOL_REFERENCE.md
- Packages/src/README.md
- Packages/src/ARCHITECTURE.md
- Packages/src/TypeScriptServer~/src/unity-tool-manager.ts
- Packages/src/TypeScriptServer~/src/tools/dynamic-unity-command-tool.ts
- Packages/src/TypeScriptServer~/src/domain/use-cases/refresh-tools-use-case.ts
- Packages/src/Editor/Api/McpTools/ExecuteDynamicCode/ExecuteDynamicCodeSchema.cs
- Packages/src/Cli~/scripts/generate-bundled-skills.ts
- SECURITY.md
- Packages/src/TypeScriptServer~/src/tools/base-tool.ts
- Packages/src/TypeScriptServer~/src/domain/models/domain-tool.ts
- Packages/src/Cli~/src/tests/cli-e2e.test.ts
- Packages/src/TypeScriptServer~/README.md
- README.md
The uLoopMCP toolset is designed to expose Unity Editor and project functionalities to Large Language Models (LLMs), enabling AI agents to autonomously perform development tasks. These tools allow an AI to compile, test, inspect logs, and operate the Unity Editor, creating a "self-hosted development loop" with minimal human intervention.
The system is built on two core concepts: providing tools for a complete development cycle (compile, run-tests, get-logs) and enabling direct Editor automation (execute-dynamic-code, execute-menu-item). For more architectural details, see the Architecture Overview.
Sources: Packages/src/README.md:18-26, Packages/src/ARCHITECTURE.md:1-3
Tool Architecture and Management
The tool system operates across three main components: the MCP Client (e.g., Cursor), the TypeScript Server, and the Unity Editor. The TypeScript server acts as a bridge, dynamically discovering and exposing tools from the Unity Editor to the MCP client.
Sources: Packages/src/ARCHITECTURE.md:12-18
This diagram shows the high-level communication flow.
Dynamic Tool Discovery and Refresh
Tools are not hardcoded in the TypeScript server. Instead, the UnityToolManager fetches tool definitions from the Unity Editor upon connection and dynamically creates DynamicUnityCommandTool instances for each. This allows for extensibility, as new tools added to the Unity project are automatically exposed.
A critical feature is the tool refresh mechanism, orchestrated by the RefreshToolsUseCase. This is essential for recovering the connection and tool state after a domain reload in Unity, which typically happens after script compilation.
Sources: Packages/src/TypeScriptServer~/src/unity-tool-manager.ts:22-29, 133-138, Packages/src/TypeScriptServer~/src/domain/use-cases/refresh-tools-use-case.ts:28-34
The following sequence diagram illustrates the tool refresh process, often triggered after a Unity domain reload.
Tool Class Structure
On the TypeScript side, all tools, including the dynamically generated ones, are based on the BaseTool class. DynamicUnityCommandTool extends this base class to handle communication with the Unity backend for a specific tool.
Sources: Packages/src/TypeScriptServer~/src/tools/base-tool.ts:12-13, Packages/src/TypeScriptServer~/src/tools/dynamic-unity-command-tool.ts:29-30
This diagram shows the class relationship.
Tool Categories
The available tools can be grouped into two main categories.
Development Loop Tools
These tools are fundamental for creating an autonomous compile-test-fix loop.
| Tool | Description |
|---|---|
compile | Executes AssetDatabase.Refresh() and script compilation, returning errors and warnings. |
get-logs | Retrieves logs from the Unity Console with advanced filtering. |
run-tests | Executes EditMode or PlayMode tests via the Unity Test Runner. |
clear-console | Clears the Unity Console logs. |
Sources: Packages/src/README.md:83-143
Unity Editor Automation & Discovery Tools
These tools allow the AI to inspect and manipulate the state of the Unity Editor and project assets.
| Tool | Description |
|---|---|
unity-search | Uses the UnitySearch API to find assets and objects in the project. |
get-provider-details | Retrieves available search providers for unity-search. |
get-menu-items | Lists MenuItem attributes defined in the project. |
execute-menu-item | Executes a MenuItem by its path. |
find-game-objects | Searches for GameObjects in the current scene based on various criteria. |
get-hierarchy | Exports the active scene hierarchy to a JSON file. |
focus-window | Brings the Unity Editor window to the foreground. |
capture-window | Captures any EditorWindow as a PNG image. |
control-play-mode | Starts, stops, or pauses the Editor's Play Mode. |
execute-dynamic-code | Executes arbitrary C# code within the Editor, subject to security levels. |
Sources: Packages/src/README.md:145-201
Detailed Tool Reference
All tools share a common TimeoutSeconds parameter and include a Ver property in their response for version checking.
Sources: Packages/src/TOOL_REFERENCE.md:5-12
1. compile
Executes compilation and returns the results.
| Parameter | Type | Description | Default |
|---|---|---|---|
ForceRecompile | boolean | If true, forces a full recompilation. | false |
Response Keys: Success, ErrorCount, WarningCount, CompletedAt, Errors, Warnings, Message.
Sources: Packages/src/TOOL_REFERENCE.md:16-36
2. get-logs
Retrieves logs from the Unity console.
| Parameter | Type | Description | Default |
|---|---|---|---|
LogType | enum | Type to filter: "Error", "Warning", "Log", "All". | "All" |
MaxCount | number | Maximum number of logs to return. | 100 |
SearchText | string | Text to search for in log messages. | "" |
UseRegex | boolean | Use regular expressions for SearchText. | false |
SearchInStackTrace | boolean | Search within stack traces as well. | false |
IncludeStackTrace | boolean | Include stack traces in the response. | true |
Response Keys: TotalCount, DisplayedCount, LogType, MaxCount, SearchText, IncludeStackTrace, Logs.
Sources: Packages/src/TOOL_REFERENCE.md:38-57
3. run-tests
Executes tests using the Unity Test Runner.
| Parameter | Type | Description | Default |
|---|---|---|---|
FilterType | enum | "all", "exact", "regex", "assembly". | "all" |
FilterValue | string | Value for the filter (e.g., test name, regex pattern). | "" |
TestMode | enum | "EditMode", "PlayMode". | "EditMode" |
SaveXml | boolean | If true, saves results to an XML file. | false |
Response Keys: Success, Message, CompletedAt, TestCount, PassedCount, FailedCount, SkippedCount, XmlPath.
Sources: Packages/src/TOOL_REFERENCE.md:59-83
4. clear-console
Clears all logs from the Unity console.
| Parameter | Type | Description | Default |
|---|---|---|---|
AddConfirmationMessage | boolean | Adds a confirmation log after clearing. | true |
Response Keys: Success, ClearedLogCount, ClearedCounts, Message, ErrorMessage.
Sources: Packages/src/TOOL_REFERENCE.md:85-98
5. find-game-objects
Finds GameObjects in the scene.
| Parameter | Type | Description | Default |
|---|---|---|---|
NamePattern | string | GameObject name pattern. | "" |
SearchMode | enum | "Exact", "Path", "Regex", "Contains". | "Exact" |
RequiredComponents | array | Array of component type names. | [] |
Tag | string | Tag to filter by. | "" |
Layer | number | Layer to filter by. | null |
IncludeInactive | boolean | Include inactive GameObjects. | false |
MaxResults | number | Maximum results to return. | 20 |
Response Keys: results, totalFound, errorMessage.
Sources: Packages/src/TOOL_REFERENCE.md:100-128
6. unity-search
Searches the project using the Unity Search API.
| Parameter | Type | Description | Default |
|---|---|---|---|
SearchQuery | string | Unity Search query string (e.g., t:Prefab). | "" |
Providers | array | Specific search providers to use (e.g., "asset", "scene"). | [] |
MaxResults | number | Maximum results to return. | 50 |
SaveToFile | boolean | Save large result sets to a file. | false |
AutoSaveThreshold | number | Automatically save to file if result count exceeds this. | 100 |
Response Keys: Results, TotalCount, ResultsFilePath, ResultsSavedToFile.
Sources: Packages/src/TOOL_REFERENCE.md:132-184
7. get-hierarchy
Retrieves the scene hierarchy structure. For large hierarchies, it automatically saves the output to a JSON file in .uloop/outputs/HierarchyResults/ to conserve LLM context tokens.
| Parameter | Type | Description | Default |
|---|---|---|---|
IncludeInactive | boolean | Include inactive GameObjects. | true |
MaxDepth | number | Maximum hierarchy depth to traverse (-1 for unlimited). | -1 |
IncludeComponents | boolean | Include component information for each GameObject. | true |
MaxResponseSizeKB | number | Max response size in KB before saving to file. | 100 |
Response Keys: hierarchy (for small hierarchies), hierarchySavedToFile, hierarchyFilePath (for large hierarchies), context.
Sources: Packages/src/TOOL_REFERENCE.md:186-215, Packages/src/README.md:173-177
8. execute-menu-item
Executes a MenuItem by its path.
| Parameter | Type | Description | Default |
|---|---|---|---|
MenuItemPath | string | The path of the menu item (e.g., "GameObject/Create Empty"). | "" |
UseReflectionFallback | boolean | Use reflection if EditorApplication.ExecuteMenuItem fails. | true |
Response Keys: MenuItemPath, Success, ExecutionMethod, ErrorMessage.
Sources: Packages/src/TOOL_REFERENCE.md:255-265
9. execute-dynamic-code
Dynamically executes C# code within the Unity Editor. This is a powerful tool with configurable security levels.
| Parameter | Type | Description | Default |
|---|---|---|---|
Code | string | The C# code snippet to execute. | "" |
Parameters | Dictionary | Runtime parameters for the snippet. | {} |
CompileOnly | boolean | If true, only compiles the code without executing it. | false |
Response Keys: Success, Result, Logs, CompilationErrors, ErrorMessage, SecurityLevel.
Sources: Packages/src/TOOL_REFERENCE.md:267-287, Packages/src/Editor/Api/McpTools/ExecuteDynamicCode/ExecuteDynamicCodeSchema.cs:10-20
Security Levels
This tool's capabilities are governed by a 3-tier security system, configured in the uLoopMCP window.
| Level | Name | Description |
|---|---|---|
| 0 | Disabled | Code execution is completely blocked. |
| 1 | Restricted | (Recommended) Allows most Unity APIs and user assemblies but blocks dangerous operations like file deletion/writing, network access, and process execution. |
| 2 | FullAccess | No restrictions. All APIs are accessible. Use only with trusted code. |
Sources: Packages/src/README.md:227-262, SECURITY.md:28-29
CLI and Skills Integration
All MCP tools are also exposed through the uloop command-line interface. This allows for direct scripting and integration with LLM "Skills" systems, like the one in Claude Code.
Sources: Packages/src/README.md:415-424
Skills
Skills are definitions that allow an LLM tool to automatically discover and use the uloop CLI commands. The system scans for SKILL.md files in the project to generate a bundled list of available skills.
Sources: Packages/src/Cli~/scripts/generate-bundled-skills.ts:1-5, Packages/src/README.md:600-605
This allows an AI to translate natural language instructions into concrete actions:
| User Instruction | Skill Used by LLM |
|---|---|
| "Fix the compile errors" | /uloop-compile |
| "Run the tests and tell me why they failed" | /uloop-run-tests + /uloop-get-logs |
| "Check the scene hierarchy" | /uloop-get-hierarchy |
| "Search for prefabs" | /uloop-unity-search |
Sources: Packages/src/README.md:451-460, Packages/src/Cli~/src/tests/cli-e2e.test.ts:300-305
Security Settings
Several tools are disabled by default for security. They can be enabled in the Window > uLoopMCP "Security Settings" panel.
| Setting | Tool(s) Enabled | Default |
|---|---|---|
| Allow Tests Execution | run-tests | Disabled |
| Allow Menu Item Execution | execute-menu-item | Disabled |
| Allow Third Party Tools | Custom user-developed tools | Disabled |
| Dynamic Code Security Level | execute-dynamic-code | Level 0 (Disabled) |
Setting changes take effect immediately without a server restart. It is strongly recommended to run AI-driven development in a sandboxed environment.