threenative-asset-mcp 0.12.0 → 0.14.0

package/README.md

@@ -1,50 +1,67 @@
 # threenative-asset-mcp
 
-A [Model Context Protocol](https://modelcontextprotocol.io/) server for finding
-3D assets across [Fab](https://www.fab.com/),
-[Poly Haven](https://polyhaven.com/), [ambientCG](https://ambientcg.com/),
-[Smithsonian 3D](https://3d.si.edu/), [Sketchfab](https://sketchfab.com/), and a
-curated game-audio catalog spanning Sonniss, Kenney, Tallbeard, Scott Buckley,
-itch.io, Mixkit, Pixabay, Freesound, OpenGameArt, and Abstraction. It gives AI clients provider-scoped,
-structured search, asset metadata, category/filter discovery, downloadable file
-data, and guarded Fab downloads for directly available free files.
-
-The audio tools separate **source discovery** from **verified direct downloads**.
-All ten sources are described with license caveats and official browse pages;
-only packs with stable official URLs and known license metadata appear in the
-direct-download catalog. The initial downloadable set is Kenney Interface
-Sounds, Kenney Music Jingles, and all five Sonniss GDC 2026 archives.
-
-`fab_search_assets` defaults to free assets. This means Fab reported at least
-one free or effectively free license; it does not imply every license tier is
-free. Use `fab_get_asset` before making license or price claims.
-
-Poly Haven results are CC0 and explicitly labelled `Powered by Poly Haven`.
-`polyhaven_list_files` exposes official download URLs, hashes, sizes, and
-dependency relationships with pagination and resolution/format filters.
-
-> Status: experimental. Fab's `/i/*` JSON routes are undocumented and can
-> change or restrict automated access. Poly Haven provides a documented public
-> API, but clients must send a unique User-Agent and visibly credit Poly Haven.
-> Sketchfab licenses vary per model and download URLs require a user API token.
-> Review each provider's terms and each asset's license.
+[![npm version](https://img.shields.io/npm/v/threenative-asset-mcp)](https://www.npmjs.com/package/threenative-asset-mcp)
+[![Node.js requirement](https://img.shields.io/node/v/threenative-asset-mcp)](package.json)
+[![CI](https://img.shields.io/github/actions/workflow/status/ThreeNativeHQ/threenative-asset-mcp/ci.yml?branch=main&label=CI)](https://github.com/ThreeNativeHQ/threenative-asset-mcp/actions/workflows/ci.yml)
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI clients find, inspect and
+download game-ready 3D assets, textures, HDRIs, animations and audio. It gives each provider structured
+search, metadata and guarded downloads, and it converts owned Unreal/Fab packs and Unity Asset Store packages to GLB.
+
+> **Status: experimental.** Fab's `/i/*` JSON routes are undocumented and can change or restrict automated
+> access. Sketchfab licenses vary per model. Review each provider's terms and each asset's license.
+> Unreal and Unity support cover specific formats and verified cases; they do not certify whole packs.
+> Unity imports are verified on three real packs; real Unity Editor reference renders are not yet available.
+> Blendkit is optional and needs documented provider permission. Live Blendkit downloads remain **UNVERIFIED**.
+
+## Contents
+
+| I want to… | Read |
+| --- | --- |
+| Install it and connect my MCP host | [Install](#install) and [Host configuration](#mcp-host-configuration) below |
+| See every tool and how to chain them | [docs/tools.md](docs/tools.md) |
+| Generate or inspect game audio | [docs/audio.md](docs/audio.md) |
+| Import an Unreal / Fab pack as GLB | [docs/unreal-import.md](docs/unreal-import.md) |
+| Import a Unity Asset Store package as GLB | [docs/unity-import.md](docs/unity-import.md) |
+| Check which Unreal formats work | [docs/unreal-format-support.md](docs/unreal-format-support.md) |
+| Check which Unity formats work | [docs/unity-format-support.md](docs/unity-format-support.md) |
+| Load imported assets in Three.js | [docs/unreal-threejs-usage.md](docs/unreal-threejs-usage.md) |
+| Read what each importer version changed | [docs/unreal-importer-history.md](docs/unreal-importer-history.md) |
+| Set environment variables | [docs/configuration.md](docs/configuration.md) |
+| Understand provider rules, caching and TLS | [docs/providers.md](docs/providers.md) |
+| Fix an error, or learn what the browser profile touches | [docs/troubleshooting.md](docs/troubleshooting.md) |
+| Run the tests and CI checks | [docs/development.md](docs/development.md) |
+| Read the Fab API contract notes | [docs/fab-contract.md](docs/fab-contract.md) |
+| Use Blendkit (optional, permission required) | [docs/blendkit-integration.md](docs/blendkit-integration.md) |
+
+## Supported providers
+
+| Provider | Content | License | Needs |
+| --- | --- | --- | --- |
+| [Fab](https://www.fab.com/) | 3D, free-file downloads, owned Unreal packs | Per listing | FabCLI login for owned packs only |
+| [Poly Haven](https://polyhaven.com/) | HDRIs, textures, models | CC0 (API use needs a visible credit) | Nothing |
+| [ambientCG](https://ambientcg.com/) | Materials, HDRIs, decals, models | CC0 | Nothing |
+| [Smithsonian 3D](https://3d.si.edu/) | Open Access scanned models | Open Access | Nothing |
+| [Sketchfab](https://sketchfab.com/) | Public models | Varies per model | `SKETCHFAB_API_TOKEN` for downloads only |
+| [Kenney](https://kenney.nl/) | 3D packs, audio | CC0 | Nothing |
+| [itch.io](https://itch.io/) (curated) | Quaternius animations, KayKit, Brackeys VFX, Tallbeard music | CC0 | Nothing |
+| [Blendkit](docs/blendkit-integration.md) (optional) | Free models through your own Blendkit-Client | Private use only, never redistributed | Local Client plus `BLENDKIT_PROVIDER_PERMISSION` |
+| Game audio catalog | Sonniss, Kenney, Tallbeard, Scott Buckley, Mixkit, Pixabay, Freesound, OpenGameArt, Abstraction | Per source | `ELEVENLABS_API_KEY` for generation only |
+
+Fab search defaults to free assets, meaning at least one license tier is free. Call `fab_get_asset` before
+making license or price claims. More in [docs/providers.md](docs/providers.md).
 
 ## Requirements
 
 - Node.js 20.19 or newer
-- A local environment capable of running Playwright Chromium when Fab requests
-  browser verification
-- No Epic or Fab login is required or automated for search and free downloads.
-  `fab_import_asset` and `fab_list_owned` use your own FabCLI session; see
-  [Fab login for owned packs](#fab-login-for-owned-packs)
-- **On Linux, `g++`, `perl`, `zlib1g-dev`, `libpng-dev` and `libsdl2-dev`** for Unreal imports
-  of UE4.0–4.20 packs. UE Viewer's Linux prebuilt is a 32-bit binary that 64-bit-only
-  hosts cannot run, so the importer builds it from source once
-- **FFmpeg and FFprobe on `PATH`** for `audio_inspect_asset` and
-  `audio_generate_sound`. Without them nothing is decoded, and the tools report
-  that they could not check rather than reporting a pass.
-- An **ElevenLabs API key of your own** for `audio_generate_sound` only. Every
-  other tool, including local audio inspection, works without one.
+- Playwright Chromium, only when Fab requests browser verification
+- FFmpeg and FFprobe on `PATH` for the audio tools
+- Unreal imports on Linux also need build packages for older packs. Run `npm run doctor` for the list.
+  See [docs/unreal-import.md](docs/unreal-import.md).
+- Unity imports need Blender 4.5 LTS to read FBX models. The MCP downloads a pinned copy into its toolchain cache on first use.
+  See [docs/unity-import.md](docs/unity-import.md).
+
+No Epic or Fab login is needed for search and free downloads. The MCP never signs in for you.
 
 ## Install
 
@@ -59,21 +76,13 @@ For a local checkout:
 ```bash
 npm ci
 npm run browser:install
-npm run typecheck
-npm test
 npm run build
 node dist/index.js
 ```
 
-Playwright does not download Chromium as part of a normal package install. Run
-`npx -p playwright@1.62.0 playwright install chromium` once on the MCP host
-before relying on the browser fallback.
-
 ## MCP host configuration
 
-### Codex
-
-Add this to `~/.codex/config.toml`:
+Codex (`~/.codex/config.toml`):
 
 ```toml
 [mcp_servers.assets]
@@ -81,17 +90,7 @@ command = "npx"
 args = ["-y", "threenative-asset-mcp"]
 ```
 
-For a local build:
-
-```toml
-[mcp_servers.assets]
-command = "node"
-args = ["/absolute/path/to/threenative-asset-mcp/dist/index.js"]
-```
-
-### Claude Desktop
-
-Add a server entry to the Claude Desktop configuration:
+Claude Desktop:
 
 ```json
 {
@@ -104,9 +103,7 @@ Add a server entry to the Claude Desktop configuration:
 }
 ```
 
-### VS Code
-
-Create `.vscode/mcp.json`:
+VS Code (`.vscode/mcp.json`):
 
 ```json
 {
@@ -120,834 +117,72 @@ Create `.vscode/mcp.json`:
 }
 ```
 
-Restart the MCP host after changing its configuration.
-
-## MCP tools
-
-Fab:
-
-- `fab_search_assets` — searches public listings. `priceMode` defaults to
-  `free`; use `any` or `range` explicitly for paid results. Search payloads
-  carry no file formats, so there is no format filter; `fab_get_asset` reports
-  a listing's formats.
-- `fab_get_asset` — returns normalized public listing details and per-license
-  effective prices.
-- `fab_list_filters` — returns known public filter labels and slugs, including
-  an explicit warning when the versioned fallback is used.
-- `fab_list_limited_time_free` — reads only a separately verified curated
-  promotion surface. In production it extracts canonical listing UUIDs from
-  Fab's public `/limited-time-free` page through the dedicated browser, then
-  resolves them through the normal detail client; it never substitutes general
-  `is_free=1` search.
-- `fab_download_free_asset` — downloads one directly available free file into
-  the dedicated download directory after explicit Fab EULA acknowledgement. It
-  refuses purchase, acquisition, library-only, ambiguous, and unsafe-path
-  flows.
-- `asset_import_unreal` — converts an already-downloaded Unreal directory to
-  self-contained GLBs plus `import-report.json`; Unreal Engine is not required.
-  Cascade `ParticleSystem` and Niagara systems are exported as data-only
-  descriptors under `Effects/<system>-<hash>.<cascade|niagara>.json`, one per
-  canonical package and object path so two same-basename systems in different
-  folders stay distinct. No runtime plays them: each descriptor lists the
-  modules and inputs it does not carry, and a placed effect component points at
-  its descriptor through `import-report.json`. Effects with no exported
-  descriptor stay named in the report; the importer never reconstructs a
-  particle simulation.
-- `fab_import_asset` — downloads an owned listing through the user's existing
-  FabCLI session, then runs the same Unreal importer. It never signs in, claims,
-  or purchases an asset.
-
-Blendkit (through the user's own official Blendkit-Client; see
-[docs/blendkit-integration.md](docs/blendkit-integration.md)):
-
-- `blendkit_status` — local-only health: whether the Client runs on loopback,
-  its version and `export_glb` recipe, whether live access is enabled, and the
-  setup steps still missing. It never contacts Blendkit.
-- `blendkit_import_asset` — acquires one free Blendkit model through the Client,
-  converts it with the Client's bundled `export_glb` recipe under headless
-  Blender, inspects the GLB (meshes, triangles, PBR texture slots, size) and
-  writes a provenance file. It needs the item's license acknowledgement and
-  explicit project-use consent, and it refuses paid items and unknown licenses.
-  The output is private use only: the Blendkit Terms forbid open-format models
-  such as GLB in software and apply that to CC0-labelled items too. It never
-  goes into game builds, demos or starter kits, and `purpose: "redistribution"`
-  is always refused. Existing outputs are never overwritten. Live search and
-  import stay off until `BLENDKIT_PROVIDER_PERMISSION` is set. With it,
-  `asset_search` also searches Blendkit.
-
-Poly Haven:
-
-- `polyhaven_search_assets` — searches HDRIs, textures, and models by text,
-  type, and category, with relevance/popularity/date/name sorting and cursor
-  pagination.
-- `polyhaven_get_asset` — returns normalized metadata, attributes, authors,
-  dimensions, resolution, and CC0 licensing for one asset.
-- `polyhaven_list_categories` — returns category labels and counts for one
-  asset type.
-- `polyhaven_list_files` — returns the official file URLs, sizes, MD5 hashes,
-  and dependency relationships. Use `resolution` and `format` to select usable
-  variants; follow `nextCursor` until absent to retrieve every matching file.
-
-ambientCG:
-
-- `ambientcg_search_assets` — searches CC0 materials, HDRIs, substances,
-  decals, atlases, 3D models, images, brushes, terrains, and HDRI elements.
-- `ambientcg_get_asset` — returns metadata, maps, technique, dimensions,
-  statistics, and CC0 licensing.
-- `ambientcg_list_categories` — lists typed categories and asset counts.
-- `ambientcg_list_files` — returns official archives with variant attributes,
-  extensions, URLs, and byte sizes.
-
-Smithsonian 3D:
-
-- `smithsonian_search_assets` — searches Open Access models by text, format,
-  quality, owning unit, Draco compression, and glTF orientation compliance.
-- `smithsonian_get_asset` — groups the file-centric API response into one model
-  summary.
-- `smithsonian_list_files` — returns direct model files with format, quality,
-  compression, and orientation metadata.
-
-Sketchfab:
-
-- `sketchfab_search_models` — anonymously searches public models, defaulting to
-  downloadable results, and preserves author, geometry, archive, and license
-  metadata.
-- `sketchfab_get_model` — returns public detail and explicit Creative Commons
-  requirements.
-- `sketchfab_list_categories` — lists public category names and slugs.
-- `sketchfab_get_downloads` — uses `SKETCHFAB_API_TOKEN` to retrieve temporary
-  download URLs. It never stores the token or returns it in tool output.
-
-Game audio:
-
-- `audio_list_sources` — lists the ten supported audio libraries, best uses,
-  official browse pages, license/attribution cautions, and honest download
-  capability (`curated-direct` or `provider-page`).
-- `audio_search_assets` — searches only the curated packs with stable official
-  direct URLs. Results preserve license, commercial-use, attribution, source,
-  size (when known), and redistribution metadata.
-- `audio_download_asset` — downloads a catalog asset by ID after
-  `acceptLicense: true`. It uses an HTTPS host allowlist, validates every
-  redirect, streams with a byte cap, writes atomically without overwrite, and
-  returns the local path, byte size, and SHA-256.
-- `audio_inspect_asset` — measures one local WAV, Ogg, MP3, or FLAC with the
-  pinned `@threenative/playtest` inspector: decode integrity, silence floor,
-  peak ceiling, DC offset, a five-band spectrum, the loop seam of a **declared**
-  loop, and the requested duration, plus a spectrogram PNG. Needs no ElevenLabs
-  key and never modifies or repairs the file. Optionally compares prompt and
-  emotional tone when local CLAP is provisioned.
-- `audio_generate_sound` — **spends ElevenLabs credits.** Generates one sound
-  effect or ambience from a prompt using *your own* `ELEVENLABS_API_KEY`, saves
-  the original response plus a PCM16 WAV, and runs the same inspection
-  automatically. Reusing a `requestId` returns the saved result instead of
-  charging again.
-
-### Generating a sound
-
-The loop is **generate once → inspect → revise the one property that failed →
-explicitly generate again.** There is no best-of-N retry: every generation is a
-separate billable invocation you ask for on purpose.
-
-Describe source, action, material, distance, and timing. A useful brief:
-
-> One short metal latch closing, close microphone, dry recording, single event
-> with natural decay, no speech or music.
-
-These are prompting conventions absorbed from ElevenLabs' own
-[sound-effects skill](https://github.com/elevenlabs/skills/blob/9edcbd4b80ed57b8e07a3f86ea520333969fbc3c/sound-effects/SKILL.md)
-(MIT, reviewed at commit `9edcbd4b`), which is linked and attributed rather than
-installed. They are conventions, not guaranteed exclusion controls.
-
-`audio_generate_sound` requires `ELEVENLABS_API_KEY` in the server environment.
-It is never bundled, defaulted, or logged: without your own key the tool fails
-with `AUDIO_GENERATE_NO_CREDENTIALS` and an instruction to set one, while the
-catalog and inspection tools keep working normally.
-
-What the inspection does and does not tell you:
-
-| It answers | It does not answer |
-| --- | --- |
-| Is it broken, silent, clipped, DC-offset, or the wrong duration? | Is it a *good* sound? |
-| Does a declared loop click at the wrap? | Does it suit this scene? |
-| Is the frequency content inside bounds *you* supplied? | Is the mix right? |
-
-`artisticQuality` is always `"unverified"`. There is no `soundsGood` flag and no
-single quality score. `recommendation: "audition"` means the technical checks
-passed and every requested check completed — it means *go listen to it*, not
-*ship it*. A definite technical failure recommends `"reject"`; a warning, a
-possible mismatch, or an incomplete requested check recommends `"review"`.
-
-If asset compilation rewrites the bytes, inspect the compiled output before
-describing that output as checked.
-
-### Optional local CLAP setup
-
-Prompt fit and emotion fit are **off by default** (`semantic: "off"`) and add no
-dependency to `npm install`. To enable them:
-
-```sh
-python3 -m venv ~/.venvs/clap
-~/.venvs/clap/bin/pip install "laion-clap==1.1.6" "torch==2.4.1" \
-    "torchaudio==2.4.1" "librosa==0.10.2.post1" "numpy<2"
-# Download 630k-audioset-best.pt from the LAION-AI/CLAP releases and check its hash.
-export AUDIO_CLAP_CHECKPOINT=/path/to/630k-audioset-best.pt
-export AUDIO_CLAP_PYTHON=~/.venvs/clap/bin/python
-```
+For a local build, use `command = "node"` and the absolute path to `dist/index.js`. Restart the host after
+changing its configuration.
 
-Nothing is downloaded implicitly and no GPU is required. With `semantic: "clap"`
-and no provisioned model, you get the technical result plus an explicit
-unavailable semantic result and this instruction — never a semantic pass. A
-generation that requests `semantic: "clap"` is refused in preflight, before
-spending, when the model is missing.
-
-Scores are cosine similarities used as **supporting evidence**, never
-probabilities or quality grades. The emotion check builds otherwise identical
-hypotheses — `The sound of {sourceDescription}, with a {mood} emotional tone.` —
-so only the mood clause differs, and **this use of CLAP is a proposed heuristic,
-not a demonstrated emotion-recognition capability**: mood status stays
-`unverified` until the held-out emotion calibration qualifies your domain. Check
-the CLAP code and checkpoint licensing separately before redistributing either.
-
-Curated itch.io packs:
-
-- `itch_list_downloads` — resolves a fresh no-account download page and lists
-  upload IDs, filenames, sizes, CC0 terms, and pack-specific cautions without
-  exposing the signed page token.
-- `itch_download_asset` — resolves a fresh 60-second signed file URL and streams
-  the selected upload into guarded storage after `acceptLicense: true`. Signed
-  URLs are not returned. The initial catalog covers Tallbeard Music Loop
-  Bundle, Quaternius Universal Animation Libraries 1 and 2, Brackeys VFX
-  Bundle, and KayKit Platformer.
-- `asset_list_bundle_entries` — reads the remote ZIP directory with HTTP byte
-  ranges and returns individual paths and sizes without downloading the archive.
-- `asset_download_bundle_entry` — range-fetches and extracts one selected file,
-  caches it with a SHA-256 sidecar, and never downloads unrelated bundle files.
-- `asset_list_bundle_animations` — range-fetches only an aggregate GLB and lists
-  its named animation clips. For Quaternius, it automatically prefers the
-  standard non-root-motion GLB.
-- `asset_download_bundle_animation` — exports one named animation as a valid
-  animation-only GLB, removing unrelated clips, meshes, materials, and textures.
-  The cached aggregate GLB is reused across requests.
-
-Unified source and download routing:
-
-- `asset_list_sources` — returns only **agent-ready sources by default** across
-  3D, textures, HDRIs, animations, VFX, 2D, UI, icons, fonts, and audio. An
-  agent-ready source has an MCP download tool and requires no manual browser,
-  login, checkout, donation prompt, or paywall. Pass `agentReadyOnly: false` to
-  inspect the broader research directory, including package-manager, Git, and
-  provider-page sources that are not yet integrated.
-- `asset_search_sources` — filters that directory by text, category, access
-  mode, and license tag (`cc0`, `cc-by`, `mit`, and others), while preserving
-  the same agent-ready-only default.
-- `asset_download_file` — streams a direct URL previously returned by
-  `polyhaven_list_files`, `ambientcg_list_files`, `smithsonian_list_files`, or
-  the Game-icons.net bulk archive or Kenney Particle Pack entry into guarded
-  local storage. Provider hosts and URL shapes are allowlisted, redirects are
-  revalidated, existing files are never overwritten, and the result includes
-  SHA-256.
-
-The additive `asset_search` tool searches individual `3d-model`, `texture`,
-`hdri` and `animation` candidates across supported clients. It reports each
-provider, bounded results and local continuation actions. Unknown prices fail
-`freeOnly`; unknown rights fail explicit commercial-use/attribution filters.
-Fab remains a specialized action and generic Sketchfab uses anonymous metadata,
-without authenticated acquisition. Existing tools retain their public names.
-
-Use `asset_get` with the returned stable `assetId` to inspect current terms and
-available variants. It prefers GLB, then glTF with its supplied dependencies;
-explicit unavailable formats return alternatives. The read-only call returns an
-expiring `planToken`, required relative files and acknowledgement information.
-A plan is not consent. Call `asset_download` with that token and explicit
-`acceptLicense: true` only after reviewing the terms. Optional `maxBytes` can
-only tighten the configured cap. Changed terms/files invalidate the plan.
-
-Acquisition stages originals under `ASSET_DOWNLOAD_DIR/acquisitions`, verifies
-checksums and all glTF buffer/texture references, then atomically publishes a
-complete directory with `asset.acquisition.json`. Replays verify cached bytes
-and provenance; a corrupt cache fails rather than being silently accepted.
-Receipts preserve asset attribution separately from Poly Haven API credit.
-No transfer/signed URLs or credentials enter the new public plan or receipt.
-Archives stay archives with `requiresExtraction: true`; runtime readiness is
-`unverified`. Acquiring originals does not change or adopt assets into a project.
-
-Kenney 3D packs are enabled by default; `ASSET_ENABLE_KENNEY=0` disables the
-generic adapter. Each query uses one official listing page and at most three
-item detail checks,
-paces requests, verifies item CC0/free/official-ZIP evidence and never crawls
-or extracts archives. One official Mini Dungeon archive was qualified through
-the packed public MCP on 2026-10-06. Broader catalog coverage and runtime import
-remain unverified; ordinary tests use hand-authored local fixtures.
-
-Recommended agent flow:
-
-1. Call `asset_search_sources` with the requested category/query. Its default
-   result set is guaranteed to contain only agent-ready sources.
-2. Call the returned `searchTool` or `detailTool` when present.
-3. Resolve variants with the returned `filesTool`.
-4. Call the returned `downloadTool` with `acceptLicense: true`.
-5. For aggregate Quaternius animation libraries, skip whole-pack download:
-   `itch_list_downloads` → `asset_list_bundle_animations` →
-   `asset_download_bundle_animation`.
-
-This is intentionally a short MCP tool chain rather than a fake universal URL:
-each provider keeps its real search/variant semantics, while source routing and
-the no-manual-flow guarantee stay uniform.
-
-All discovery tools are read-only. Download tools write only within their
-dedicated local directories and never purchase, add to cart or library,
-wishlist, sign in, or overwrite an existing download. Audio packs remain
-subject to their source license; raw redistribution is not implied by download.
-
-## Unreal import support
-
-The importer writes the same GLB/report layout for cooked and uncooked inputs.
-It auto-provisions UE Viewer for package metadata, textures, and cooked render
-data. For uncooked UE4 editor meshes it also provisions the separate GPL-3.0+
-`unreal-assets-to-glb` CLI in an isolated Python virtual environment and invokes
-it out of process. Modern UE5 packages rejected by UE Viewer use a pinned,
-out-of-process CUE4Parse adapter. Set `THREENATIVE_TOOLCHAIN_AUTOINSTALL=0` to
-require manually installed tools instead.
-
-**Supported, verified and missing formats:** [`docs/unreal-format-support.md`](docs/unreal-format-support.md)
-is the tracking ledger for every Unreal 4 and 5 class, with its status, evidence and gaps.
-
-### Fab login for owned packs
-
-`fab_import_asset` and `fab_list_owned` read your Fab library through
-[FabCLI](https://github.com/zirklerite/FabCLI), which the importer installs on first
-use. The MCP never signs in for you. Log in once; the session is kept in the OS
-keyring (Secret Service on Linux) and lasts about 90 days:
-
-```bash
-~/.cache/threenative-asset-mcp/toolchain/fabcli/fabcli auth login           # opens a login window
-~/.cache/threenative-asset-mcp/toolchain/fabcli/fabcli auth login --manual  # no window: paste a code
-~/.cache/threenative-asset-mcp/toolchain/fabcli/fabcli auth status
-```
+## Tools at a glance
 
-`--manual` reuses the browser where you are already signed in to Epic. FabCLI prints a
-`epicgames.com/id/login?redirectUrl=…` link; open it there, copy `authorizationCode` from the
-JSON the page shows, and paste it into the prompt within a few minutes. It needs an
-interactive terminal. In Claude Code, run it with a `!` prefix. Never paste the code into an
-untrusted service: it grants full access to the Epic account.
-
-`fab_list_owned` lists each listing's Unreal artifacts separately (`artifacts[]`: `artifactId`,
-`engineVersions`, `oldestEngine`, decoder `route`, `targetPlatforms`). An artifact's format is its
-oldest listed engine, and that picks the decoder. When a listing has several artifacts and
-`fab_import_asset` gets neither `engine` nor `artifactId`, it takes the best route (CUE4Parse, then
-the MeshDescription converter, then UE Viewer; the newest source format breaks a tie) and says so
-in the report `warnings`. Pass `artifactId` or `engine` to override.
-
-**Graph-only colour.** Some Unreal materials compute BaseColor in the material graph (layered
-masters that blend colour textures by mask channels and tint them), so no texture binding can
-reproduce them. A section left without a base colour is baked from its graph: the pack's editor
-package is read with CUE4Parse, a closed node set is evaluated per texel, and the result is a
-base-colour PNG with `source: "graph"` in the section's bindings. The bake is `exact` only when
-every node is understood; engine layer functions that are not in the pack, a mesh without vertex
-colours standing in white, and a UV set the importer drops make it `heuristic`, and the section's
-`graph` field names each approximation. View-dependent nodes (`Fresnel`, `DepthFade`, `TwoSidedSign`)
-stand in as a recorded approximation: a bake has no camera, so `Fresnel` is its mean over a sphere's visible
-surface, `DepthFade` is fully faded in and `TwoSidedSign` is the front face. Nodes it cannot evaluate (for
-example `ReflectionVectorWS` feeding a cubemap lookup, or `Time`) leave the neutral fallback and are listed
-under `graph.unsupportedNodes`.
-The first bake installs the CUE4Parse converter and its private .NET SDK (hundreds of MB, once);
-pass `graphBake: false` to the importer, or set `THREENATIVE_TOOLCHAIN_AUTOINSTALL=0`, to skip it.
-`fab_import_asset` also skips it when its environment has `THREENATIVE_GRAPH_BAKE=0` (the parity
-sweep's `--no-graph-bake` uses this to produce a baseline).
-
-| Input | Current result |
+| Group | Tools |
 | --- | --- |
-| Cooked loose UE4 static meshes and textures | GLB geometry, LOD sections, embedded textures, and common PBR reconstruction |
-| Cooked loose UE4 skeletal meshes and standalone animation packages | Standard skinned GLB; joints, weights, inverse-bind matrices, and existing clips are preserved; ActorX PSA clips are attached by case-insensitive bone name when at least 80% of tracks match, without duplicating an existing clip name |
-| UE5 `AnimSequence`, blend spaces, aim offsets, montages and composites | UE5.0–5.5 conventional clips and UE5.4+ FK Sequencer-model clips become glTF animations and attach by bone name; blend spaces, aim offsets, montages and composites become `Animation/<name>.json` with typed axes, mirror flags and resolved section starts, and `<clip>.clip.json` sidecars preserve notifies, curves and sync markers. Current release 0.12.0 / importer124 / converter `.584.10.2` fresh public/native proof retains 325 selected UE5.4 clips and 7 UE5.8 clips. Independent actual UE5.8.3 full-pose comparison passes 7 clips, 8 GLB-document comparisons and 72,233 keys (actual current maximum 0.000264° against 0.5°); scope is serialized raw bones, excluding only 2 independently declared mannequin virtuals and no face bones. Static poses remain intact; non-FK graphs remain reported. Current independent replay and all four local repository gates pass (PRD-596); selected clips do not prove whole-pack or generated-virtual-bone support. |
-| Uncooked UE4 `FMeshDescription` static meshes (object versions 517–522) | GLB geometry with centimetres converted to metres; verified on Fab Office Pack Vol.1 (47/47 meshes) |
-| Uncooked UE5 editor static meshes (source models only, no render data) | Requested payload-backed `FMeshDescription` source models are decoded from the package trailer's Oodle payloads as `Models/<name>_LOD<n>.glb`; `BuildScale3D` from `SourceModels[0].BuildSettings` is applied on the modern route. Source models Unreal generates at build time are reported as generated and are not faked. Verified on Fab's Megascans European Hornbeam UE5.1 artifact for LOD0/1/2 |
-| Uncooked UE4.0–4.20 static and skeletal meshes (object versions below 517) | Exported by UE Viewer from the editor source data, with materials, skins, and ActorX clips like cooked packages. Verified on Fab packs from UE4.10 to UE4.20: Modular Building Set (129 meshes), Animal Variety Pack (6 rigged animals, 146 clips), STF Landscape Pro 2.0 (61), Power Plant (65), and a UE4.19 fern pack (38) |
-| Standalone `Texture2D` packages | Collision-free source-relative PNGs under `textures/`; duplicate Unreal basenames are exported independently instead of overwriting one another |
-| `Texture2D` with an `RGBA16F` source | Raw little-endian half-float RGBA binaries and a versioned JSON manifest under `data-textures/`, promoted together under the package's qualified path. Values are stored, not decoded: no PivotPainter, classifier, source UV, graph or WPO semantics, and no material binding. The PNG exporters cannot encode the format, so the importer asks the converter for this route after a legacy PNG export fails; a UE 4.x pack needs its `engine` (`UE_4.19`), since the default detector reads every UE4 package as the latest UE4. Loaded in the browser with `threenative-asset-mcp/data-texture` (see Three.js usage) |
-| `TextureCube` environment maps | Collision-free 2:1 equirectangular PNG or lossless Radiance HDR files under `cubemaps/`; CUE4Parse decodes cooked faces, while editor `TSF_BGRE8` source art retains its lighting range without Unreal Engine |
-| `Texture2DArray`, `TextureCubeArray`, and `VolumeTexture` | Collision-free RGBA8 slice data plus JSON dimensions under `textures3d/`; use `DataArrayTexture` for arrays and `Data3DTexture` for volumes. Cube-array faces remain ordered in groups of six for custom shaders. Floating-point/HDR stacks are rejected rather than reduced to RGBA8 |
-| Standalone `Material` and `MaterialInstanceConstant` packages | One directly loadable `Materials/UnrealMaterialLibrary.glb`; each source-relative swatch name is collision-free, follows parent instances, embeds resolved texture inputs, and applies common base-color/emissive vectors plus roughness/metallic/opacity scalars |
-| Standalone `SoundWave` packages | Collision-free WAV/Ogg/MP3/FLAC files under `audio/`; modern UE5 editor source WAVs and cooked formats exposed by CUE4Parse feed the same report path, verified through Three.js `AudioLoader` |
-| Skeletal and static mesh sockets, static-mesh simple collision, `PhysicsAsset`, and `SoundCue` graphs | Socket nodes (`socket:<name>`) under the joint their bone names (or the mesh node for a static socket); simple collision on the mesh node's `extras.unrealCollision` and in `Collision/<package>.json`; physics bodies, constraints (limits, motions and drives) and collision-disabled pairs in metre-scale `Physics/<asset>.json`, referenced from the skinned mesh node; and each SoundCue graph in `Audio/<cue>.cue.json` with every `WavePlayer` leaf rewritten to the exported audio file or reported as a missing wave. A UE4 package that holds one of these classes routes to the CUE4Parse adapter, which UE Viewer cannot decode; an ordinary UE4 mesh whose only gameplay signal is a `BodySetup` or a cross-package PhysicsAsset/Skeleton reference joins the adapter run for its metadata while keeping its verified UE Viewer geometry route |
-| Runtime `Font` and inline `FontFace` packages | Validated TTF/OTF faces under collision-free `fonts/` paths; direct SFNT and legacy multi-block zlib `FontBulkData` are supported without Unreal Engine, with family/style/weight metadata for the browser `FontFace` API |
-| Offline `Font` packages | Pre-baked glyph pages and serialized `FontCharacter` rectangles become collision-safe atlas PNGs plus BMFont-compatible JSON under `bitmap-fonts/`; Unicode remaps, baseline metrics, kerning, page indices, and distance-field metadata are retained for Three.js bitmap/SDF text |
-| Paper2D `PaperSprite` and `PaperFlipbook` packages | Each sprite becomes a self-contained, unlit GLB with exact baked triangles and a cropped atlas region; flipbooks become JSON manifests preserving FPS and per-frame run lengths. Verified in Three.js on a real UE5.2 Paper2D project without Unreal Engine |
-| Paper2D `PaperTileSet` and `PaperTileMap` packages | Populated layers become indexed, unlit GLB quads with atlas UVs, empty cells omitted, layer order retained, and packed horizontal/vertical/diagonal tile flips decoded. Placed tile maps and inherited Blueprint flipbook components are reconstructed in modern UE5 levels |
-| Paper2D grouped sprites and `TextRenderActor` | Grouped sprite instances become `EXT_mesh_gpu_instancing` batches over shared sprite GLBs; text becomes unlit glyph geometry from offline `UFont` atlas pages, preserving alignment, colour, world size, and placement |
-| `DataTable`, `StringTable`, `CurveTable`, and float/vector/colour curves | Collision-free, directly fetchable JSON under `data/`; row names, typed fields, localized strings, asset references, and rich-curve keys/tangents are retained |
-| Modern UE5 loose static meshes, skeletal meshes, `Texture2D`, Material, and `.umap` packages rejected by UE Viewer | CUE4Parse converts directly to the same output/report pipeline; verified with UE5.5 cooked static geometry, UE5 editor skeletal geometry, Oodle-compressed UE5.3 editor texture source art, and a UE5.2 Paper2D map. Editor source art is restored to display colour: `TSF_BGRA8` sources are stored with red and blue swapped, and sRGB-sampled `TSF_RGBA16` sources are linear, so both are corrected (checked against UE Viewer's export of the same textures from the UE4.27 artifact). Cooked packages using unversioned properties require one matching `.usmap` file beside the imported tree |
-| Separate roughness/metalness, solid palette maps, glass, and mirrors | Packed glTF PBR maps or explicit material fallbacks; extra graph inputs remain named sidecars |
-| UE4 `.umap` placement, direct lights, and serialized Blueprint component templates (object versions 517–522) | Directly loadable scene GLB plus a transform/source manifest; repeated actors instance shared meshes; inherited mesh/light defaults are merged into placed instances; directional, point, and spot lights use `KHR_lights_punctual` |
-| UE5 World Partition `.umap` external actors | The selected level export loads `__ExternalActors__` packages with the same provider mount and complete map path into the scene; external actor/object packages belonging to maps outside the import remain reported as skipped. Real-pack verification is tracked by PRD-598 |
-| Standalone modern UE5 Blueprint prefabs | Serialized static/skeletal mesh and light component defaults become directly loadable scene GLBs; referenced meshes, transforms, skins, and bone hierarchies are retained, while bytecode is explicitly reported and never executed |
-| UE4 ISM/HISM and painted static-mesh foliage placement | Bulk-serialized instance matrices become `EXT_mesh_gpu_instancing`, which Three.js `GLTFLoader` loads as GPU-instanced meshes |
-| UE4 editor `LandscapeComponent` heightfields | Package-relative compressed BGRA8 heightmaps become indexed terrain meshes with decoded normals, component transforms, and original material names |
-| UE5 level `Landscape` and `LandscapeStreamingProxy` heightfields | CUE4Parse follows every proxy component, restores trailer-backed BGRA8 source pixels, and emits indexed terrain meshes with decoded heights, normals, proxy-root transforms, and material identity |
-| ActorX per-frame bone scale, dynamic Blueprint bytecode/construction scripts, Paper Terrain/spline deformation, and Nanite-only data without a fallback mesh | Detected or reported honestly; scene-level omissions are listed in `scenes[].omittedActors`, and Blueprint bytecode is never executed by the importer |
-| Arbitrary Unreal shader graphs | Recoverable PBR inputs become standard glTF materials. Reports mark materials as degraded when shader connections are unavailable, even if every section has a texture; section `limitations` explain omitted layering, graph UV transforms, subsurface lighting, normal strength, and deformation |
-| Encrypted Pak/IoStore | Unsupported without user-supplied keys and archive extraction; never reported as a complete conversion |
-
-Importer version 49 also respects material-instance override flags and modern
-parameter names. Contradictory texture samples duplicated across distinct mesh
-section families are repaired only when referenced texture families are
-unambiguous in the same export namespace. These bindings remain heuristic.
-Separate same-resolution opacity maps can supply base-colour alpha without
-altering RGB; different source dimensions are currently unsupported. Existing
-cached conversions are invalidated. A textured result does not certify the
-appearance of the original Unreal shader.
-
-Importer version 51 uses adaptive PNG row filtering for composed opacity maps,
-preserving the previous encoder's decoded RGBA and PNG metadata. Untouched textures
-retain their original bytes; their profiles, bit depth, and metadata are not
-re-encoded for storage savings.
-
-Importer version 56 stops a colour parameter's zero alpha from becoming the base
-colour factor's opacity (a `Tint` of `A=0` clipped every pixel of a masked grass
-card, so the GLB drew nothing), binds a masked or translucent material's separate
-opacity map (`Opacity=` or an `Other` named `*_Opacity*`) as the base colour's alpha
-heuristically, and composes an opacity map of another resolution when the aspect
-ratio matches. A sweep sheet tile that renders nothing although Unreal has a
-thumbnail for it is recorded under the entry's `sheet.warnings`.
-
-Importer version 58 stops a texture-parameter default from inventing a glTF slot from a
-texture UE Viewer already named as another output. A parameter can exist without being
-wired to its own output, so when its default texture is already the resolved `.mat`'s
-Diffuse (or Normal, and so on) it is a shared placeholder, not a second live slot (Old
-West - VOL 5 Town Props declared an unused `Emissive` default equal to the Fill albedo,
-which painted every dark-wood model with a flat grey emissive wash). Real parameter
-overrides and `.mat`-named Emissive slots still bind, a default whose texture the `.mat`
-left in `Other[]` still recovers its slot by parameter name, and a `.mat` that names no
-slot (the modern converter's `Other[n]` references only) still falls back to the
-collected defaults.
-
-Importer version 60 recovers the cut-out of a masked foliage card whose UE Viewer `.mat`
-resolves `Opacity=` to the albedo itself, which has no alpha. When the material references a
-packed `<stem>_AORO` map (AO / roughness / opacity in R / G / B) beside that albedo, the map's
-blue channel becomes the base colour's alpha. Temperate Vegetation: conifer Bushes & Saplings
-had every needle card render as a solid rectangle (Pine_GroundTwig_01 as a full quad with the
-needle atlas painted inside it) because the mask was never applied. The binding is heuristic
-and named in the section's limitations; an opaque material, an unrelated texture stem, or a
-map the pack did not export is left alone.
-
-Importer version 59 applies a material instance's base-colour tint vector even when its
-parameter name carries extra words. Old West - VOL 5 Town Props overrides both
-`Albedo Color Tint (Base)` (a bright global multiplier) and `Base Color Tint (Mask)` (the
-dark cloth colour) on a master that tints its albedo through a mask; the exact names missed
-both, so every curtain kept `baseColorFactor` [1,1,1] and rendered the untinted light-grey
-albedo. When both a global base multiplier and a mask colour are overridden, the mask tint is
-the surface colour that shows through. Only an instance's own override is matched broadly, so
-a master's placeholder default (the master's red `Base Color Tint (Mask)`) never paints an
-un-tinted instance; a lone mask tint with no global multiplier (the 03a curtain, whose editor
-mesh thumbnail is the untinted albedo) is left alone, and a `RockTint`-style name with no
-colour token beside `Tint` is left to the graph baker.
-
-Importer version 57 gives a mesh the `.mat` / `.props.txt` that sit beside it when two
-packages share an object name (a pack with `MI_Rock_Inst` in two folders bound one
-folder's normal map to the other's meshes); with none beside the mesh the pick is named
-in the section's limitations. The graph bake now evaluates `ObjectScale` (1),
-`PerInstanceRandom` (0.5) and `ObjectPositionWS` (origin) as named heuristic
-approximations and `SplitComponents` exactly, which lets layered cliff-rock masters bake
-their colour texture instead of falling back to neutral grey. The parity S4 check no
-longer lets a 90% colour share hide sections whose graph is known to carry colour.
-
-Legacy instance sidecars without override flags retain inherited settings for
-ambiguous opaque, false, and zero defaults. Their non-default values retain the
-previous behavior; missing flags are reported as a material limitation.
-
-Importer version 50 reads a bounded authored-material subset from tagged UE4
-object-version 516 packages (legacy -7, UE3 864, licensee 0). Exact source paths
-and closest flagged static overrides select the active branches before reduction.
-Mesh-only package selection still loads needed material parents from the source
-file inventory without exporting unrelated packages; lookups stay within the same
-Content namespace. Mesh import-table material references resolve duplicate source
-basenames by exact object path. Multiple matching references refuse source routing;
-a unique basename fallback reports its unresolved mesh routing.
-Reroutes, scalar constants/parameters and representable multiplication recover
-scalar roughness; glTF normalization retains the raw authored value in the report.
-An authored scalar replaces any earlier roughness texture contribution while
-retaining its packed metallic channel. Source functions, Specular conversion,
-foliage shading and unsupported sampling remain explicit limitations.
-
-AO.R is attached only with explicit `Texture2D.SRGB=false`, a serialized linear
-sampler mode (`LinearColor`, `LinearGrayscale` or `Masks`), and source coordinates
-matching the sampler of the currently bound albedo. Its existing glTF coordinate
-mapping is reused only after the selected albedo attaches; an incoming unrelated
-base texture cannot establish that reference. Omitted Unreal defaults remain
-unresolved. Unknown color
-interpretation, ambiguous source paths or exported PNG basenames, nonidentity AO
-multipliers and unproved UV transforms withhold AO, including earlier filename
-guesses. Texture metadata is
-read lazily for the selected AO candidate; unrelated large images are untouched
-by the material reader. Other package profiles keep prior reconstruction with a
-named source-reader limitation. Cached conversions are invalidated.
-
-The Buffer reader is independently implemented from the tagged package, property
-and native-input schemas at [CUE4Parse commit b4e9544](https://github.com/FabianFG/CUE4Parse/tree/b4e95441bcf0c975eb3adb68c0fb44c740c2cf62/CUE4Parse/UE4).
-Native expression inputs require verified Core=2 and Framework=33 custom versions;
-tagged instances without native inputs do not require these versions. Native
-trailers and omitted class defaults are outside its scope. This subset does not
-certify original Unreal appearance.
-
-Automatic uncooked conversion needs Python 3 with `venv` and `pip`. A Linux
-source build fallback for UE Viewer additionally needs `git`, `g++`, `perl`,
-zlib, and SDL2 development headers. Unreal import currently runs on Linux and
-Windows; use the path overrides below for preinstalled executables.
-
-Load a reconstructed level with the normal Three.js loader — no Unreal runtime
-or custom `.uasset` loader is involved:
-
-```js
-new GLTFLoader().load("assets/fab/<listing>/Scenes/DemoMap.glb", ({ scene }) => {
-  threeScene.add(scene);
-});
-```
-
-Standalone materials use that same loader. Find a swatch by the report's
-`materialAssets[].libraryName`, then assign its standard Three.js material:
-
-```js
-new GLTFLoader().load("assets/fab/<listing>/Materials/UnrealMaterialLibrary.glb", ({ scene }) => {
-  const swatch = scene.getObjectByName(materialAsset.libraryName);
-  targetMesh.material = swatch.material;
-});
-```
-
-Sound waves use Three.js directly as well:
-
-```js
-const buffer = await new THREE.AudioLoader().loadAsync(audioAsset.file);
-sound.setBuffer(buffer);
-```
-
-Structured data is ordinary runtime JSON — no Unreal object loader is needed:
-
-```js
-const table = await fetch(dataAsset.json).then((response) => response.json());
-const defaultAmmo = table.Rows.Default;
-```
+| Unified | `asset_search_sources`, `asset_search`, `asset_get`, `asset_download`, `asset_download_file` |
+| Fab | `fab_search_assets`, `fab_get_asset`, `fab_download_free_asset`, `fab_list_owned`, `fab_import_asset` |
+| Poly Haven | `polyhaven_search_assets`, `polyhaven_get_asset`, `polyhaven_list_files` |
+| ambientCG | `ambientcg_search_assets`, `ambientcg_get_asset`, `ambientcg_list_files` |
+| Smithsonian 3D | `smithsonian_search_assets`, `smithsonian_get_asset`, `smithsonian_list_files` |
+| Sketchfab | `sketchfab_search_models`, `sketchfab_get_model`, `sketchfab_get_downloads` |
+| Blendkit | `blendkit_status`, `blendkit_import_asset` |
+| Audio | `audio_search_assets`, `audio_download_asset`, `audio_inspect_asset`, `audio_generate_sound` |
+| itch.io bundles | `itch_list_downloads`, `asset_list_bundle_entries`, `asset_download_bundle_animation` |
+| Unreal | `asset_import_unreal` |
+| Unity | `unity_list_packages`, `asset_import_unity` |
 
-Fonts can back Three.js canvas textures or text libraries that accept web fonts:
+Recommended flow: `asset_search_sources` → the returned search tool → the returned files tool → the returned
+download tool with `acceptLicense: true`. All discovery tools are read-only. Download tools write only inside
+their own directories, and never purchase, sign in or overwrite. Full list: [docs/tools.md](docs/tools.md).
 
-```js
-const face = new FontFace(font.family, `url(${font.file})`, {
-  style: font.fontStyle,
-  weight: String(font.weight),
-});
-await face.load();
-document.fonts.add(face);
-// Draw with this family on a canvas, then pass the canvas to THREE.CanvasTexture.
-```
-
-Paper2D flipbooks reference ordinary GLBs. Select a frame using the manifest's
-`frameRun` and `framesPerSecond`, then show its loaded scene:
-
-```js
-const flipbook = await fetch(report.flipbooks[0].manifest).then((response) => response.json());
-const frames = await Promise.all(flipbook.frames.map((frame) => loader.loadAsync(frame.glb)));
-const tick = Math.floor(elapsedSeconds * flipbook.framesPerSecond) % flipbook.frameCount;
-let end = 0;
-frames.forEach(({ scene }, index) => {
-  end += flipbook.frames[index].frameRun;
-  scene.visible = tick < end && tick >= end - flipbook.frames[index].frameRun;
-});
-```
-
-Cubemaps use the standard Three.js equirectangular environment path:
-
-```js
-const loader = cubemapAsset.dynamicRange === "hdr" ? new RGBELoader() : new THREE.TextureLoader();
-const environment = await loader.loadAsync(cubemapAsset.file);
-environment.mapping = THREE.EquirectangularReflectionMapping;
-threeScene.environment = environment;
-```
-
-Multidimensional textures use the report's explicit Three.js type:
-
-```js
-const metadata = await fetch(textureStack.manifest).then((response) => response.json());
-const bytes = new Uint8Array(await fetch(textureStack.data).then((response) => response.arrayBuffer()));
-const texture = metadata.threeTexture === "Data3DTexture"
-  ? new THREE.Data3DTexture(bytes, metadata.width, metadata.height, metadata.depth)
-  : new THREE.DataArrayTexture(bytes, metadata.width, metadata.height, metadata.depth);
-texture.format = THREE.RGBAFormat;
-texture.type = THREE.UnsignedByteType;
-texture.needsUpdate = true;
-```
-
-Raw `RGBA16F` textures load through the package's `./data-texture` subpath. The loader
-checks the manifest against the binary (exact length, SHA-256, finite samples) and refuses the
-load, rather than skipping a check, when one cannot run. The source package cannot be fetched
-or re-hashed in a browser, so pin the value the report gives for the texture's source package:
-
-```js
-import { loadRgba16fDataTexture } from "threenative-asset-mcp/data-texture";
-
-const { texture, manifest } = await loadRgba16fDataTexture(
-  new URL(dataTexture.manifest, reportBaseUrl),
-  { expectedSourceSha256: dataTexture.sourceSha256 },
-);
-// texture: THREE.DataTexture, RGBAFormat, HalfFloatType, NoColorSpace, no mipmaps.
-// The stored values are unchanged: negative, HDR, subnormal and alpha bits reach the shader as stored.
-```
-
-`loadRgba16fDataTexture` needs an absolute URL and `crypto.subtle`, so serve the page over
-https or from localhost. Its limit is the import's: the texture holds linear half-float
-samples with no decoding, so a material must decide what they mean.
-
-Installation-only Unreal `BasicShapes/Plane` references are generated locally
-when the asset pack does not contain that mesh. Rectangular area lights are
-preserved in scene metadata and approximated as punctual point lights because
-glTF's standard punctual-light extension has no area-light type.
-
-### Parity sweep and material metadata dumps
-
-`npm run parity:fab` imports every owned Fab artifact and scores it against its source package
-(`scorecard.json`). `--export-metadata <dir>` also writes one replayable material dump per pack;
-replay them with `FAB_METADATA_DIR=<dir> npx vitest run tests/fab-metadata.test.ts`. Dumps hold
-licensed pack names and are local-only: never commit them.
-
-Set `THREENATIVE_UNREAL_PREVIEW_REFERENCE=/path/to/reference.json` to light the comparison sheets (`parity:fab` and
-`scripts/fidelity-sheet.ts`) with a local version-1 reference profile: radiance and Grid binaries beside the JSON, each
-checked by SHA-256. It is read once per command, and an invalid profile stops the run before any download. Unset, the
-sheets use the approximation and say so. Each picture records what lit it (`identity` in `picture-lighting.json`,
-`sheets/<label>.json` and the scorecard entry). `--resume --sheets` refuses a kept sheet drawn otherwise: resume into a
-new `--out`, or add `--no-sheets`. Profiles and binaries derive from licensed packs: keep them local-only, never commit them.
-
-## Configuration
-
-| Variable                        | Default                                            | Purpose                                                  |
-| ------------------------------- | -------------------------------------------------- | -------------------------------------------------------- |
-| `FAB_DIRECT_TIMEOUT_MS`         | `20000`                                            | Direct JSON request timeout.                             |
-| `FAB_BROWSER_TIMEOUT_MS`        | `30000`                                            | Dedicated browser request timeout.                       |
-| `FAB_BROWSER_MANUAL_TIMEOUT_MS` | `10000`                                            | Headed-mode grace period for visible verification.       |
-| `FAB_BROWSER_HEADLESS`          | `true`                                             | Set to `0` temporarily for manual verification.          |
-| `FAB_BROWSER_PROFILE_DIR`       | OS state directory under `threenative-asset-mcp/fab-browser-profile` | MCP-owned Fab browser state.                    |
-| `FAB_DOWNLOAD_DIR`              | `~/Downloads/threenative-asset-mcp/fab`            | Dedicated directory for Fab free-file downloads.         |
-| `FAB_MAX_DOWNLOAD_BYTES`        | `2147483648`                                       | Maximum accepted download size in bytes.                 |
-| `FAB_DOWNLOAD_TIMEOUT_MS`       | `600000`                                           | Total timeout for one file download.                     |
-| `FAB_CURL_IMPERSONATE`          | auto-detected on `PATH`                            | curl-impersonate wrapper override; `0`/`off` disables.   |
-| `FAB_MIN_REQUEST_INTERVAL_MS`   | `1000`                                             | Minimum spacing between direct upstream requests.        |
-| `FAB_LOG_LEVEL`                 | `warn`                                             | `debug`, `info`, `warn`, or `error`.                     |
-| `FAB_LOG_QUERIES`               | `false`                                            | Set to `1` only if query text may be written to logs.    |
-| `SKETCHFAB_API_TOKEN`           | unset                                              | User token for temporary Sketchfab download URLs.        |
-| `AUDIO_DOWNLOAD_DIR`            | `~/Downloads/threenative-asset-mcp/audio`          | Dedicated directory for curated audio downloads.         |
-| `AUDIO_MAX_DOWNLOAD_BYTES`      | `10737418240`                                      | Maximum accepted bytes per audio archive (10 GiB).       |
-| `AUDIO_DOWNLOAD_TIMEOUT_MS`     | `1800000`                                          | Total timeout for one audio download (30 minutes).       |
-| `ELEVENLABS_API_KEY`            | unset                                              | **Your own** key; required only by `audio_generate_sound`. Never bundled or logged. |
-| `AUDIO_INSPECT_ROOTS`           | the audio dir plus the launch directory            | Extra `:`-separated roots `audio_inspect_asset` may read. |
-| `AUDIO_CLAP_PYTHON`             | unset                                              | Interpreter with LAION-CLAP installed; enables `semantic: "clap"`. |
-| `AUDIO_CLAP_CHECKPOINT`         | unset                                              | Path to the `630k-audioset-best.pt` checkpoint.          |
-| `AUDIO_CLAP_CHECKPOINT_SHA256`  | unset                                              | Optional pin; a mismatched checkpoint is refused.        |
-| `ASSET_DOWNLOAD_DIR`            | `~/Downloads/threenative-asset-mcp/assets`         | Dedicated directory for direct provider downloads.       |
-| `ASSET_MAX_DOWNLOAD_BYTES`      | `10737418240`                                      | Maximum bytes per direct file or complete generic acquisition (10 GiB).       |
-| `ASSET_DOWNLOAD_TIMEOUT_MS`     | `1800000`                                          | Total timeout for one provider download (30 minutes).    |
-| `ASSET_ENABLE_KENNEY`           | `1`                                                | Bounded official Kenney 3D-pack discovery; `0` disables it. Other values fail initialization. |
-| `ASSET_SEARCH_CONCURRENCY`      | `4`                                                | Concurrent provider operations per search; range 1–4. |
-| `ASSET_PROVIDER_TIMEOUT_MS`     | `8000`                                             | Provider deadline; range 1–30000 milliseconds. |
-| `ASSET_SEARCH_TIMEOUT_MS`       | `10000`                                            | Aggregate search/metadata deadline including queue time; range 1–60000. |
-| `ASSET_PLAN_TTL_MS`             | `300000`                                           | Acquisition-plan TTL; range 1–900000; at most 100 bounded plans. |
-| `BLENDKIT_CLIENT_URL`           | `http://127.0.0.1:62485`                           | Loopback address of the user's official Blendkit-Client; other hosts fail. |
-| `BLENDKIT_PROVIDER_PERMISSION`  | unset                                              | Citation of documented Blendkit permission for this use. Unset keeps live Blendkit search and import off. |
-| `BLENDKIT_API_KEY`              | unset                                              | **Your own** key from the official Blendkit sign-in; sent only to the loopback Client, never logged or returned. |
-| `BLENDKIT_BLENDER_PATH`         | Client-stored Blender                              | Absolute path to the Blender that runs the `export_glb` recipe. |
-| `THREENATIVE_TOOLCHAIN_AUTOINSTALL` | `1`                                            | Set to `0` to disable first-use external-tool installs.  |
-| `THREENATIVE_TOOLCHAIN_DIR`     | OS cache under `threenative-asset-mcp/toolchain`   | UE Viewer, FabCLI, and uncooked-converter cache.          |
-| `THREENATIVE_UMODEL_PATH`       | auto-detected/provisioned                           | Absolute path to a UE Viewer executable override.        |
-| `THREENATIVE_UNCOOKED_CONVERTER_PATH` | auto-detected/provisioned                     | Absolute path to `unreal-assets-to-glb`.                  |
-| `THREENATIVE_FABCLI_PATH`       | auto-detected/provisioned                           | Absolute path to FabCLI; login remains user-controlled.  |
-
-Direct requests are spaced at least `FAB_MIN_REQUEST_INTERVAL_MS` apart. Only
-HTTP 429, 502, 503, and 504 are retried, at most twice, with backoff and
-`Retry-After` support. Challenges, access denial, invalid input, missing
-listings, and schema drift are never retried by the transport; a
-curl-impersonate challenge response is additionally retried inside the
-impersonation wrapper with longer, jittered waits before the browser fallback
-is engaged.
-
-## Browser-fingerprint TLS (curl-impersonate)
-
-Fab's `/i/*` JSON routes sit behind Cloudflare bot management that challenges
-Node's default TLS fingerprint — including plain `fetch` from this MCP and
-headless Chromium — while real browser fingerprints pass. When a
-[curl-impersonate](https://github.com/lwthiker/curl-impersonate) wrapper (for
-example `curl_chrome146`) is available on the host `PATH`, the server performs
-all anonymous JSON reads through it and no browser is needed for search,
-detail, or download resolution. Set `FAB_CURL_IMPERSONATE=0` to force the old
-behavior (plain Node fetch plus the Playwright fallback), or point it at a
-specific wrapper binary.
-
-Downloads of free files resolve entirely through the anonymous JSON contract
-when possible: listing detail → `asset-formats/{format}` file listing →
-`download-info` signed URL → guarded file write. The signed distribution URL
-is validated against an exact Epic distribution-host allowlist before use.
-Only when the direct path is challenged does the server fall back to the
-guarded browser click flow below.
-
-Process-local cache TTLs are five minutes for search, fifteen minutes for
-listing details, six hours for taxonomy data, and ten minutes for promotions.
-The shared LRU is capped at 500 entries and is cleared on process exit.
-
-## Poly Haven API behavior
-
-Poly Haven requests go only to `https://api.polyhaven.com`, with the required
-`threenative-asset-mcp` User-Agent. Asset lists are cached for 15 minutes and
-details, categories, and file trees are cached for up to one hour. Returned file
-URLs are accepted only from `https://dl.polyhaven.org`.
-
-The live API is free for personal and commercial use, but use of the API
-requires a visible Poly Haven credit. The assets themselves are CC0. This MCP
-includes `provider`, `license`, and `attribution` fields so downstream clients
-can preserve that distinction. See the
-[official API page](https://polyhaven.com/our-api) and
-[API documentation](https://api.polyhaven.com/).
-
-## Other provider behavior
-
-ambientCG uses its anonymous, read-only v3 API. Its files are CC0 and its API
-exposes searchable metadata, categories, and downloadable variants.
-
-Smithsonian uses the anonymous Smithsonian 3D file-search API. Files exposed by
-that API are part of Smithsonian Open Access; the MCP retains direct source
-URLs and format/quality metadata.
-
-Sketchfab public search, categories, and model detail do not require a token.
-The download endpoint requires a token belonging to the user, configured
-through `SKETCHFAB_API_TOKEN`. The token is sent only in the Sketchfab
-`Authorization` header, is never logged or persisted, and is not included in
-MCP responses. Sketchfab models use different Creative Commons licenses; always
-inspect `license.requirements` before use.
-
-Audio direct downloads are catalog-ID based; the MCP does not accept arbitrary
-URLs. Official Kenney downloads are restricted to `kenney.nl` and Sonniss GDC
-downloads to `downloads.sonniss.com`, including redirect revalidation. Sources
-without a stable, verified direct contract remain discoverable as
-`provider-page` instead of being falsely presented as one-click downloads.
-
-The generic direct downloader is intentionally narrower than an arbitrary URL
-fetcher. It accepts only official Poly Haven, ambientCG, Smithsonian,
-Game-icons.net, and curated Kenney URL contracts. The itch.io downloader uses
-fresh signed mirror URLs internally but never exposes them. Sketchfab signed
-downloads are exposed through `sketchfab_get_downloads` but are not persisted
-by the generic downloader because their temporary CDN hosts vary and require
-the user's token-backed session. Provider-page-only sources stay provider-page-only until a stable,
-license-safe download contract is verified.
-
-## Dedicated browser profile and privacy
-
-When a direct anonymous request receives a Cloudflare challenge, the server may
-open Playwright Chromium with a dedicated MCP-owned profile. It never attaches
-to, copies, or reads the user's normal Chrome/Edge/Chromium profile, cookie
-database, local storage, passwords, or Epic session.
-
-If the tool returns `FAB_BROWSER_ATTENTION_REQUIRED`, run the same MCP command
-once with `FAB_BROWSER_HEADLESS=0`. The MCP opens its dedicated Fab homepage at
-startup, so complete any visible verification before calling the tool. A tool
-call allows an additional `FAB_BROWSER_MANUAL_TIMEOUT_MS` grace period, then
-returns `FAB_BROWSER_ATTENTION_REQUIRED` rather than exceeding typical MCP
-client timeouts. Close the MCP process after verification and return to headless
-mode. The server does not solve or bypass challenges.
-
-Browser process startup is capped at ten seconds. On a host without a working
-graphical session, headed mode returns `FAB_UPSTREAM_UNAVAILABLE` instead of
-hanging an MCP call; run the manual release gate on a graphical host.
-
-To clear browser-owned Fab state, stop every `threenative-asset-mcp` process and
-move only the dedicated directory reported by your configuration out of
-service. The default on Linux can be cleared recoverably with:
-
-```bash
-mv -- "${XDG_STATE_HOME:-$HOME/.local/state}/threenative-asset-mcp/fab-browser-profile" \
-  "${XDG_STATE_HOME:-$HOME/.local/state}/threenative-asset-mcp/fab-browser-profile.cleared"
-```
-
-Do not point `FAB_BROWSER_PROFILE_DIR` at a normal browser profile. The server
-rejects known normal-profile locations.
-
-The MCP has no analytics or remote telemetry. Application logs are structured
-JSON written only to stderr; stdout is reserved for MCP JSON-RPC. Search query
-text is omitted from logs unless `FAB_LOG_QUERIES=1`. Raw upstream bodies,
-headers, cookies, tokens, stack traces, and browser profile paths are not logged
-or returned to the model.
-
-## Troubleshooting
+`audio_generate_sound` spends **your own** ElevenLabs credits. Nothing else costs money.
 
-`FAB_CHALLENGE` or `FAB_BROWSER_ATTENTION_REQUIRED`
-: Fab asked for browser verification. First check whether a curl-impersonate
-wrapper is installed (`FAB_LOG_LEVEL=info` logs `fab_impersonate_enabled`
-when active). Otherwise use the headed dedicated-profile step above. If
-verification continues to fail, stop; do not copy a signed-in browser
-session.
+## Unreal / Fab import
 
-`FAB_RATE_LIMITED`
-: Wait for `retryAfterSeconds` when present. The MCP already applied its bounded
-retries.
+`fab_import_asset` and `asset_import_unreal` turn an Unreal pack (UE4 and UE5, cooked or uncooked) into
+self-contained GLBs plus an `import-report.json`. Unreal Engine is not required. The importer reports what it
+could not convert instead of claiming a full conversion. Setup, login and output types:
+[docs/unreal-import.md](docs/unreal-import.md). Per-class status: [docs/unreal-format-support.md](docs/unreal-format-support.md).
 
-`FAB_UPSTREAM_CHANGED`
-: Fab's undocumented response changed. Re-run the sanitized contract probe and
-update normalization and fixtures before continuing.
+## Unity Asset Store import
 
-`FAB_UPSTREAM_UNAVAILABLE`
-: Fab is unavailable, or a currently unverified discovery contract was
-  intentionally disabled.
+`asset_import_unity` turns a `.unitypackage`, a UPM tarball or a Unity project folder you already have into
+self-contained GLBs (one per model, plus one per prefab with its materials bound) and an `import-report.json`.
+`unity_list_packages` lists the packages your Unity Editor cached. `fab_import_asset` hands a Unity-format Fab
+artifact to the same importer when FabCLI exposes it. The MCP never signs in to Unity, never calls Unity
+services and never decrypts a download. Unity is not required. The importer reports what it could not convert,
+such as custom shaders, which keep their saved colour and base texture. Setup and output:
+[docs/unity-import.md](docs/unity-import.md). Per-class status: [docs/unity-format-support.md](docs/unity-format-support.md).
 
-The MCP host shows no tools
-: Build first, confirm the configured path is absolute, and run
-`npm run inspect`. Logs belong on stderr; any non-JSON stdout is a bug.
+## Privacy
 
-## Verification
+No analytics or remote telemetry. Logs go to stderr only and omit query text unless `FAB_LOG_QUERIES=1`. The
+dedicated browser profile never reads your normal browser profile or Epic session.
+See [docs/troubleshooting.md](docs/troubleshooting.md).
 
-GitHub-hosted CI checks pull requests, pushes to main and manual runs on the
-minimum supported Node 20.19 and Node 24. It installs the committed npm lockfile,
-runs typecheck/build, deterministic fixtures and actual built/npm-packed stdio
-consumers. Reports distinguish intentionally conditional proprietary Unreal
-fixtures. No provider live probes, credentials, package publishing or account
-changes run in that workflow. Local CI-equivalent commands are:
+## Development
 
 ```bash
-npm ci
-npm run build
-npm run typecheck
-npm run test:ci
-npm run test:smoke
+npm ci && npm run typecheck && npm test
 ```
 
-The suite needs Chromium (`npx playwright install --with-deps chromium`),
-ffmpeg and Python with NumPy/Pillow for local render/audio fixtures. Live probes
-remain separate from deterministic acceptance tests.
+`npm run doctor` lists missing local prerequisites. CI details and live probes: [docs/development.md](docs/development.md).
 
-Run `npm run doctor` to see which of these your host has. Each missing tool is
-listed with its install command. Locally, a suite whose tool is missing is
-skipped with that command as the reason. With `CI=true` it fails instead.
-Add `--toolchain` to also require what the Unreal importers need on a fresh
-Linux host, or `--toolchain-only` to check only that group.
+## Contributing and help
 
+Start with [Troubleshooting](docs/troubleshooting.md) and `npm run doctor`. Report bugs through
+[GitHub issues](https://github.com/ThreeNativeHQ/threenative-asset-mcp/issues) with the package version, Node
+version, OS, affected tool and sanitized reproduction steps. Never include credentials, signed download URLs or
+licensed asset files. Before a pull request, read [AGENTS.md](AGENTS.md) and run the checks in
+[docs/development.md](docs/development.md).
 
-```bash
-npm ci
-npm run browser:install
-npm run typecheck
-npm test
-npm run build
-npm pack --dry-run
-npm run inspect
-npm run test:providers:live
-```
-
-Live checks are opt-in because they contact Fab:
-
-```bash
-npm run test:live
-```
+## License
 
-This runs the real anonymous search, cursor, detail, and dedicated-browser
-contract probe. It exits nonzero when Fab challenges the clean browser or the
-required contract cannot be verified. Live verification must remain anonymous,
-concurrency-one, capped and paced. It must never acquire, purchase, wishlist,
-download, or automatically solve a challenge.
-
-`npm run test:providers:live` launches the compiled stdio MCP and exercises live
-search, detail, categories, and file discovery for ambientCG, Smithsonian 3D,
-and Sketchfab. If `SKETCHFAB_API_TOKEN` is configured it also verifies the
-authenticated download endpoint; otherwise it verifies the explicit
-authentication-required response.
+The package declares **UNLICENSED** in [package.json](package.json). No open-source license is granted.
+Downloaded assets and external tools keep their own licenses and terms. Public availability does not grant
+redistribution rights.