UAsset Reference MCP: Indexing External Unity Packages

Fri, 24 Jul 2026 00:00:00 +0700

UAsset Reference MCP v0.3.2 fixes a gap that appears as soon as a Unity project becomes modular. A game can depend on a local Unity Package Manager package through Packages/manifest.json, while that package’s source folder lives outside the Unity project directory. Unity imports it, resolves its GUIDs, and lets project assets reference it. A project-root-only asset scan can still miss it.

The change in v0.3.2 is automatic external local UPM package indexing. The indexer now discovers active local directory packages from Unity package metadata, reads their files from their physical source folders, and stores graph nodes under canonical Unity paths such as Packages/com.company.gameplay/Runtime/EnemyConfig.asset. The SQLite graph stays portable, and traversal still works through GUID edges rather than through filesystem assumptions.

The Missing Root Is Not Optional

Unity projects often split shared gameplay, UI, networking, or tools code into UPM packages. During development, those packages are commonly referenced as local directories so the package can be edited alongside the game.

The Unity manifest might look like this:

{
  "dependencies": {
    "com.company.gameplay": "file:../../modules/com.company.gameplay"
  }
}

From Unity’s point of view, assets inside that module are part of the active project package set. A prefab in Assets/Characters/Enemy.prefab can serialize a reference to a ScriptableObject inside com.company.gameplay, and Unity resolves the reference through the target asset’s .meta GUID.

A scanner that only walks the project root has a different view. It can see Assets/, embedded packages under Packages/, and cached registry packages under Library/PackageCache/. It cannot see ../../modules/com.company.gameplay unless it understands Unity’s package metadata. The result is an unresolved GUID even though the Unity Editor can resolve the same asset.

v0.3.2 makes the scan scope match the active Unity package graph more closely:

Unity project root
  Assets/                         scanned as project assets
  Packages/com.embedded.tool/      scanned as embedded package assets
  Library/PackageCache/...         scanned as cached package assets

External local package
  ../../modules/com.company.gameplay/
                                  scanned as package assets
                                  stored as Packages/com.company.gameplay/...

The indexer is still static and offline. It does not launch Unity or ask the Editor for a package list. It reads the metadata Unity already writes, then builds the graph from files on disk.

Physical Sources Become Unity Paths

The central model is physical root versus virtual path. The physical root is where the indexer reads bytes. The virtual path is the Unity path stored in the graph.

For an external package named com.company.gameplay, the physical source might be:

/Users/vincewang/modules/com.company.gameplay/Runtime/EnemyConfig.asset

The graph stores it as:

Packages/com.company.gameplay/Runtime/EnemyConfig.asset

That stored path is the important part. Absolute machine paths are local development details. If the index persisted /Users/... or ../../modules/..., a shared snapshot would describe one developer’s folder layout instead of the Unity project model. Packages/<package-name>/... is the path Unity users expect when talking about package assets, so it is the path the database records.

The node still carries package identity:

path:       Packages/com.company.gameplay/Runtime/EnemyConfig.asset
origin:     package
package_id: com.company.gameplay

Reference extraction does not need a separate package traversal mode. Unity serialized references point to GUIDs, and the index resolves GUIDs across all active roots. A project asset can reference a package asset. A package asset can reference a project asset. Two packages can reference each other. Once the GUID map includes every active root, the edge model remains the same.

Discovery Follows Unity Metadata

The scanner builds a package-source plan before walking files. It reads Packages/manifest.json for direct dependencies and Packages/packages-lock.json when Unity has written resolved package metadata.

The manifest is the authority for direct dependency declarations. A direct local dependency using a file: directory can be discovered from the manifest alone. Relative file: paths resolve from the project’s Packages/ directory, matching how Unity interprets those paths, not from whichever directory happened to launch the CLI.

The lockfile can add resolved local-package information, including local transitive packages. That matters when a project pulls in a package that itself depends on another local package. The indexer can include the package Unity resolved without asking the user to configure extra scan roots.

Discovery is intentionally narrow. The indexer follows package paths explicitly declared or resolved by Unity project metadata. It does not crawl parent folders, scan sibling repositories, expand arbitrary workspace directories, read environment variables, download missing packages, or treat local .tgz files and file:// Git URLs as external directories. Those sources remain Unity package-resolution concerns, and cached package content continues to be handled through Library/PackageCache/ when present.

Each external package candidate has to be an accessible directory with a parseable package.json. The package manifest’s name must match the dependency name declared by the project. A mismatch is skipped with a package-discovery warning instead of being indexed under the wrong Unity path.

Precedence Prevents Duplicate Package Views

One package name must map to one active source. Otherwise the graph could index both a live local package and a stale cached copy of the same package, creating duplicate nodes and confusing dependency answers.

v0.3.2 uses deterministic source precedence:

Embedded package under Packages/<name>
Active external local package from manifest or lock metadata
Matching package cache under Library/PackageCache

An embedded package wins because it is physically inside the Unity project and overrides package-manager resolution for that package name. An active external local package wins over a matching cache entry because the local source is the package Unity is using for development. The cache remains useful for registry and Git packages, but it should not compete with the current local source.

The existing duplicate-GUID validation remains the final safety boundary. If two genuinely active assets claim the same Unity GUID, indexing fails before publishing a new database. External package discovery does not silently choose a GUID winner, because Unity asset identity has to stay unambiguous for graph answers to be trustworthy.

Incremental Refresh Tracks Package Selection

Normal indexing is still incremental. Each logical asset uses the newer modification time of the asset file and its sibling .meta, including assets inside external packages. Editing a package asset or its .meta therefore participates in the same incremental path as project assets.

Package selection introduces another freshness problem. The manifest or lockfile can change while the selected package assets appear unchanged. A dependency can be removed, pointed at another folder, or replaced with a different source that preserves the same virtual path, GUID, and timestamps. A file-level timestamp check is not enough to detect that package-source decision.

v0.3.2 records a package-discovery fingerprint for the indexed package plan. The fingerprint is derived from the project manifest, lockfile, and selected package-source descriptors. When that fingerprint changes, the next index run discards the copied incremental staging database and performs a fresh candidate-graph reconciliation before the atomic publish step.

That gives the indexer two layers of freshness. Asset and .meta mtimes handle ordinary edits. The package-discovery fingerprint handles changes to which package sources are active. force: true remains the explicit guaranteed-freshness path and scans all active roots unconditionally.

unity-asset-reference-mcp-index index /path/to/UnityProject --force

MCP callers use the same public tool as before:

index_project(path, force?)

There is no new scan-root argument. The point of this release is that active local UPM packages are project metadata, so indexing them should not require a second configuration system.

Warnings Are Bounded and Localized

Package discovery can fail for reasons that should not make the whole project impossible to index. A package directory may be missing on one machine. A local path may be inaccessible. A package.json file may be malformed. A package may declare a different name than the dependency key in the Unity manifest.

Those cases produce package-discovery warnings and skip the invalid source. Other valid roots continue to index. The previous good index is still replaced only after the complete candidate graph passes the existing validation and publication checks.

A missing or malformed project manifest disables external-local discovery for that run and emits one bounded manifest warning. Embedded package and package-cache scanning still continue, so the indexer preserves as much useful graph data as it can without inventing package state.

Ignore rules use canonical paths, not physical source paths. A configured ignore such as Packages/com.company.gameplay/Samples~/** applies to the external package as it appears in Unity. Root-level ignores and descendant ignores are evaluated before recursion, so an ignored package root produces neither nodes nor per-file warning noise.

The Release Changes Scope, Not the Public Shape

v0.3.2 expands what the existing indexer can see. It does not change the public query surface.

The npm package was published as unity-asset-reference-mcp@0.3.2, and the annotated v0.3.2 tag points at the published release commit. The Unity verification package stays at 0.2.0. SQLite remains schema 3. MCP and CLI inputs and successful response shapes are unchanged.

The release validation covered the package-indexing behavior and the publication boundary. The release evidence records root Vitest passing across 39 test files and 298 tests, npm run typecheck, npm run build, package dry-runs for both the root package and Unity package, git diff --check, a successful GitHub Actions release workflow, and npm registry verification returning exactly 0.3.2.

The exclusions are as important as the feature. v0.3.2 does not add manual root configuration, filesystem watchers, Unity Editor callbacks, package downloads, local package mutation, schema migration, or new MCP tools. It reads the active local packages Unity already knows about, represents them with Unity’s virtual package paths, and lets the existing GUID graph answer cross-boundary dependency questions.

External local package indexing makes the graph match modular Unity projects more closely. Package assets no longer disappear just because their source folder sits outside the game repository. The index still publishes portable SQLite data, still resolves by GUID, and still keeps package discovery explicit enough to warn when local machine state does not match the project’s package declarations.

UAsset Reference MCP: Modeling Unity Addressables Separately

Tue, 21 Jul 2026 00:00:00 +0700

Addressables changed the unused-asset question in UAsset Reference MCP. A texture, prefab, or scene can be unreferenced by serialized assets and still be intentionally loaded through an Addressables entry.

That means a reference graph needs two different kinds of evidence. One answers whether a serialized asset points to another asset. The other answers whether an asset is reachable because the project declares it as Addressable content.

Serialized References and Addressables Answer Different Questions

The first release of UAsset Reference MCP focused on Unity’s serialized reference records. In text mode, Unity writes links as {fileID, guid, type} values. Those records are direct asset-to-asset edges.

Addressables are not the same shape. An Addressables group file describes entries, labels, read-only state, group membership, and an address that can be loaded at runtime. That metadata does not mean another asset serialized a field reference to the entry. It means the project author declared the entry as loadable content.

Flattening both concepts into one edge type would make the graph easier to query but harder to trust. A developer reviewing unused assets needs to know why an asset is reachable.

Serialized edge:
Assets/Scenes/Battle.unity -> Assets/Prefabs/Enemy.prefab

Addressables reachability:
Addressables group "RemoteCharacters" contains Assets/Prefabs/Enemy.prefab

Those statements support different decisions. The scene edge explains a concrete dependency. The Addressables entry explains runtime availability.

Normalized Tables Keep the Model Honest

UAsset Reference MCP stores Addressables metadata in separate SQLite tables instead of hiding it inside the regular edges table.

addressable_groups
addressable_entries
addressable_entry_labels

The group table records the Addressables group identity and source file. The entries table records the asset GUID, address, owning group, read-only state, and indexed source bytes. Labels live in their own table because one entry can have multiple labels, and queries need deterministic filtering.

This structure keeps regular graph traversal simple while still letting the query layer answer Addressables-specific questions. find_unused_assets can treat Addressables entries as roots when configured to do so, while get_addressable_info can explain the exact group and labels that make one asset reachable.

Reachability Is a Review Signal

reachableOnlyBecauseAddressable is deliberately a review signal. It tells the user that an asset is not reachable through scenes or serialized asset references, but it is reachable through Addressables metadata.

That distinction matters because Unity projects often load content through code:

Addressables.LoadAssetAsync<GameObject>("EnemyBoss");

Static graph indexing does not prove whether string-based runtime loading is used correctly. It can show that the asset is declared as an Addressables entry and that no serialized edge points at it. A developer still needs to review the loading code before deleting or moving the asset.

The tool avoids presenting Addressables reachability as deletion safety. It reports the graph evidence and leaves the production decision with the engineer.

MCP Tools Make Addressables Queryable

The Addressables release added read-only MCP tools for common inspection paths.

get_addressable_info(asset)
search_addressables(query?, group?, label?, pathPrefix?, type?, reachableOnlyBecauseAddressable?, limit?)
list_addressable_groups()

get_addressable_info resolves one asset or Addressables address and returns membership, owning group, labels, reference counts, and reachability signals. search_addressables gives agents bounded discovery across entries. list_addressable_groups gives a compact inventory of groups, labels, entry counts, and indexed source bytes.

The tools are intentionally read-only. They help an agent explain the project; they do not rewrite Addressables configuration, move entries between groups, or predict bundle output.

Verification Uses Real Project Exports

Addressables parsing has more edge cases than plain .meta GUID scanning. Group files can have different layouts, entries can be read-only, labels can be absent, and generated metadata can vary between package versions.

The implementation was verified against Unity-side exports from a real project. The verification flow compares what Unity reports with what the Node indexer stored. That gives the parser a concrete contract: group identity, entry identity, labels, and reachability data must match the project Unity understands.

The result is still scoped. Stage 1 models Addressables discovery and query behavior. Group schemas, profiles, providers, packing, compression, build/load paths, content-update settings, and bundle analysis remain outside this release.

Addressables support is useful because it keeps the asset graph from pretending every reachable asset is reachable for the same reason. Serialized references, Addressables entries, and runtime string loads need separate evidence. UAsset Reference MCP models the first two directly and makes the third explicit as a limitation.

UAsset Reference MCP: Building a Unity Asset Reference Graph

Wed, 08 Jul 2026 00:00:00 +0700

UAsset Reference MCP turns a Unity project’s serialized assets into a queryable reference graph. The indexer reads Unity’s .meta GUIDs and YAML reference records, stores the result in SQLite, then exposes that database through a CLI, an MCP server, and a local web viewer.

The goal is to answer asset questions before they become production problems. If a developer wants to delete a material, rename a prefab folder, split an Addressables group, or understand why a scene pulls in a dependency chain, the graph gives them a concrete answer instead of a manual search across the Project window.

Unity Already Stores the Asset Graph

Unity assets have stable identity through .meta files. A prefab, scene, material, texture, script, or Addressables asset has a GUID that other serialized files can reference.

When a project uses text serialization, Unity writes asset references into YAML-like files as records such as {fileID, guid, type}. That format is not a guess. It is the same reference information Unity uses to reconnect serialized fields to project assets.

UAsset Reference MCP builds on that property. The indexer scans project assets, parses each asset’s .meta GUID, extracts serialized reference records, resolves those GUIDs back to asset paths, and stores the result as directed edges.

Assets/Scenes/Battle.unity
  -> Assets/Prefabs/Enemy.prefab
  -> Assets/Materials/BattleFloor.mat

Assets/Prefabs/Enemy.prefab
  -> Assets/Textures/Enemy_Diffuse.png
  -> Assets/Animations/Enemy.controller

That graph becomes useful once it is durable. A one-off scan can answer one question, but a SQLite index lets command-line tools, MCP clients, and the web viewer share the same model.

SQLite Is the Boundary Between Indexing and Querying

The indexer writes .asset-memory/index.db inside the Unity project. That database stores assets as nodes, references as edges, unresolved references as broken links, and Addressables metadata in normalized tables.

SQLite keeps the tool simple. There is no service to deploy, no graph database to run, and no MCP client lock-in. The MCP server can expose curated tools for agents, while external scripts can still inspect the artifact directly when needed.

The core workflow looks like this:

unity-asset-reference-mcp-index index /path/to/UnityProject --force

After indexing, the project has a local graph database:

/path/to/UnityProject
└── .asset-memory
    └── index.db

The same index can support impact analysis, dependency tracing, unused-asset review, broken-reference reporting, and JSON export without rescanning the project for every query.

MCP Gives Agents a Curated Query Surface

The MCP server runs over stdio and works with MCP-compatible hosts. Instead of giving an agent raw SQL access, it exposes specific tools with bounded behavior.

{
  "mcpServers": {
    "unity-asset-graph": {
      "command": "npx",
      "args": ["-y", "unity-asset-reference-mcp", "--project", "/path/to/UnityProject"]
    }
  }
}

An agent can then ask practical Unity questions through tools such as find_references, get_dependencies, trace_path, find_unused_assets, search_assets, and get_overview.

That boundary matters. The agent receives a project-specific graph interface, not a general file-system search habit. It can answer, “what references this prefab?” or “why is this texture reachable?” with graph data instead of scanning every YAML file during the conversation.

Verification Keeps the Parser Honest

The Node indexer parses Unity serialization outside the Unity Editor. That keeps indexing scriptable and agent-friendly, but it also means the parser needs a way to prove its results against Unity’s own view of the project.

The companion Unity package exports a verification file from the Editor:

Tools > Asset Reference Memory > Export Verification

The CLI compares that export against the SQLite graph:

unity-asset-reference-mcp-index verify-index /path/to/UnityProject \
  --verify /path/to/UnityProject/.asset-memory/verify.json

This makes parser accuracy measurable. Missed edges, extra edges, and unresolved references can be reported as data instead of discovered later through a broken production workflow.

What This Series Will Cover

This first post sets the boundary of the tool: Unity text serialization in, SQLite graph out, MCP and viewer queries on top. The rest of the series can go deeper into the implementation details that made the asset useful in real projects.

Future posts can cover the GUID and YAML parser, the SQLite schema, incremental indexing, Addressables modeling, MCP tool design, the web viewer, and the Unity verification harness.

The useful part is not that Unity assets can be scanned. The useful part is turning Unity’s existing serialized reference data into a durable graph that both developers and agents can query before changing a project.