Tools: Unity Search Integration

Relevant source files

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

• Packages/src/Editor/Api/McpTools/UnitySearch/UnitySearchTool.cs
• Packages/src/Editor/Api/McpTools/UnitySearchProviderDetails/UnitySearchProviderDetailsTool.cs
• Packages/src/Editor/Api/McpTools/UnitySearch/UnitySearchService.cs
• Packages/src/Editor/Api/McpTools/UnitySearch/UnitySearchResponse.cs
• Assets/Editor/UnitySearchTester.cs
• Packages/src/TOOL_REFERENCE.md
• Packages/src/README.md
• Packages/src/ARCHITECTURE.md

The Unity Search Integration provides a set of tools that expose Unity's powerful UnitySearch API to AI agents via the Model Context Protocol (MCP). This allows an AI to programmatically search for assets, scenes, menu items, and other project elements, enabling autonomous inspection, analysis, and manipulation of project resources.

This integration is a key part of the "Unity Editor Automation & Discovery Tools" feature set. It consists of two primary tools: unity-search for performing searches and get-provider-details for discovering what can be searched. These tools are crucial for use cases like having an AI inspect large numbers of prefabs or organize scene structures.

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

Architecture

The Unity Search tools follow the standard uLoopMCP architecture. A request from an MCP client is routed through the TypeScript server, which then communicates with the C# TCP server running in the Unity Editor. The C# side executes the search using the Unity Search API and returns the results.

Sources: Packages/src/ARCHITECTURE.md

This diagram illustrates the high-level communication flow for a search request.

Core Tools

The integration provides two main tools for interacting with Unity Search.

1. unity-search

This is the primary tool for executing search queries against the Unity project. It leverages the UnitySearchService to interact with the underlying Unity Search API, providing comprehensive filtering and result formatting.

Sources: Packages/src/Editor/Api/McpTools/UnitySearch/UnitySearchTool.cs, Packages/src/TOOL_REFERENCE.md

Parameters

The unity-search tool accepts several parameters to refine the search.

Parameter	Type	Description	Default
SearchQuery	string	The search query string, supporting Unity Search syntax (e.g., t:prefab, ref:MyScript).	""
Providers	string[]	An array of specific search providers to use (e.g., "asset", "scene"). An empty array uses all active providers.	[]
MaxResults	number	The maximum number of search results to return.	50
SaveToFile	boolean	If true, forces the results to be saved to a file instead of being returned in the response.	false
AutoSaveThreshold	number	If the number of results exceeds this threshold, they are automatically saved to a file. Set to 0 to disable.	100
OutputFormat	enum	The format for the output file when SaveToFile is true (JSON, CSV, TSV).	JSON
FileExtensions	string[]	Filters results by file extension (e.g., "cs", "prefab").	[]
AssetTypes	string[]	Filters results by asset type (e.g., "Texture2D", "MonoScript").	[]
PathFilter	string	Filters results by a path pattern, supporting wildcards.	""

Sources: Packages/src/TOOL_REFERENCE.md, Packages/src/Editor/Api/McpTools/UnitySearch/UnitySearchTool.cs

Execution Flow

The following sequence diagram shows the process of executing a unity-search command.

Response Structure (UnitySearchResponse)

The response is designed to be token-efficient. For large result sets, it automatically saves the results to a file in the {project_root}/.uloop/outputs/ directory and returns the file path instead of the full data.

Property	Type	Description
Success	boolean	Indicates if the search was successful.
TotalCount	int	The total number of items found, before MaxResults was applied.
DisplayedCount	int	The number of results included in the Results array.
Results	SearchResultItem[]	An array of search results. Empty if results were saved to a file.
ResultsSavedToFile	boolean	True if the results were saved to a file.
ResultsFilePath	string	The path to the saved results file.
SaveToFileReason	string	The reason results were saved to a file (e.g., user_request, auto_threshold).
SearchDurationMs	long	The time the search took in milliseconds.
AppliedFilters	SearchFilterInfo	An object detailing the filters that were applied to the search.

Sources: Packages/src/Editor/Api/McpTools/UnitySearch/UnitySearchResponse.cs

The response classes have the following structure:

2. get-provider-details

This tool allows an agent to discover the available search providers in the current Unity project. This is useful for determining the scope of what can be searched (e.g., assets, scene, menus, settings).

Sources: Packages/src/Editor/Api/McpTools/UnitySearchProviderDetails/UnitySearchProviderDetailsTool.cs, Packages/src/TOOL_REFERENCE.md

Parameters

Parameter	Type	Description	Default
ProviderId	string	The ID of a specific provider to get details for. If empty, returns all providers.	""
ActiveOnly	boolean	If true, returns only currently active providers.	false
SortByPriority	boolean	If true, sorts the returned providers by their priority.	true
IncludeDescriptions	boolean	If true, includes the detailed description for each provider.	true

Sources: Packages/src/TOOL_REFERENCE.md, Packages/src/Editor/Api/McpTools/UnitySearchProviderDetails/UnitySearchProviderDetailsTool.cs

Response Structure

The response contains a list of providers with their metadata.

Property	Type	Description
Providers	ProviderInfo[]	An array of provider information objects.
TotalCount	number	The total number of providers found.
ActiveCount	number	The number of active providers.
Success	boolean	Indicates if the request was successful.

Sources: Packages/src/TOOL_REFERENCE.md

Usage Example

The UnitySearchTester.cs class provides a clear example of how to invoke the UnitySearchTool from C# code. It constructs a schema, executes the tool, and processes the response.

// From: Assets/Editor/UnitySearchTester.cs
private async Task TestBasicSearchAsync()
{
    UnitySearchTool tool = new UnitySearchTool();
    UnitySearchSchema schema = new UnitySearchSchema
    {
        SearchQuery = _searchQuery,
        MaxResults = _maxResults,
        SaveToFile = _saveToFile
    };
    
    await ExecuteTestAsync(tool, schema, "Basic Search");
}

private async Task ExecuteTestAsync(UnitySearchTool tool, UnitySearchSchema schema, string testName)
{
    try
    {
        string json = Newtonsoft.Json.JsonConvert.SerializeObject(schema);
        JToken token = JToken.Parse(json);
        
        BaseToolResponse baseResponse = await tool.ExecuteAsync(token);
        UnitySearchResponse response = baseResponse as UnitySearchResponse;
        
        // ... process response ...
    }
    // ...
}

Sources: Assets/Editor/UnitySearchTester.cs:68-93

Summary

The Unity Search Integration is a vital component for enabling AI-driven development within Unity. By providing the unity-search and get-provider-details tools, it gives AI agents the ability to explore and understand the project's structure and contents. The design, particularly the automatic file export for large results, is optimized for the token-constrained environment of LLMs, making it a practical and efficient solution for complex automation tasks.

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