# MeshVault

> MeshVault is a local-first 3D asset browser and viewer with an embeddable, server-less
> viewer core that exposes a self-describing control API designed to be driven by AI
> agents. An agent can load a model, find and frame its semantic "front", inspect the mesh,
> take cross-sections, and capture hero shots — all through one JSON command interface.

Key facts for agents:
- The standalone viewer runs with no backend. Load it as an ES module
  (`import { createViewer } from ".../meshvault-viewer.js"`) or via the global
  `window.MeshVaultViewer.createViewer(container)`. A live demo/harness is at `/static/viewer.html`
  where `window.mv` is the API instance.
- Everything is driven through ONE entry point: `api.execute({ action, params }) → { ok, result | error }`.
  It never throws; errors are structured strings. Discover all commands and their parameter
  schemas at runtime with `api.listCommands()`.
- Observe state (JSON, no vision needed) with `api.getState()`, `api.getSceneInfo()`, and the
  `get_bounds` command. Capture what the viewer sees with `screenshot` (returns a PNG data URL).
- Best first move after loading: `describe_scene` — one structured snapshot (summary sentence,
  inventory, size hint, hierarchy, materials, detected geometry issues, current view) so you can
  reason about the model without any screenshot.
- Explore parts: describe_scene gives each mesh a stable `id` + world `center`/`size`;
  `focus {id}` (or name/point) frames that part — even tiny ones — keeping the view direction.
  `reset_camera` returns to the whole model.
- "front/back/left/right" presets are WORLD-AXIS conventions and are often wrong for
  mis-oriented models. To find a model's real front, use `find_best_view` (scores angles by
  lighting-independent visible detail and auto-uprights the camera).
- Compressed glTF (Draco geometry, KTX2/Basis textures, Meshopt) loads transparently;
  decoders are bundled locally (offline-safe, no CDN).
- Image-based lighting (IBL) is on by default for realistic PBR reflections; control it
  with `set_environment { enabled, intensity, asBackground }` / `get_environment`.

- MCP: agents can drive MeshVault natively via the bundled MCP server (`meshvault-mcp`,
  11 tools: load_model [URL or local path; multi-file OBJ/FBX/gltf assets load
  textured; add:true composes multi-object scenes], describe_scene, viewer_execute,
  list_viewer_commands, get_state, compare_models [geometric shape registration],
  screenshot [supports preset:"studio"|"neutral"|"dark" for renders comparable across
  sessions], save_scene/load_scene [.mvscene manifests persist composed scenes],
  open_in_app [push your model + camera into the running app so a human co-views
  live], get_app_state [read what the HUMAN is looking at — path + camera — and
  continue their session headless]).
  See https://github.com/lpalbou/MeshVault/blob/main/docs/mcp.md.
- Scene composition: `load` replaces, `add_model` composes; per-object placement via
  set_object_transform (wrapper transforms, never baked); single-object commands act
  on the ACTIVE object (set_active_object); frame_all for scene-wide framing;
  get_scene_manifest serializes the composition.
- REST screenshot (local server, no MCP needed): `GET /api/screenshot?path=/abs/
  model.glb&best_view=true&preset=studio` returns a PNG (token header required;
  metadata in the X-MeshVault-Screenshot header). Docs: docs/api.md.
- Deep links (local app): `/?path=/abs/model.glb` selects + loads an asset;
  `/?dir=/abs/folder` opens a folder; `/?path=/abs/pack.zip!inner/model.obj` loads an
  archive member; `/?scene=/abs/file.mvscene` rebuilds a composed scene. URL params
  win over the remembered last directory, and the URL stays in sync while browsing —
  the address bar is always a shareable deep link.
- A hosted, zero-install build of this viewer (same window.mv control API, URL-loading
  only, no backend tools) is live at https://www.lpalbou.info/MeshVault/ with its own
  llms.txt for the remote context.

## Docs

- [Control API reference (full)](/llms-full.txt): Every command, parameters, return shapes, and worked examples for driving the viewer.
- [MCP server](https://github.com/lpalbou/MeshVault/blob/main/docs/mcp.md): Drive the viewer from Claude/Cursor via Model Context Protocol — install, client config, tools.
- [MCP usage examples](https://github.com/lpalbou/MeshVault/tree/main/examples/mcp): Runnable agent workflows (inspect, compare iterations, explore parts, hero shots).
- [Architecture](https://github.com/lpalbou/MeshVault/blob/main/docs/architecture.md): System design, the viewer core / control API / standalone bundle, and the backend.
- [API Reference (backend REST)](https://github.com/lpalbou/MeshVault/blob/main/docs/api.md): The local server's HTTP endpoints and security model.
- [Getting Started](https://github.com/lpalbou/MeshVault/blob/main/docs/getting_started.md): Install, run, UI overview.

## Optional

- [FAQ](https://github.com/lpalbou/MeshVault/blob/main/docs/faq.md): Formats, troubleshooting, dev/build notes.
- [Demo harness](/static/viewer.html): Live standalone viewer exposing `window.mv`.
