[00] · MCP SERVER

Drop SpatialPack into your editor.

29 tools — analyze, optimize, commerce-readiness, autocorrect, batch-autocorrect, USDZ export/validate, recipe-search, dedup, cohort recipes, LOD bundles — exposed over Model Context Protocol. Works with Claude Code, Cursor, Claude Desktop, and Continue.dev. One npx command, no install.

Stdio + Streamable HTTPPer-key Bearer authProgress + cancellationSandbox enforced

[01] · INSTALL

Copy. Paste. Done.

npm i @spatialpack/mcp →

Claude Code

anthropic.com/claude-code

json

// ~/.claude.json  (or run: claude mcp add spatialpack)
{
  "mcpServers": {
    "spatialpack": {
      "command": "npx",
      "args": ["-y", "@spatialpack/mcp"]
    }
  }
}

Cursor

cursor.com

json

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "spatialpack": {
      "command": "npx",
      "args": ["-y", "@spatialpack/mcp"]
    }
  }
}

Claude Desktop

claude.ai/download

json

// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "spatialpack": {
      "command": "npx",
      "args": ["-y", "@spatialpack/mcp"]
    }
  }
}

Continue.dev

continue.dev

json

# ~/.continue/config.yaml
mcpServers:
  - name: spatialpack
    command: npx
    args:
      - "-y"
      - "@spatialpack/mcp"

Self-host HTTP (team / shared)

Same code, served over Streamable HTTP. When DATABASE_URL points at the same Postgres as the dashboard, every spatialpack login key is a valid Bearer token.

shell

# Self-host the HTTP transport (e.g. for shared team use).
# When DATABASE_URL points at the same Postgres that backs the
# web dashboard, every `spatialpack login`-generated key is
# accepted as a Bearer token.

DATABASE_URL=postgresql://... \
  npx -y @spatialpack/mcp http --port 3037 --host 0.0.0.0

# Then any MCP client can point at:
#   http://your-host:3037
# with header:  Authorization: Bearer spk_live_...

[02] · AUTH

Personal API keys.

step 01 · Sign in at spatialpack.dev/signin (free, no card).
step 02 · On the dashboard, open the [02] API KEYS card and click Generate API key. Copy it — shown once.
step 03 · Install the CLI and pair the key: npm i -g @spatialpack/cli && spatialpack login.

Free signed-in tier: 25 compute operations / month, shared across web, CLI, and MCP — read-only tools (analyze, find_similar_assets, list_presets) are always free. Pro: unlimited. Keys are revocable from the dashboard at any time.

[03] · TRY IT

First prompt.

prompt

Optimize the .glb at /path/to/asset.glb with the
web-mobile preset, then run safety_gate against the
result with bytesBudget=500_000 and deltaE94Max=2.0.
If the gate passes, give me the output path. If it
fails, run recipe_search and try again.

The model picks the right tools, chains them, and reports the outcome. safety_gate + recipe_search together form a self-tuning loop.

prompt

This .glb came out of an AI 3D generator. Run
commerce_readiness on it. If it's not ready, run
autocorrect and show me which blockers were resolved.
Then export a USDZ with usdz_export and validate it,
so I can ship it to AR Quick Look.

The AI-3D shipping loop: commerce_readiness → autocorrect → usdz_export → usdz_validate — raw generator output to AR-ready, one prompt.

[04] · TOOL CATALOG

All 29 tools.

Analyze

analyzeFull glTF/GLB report — vertex/triangle/texture/animation counts, cohort tags, extensions, GPU memory, compatibility rollup.
diagnose_assetActionable recommendations with suggested_args the model can chain straight into optimize.
compatibility_checkPer-target compatibility matrix (three.js, Babylon, model-viewer, AR Quick Look, Scene Viewer).
canonical_cidDeterministic geometry-identity hash (order/endian-robust SHA-256 prefix) for caching + dedup.

Optimize

optimizeRun the full pipeline against a preset (web-mobile · web-desktop · quality-max) with every opt-in pass exposed.
batch_optimizeWalk files/dirs and optimize each into out_dir with per-asset reports; resumable, continue-on-error.
recipe_searchTPE Bayesian search for the winning recipe under a size/quality budget; optional visual-diff gate.
dedup_texturesExtract byte-identical embedded images shared across GLBs into a shared sidecar; per-image savings report.
lod_bundleBake high/medium/low LOD tiers + a spatialpack.lod.json manifest for screen-height-driven selection.

Readiness

commerce_readinessOne verdict — ready / warnings / not-ready — composing ACG conformance + AR parity + geometry, with blockers.
autocorrectRepair an asset (floater prune + USDZ-safe material bake + optimize), then re-score with resolved/remaining blockers.
batch_autocorrectRepair + re-score a whole catalog into out_dir with a roll-up of readiness-status transitions and total savings.
safety_gateCohort-aware quality gate over visual-diff metrics; per-asset verdicts + aggregate pass/fail report.

Recipes

cohort_recipes_buildRun recipe-search per cohort bucket across a corpus subset; emit a cohort-recipes.json the runtime can look up.
cohort_recipes_lookupResolve the recipe for given cohort tags from a cohort-recipes.json manifest (with graceful fallbacks).
find_similar_assetsTop-K nearest neighbours by cosine similarity against an on-disk embedding index.
recipe_search_with_inheritanceRecipe search seeded from the cached winning recipes of the asset’s k nearest neighbours.

USD / AR

usdz_exportConvert GLB → USDZ for AR Quick Look via the local converter, with an optional post-export validation pass.
usdz_validatePure-JS USDZ conformance check — size budget, asset-ref resolution, missing textures, file-size cap.
usdc_to_usdaRender binary USDC → USDA text (usdcat-equivalent) so an agent can read scene structure as plain text.
splat_to_usdzConvert a Gaussian splat (PLY / .splatz) → Apple ParticleField3DGaussianSplat USDZ + optional RealityKit buffers. Structural conformance, NOT RealityKit-verified.
model_readySafari 27 <model> / AR Quick Look readiness verdict for a USDZ — ready / warnings / not-ready with blockers. Documented-constraint conformance, NOT a live render.

Compare + hash

compare_imagesPixel-precise PNG diff — differing pixels, MAE, ΔE94 mean/max/p95, Sobel-edge delta, SSIM.
phash64-bit DCT-based perceptual hash of a PNG (16-char hex).
phash_distanceHamming distance between two pHashes (≤5 near-duplicate, >15 clearly different).

Bundle + info

bundle_glb_zipPack a GLB + sidecars into a single .glb.zip with a versioned manifest (per-entry DEFLATE/stored).
unbundle_glb_zipExtract a .glb.zip — primary GLB + every sidecar — with CRC32 + manifest cross-checks.
list_presetsEnumerate preset ids and their key budget knobs so the agent picks intelligently.
explain_budgetThe cohort budget + quantization + meshopt-scheduler tables — pure data for agent reasoning.