threenative-asset-mcp 0.9.5 → 0.11.0

package/README.md

@@ -34,7 +34,12 @@ dependency relationships with pagination and resolution/format filters.
 - 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
+- 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.
@@ -140,6 +145,14 @@ Fab:
   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.
@@ -316,6 +329,38 @@ Unified source and download routing:
   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
@@ -346,18 +391,64 @@ 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.
 
+### 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
+```
+
+`--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 |
 | --- | --- |
 | 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 cooked clips become glTF animations through CUE4Parse 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 each clip gets `<clip>.clip.json` notifies, curves and sync markers. A clip with no raw or compressed bone data is reported from its package's own evidence (a `DataModel` export, a `ControlRig` model, or `NumFrames`) instead of exporting a bind pose |
 | 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) | LOD0 of the `FMeshDescription` source model is decoded from the package trailer's Oodle payloads, with the cooked glTF writer's axes, scale, and material naming. Verified on Fab's Megascans Common Hazel and European Hornbeam UE5.1 artifacts: triangle counts match the UE4.27 decoder of the same scans exactly |
 | 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 |
@@ -371,9 +462,110 @@ require manually installed tools instead.
 | 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 |
 | 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 | Common PBR inputs become standard glTF materials; graph inputs with no glTF counterpart remain named in the report instead of being silently discarded |
+| 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
@@ -460,11 +652,45 @@ 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                                                  |
@@ -491,8 +717,13 @@ glTF's standard punctual-light extension has no area-light type.
 | `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 accepted bytes per provider file (10 GiB).       |
+| `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. |
 | `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.        |
@@ -639,6 +870,32 @@ The MCP host shows no tools
 
 ## Verification
 
+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:
+
+```bash
+npm ci
+npm run build
+npm run typecheck
+npm run test:ci
+npm run test:smoke
+```
+
+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.
+
+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.
+
+
 ```bash
 npm ci
 npm run browser:install

package/dist/ambientcg/client.d.ts

@@ -1,3 +1,4 @@
+import { type MetadataContext } from "../discovery/metadata.js";
 export declare const AMBIENTCG_TYPES: readonly ["material", "hdri", "substance", "decal", "atlas", "3d-model", "plain-image", "brush", "terrain", "hdri-element"];
 export type AmbientCgAssetType = (typeof AMBIENTCG_TYPES)[number];
 export interface AmbientCgDownload {
@@ -39,11 +40,13 @@ export interface AmbientCgCategory {
 export declare class AmbientCgClientError extends Error {
     readonly code: "AMBIENTCG_INVALID_INPUT" | "AMBIENTCG_NOT_FOUND" | "AMBIENTCG_RATE_LIMITED" | "AMBIENTCG_UPSTREAM_UNAVAILABLE" | "AMBIENTCG_UPSTREAM_CHANGED";
     readonly retryable: boolean;
-    constructor(code: "AMBIENTCG_INVALID_INPUT" | "AMBIENTCG_NOT_FOUND" | "AMBIENTCG_RATE_LIMITED" | "AMBIENTCG_UPSTREAM_UNAVAILABLE" | "AMBIENTCG_UPSTREAM_CHANGED", message: string, retryable?: boolean);
+    readonly retryAfter?: string | undefined;
+    constructor(code: "AMBIENTCG_INVALID_INPUT" | "AMBIENTCG_NOT_FOUND" | "AMBIENTCG_RATE_LIMITED" | "AMBIENTCG_UPSTREAM_UNAVAILABLE" | "AMBIENTCG_UPSTREAM_CHANGED", message: string, retryable?: boolean, retryAfter?: string | undefined);
 }
 type FetchLike = typeof fetch;
 export declare class AmbientCgClient {
     private readonly fetchImpl;
+    private readonly requests;
     constructor(fetchImpl?: FetchLike);
     private request;
     search(input: {
@@ -53,9 +56,9 @@ export declare class AmbientCgClient {
         limit: number;
         offset: number;
         includeDownloads?: boolean;
-    }): Promise<AmbientCgSearchResult>;
-    getAsset(id: string): Promise<AmbientCgAsset>;
-    listCategories(): Promise<AmbientCgCategory[]>;
+    }, context?: MetadataContext): Promise<AmbientCgSearchResult>;
+    getAsset(id: string, context?: MetadataContext): Promise<AmbientCgAsset>;
+    listCategories(context?: MetadataContext): Promise<AmbientCgCategory[]>;
 }
 export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/ambientcg/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/ambientcg/client.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,eAAe,YAC1B,UAAU,EACV,MAAM,EACN,WAAW,EACX,OAAO,EACP,OAAO,EACP,UAAU,EACV,aAAa,EACb,OAAO,EACP,SAAS,EACT,cAAc,CACN,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,kBAAkB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,iBAAiB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,kBAAkB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,IAAI,EACT,yBAAyB,GACzB,qBAAqB,GACrB,wBAAwB,GACxB,gCAAgC,GAChC,4BAA4B;IAEhC,QAAQ,CAAC,SAAS;IARpB,YACW,IAAI,EACT,yBAAyB,GACzB,qBAAqB,GACrB,wBAAwB,GACxB,gCAAgC,GAChC,4BAA4B,EAChC,OAAO,EAAE,MAAM,EACN,SAAS,UAAQ,EAI3B;CACF;AAED,KAAK,SAAS,GAAG,OAAO,KAAK,CAAC;AAuH9B,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,SAAS;IAAtC,YAA6B,SAAS,GAAE,SAAiB,EAAI;YAE/C,OAAO;IAyCf,MAAM,CAAC,KAAK,EAAE;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,kBAAkB,CAAC;QAC1B,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;QAC5E,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAwCjC;IAEK,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAgBlD;IAEK,cAAc,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAkBnD;CACF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/ambientcg/client.ts"],"names":[],"mappings":"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"}

package/dist/ambientcg/client.js

@@ -1,3 +1,4 @@
+import { MetadataRequests, readMetadata } from "../discovery/metadata.js";
 const API_BASE = "https://ambientcg.com/api/v3";
 const TIMEOUT_MS = 20_000;
 export const AMBIENTCG_TYPES = [
@@ -15,10 +16,12 @@ export const AMBIENTCG_TYPES = [
 export class AmbientCgClientError extends Error {
     code;
     retryable;
-    constructor(code, message, retryable = false) {
+    retryAfter;
+    constructor(code, message, retryable = false, retryAfter) {
         super(message);
         this.code = code;
         this.retryable = retryable;
+        this.retryAfter = retryAfter;
         this.name = "AmbientCgClientError";
     }
 }
@@ -28,18 +31,13 @@ function record(value) {
         : undefined;
 }
 function text(value, max = 12_000) {
-    return typeof value === "string" && value.length > 0
-        ? value.slice(0, max)
-        : undefined;
+    return typeof value === "string" && value.length > 0 ? value.slice(0, max) : undefined;
 }
 function number(value) {
-    return typeof value === "number" && Number.isFinite(value)
-        ? value
-        : undefined;
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 function isType(value) {
-    return (typeof value === "string" &&
-        AMBIENTCG_TYPES.includes(value));
+    return typeof value === "string" && AMBIENTCG_TYPES.includes(value);
 }
 function normalizeDownload(value) {
     const item = record(value);
@@ -47,16 +45,27 @@ function normalizeDownload(value) {
     const extension = text(item?.extension, 20);
     const url = text(item?.url, 2_048);
     const sizeBytes = number(item?.size);
-    if (!attributes || !extension || !url || sizeBytes === undefined)
-        return;
+    if (!attributes ||
+        !extension ||
+        !url ||
+        sizeBytes === undefined ||
+        !Number.isSafeInteger(sizeBytes) ||
+        sizeBytes < 0) {
+        throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_CHANGED", "ambientCG returned invalid download metadata.");
+    }
     try {
         const parsed = new URL(url);
-        if (parsed.protocol !== "https:" || parsed.hostname !== "ambientcg.com") {
-            return;
+        if (parsed.protocol !== "https:" ||
+            parsed.hostname !== "ambientcg.com" ||
+            parsed.username ||
+            parsed.password ||
+            parsed.port ||
+            parsed.hash) {
+            throw new Error("Unsafe provider file URL.");
         }
     }
     catch {
-        return;
+        throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_CHANGED", "ambientCG returned an unsafe download URL.");
     }
     return { attributes, extension, url, sizeBytes };
 }
@@ -69,10 +78,7 @@ function normalizeAsset(value) {
     if (!id || !isType(type) || !title || !url) {
         throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_CHANGED", "ambientCG returned invalid asset metadata.");
     }
-    const descriptions = [
-        text(item?.longDescription),
-        text(item?.shortDescription),
-    ];
+    const descriptions = [text(item?.longDescription), text(item?.shortDescription)];
     const description = descriptions.find((entry) => entry !== undefined);
     const statistics = record(item?.downloadStatistics);
     const dimensions = record(item?.dimensions);
@@ -80,6 +86,8 @@ function normalizeAsset(value) {
     const thumbnailUrl = text(thumbnails?.["512-WEBP"], 2_048) ??
         text(thumbnails?.["512-PNG"], 2_048) ??
         text(thumbnails?.["256-WEBP"], 2_048);
+    if (Array.isArray(item?.downloads) && item.downloads.length > 500)
+        throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_CHANGED", "ambientCG download variants exceed the entry limit.");
     const downloads = Array.isArray(item?.downloads)
         ? item.downloads
             .map(normalizeDownload)
@@ -105,12 +113,8 @@ function normalizeAsset(value) {
             : [],
         downloads,
         ...(description ? { description } : {}),
-        ...(text(item?.releaseDate, 20)
-            ? { releaseDate: text(item?.releaseDate, 20) }
-            : {}),
-        ...(text(item?.technique, 100)
-            ? { technique: text(item?.technique, 100) }
-            : {}),
+        ...(text(item?.releaseDate, 20) ? { releaseDate: text(item?.releaseDate, 20) } : {}),
+        ...(text(item?.technique, 100) ? { technique: text(item?.technique, 100) } : {}),
         ...(number(statistics?.total) !== undefined
             ? { downloadCount: number(statistics?.total) }
             : {}),
@@ -131,37 +135,44 @@ function normalizeAsset(value) {
 }
 export class AmbientCgClient {
     fetchImpl;
+    requests = new MetadataRequests();
     constructor(fetchImpl = fetch) {
         this.fetchImpl = fetchImpl;
     }
-    async request(path) {
-        let response;
-        try {
-            response = await this.fetchImpl(`${API_BASE}${path}`, {
-                headers: {
-                    accept: "application/json",
-                    "user-agent": "threenative-asset-mcp/0.4.0",
-                },
-                signal: AbortSignal.timeout(TIMEOUT_MS),
-            });
-        }
-        catch {
-            throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_UNAVAILABLE", "ambientCG could not be reached.", true);
-        }
-        if (response.status === 429) {
-            throw new AmbientCgClientError("AMBIENTCG_RATE_LIMITED", "ambientCG rate-limited the request.", true);
-        }
-        if (!response.ok) {
-            throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_UNAVAILABLE", `ambientCG returned HTTP ${response.status}.`, response.status >= 500);
-        }
-        try {
-            return (await response.json());
-        }
-        catch {
-            throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_CHANGED", "ambientCG returned invalid JSON.");
-        }
+    async request(path, context = {}) {
+        return this.requests.run(path, context.signal, async (callerSignal) => {
+            const signal = AbortSignal.any([callerSignal, AbortSignal.timeout(TIMEOUT_MS)]);
+            let response;
+            try {
+                response = await this.fetchImpl(`${API_BASE}${path}`, {
+                    headers: {
+                        accept: "application/json",
+                        "user-agent": "threenative-asset-mcp/0.4.0",
+                    },
+                    signal,
+                    redirect: "error",
+                });
+            }
+            catch {
+                throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_UNAVAILABLE", "ambientCG could not be reached.", true);
+            }
+            if (!response.ok)
+                await response.body?.cancel();
+            if (response.status === 429) {
+                throw new AmbientCgClientError("AMBIENTCG_RATE_LIMITED", "ambientCG rate-limited the request.", true, response.headers.get("retry-after")?.slice(0, 100));
+            }
+            if (!response.ok) {
+                throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_UNAVAILABLE", `ambientCG returned HTTP ${response.status}.`, response.status >= 500);
+            }
+            try {
+                return JSON.parse(await readMetadata(response, 16 * 1024 * 1024, signal));
+            }
+            catch {
+                throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_CHANGED", "ambientCG returned invalid JSON.");
+            }
+        });
     }
-    async search(input) {
+    async search(input, context = {}) {
         const params = new URLSearchParams({
             sort: input.sort,
             limit: String(input.limit),
@@ -185,10 +196,10 @@ export class AmbientCgClient {
             params.set("q", input.query);
         if (input.type)
             params.set("type", input.type);
-        const payload = record(await this.request(`/assets?${params}`));
-        const assets = Array.isArray(payload?.assets)
-            ? payload.assets.map(normalizeAsset)
-            : undefined;
+        const payload = record(await this.request(`/assets?${params}`, context));
+        if (Array.isArray(payload?.assets) && payload.assets.length > 1000)
+            throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_CHANGED", "ambientCG asset list exceeds its entry limit.");
+        const assets = Array.isArray(payload?.assets) ? payload.assets.map(normalizeAsset) : undefined;
         const total = number(payload?.totalResults);
         if (!assets || total === undefined) {
             throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_CHANGED", "ambientCG returned an invalid search result.");
@@ -196,26 +207,24 @@ export class AmbientCgClient {
         return {
             assets,
             total,
-            ...(input.offset + assets.length < total
-                ? { nextOffset: input.offset + assets.length }
-                : {}),
+            ...(input.offset + assets.length < total ? { nextOffset: input.offset + assets.length } : {}),
         };
     }
-    async getAsset(id) {
+    async getAsset(id, context = {}) {
         const params = new URLSearchParams({
             id,
             limit: "1",
             include: "type,releaseDate,shortDescription,longDescription,title,url,tags,dimensions,downloadStatistics,downloads,technique,maps,thumbnails",
         });
-        const payload = record(await this.request(`/assets?${params}`));
+        const payload = record(await this.request(`/assets?${params}`, context));
         const first = Array.isArray(payload?.assets) ? payload.assets[0] : undefined;
         if (!first) {
             throw new AmbientCgClientError("AMBIENTCG_NOT_FOUND", "The ambientCG asset was not found.");
         }
         return normalizeAsset(first);
     }
-    async listCategories() {
-        const payload = await this.request("/categories");
+    async listCategories(context = {}) {
+        const payload = await this.request("/categories", context);
         if (!Array.isArray(payload)) {
             throw new AmbientCgClientError("AMBIENTCG_UPSTREAM_CHANGED", "ambientCG returned an invalid category list.");
         }