unity-indexer indexes a Unity project — scenes, prefabs, C# scripts, and assets — into a SQLite database and exposes 23 MCP tools so Claude can explore the project via structured queries. Instead of reading raw .unity, .prefab, and .asset files (Unity's non-standard YAML with GUIDs), Claude calls purpose-built tools that return exactly what's needed.

Distributed as a Claude Code plugin via GitHub with automatic MCP server registration on install.

⚡ Quick Start

/plugin marketplace add Mbogdan95/unity-indexer
/plugin install unity-indexer@unity-indexer

[!TIP] MCP server auto-registers on install. Tools are available in the next session.

🏗️ How it works

Architecture

  ┌───────────────────────────────────────────┐
  │         Claude Code  (MCP client)         │
  └─────────────────────┬─────────────────────┘
                        │ 23 MCP tool calls
  ┌─────────────────────▼─────────────────────┐
  │               MCP Server                  │
  └─────────────────────┬─────────────────────┘
                        │ SQL + graph queries
  ┌─────────────────────▼─────────────────────┐
  │              Index Store                  │
  │                                           │
  │  SQLite                Graphology         │
  │  ├─ files              (in-memory)        │
  │  ├─ game_objects       ├─ INHERITS        │
  │  ├─ components         ├─ IMPLEMENTS      │
  │  ├─ scripts            ├─ CALLS           │
  │  ├─ script_members     ├─ SUBSCRIBES_TO   │
  │  ├─ guids              └─ USES            │
  │  ├─ references                            │
  │  └─ graph_edges ──────▶ loaded on start   │
  └─────────────────────┬─────────────────────┘
                        │ parse & upsert
  ┌─────────────────────▼─────────────────────┐
  │            Parser Pipeline                │
  │                                           │
  │  .meta    ──▶  GUID registry              │
  │  .cs      ──▶  tree-sitter AST            │
  │  .unity   ──▶  scene hierarchy            │
  │  .prefab  ──▶  prefab tree                │
  │  .asset   ──▶  ScriptableObject fields    │
  │  .asmdef  ──▶  assembly dependencies      │
  └─────────────────────┬─────────────────────┘
                        │ file events
  ┌─────────────────────▼─────────────────────┐
  │        File Watcher  (chokidar)           │
  │        Assets/  ·  500 ms debounce        │
  └───────────────────────────────────────────┘

Indexing pipeline

On first run, unity-indexer walks Assets/ and indexes files in four phases:

Each file passes a two-stage guard before parsing: mtime check (fast — skips unchanged files) then SHA-256 content hash (catches content changes with no mtime update). Only changed files are re-parsed.

C# parsing

Scripts are parsed with tree-sitter (C# WASM grammar — no external toolchain). The parser extracts:

• Class name, namespace, base class, interfaces
• Members: fields, methods, properties, events — with access modifiers, return types, parameters, attributes, and exact line numbers
• Unity-specific flags: MonoBehaviour, ScriptableObject, Editor subclass detection
• Relationships: what this class calls, inherits, implements, uses, or subscribes to

Method bodies are not stored. Tools return file_path + start_line/end_line per member — fetch bodies on demand with Read.

Code graph

C# class relationships are stored as a directed graph (graphology) with five edge types:

Graph tools (trace_dependencies, find_path, detect_cycles, etc.) load this graph in-memory from graph_edges in SQLite and run graphology algorithms over it.

Incremental updates

The file watcher monitors Assets/ (not Packages/ — rarely changes). Changes batch with a 500 ms debounce to avoid thrashing on large saves. When more than 50 files change within 2 seconds (e.g. a git checkout), the indexer switches to bulk mode and reindexes all affected files.

Importance scoring & summaries

Every file and GameObject gets a float importance_score [0, 1] from:

• Incoming reference count (how many other files reference it)
• Presence of custom scripts
• Change frequency
• Hierarchy depth (for GameObjects)

Scores rank results — high-importance items surface first.

Pre-computed one-line summaries (component_summary, api_summary, subtree_summary) are stored alongside structured data. Most tools return summaries by default; drill-down calls fetch full detail on demand.

SQLite schema (key tables)

🔧 Available Tools

📁 Multiple projects

When multiple projects are indexed, pass project: "<name>" to scope any tool call. The name is the directory name of the Unity project root.

project: "MyGame"

Omit it when only one project is indexed.

🛠️ Development

Node.js >= 20.17.0 required.

npm run build      # compile TypeScript
npm run test       # run tests (vitest)
npm run typecheck  # type-check without emitting
npm run lint       # eslint
npm run ci         # typecheck + lint + format-check + test + build

📄 License

MIT