Tool: get-hierarchy
Relevant source files
The following files were used as context for generating this wiki page:
The get-hierarchy tool is a core feature of uLoopMCP designed to analyze and retrieve the structure of the currently active scene hierarchy in the Unity Editor. It provides a nested JSON representation of GameObjects, their parent-child relationships, and attached components. This allows an AI agent to understand the scene's composition, discover structural issues, and perform targeted manipulations.
A key design principle of this tool is context-efficiency. For large hierarchies that would consume excessive LLM context tokens, the tool automatically exports the data to a JSON file and returns only the file path. This makes it feasible for an AI to inspect even very large and complex scenes. The tool is accessible via the MCP server and the uloop command-line interface.
Sources: README.md:121-126, TOOL_REFERENCE.md:200-202
Architecture and Core Components
The get-hierarchy tool is implemented in C# within the Unity Editor and follows the project's "UseCase + Tool Pattern" architecture. This pattern separates the tool's public-facing interface from its internal business logic, promoting a clean separation of concerns.
Sources: Packages/src/Editor/Api/McpTools/GetHierarchy/GetHierarchyTool.cs:6-11, Packages/src/ARCHITECTURE.md:46-47
The main classes involved are:
GetHierarchyTool: The entry point for the tool, registered with the[McpTool]attribute. It receives the request and delegates execution to theGetHierarchyUseCase.GetHierarchyUseCase: Orchestrates the business logic. It usesHierarchyServiceto traverse the scene andHierarchySerializerto format the output.HierarchyService: Contains the core logic for traversing the Unity scene graph.HierarchySerializer: Responsible for converting the traversed hierarchy data into a JSON string.
Sources: Packages/src/Editor/Api/McpTools/GetHierarchy/GetHierarchyTool.cs:12-20, 30-32
The relationship between these components is illustrated in the class diagram below.
This diagram shows how GetHierarchyTool delegates its work to GetHierarchyUseCase, which in turn uses specialized services for traversal and serialization.
Sources: Packages/src/Editor/Api/McpTools/GetHierarchy/GetHierarchyTool.cs:24-32
Execution Flow
When a client (like an LLM agent or CLI) invokes get-hierarchy, the request flows from the TypeScript server to the C# backend in Unity. The tool then processes the request and decides whether to return the hierarchy data directly or save it to a file.
The sequence diagram below shows the typical execution flow.
Parameters
The tool's behavior can be customized with several parameters. These are defined in the tool's schema and can be passed in the request.
| Parameter | Type | Description | Default Value |
|---|---|---|---|
IncludeInactive | boolean | If true, includes inactive GameObjects in the result. | true |
MaxDepth | number | The maximum depth to traverse the hierarchy. A value of -1 means unlimited depth. | -1 |
RootPath | string | The path to a root GameObject to start traversal from. If null or empty, starts from all root objects. | null |
IncludeComponents | boolean | If true, includes a list of component type names for each GameObject. | true |
MaxResponseSizeKB | number | The maximum response size in KB. If the resulting JSON exceeds this, it is saved to a file instead. | 100 |
Sources: TOOL_REFERENCE.md:203-217, Assets/Tests/Editor/GetHierarchyToolTests.cs:72-79
Response Structure
The tool has a dual response format depending on the size of the generated hierarchy data.
Small Hierarchies (Direct JSON Response)
If the generated JSON is smaller than MaxResponseSizeKB (default 100KB), the data is returned directly in the response payload. The JSON has a nested structure representing the scene graph.
hierarchy: An array of root-level GameObject nodes.id: The GameObject's instance ID.name: The GameObject's name.depth: The node's depth in the hierarchy (root is 0).isActive: The active state of the GameObject.components: An array of component type names.children: A recursive array of child GameObject nodes.
context: Metadata about the retrieval process.
Sources: TOOL_REFERENCE.md:219-233
Large Hierarchies (File Export)
If the data exceeds the size threshold, it is automatically saved to a file to avoid consuming a large number of LLM tokens. The response then contains the path to this file.
hierarchySavedToFile: A boolean that istrue.hierarchyFilePath: The relative path to the saved JSON file, located in{project_root}/.uloop/outputs/HierarchyResults/.saveToFileReason: A string indicating why the file was saved (e.g.,"auto_threshold").context: The same metadata as in the direct response.
Sources: TOOL_REFERENCE.md:234-240, README.md:123-124
CLI and Skills Integration
The get-hierarchy tool is fully integrated with the uloop CLI and the Skills system, making it easily accessible from various development environments.
CLI Usage
You can invoke the tool directly from the command line. This is useful for scripting or manual inspection.
# Retrieve the hierarchy with a max depth of 2
uloop get-hierarchy --max-depth 2
The CLI command will output a JSON response containing the file path to the hierarchy data.
Sources: Packages/src/Cli~/src/tests/cli-e2e.test.ts:200-206
Skill Definition
The tool is exposed as a Skill, which allows LLM tools like Claude Code to discover and use it automatically. The skill definition provides the LLM with the necessary context on when and how to use the tool.
The skill is named /uloop-get-hierarchy and is recommended for tasks like understanding scene structure or finding specific GameObjects.
Sources: Packages/src/Editor/Api/McpTools/GetHierarchy/SKILL.md, README.md:252-255