UAsset Reference MCP: Shipping the Tool, Not the Toolchain

Mon, 24 Aug 2026 04:00:00 +0000

UAsset Reference MCP ships three command-line binaries and a browser UI from one npm package, plus a Unity Editor package that must not reach npm at all. In v0.4.0 a global install dropped from roughly 134 MB to about 40 MB, and the published tarball from 1.45 MB to 0.72 MB.

Nothing was removed from the tool. What changed is the answer to a question that had been answered by habit: which of these packages does the installed artifact actually need?

A Dependency Is Not a Runtime Dependency Because Your Code Imports It

The viewer is a React application. It imports three, @react-three/fiber, @tanstack/react-query, zustand, lucide-react, @fontsource/*, and more. All of them were declared in dependencies, which is what you do when your code imports something.

But the viewer is bundled by Vite at publish time. What lands in the published package is dist/web/public/, a set of already-built JavaScript chunks. A user installing the prebuilt tarball never resolves those imports, because the imports no longer exist in the shipped form — they were inlined at build time.

Declaring them as runtime dependencies meant every global install downloaded roughly 93 MB of packages that nothing on that machine could ever execute.

The distinction is worth being precise about, because moving a package from dependencies to devDependencies does not delete it. A contributor cloning the repository and running a plain npm install still downloads the whole tree — that number did not move. What changed is npm install --omit=dev, which is what a consumer of the published package actually gets: roughly 134 MB before, about 37-40 MB after. Those are two different installs, and only one of them is the user-facing story.

The correct test is not “does my source import it” but “does the installed artifact need it present.” For a bundled frontend, most of the frontend’s dependencies fail that test.

Finding the Real Answer by Reading the Built Output

The safe way to move a dependency to devDependencies is not to reason about it. It is to scan every non-relative import in the built output, outside the viewer bundle, and see what is left.

The built server imports exactly three packages:

"dependencies": {
  "@modelcontextprotocol/sdk": "^1.29.0",
  "better-sqlite3": "^12.11.1",
  "zod": "^4.4.3"
}

An MCP transport, a SQLite driver, and a schema validator. Everything else the project builds with is a build-time concern.

The verification that matters is that the viewer still works with those packages absent. It does: the 915 KB three.js chunk loads from the static bundle with three nowhere in node_modules, because that chunk is three.js, already bundled.

A production install now reports 0 vulnerabilities from npm audit as a side effect, since the advisories lived in packages that were never needed at runtime in the first place.

The Artifact That Did Not Belong Inside the Artifact

The server-less WASM viewer is a build of the same UI against sql.js, meant to be opened directly from the filesystem with no server running. It shipped inside the npm package.

That package installs three binaries, one of which starts a server. Anyone who installs it has the server. The WASM flavor was charging every install about 706 KB of WebAssembly that a server-backed install would never load, to serve a use case that install had already solved.

It is now a release-page download, asset-graph-viewer-static-<version>.zip. Nothing about the flavor itself changed, but this is a real removal for anyone who was using it from inside node_modules, which is why it is called out in the changelog rather than quietly dropped.

Fonts, Twice, in Six Alphabets

Fontsource’s weight-level CSS declares one @font-face per subset — cyrillic, cyrillic-ext, greek, vietnamese, latin, latin-ext — and each rule carries a WOFF2 source with a WOFF fallback.

The viewer shipped all of it: 54 font files, 704 KB. Half of those were .woff files that no browser capable of running this UI would ever request. Most of the rest were alphabets that Unity asset paths do not use.

Trimming to latin and latin-ext WOFF2 leaves 10 files and 180 KB.

The `unicode-range` Bug That a Green Build Hid

The obvious way to trim is to import Fontsource’s per-subset entrypoints — latin-400.css instead of 400.css. It looks correct. It produces exactly the right file count. It would have broken every glyph in the UI.

Those per-subset files omit unicode-range. Two @font-face rules with the same family and weight and no unicode-range do not merge into a complementary set — the later one simply wins. latin-ext contains only accented characters, so it would have shadowed latin, and every piece of basic ASCII in the interface would have silently fallen back to a system font.

The build would have been green. The file count would have been right. Only reading the emitted CSS catches it.

So the pruning happens in a Vite transform that filters the original weight-level rules, keeping their unicode-range intact:

const KEEP_SUBSET = /-(latin|latin-ext)-\d+-normal\./;
const WOFF_FALLBACK = /,\s*url\([^)]+\.woff\)\s*format\(\s*(['"])woff\1\s*\)/g;

const kept = faces.filter((face) => KEEP_SUBSET.test(face));
if (kept.length === 0) {
  // A fontsource layout change would otherwise silently ship no fonts.
  throw new Error(`trim-font-subsets: no latin @font-face left in ${id}`);
}

The throw is the important line. A future Fontsource restructure that leaves no matching face behind now fails the build instead of shipping a UI with no fonts, because the failure mode of this optimization is invisible in every automated check that is not looking at glyphs.

Two Package Managers, One Repository

The Unity Editor package is not an npm concern, and files in package.json is an allowlist:

"files": ["dist", "CHANGELOG.md", "scripts/install.ps1", "scripts/install.sh", "README.md", "LICENSE"]

unity/ and rust/ are excluded by omission, which is the property worth relying on. A denylist would have to be updated every time a new top-level directory appears; an allowlist fails closed.

The Unity package versions independently and sits at 0.2.0. It changes only when the Editor exporter changes, so the npm version moving to 0.4.0 does not drag it along.

It installs three ways, and they are not equivalent:

.tgz            Package Manager -> Add package from tarball   UPM-managed
.zip            unzip, then Add package from disk             UPM-managed
.unitypackage   Assets -> Import Package -> Custom Package    not UPM-managed

A .tgz requires a package/ root, because that is the npm tarball layout Unity’s Package Manager expects. A .unitypackage is a different thing entirely: it imports files into Assets/ and is not upgradable in place. Listing it as an equal third option would be misleading, so it is listed with what it does.

Building a `.unitypackage` Without Unity

All three formats are built in CI with no Unity Editor and no licence. That works because of one property: every asset in the package carries a committed .meta with a stable GUID, and the GUID is the only thing a .unitypackage needs that Unity would otherwise generate.

The format is a gzipped tar of one directory per asset:

<guid>/asset        the file itself
<guid>/asset.meta   its committed .meta
<guid>/pathname     where it lands, e.g. Assets/AssetReferenceMemory/Editor/Exporter.cs

The builder walks the package, reads each sibling .meta for its GUID, and writes those three files per entry. An entry with no GUID is a hard failure rather than a skip:

if (!guid) {
  // Without a GUID the entry cannot be represented and Unity would simply
  // not import it. Fail rather than ship a package missing files.
  throw new Error(`no .meta guid for ${relative(repoRoot, path)} — .unitypackage would silently drop it`);
}

Unity does not report a missing entry on import. It imports what it was given and says nothing about what it was not, so a silently incomplete package would be discovered by a user rather than by CI.

Ports That Pick Themselves

The last piece of packaging is what happens after installation. The viewer used to require a port, and a second instance died with an unhandled EADDRINUSE. It now binds the first free port starting at 7777, so several Unity projects can be served at once with no coordination between them.

Configuration that can be derived is configuration a user should not have to supply. The same reasoning gives the viewer project discovery from the working directory, and the whole install-to-running path is now three commands:

npm install -g unity-asset-reference-mcp
cd /path/to/UnityProject
unity-asset-reference-mcp-web

Smaller, Not Faster

None of this made the tool faster — that was a separate investigation with its own numbers. It made the tool smaller, and it is worth being precise about which is which.

The summary, measured:

Consumer install       ~134 MB  ->  ~37-40 MB   (npm install --omit=dev)
Published package      1.45 MB  ->  0.72 MB packed
                        2.9 MB  ->  2.1 MB unpacked
Fonts                 704 KB / 54 files  ->  180 KB / 10 files
npm audit                        0 vulnerabilities

Every one of those came from asking what the installed artifact needs, rather than what the repository builds with. Those are different questions, and a dependencies block is where the difference gets lost.

UAsset Reference MCP: The Bottleneck Was Never the Language

Mon, 24 Aug 2026 03:00:00 +0000

Indexing a Unity project means parsing YAML looking for {fileID, guid, type} records. It is the most obviously compute-heavy step in the pipeline, which made it the obvious candidate for a native rewrite. So a Rust extractor was built, it produced byte-identical output, and it was benchmarked properly.

It parsed about 2.9x faster and delivered results about 38x slower. Then measuring the real project moved the bottleneck somewhere neither implementation touched.

The Obvious Optimization Was Obvious for the Wrong Reason

The proof of concept lives in rust/uasset-ref-extractor, parses with Rayon, and is invoked as a subprocess over NDJSON by a benchmark script. It was never wired into product code.

Against the same 2,000 prefab records, with every mode producing 2,000 outputs, 1,998 edges, zero unresolved references, and exact output parity:

Mode	End-to-end median	Extractor-only median
Node, 8 workers	3.146 ms	3.146 ms
Rust, 8 threads	119.852 ms	1.074 ms

The parse itself went from 3.146 ms to 1.074 ms. Delivering that parse cost roughly 118 ms of process startup plus NDJSON serialization, which the in-process Node path never pays.

That is not a result about Rust. Rust parsed faster, exactly as expected. It is a result about a subprocess being the wrong delivery shape for work measured in single-digit milliseconds. An in-process binding would erase the overhead entirely — which turns the interesting question into a different one. If the parse were free, how much would indexing actually save?

The Fixture That Said 3%, and the Fixture That Said 76%

This is the part worth telling straight, because both attempts to answer that question were wrong.

The repository’s own benchmark fixture generated 2,000 Unity-shaped prefab assets of about 100 bytes each, carrying one reference apiece. Measured against it at concurrency 8, total indexing was roughly 110 ms and the extraction phase roughly 40 ms, most of it file reads — the parse itself was around 3 ms. Removing parsing entirely would have saved under 3% of runtime.

That number was used to shelve the Rust port. It was also measuring the wrong thing: 100-byte single-reference files measure per-file overhead, not parse throughput. The fixture answered a question about open/read/close, and the question was about parsing.

So a denser fixture was built for the write-path benchmark, generating about 139 references per asset. Against that corpus, SQLite writes looked like roughly 76% of the work — a completely different conclusion, pointing at a completely different phase.

The real project has 0.89 references per asset. The second fixture was around 150x too dense, wrong in the opposite direction from the first.

Both synthetic corpora encoded an assumption about the shape of a Unity project, and both assumptions were wrong. Neither was a rhetorical setup; they were two real mistakes made in sequence, and the only thing that settled the question was measuring a project that actually exists.

What the Real Project Showed

The profile was captured against a real Unity project of 32,579 indexed assets and 28,842 edges, on macOS with 8 logical CPUs. The project’s own .asset-memory/index.db was never written to; every run used a scratch database.

At concurrency 8, medians over four runs with about 4% total spread:

Phase	Median	Share
scan	2963-3082 ms	~60%
extract (read + parse)	1631-1733 ms	~33%
write	267-338 ms	~6%
total	4964-5164 ms

Reference parsing alone, measured across the project’s 1,827 YAML assets totalling 128.8 MB, takes 485 ms serial — about 266 MB/s. Against a ~5,000 ms total, that is roughly 2% once parallelized.

The Node parser is not fast in absolute terms. It is simply not the bottleneck, and a 2.9x faster parser applied to 2% of runtime is a rounding error with a cross-compilation matrix attached.

Most of the Dominant Phase Was Not Filesystem Work

Scan was 60%, so scan is where the time was. Decomposing it is where the actual finding is.

Pure directory traversal across the project measured around 160 ms. Reading every .meta file measured around 400 ms. That is roughly 560 ms of real filesystem work inside a phase that reports 1,600-3,000 ms.

Around 65-80% of the dominant phase was not filesystem I/O at all. It was promise-scheduling overhead — the cost of concurrency pools nested per directory, one pool spawned per level of recursion, each one coordinating work that was mostly waiting anyway.

The bottleneck was coordination structure, in a language whose scheduler you do not rewrite by switching languages.

What Actually Got Faster

v0.4.0 ships bounded concurrency for scanning and reference extraction, with SQLite writes still transactional and serialized. On the repository fixture at concurrency 8 that measured about 2.7x total speedup with identical output.

Correctness was the gate, not the speedup. A full index at concurrency 1 and at concurrency 8 produces byte-identical assets and edges tables, verified by hashing the fully sorted tables rather than by comparing row counts.

The concurrency cap itself turned out to be the largest remaining measured win, and the reason is the same finding restated:

DEFAULT_INDEX_CONCURRENCY = Math.min(8, Math.max(2, availableParallelism()))

That is a CPU-count heuristic applied to a workload that is roughly 93% filesystem I/O. Workers spend their time waiting on syscalls, not computing, so throughput keeps improving well past the core count. On the real project, with edge counts identical across every run:

Concurrency	Median total	vs 8	CV
8 (current default cap)	4203 ms	1.00x	4.3%
16	3841 ms	1.09x	2.7%
32	3558 ms	1.18x	8.5%
48	3359 ms	1.25x	9.3%

The default cap did not change in this release. The gains above 16 carry 8-9% coefficient of variation, close to their own effect size, and every number here comes from one macOS machine. A spinning disk, a network share, or a virus scanner walking the same directories could reorder the phases entirely. So --concurrency <n> ships as a flag to tune per machine, and the default stays where it can be defended.

UV_THREADPOOL_SIZE was checked and is not the lever: raising it from 4 to 32 moved scan about 8% and total about 5%, near the noise floor.

The Write Path Was Measured Too, and Mostly Left Alone

The same benchmark ran nine variants of the write configuration against a dense corpus, interleaved across rounds with a discarded warm-up so drift hit every variant equally, and asserting row-count parity so a variant that lost rows could not read as a win.

WITHOUT ROWID on edges measured consistently slower at 0.92x — the key is four wide TEXT columns, so the b-tree rows are large. synchronous = NORMAL, foreign_keys = OFF, and a larger cache_size all landed within noise, and the first two buy nothing measurable in exchange for durability and integrity.

One finding holds independently of any timing: idx_edges_from is redundant. edges is keyed PRIMARY KEY (from_guid, to_guid, ref_kind, context), so from_guid is already the leftmost column of the primary key index, and the extra index costs write time and disk for no read benefit.

None of those write-path changes shipped in v0.4.0. They are measured candidates with their own validation still ahead, and the write phase is ~6% of runtime, so the ceiling on all of them together is small. Saying that plainly is cheaper than shipping a change whose benefit cannot be distinguished from noise.

The Decision Is Written Down So the Argument Happens Once

Keeping extraction in TypeScript is recorded as ADR 0020, with two conditions for revisiting, in order:

A phase breakdown from a real Unity project — not a synthetic fixture — showing that parsing is a materially larger share than measured here.
An in-process binding rather than a subprocess. The ~118 ms overhead is structural and cannot be tuned away.

If both ever hold, native extraction ships as prebuilt per-platform binaries selected at install time, never as a source build that requires a toolchain on a user’s machine.

The Rust crate was kept rather than deleted, on an unmerged branch. It is not built, not published, and not on any code path a user reaches — but the measurements in this post are only reproducible because it still exists, and a decision defended by numbers should stay re-runnable.

The lesson is not that Rust is slow, because it was not. It is that “the parser is the bottleneck” was a hypothesis that felt too obvious to test, and the two fixtures built to test it were each shaped by an assumption about Unity projects that the actual Unity project did not share.

UAsset Reference MCP: Looking at the Graph Instead of Querying It

Mon, 24 Aug 2026 02:00:00 +0000

UAsset Reference MCP v0.4.0 adds an interactive viewer for the asset graph. It renders the dependency graph in three modes, points at what already looks wrong, and starts with no arguments from anywhere inside a Unity project.

The first three releases made the graph queryable. find_references, get_dependencies, trace_path, and find_unused_assets all answer a question precisely, and all of them require the same thing first: a name. On a project with 32,579 indexed assets, naming the right asset is the hard part. Answering “what references BattleFloor.mat” is cheap once you already suspect BattleFloor.mat.

A Query Answers a Question You Already Have

The graph in that project holds 32,579 assets and 28,842 edges. There is no useful way to read that as a list. Sorting by reference count gives you the top of the list and nothing about shape. Sorting by path gives you the Project window, which is the view you already had when you got stuck.

What a developer usually wants before a refactor is not one answer but a direction: which corner of the project is dense, which assets sit at the center of everything, which references are already broken, which folders nothing points at. Those are shape questions, and the reason they are hard to ask through a query API is that you cannot name the answer in advance.

So v0.4.0 stops requiring the name. The viewer draws the graph, and the first thing it draws is a short list of things that already deserve attention.

The Attention Panel Answers the Unasked Question

The panel is deliberately narrow. It reports three categories, each one already computable from the index:

Broken references      edges whose target GUID resolves to nothing
Unused candidates      assets with no incoming serialized edge
Most referenced        dependency hubs, ranked by incoming edge count

Broken references are the least ambiguous. If an asset serialized a {fileID, guid, type} record and no asset in the graph owns that GUID, something was deleted or moved outside Unity, and the index can say so without judgment.

Unused candidates are a review signal, not a delete list, for the same reason described in the Addressables post: an asset with no incoming edge can still be loaded by an Addressables address or a Resources.Load string. The panel sorts those candidates by size, because the ones worth reviewing first are the ones costing the most.

Most-referenced assets are the opposite signal. They are the assets where a change is expensive, which makes them the assets worth looking at before planning one.

Clicking any row selects that asset in the graph, so the panel is an entry point into the picture rather than a separate report.

Three Renderings, One Graph

The viewer draws the same graph three ways:

2D    force-directed, inline SVG        cluster and density
DAG   layered hierarchy, inline SVG     direction of dependency
3D    three.js, loaded on demand        structure of a large neighborhood

2D and DAG are plain inline SVG, so they cost nothing beyond the page. 3D pulls in three.js, and it does so only when the mode is selected — the module is not on the initial load path.

The important part is what the modes do not mean. They are three ways to draw one graph, not three levels of detail. Switching to 3D does not reveal edges that 2D was hiding. DAG is useful when the question is “what flows into what” and 2D is useful when the question is “what is clumped together,” and both are reading the same rows from the same SQLite index.

The Node Budget Bounds the Drawing, Not the Index

A 32,000-node force layout is a hairball, and a hairball is not a visualization. The viewer keeps large projects readable with two controls.

Filters restrict the graph by asset type and by origin, where origin is project, package, or builtin — the same distinction the indexer records when it walks project assets, embedded and external UPM packages, and Unity’s built-in resources.

The node budget caps how many nodes are requested at all. It defaults to 320 and is clamped between 50 and 5,000:

setNodeBudget: (nodeBudget) =>
  set({ nodeBudget: Number.isFinite(nodeBudget) ? Math.max(50, Math.min(5000, Math.trunc(nodeBudget))) : 320 }),

The budget is a rendering bound, not an indexing bound. Nothing is dropped from .asset-memory/index.db, and no query result is silently truncated on the server’s behalf — the viewer asks for a bounded slice because a bounded slice is the only kind a person can read.

Starting It Takes No Path, No Port, and No Config

The viewer used to want a database path and a port. Both are now inferred.

Project discovery walks up from the working directory the way git finds a repository. A directory counts as a project scope if it already holds an index, or if it looks like a Unity project root:

export function isProjectRoot(dir: string, exists = existsSync): boolean {
  if (exists(join(dir, ".asset-memory"))) return true;
  return exists(join(dir, "Assets")) && exists(join(dir, "ProjectSettings"));
}

.asset-memory is checked first, so a project that has already been indexed is recognized even when its layout is unusual.

Port selection starts at 7777 and advances to the first free port. Previously a second viewer died on an unhandled EADDRINUSE; now it binds the next port and prints where it landed. If --port was passed explicitly and that port was taken, it says so rather than pretending.

The result is that the whole workflow is two commands from inside the project:

unity-asset-reference-mcp-index index .
unity-asset-reference-mcp-web

asset graph viewer → http://localhost:7777  (db: /path/to/UnityProject/.asset-memory/index.db)

--project <root> still works, and now matches the argument the MCP server and indexer already accept, so none of the three binaries asks the user to spell out .asset-memory/index.db.

Five Routes, and No New MCP Tools

The viewer is a client of the same HTTP API the tool already served. v0.4.0 adds five routes to support it:

/api/asset-detail
/api/broken-references
/api/graph
/api/index-status
/api/root-trace

The MCP tool count is unchanged at 15. Nothing about the agent-facing surface moved to make room for a UI, because the UI is reading the same index through the same query layer.

What It Does Not Do

The viewer is read-only. It does not edit, move, refactor, or delete anything in the Unity project, and it never writes to the index. It reports what the graph contains and leaves every production decision in the Editor where it belongs.

Two changes are worth knowing before upgrading. The new viewer is served at /, and the previous Cytoscape viewer is still bundled at /legacy.html. The server-less WASM viewer left the npm package: it exists to be opened directly from the filesystem, so it was charging every install roughly 706 KB of WASM that a server-backed install would never load. It is now a release-page download, asset-graph-viewer-static-<version>.zip, and nothing about that flavor itself changed.

Upgrading from 0.3.x needs nothing else. The index schema is still version 3, so an existing .asset-memory/index.db is read as-is.

Three releases of query tools were the right order to build this in. The graph had to be trustworthy before it was worth looking at. But a trustworthy graph you can only address by name is still a graph you have to already understand, and drawing it is the cheapest way to stop needing to.

UAsset Reference MCP: Indexing External Unity Packages

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

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 +0000

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 +0000

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.