# Unity MCP Search

A Unity Editor package that exposes asset search, references, and dependency analysis as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server, enabling AI coding assistants like Claude Code and OpenCode to query your Unity project's asset graph.

## Architecture

```
AI Client (Claude Code / OpenCode / ...)
    | MCP Protocol (stdio)
    v
Python MCP Server (server.py)
    | HTTP (localhost:8090)
    v
Unity Editor HTTP Server (McpHttpServer.cs)
    |
    v
Unity AssetDatabase & SearchService APIs
```

The Python process acts as a thin MCP-to-HTTP bridge. The real work happens inside the Unity Editor on the main thread, using `AssetDatabase` and `SearchService` APIs.

## Requirements

- **Unity** 2021.3 or later
- **Python** 3.10 or later

## Installation

### Option A: Unity Package Manager (Git URL)

1. Open Unity, go to **Window > Package Manager**
2. Click **+** > **Add package from git URL...**
3. Enter:
   ```
   https://github.com/StromKuo/Unity-MCP-Search.git
   ```

### Option B: Git Submodule

```bash
git submodule add https://github.com/StromKuo/Unity-MCP-Search.git Packages/com.strodio.unity-mcp-search
```

### Option C: Local Clone

Clone the repo into your project's `Packages/` folder:

```bash
cd YourProject/Packages
git clone https://github.com/StromKuo/Unity-MCP-Search.git com.strodio.unity-mcp-search
```

## Setup

### 1. Setup Python Environment

Go to **Tools > MCP Search > Setup Python Environment**.

This will:
- Find a suitable Python 3.10+ interpreter on your system
- Create a virtual environment inside the package (`MCP~/venv/`)
- Install the Python dependencies (`mcp`, `httpx`)

### 2. Configure Your AI Client

Go to **Tools > MCP Search > Copy MCP Config** to copy the MCP server configuration JSON to your clipboard.

The config looks like this:

```json
{
  "mcpServers": {
    "unity-search": {
      "command": "/path/to/Packages/com.strodio.unity-mcp-search/MCP~/venv/bin/python",
      "args": ["/path/to/Packages/com.strodio.unity-mcp-search/MCP~/server.py"]
    }
  }
}
```

Paste it into your AI client's MCP settings:
- **Claude Code**: `~/.claude/settings.json`
- **OpenCode**: `~/.config/opencode/config.json` (under the `mcp_servers` section)

### 3. Verify

Go to **Tools > MCP Search > Check Environment** to verify everything is set up correctly. You should see:

```
System Python 3.10+:  OK
Virtual Env:          OK
Dependencies:         OK
HTTP Server:          Running (port 8090)
```

## Available MCP Tools

Once configured, your AI client can use the following tools:

### `search_assets`

Search for assets using [Unity Search](https://docs.unity3d.com/Manual/search-overview.html) query syntax.

```
search_assets(query="t:Material sky")
```

Supported filters:
- `t:Type` — filter by asset type (e.g. `t:Texture`, `t:Prefab`, `t:Scene`)
- `l:label` — filter by asset label
- `ref:path` — find assets referencing a given path
- `dep:path` — find assets that depend on a given path

Returns: `path`, `name`, `type` for each match.

### `get_asset_info`

Get detailed info about a specific asset.

```
get_asset_info(asset_path="Assets/Materials/Default.mat")
```

Returns: `path`, `guid`, `type`, `size`, `sizeFormatted`, `dependencyCount`, `referenceCount`, `dependencies`, `references`.

### `find_asset_references`

Find all assets that reference the specified asset.

```
find_asset_references(asset_path="Assets/Sprites/hero.png")
```

Returns a list of asset paths.

### `find_asset_dependencies`

Find all dependencies of the specified asset.

```
find_asset_dependencies(asset_path="Assets/Prefabs/Enemy.prefab", recursive=True)
```

Returns a list of asset paths.

### `find_unused_assets`

Scan a directory for assets that are not referenced by anything in the project.

```
find_unused_assets(directory="Assets/Art", extensions="png,jpg,mat")
```

Automatically excludes:
- `Resources/` folders (loaded at runtime by name)
- Build scenes
- Addressable asset entries
- `StreamingAssets/`
- Scripts and shaders
- `Editor/` folders
- `Packages/`

Returns: `path`, `size`, `sizeFormatted` for each unused asset.

## Unity Editor Menu

All menu items are under **Tools > MCP Search**:

| Menu Item | Description |
|---|---|
| Start Server | Start the HTTP server (auto-starts on editor launch) |
| Stop Server | Stop the HTTP server |
| Setup Python Environment | Create venv and install dependencies |
| Check Environment | Verify all components are working |
| Copy MCP Config | Copy MCP server config JSON to clipboard |
| Server Status | Show current server status |

## How It Works

- The **Unity HTTP server** (`McpHttpServer.cs`) starts automatically when the editor opens via `[InitializeOnLoad]`. It listens on `localhost:8090`.
- HTTP requests from the Python bridge are queued and processed on Unity's main thread (required by `AssetDatabase` and `SearchService` APIs).
- The **Python MCP server** (`MCP~/server.py`) translates MCP tool calls into HTTP requests. The `MCP~` directory is ignored by Unity's asset importer (directories ending with `~` are excluded).
- The Python venv lives inside the package at `MCP~/venv/` and is excluded from version control via `.gitignore`.

## Troubleshooting

**"Cannot connect to Unity Editor"**
- Make sure Unity Editor is open and focused (the HTTP server runs in the editor process)
- Check **Tools > MCP Search > Server Status**
- Try **Tools > MCP Search > Stop Server**, then **Start Server**

**"Asset not found" errors**
- Asset paths must use forward slashes and start with `Assets/` (e.g. `Assets/Sprites/hero.png`)

**Python setup fails**
- Ensure Python 3.10+ is installed: `python3 --version`
- On macOS with Homebrew: `brew install python@3.12`
- On Windows: download from https://www.python.org/downloads/

**Timeouts on large projects**
- `find_unused_assets` on the root `Assets/` directory may take a while on large projects. Use the `directory` parameter to narrow the scope, or `extensions` to filter by file type.

## License

MIT