shotops-mcp 0.5.0

package/README.md

@@ -0,0 +1,419 @@
+# shotops-mcp
+
+A hosted-ready **MCP server** that turns app screenshots into styled 3D App Store mockups,
+emits a `fastlane deliver`-ready bundle, and reads your saved ShotOps look — for agents
+(ChatGPT / Claude Code / Cursor / CI). It runs over the same `@engine` render spine the Studio web app
+and the `mockup-mcp` CLI use, driving headless Chromium (Playwright).
+
+Ships as **two tiers, one engine**: a free `npx shotops-mcp` **local stdio server** that
+renders on your own machine with no account (see [Local (free tier)](#local-free-tier---npx-shotops-mcp)
+below), and a **hosted** server on Fly.io with an account, saved looks, and share links (see
+[Hosted (Fly.io)](#hosted-flyio) below, or the public
+[`/connect`](https://storeframe-studio.vercel.app/connect) page in the studio app).
+
+## Zero-custody
+
+This server **never touches a store-signing credential.** There is no tool input, env var,
+or code path that accepts, stores, or forwards one. `emit_bundle` hands you a zip; **you**
+upload it with **your own** `fastlane`, signed in as yourself. The generated `Deliverfile`
+is screenshots-only and **never submits for review**. The only secrets this process holds
+are Supabase service credentials (to resolve your API token, read your saved look, and back
+share links) — nothing that could reach a store on your behalf.
+
+## Tools
+
+| Tool | What it does | Key inputs |
+|------|--------------|------------|
+| `render_strip` | Render screenshots into mocked-up per-panel PNGs | `screenshots`, `panelPresetId?`, `clip?`, `style?` **+** `look?` (they compose) / `useSavedLook?`, `project?`, `version?`, `locale?`, `preview?`, `output?` |
+| `emit_bundle` | `render_strip` (or pre-rendered `panels` — refs or local `{ path }`) + a `fastlane deliver` zip (+ optional share link) | `screenshots` or `panels`, `bundleId`, `clip?`, `locale?`, `locales?` (multi-locale bundle), `projectName?`, `share?`, `output?` (+ the same styling params) |
+| `save_project` | Save the strip as an editable Studio project (structure + look only — does NOT render, so it never hits the render timeout); returns `projectId` + an `openUrl` | `screenshots`, `project?` (update in place; omit to create), `projectName?`, `panelPresetId?`, `style?` / `look?` / `useSavedLook?`, `version?`, `locale?`, `sourceDir?` |
+| `read_look` | Return a project's saved ShotOps look (styling only), with its latest version, the held version, and the `versions` history | `project?` (default: your most recently edited project) |
+| `read_project` | Return a project's FULL current state as an opaque `ProjectFile` — frame order, per-locale caption words, locale list, styling. Answers *"what did the designer change?"* (remember `updatedAt`, re-read later) | `project?` (default: your most recently edited project) |
+| `render_project` | Re-render a SAVED project with your OWN raw screenshots, matched to its shots **by filename** — the project supplies frame order, captions + styling, so the result reproduces the designer's strip | `project?`, `screenshots` (a FLAT list, each with its original filename as `name`), `locale?`, `preview?`, `output?` |
+| `save_look` | Persist a composed look on a project (styling only — appends a new version) | `look`, `project?`, `sourceName?` |
+| `hold_look` | Hold which saved version agents render by default (replaces pinning) — the version must exist (`read_look` `versions`) | `version`, `project?` |
+| `release_look` | Clear the held version — agents Follow latest (render the newest saved look) | `project?` |
+| `describe_look` | The styling field catalog + defaults, for authoring from scratch | *(none)* |
+| `request_screenshot_upload` | Mint signed upload slots for real screenshots | `count` (1–10), `names?`, `locale?` (a per-locale batch tag) |
+| `import_screenshot` | Import a PNG attached in ChatGPT and return a render-ready ref | `file`, `name?`, `locale?` |
+| `delete_assets` | Permanently delete private uploaded screenshots, rendered panels, or generated bundles owned by the signed-in account | `refs` (1–50 ShotOps refs) |
+
+- **`panelPresetId`** — App Store size: `r69` (default, 6.9″ iPhone 1290×2796), `r65`, `r55`,
+  `ipad13`, `ipad129`. This enum is a hand-kept copy of `mockup-engine/appstore.ts`'s
+  `PANEL_PRESETS` (see `shotops-mcp/src/schemas.ts`'s `PANEL_PRESET_IDS`/`PANEL_DIMENSIONS`)
+  — when Apple revises required sizes, add the preset in the engine first, then mirror it
+  here.
+- **`style`** — the structured styling input (call `describe_look` for the full catalog):
+  `{ shotLook?, background?, captions? }`. `shotLook` is **one device for every phone**; `captions`
+  is one entry PER PANEL in slot order — each entry is EITHER a single caption object OR an **array
+  of caption layers** stacked on that panel (headline + subline + …). Each layer's `text` (and a
+  single caption's `subtitle`) is per-RENDER input (never stored — a look carries styling only).
+  Captions auto-layout above the device so they never collide with the phone.
+- **`look`** — a ShotOps look JSON exactly as `read_look` returns it, but you can also
+  hand-author one: it gives each panel its **own** device (`shots[]`, tint/tilt/size per panel),
+  which `style.shotLook` can't. **Validated** — unknown keys are rejected (a typo won't silently
+  render wrong). Omit for default styling.
+- **`style` + `look` compose** — every real App Store strip needs BOTH a different device per
+  panel AND captions, so pass them **together**: the `look` supplies the per-panel devices +
+  background, `style.captions` supplies the words, in one render. (Alone, `style` styles every
+  phone identically. If you pass `style.shotLook`/`style.background` *alongside* a `look`, the look
+  wins and the result carries a note.) Also composes with `useSavedLook`/`version`.
+- **`clip`** — `"strip"` (default) renders one continuous canvas, so a wide/offset device can
+  straddle the seam into the next panel (swipe-through scenes). `"panel"` clips each phone to its
+  own panel so it can't bleed a foreign edge into the neighbouring App Store screenshot. A render
+  option, not part of the saved look.
+- **`version`** — render a specific saved look version (implies the saved look). Without it,
+  a project with a PINNED version renders the pin; otherwise the latest saved look.
+- **`emit_bundle` output** — a zip (`README.md`, `fastlane/Deliverfile`,
+  `fastlane/screenshots/<locale>/NN_shotops.png`) as `zipBase64` or `zipUrl`/`zipRef` (see
+  Output below), plus `shareLink` when `share: true`.
+- **`locale`** — an App Store locale code, e.g. `de-DE` (default `en-US`). Labels the render,
+  picks which `{ "locales": … }` screenshot variants render (see
+  [Per-locale screenshots](#per-locale-screenshots--multi-locale-bundles)), and, for
+  `emit_bundle`, picks the `fastlane/screenshots/<locale>/` folder. **It does not
+  select caption text** — this server never stores or looks up Studio-typed copy (repo owns
+  the words). Pass the right words for that locale yourself in `style.captions[].text` /
+  `subtitle`.
+
+### Per-locale screenshots & multi-locale bundles
+
+Any `screenshots` entry (and any `emit_bundle` `panels` entry) can carry **per-locale
+variants** instead of one image:
+
+```json
+{ "locales": { "en-US": { "ref": "…en…" }, "de-DE": { "ref": "…de…" } } }
+```
+
+- `render_strip({ locale: "de-DE", … })` renders the `de-DE` variant of each such entry. A
+  locale with **no variant of its own falls back** to the `en-US` variant (else the first
+  declared) — so you can ship German captions over English screenshots today and upgrade the
+  pixels later. Plain (non-`locales`) entries serve every locale. The response echoes the
+  declared locales as `screenshotLocales`.
+- `emit_bundle({ locales: ["en-US", "de-DE"], … })` emits **ONE zip** with a
+  `fastlane/screenshots/<locale>/` folder per listed locale — `fastlane deliver` uploads every
+  locale in a single run. A single-entry list behaves exactly like `locale`; omitting `locales`
+  is the unchanged single-locale bundle.
+- `request_screenshot_upload({ count, names, locale })` tags a batch of upload slots with the
+  locale it's for (echoed back — bookkeeping only; refs are locale-agnostic).
+
+**Recommended multi-locale flow — render per locale, then compose once.** Caption text is
+per-render input, so this is also the only way to get per-locale *captions* into one bundle,
+and it keeps each call fast (see "Cheap preview, then compose" below):
+
+1. Per locale `L`: `render_strip({ locale: L, output: "urls", style: { captions: [<L's words>] },
+   screenshots: […] })` → per-panel refs for `L`.
+2. One `emit_bundle({ locales: […], bundleId, panels: [ { "locales": { "en-US": { "ref": "p1-en" },
+   "de-DE": { "ref": "p1-de" } } }, … ] })` — zips every locale **without re-rendering**.
+
+The one-call form (`emit_bundle` with `screenshots` + `locales`) works too, but renders once
+per locale with the *same* captions for every locale, and multiplies the slow full-res render
+by the locale count.
+
+### The `captions.<locale>.json` convention
+
+The canonical source of shipping caption copy is a file **in your own repo**, one per locale,
+keyed by **panel ordinal** (0-based, in strip order — not panel id, so the file stays stable
+across re-renders):
+
+A panel's entry is EITHER a single caption (`{ headline, subtitle? }`) OR an **array of layers**
+(each `{ text, … }`, stacked in order) — use the array when you want more than a headline + one
+subtitle, e.g. an eyebrow over a headline over a caption:
+
+```json
+// captions.de-DE.json
+{
+  "0": { "headline": "Alles im Blick", "subtitle": "Deine Tage, übersichtlich." },
+  "1": [ { "text": "NEU" }, { "text": "Schneller planen" } ]
+}
+```
+
+To render a locale: read that file, map it onto `style.captions[]` in the same order (index
+`i` → panel `i`, `null` for a panel with no caption), and pass `locale` alongside so the
+render/bundle is labeled and routed consistently. A single caption maps to one object; a layer
+array maps straight through as an array:
+
+```json
+{
+  "locale": "de-DE",
+  "style": { "captions": [
+    { "text": "Alles im Blick", "subtitle": "Deine Tage, übersichtlich." },
+    [ { "text": "NEU", "sizePt": 28 }, { "text": "Schneller planen" } ]
+  ] }
+}
+```
+
+There is no MCP tool to read Studio-typed caption text back — Studio's per-locale captions
+are for *visual preview* only; your repo's `captions.<locale>.json` is what actually ships.
+
+### Agents: don't inline large images
+
+A real marketing screenshot is easily 1–2MB as a PNG — 30–40% bigger again as base64 — and
+that base64 string flows through your OWN tool-call arguments, in YOUR context window, before
+it ever reaches this server. Passing full-resolution screenshots inline can blow past your
+context budget (or get silently truncated by a file-read tool) long before rendering happens.
+
+**Upload out-of-band instead:**
+
+In ChatGPT, attach the PNG and call `import_screenshot` once per file. ChatGPT supplies the
+temporary file parameter; ShotOps downloads and stores it server-to-server, then returns
+the same `{ ref }` used by the render tools. In other hosted MCP clients, use the signed-slot
+flow below:
+
+1. Call `request_screenshot_upload({ count: N })` — returns `N` `{ ref, uploadUrl }` slots
+   under your own private prefix, plus a copy-paste `curl -T` example.
+2. `curl -T screenshot.png "<uploadUrl>"` each screenshot directly (bytes never touch this
+   conversation).
+3. Pass `{ "ref": "<ref>" }` — not inline base64 — as that screenshot's entry in
+   `render_strip`/`emit_bundle`'s `screenshots` array.
+
+`screenshots` entries accept these shapes: an inline base64 string (small payloads only —
+inline is capped and returns a clear "payload too large" error above ~8MB decoded, pointing
+you back at this flow), `{ ref }` from step 1, `{ url }` (an https URL this server fetches
+itself: image/png, no redirects, ~20MB cap), `{ path }` (local stdio server only — see below),
+or `{ "locales": { "<locale>": <any of those> } }` for per-locale variants (see
+[Per-locale screenshots](#per-locale-screenshots--multi-locale-bundles) above).
+
+**Output** works the same way in reverse: `render_strip`/`emit_bundle` take an `output` field
+— `"inline"` (base64), `"urls"` (uploaded under your own prefix, short-lived signed download
+URLs), or omit for auto (inline under ~200KB total, `urls` above). Use `"urls"` for
+full-resolution work so results never transit your context either.
+
+**Cheap preview, then compose:** `render_strip({ preview: true })` renders at ~25% resolution
+for fast, cheap styling iteration — small enough to always come back inline; don't ship it,
+re-render without `preview` (or call `emit_bundle` directly) once the look is right. Once
+you have full-resolution panel refs from a `render_strip({ output: "urls" })` call,
+`emit_bundle({ panels: [{ ref }, ...] })` packages them into a bundle WITHOUT rendering again
+— skip `screenshots` entirely in that call.
+
+Private uploaded screenshots and generated files are retained until deleted. Treat refs as
+short-lived and single-use, then call `delete_assets({ refs: [...] })` when the files are no
+longer needed. Deleting a ref is irreversible and can make a saved project's referenced
+screenshot unavailable; public privacy disclosures must accurately state this retention model.
+
+## Prerequisites
+
+1. **A ShotOps API token.** Sign in at the Studio app → account menu → **API tokens** →
+   create one. It looks like `shotops_9Zq3Xr7Tp0Vn6Lk2Wd8Yb4Mf1Hc5Ju3Rs9Ea7Gt0Nz1` and is
+   shown once — copy it then.
+2. **Supabase service env** (already in the repo's `.env.local` for local dev): `SUPABASE_URL`
+   and `SUPABASE_SERVICE_ROLE_KEY`. The server loads `../.env.local` automatically.
+3. Playwright's Chromium (installed with the package; run `npx playwright install chromium`
+   once if it's missing).
+
+## Run it
+
+```bash
+cd shotops-mcp
+npm install
+npm run dev            # boots on http://localhost:8788/mcp  (override with MCP_PORT)
+```
+
+Chromium boots lazily on the first `render_strip` / `emit_bundle` call, so startup is fast.
+`GET /health` is an unauthenticated liveness probe.
+
+## Connect ChatGPT (Developer Mode)
+
+Deploy the hosted server at a public HTTPS origin, enable Developer Mode in ChatGPT, and create
+an app whose MCP server URL is `https://<your-host>/mcp`. Do not paste a personal `shotops_` token
+into the app definition: ChatGPT discovers the protected-resource metadata from the endpoint and
+runs the server's OAuth + PKCE browser sign-in flow. This is a tool-only app — no widget or UI
+resource is required. User-attached PNGs enter through `import_screenshot`.
+
+For public plugin submission, OpenAI supplies a domain-verification token after the MCP domain
+is entered in the Platform dashboard. Set it on the hosted server as
+`OPENAI_APPS_CHALLENGE_TOKEN`; the server then returns that exact value from
+`/.well-known/openai-apps-challenge`. With no token configured, the route returns 404.
+The server also exposes a synthetic, non-user PNG at
+`/review-fixtures/sample-app-screen.png` so reviewers can reproduce attachment and URL-input
+tests without private fixture data or third-party hosting.
+
+## Connect Claude Code
+
+```bash
+claude mcp add --transport http shotops http://localhost:8788/mcp \
+  --header "Authorization: Bearer shotops_9Zq3Xr7Tp0Vn6Lk2Wd8Yb4Mf1Hc5Ju3Rs9Ea7Gt0Nz1"
+```
+
+Then ask the agent to, e.g., *"render these two screenshots into a 6.9″ App Store strip and
+emit a fastlane bundle for com.acme.app."* Every request must carry the
+`Authorization: Bearer shotops_…` header; a missing, unknown, or revoked token gets a `401`
+before any tool runs.
+
+### Other clients
+
+- **Cursor / any MCP client** — point it at the Streamable-HTTP URL `http://localhost:8788/mcp`
+  with the same `Authorization: Bearer shotops_…` header.
+- **Raw / CI** — POST JSON-RPC to `/mcp` with the header; use the official MCP client or the
+  inspector (`npx @modelcontextprotocol/inspector`) to explore interactively.
+
+## After you get a bundle
+
+```bash
+# decode zipBase64 from emit_bundle's result to a file, then:
+unzip shotops-appstore-upload.zip -d upload && cd upload
+fastlane deliver        # signs in as YOU, previews, uploads screenshots to a draft — never submits
+```
+
+## Hosted (Fly.io)
+
+The server also runs hosted, 24/7-reachable (scale-to-zero when idle), at:
+
+```
+https://shotops-mcp.fly.dev/mcp
+```
+
+Nothing to install — point any MCP client at that URL with your `Authorization: Bearer
+shotops_…` header, same as local dev, just swap the base URL:
+
+```bash
+claude mcp add --transport http shotops https://shotops-mcp.fly.dev/mcp \
+  --header "Authorization: Bearer shotops_…"
+```
+
+The public [`/connect`](https://storeframe-studio.vercel.app/connect) page in the studio
+app has the same instructions for Cursor/CI, plus a link to where to create a token — it's
+the one place an external agent user (not a repo collaborator) can find the connect story,
+since this repo is private.
+
+### Ops (this repo's maintainer only)
+
+- **Deploy** (from the **repo root** — the Dockerfile needs `../mockup-engine` and
+  `../api/_lib` as build-context siblings):
+  ```bash
+  flyctl deploy . --config shotops-mcp/fly.toml --remote-only --ha=false
+  ```
+- **Secrets** (`fly secrets set -a shotops-mcp KEY=value`): `SUPABASE_URL`,
+  `SUPABASE_SERVICE_ROLE_KEY`, plus `OPENAI_APPS_CHALLENGE_TOKEN` while verifying the MCP
+  domain for public ChatGPT plugin submission — nothing Apple-related, ever, by construction.
+- **Verify after any deploy** — a green `flyctl deploy` isn't proof the server answers MCP
+  calls:
+  ```bash
+  node verify-mcp.mjs https://shotops-mcp.fly.dev/mcp <a-real-shotops_-token>
+  ```
+  Exercises `tools/list`, `read_look`, `emit_bundle` (asserts the zip unzips to
+  README/Deliverfile/screenshots), and asserts no-token / bad-token both get `401`.
+- **Logs / status:** `flyctl logs -a shotops-mcp`, `flyctl status -a shotops-mcp`.
+- The Dockerfile is pinned to `mcr.microsoft.com/playwright:v1.61.1-noble` — matching the
+  `playwright` npm version in `package.json`. If you bump one, bump the other.
+- The container builds the browser harness once and serves it through a loopback-only static
+  server at runtime. Vite is build/parity tooling only and is pruned from production
+  dependencies; the Docker build context still includes `mockup-engine` so the harness can
+  bundle the shared engine + GLB.
+- **VM size is `shared-cpu-2x` (2 vCPU / 2GB), not `shared-cpu-1x`** (found live, Phase 10):
+  Chromium's software WebGL render (no GPU on Fly's shared tier) is CPU-heavy enough that on
+  a single shared vCPU it can starve the whole process — health checks stop responding,
+  SIGTERM/SIGINT get ignored, and Fly force-kills the VM ("Virtual machine exited abruptly")
+  mid-render. On 2 vCPUs the same 3-panel real-screenshot render completes in ~8s. Don't
+  drop back to `shared-cpu-1x` to save cost — a render-triggering tool call is expected to
+  occasionally saturate a whole core, and 1x has no second core to keep the process alive
+  while that happens. Client callers (agents, `verify-mcp.mjs`) should still set a generous
+  per-call timeout (≥180s) for `render_strip`/`emit_bundle` — even warm, cold-machine renders
+  can take 60-110s before the CPU fix, and network/Supabase round trips add more on `urls`
+  output.
+
+## Local (free tier) — `npx shotops-mcp`
+
+The SAME server also runs as a **local stdio MCP**, entirely on your own machine — no URL, no
+account, no Fly cost, and no render-timeout ceiling (the hosted server's one real limit — see
+"Ops" above). It's the same `registerTools`/render engine as the hosted server; only the
+transport and a few account-shaped tools differ.
+
+```bash
+claude mcp add shotops -- npx -y shotops-mcp
+```
+
+One-time setup: Chromium isn't bundled in the npm package (it's ~150MB) — Playwright downloads
+it on first run, or install it explicitly:
+
+```bash
+npx playwright install chromium
+```
+
+**Screenshots are read straight off your disk** — no upload dance. Pass a local file path
+instead of `{ ref }`/`{ url }`:
+
+```json
+{ "screenshots": [[{ "path": "/Users/you/screens/01_home.png" }]] }
+```
+
+(`{ "path": ... }` only works over this LOCAL server — the hosted server rejects it, since
+reading an arbitrary server-side path there would be a local-file-inclusion hole.)
+
+**`emit_bundle` reads local panels off disk too** — the free tier has no account, so it can't
+produce `output: "urls"` refs. After rendering, pass the on-disk PNGs straight to `emit_bundle`
+(same local-only `{ path }` door as screenshots) to package a `fastlane deliver` zip with no upload:
+
+```json
+{ "bundleId": "com.acme.app", "panels": [{ "path": "/abs/panel-01.png" }, { "path": "/abs/panel-02.png" }] }
+```
+
+**What's different locally, and why:** every tool that needs an ACCOUNT to read or persist to —
+`read_look` / `save_look` / `save_project` / `read_project` / `render_project` / share links —
+has nothing to talk to in local mode by default, so they cleanly no-op with a "sign in" message.
+`render_strip` / `emit_bundle` are otherwise **fully functional** — you lose nothing on rendering
+itself, only on persistence, which is exactly the free/paid line:
+
+| | Local (free, `npx shotops-mcp`) | Hosted (Fly, `shotops_…` token) |
+|---|---|---|
+| Render compute | **your machine** ($0, no timeout) | our Fly machine |
+| Auth | none (the process runs as you) | account + API token |
+| Saved looks / editable projects / project read+re-render / share links | opt-in via a token (below) — share links still need a direct hosted connection | ✅ |
+| Screenshot input | local `{ path }` off disk | `request_screenshot_upload` → `{ ref }` |
+
+### Optional: bridge a local render into your hosted account
+
+Pass a personal ShotOps API token (Studio → account menu → **API tokens** — the same
+`shotops_…` token the hosted server takes as a bearer) and `save_project` / `read_look` /
+`save_look` / `read_project` / `render_project` start working too — **rendering still happens
+locally and for free; only the small saved-project JSON (structure + look, never screenshot
+bytes) goes to your account:**
+
+```bash
+SHOTOPS_TOKEN=shotops_… claude mcp add shotops -- npx -y shotops-mcp
+# or: npx shotops-mcp --token shotops_…
+```
+
+The saved project remembers the exact on-disk folder your screenshots came from (not just their
+filenames), so re-opening it on the SAME machine can point right back at it. Share links aren't
+bridged yet — they'd need a hosted rendering step, which would defeat local rendering's whole
+point — connect directly to the hosted server (above) for those.
+
+## Layout
+
+```
+shotops-mcp/
+  src/
+    app.ts          the Express app as a pure factory (OAuth AS router + /oauth/callback +
+                    /mcp's per-request auth gate + stateless transport) — driveable in tests
+                    with injected deps; server.ts calls it with the real Supabase-backed ones
+    server.ts       wires app.ts's real deps (Supabase-backed auth/looks/oauth) + listens
+    auth.ts         thin wrapper over the verifyApiToken substrate (covers both shotops_ tokens
+                    and OAuth-minted tokens — both are api_tokens rows)
+    oauthProvider.ts  the OAuth 2.1 Authorization Server (DCR + PKCE + token mint) the SDK's
+                    mcpAuthRouter drives; delegates human login to Supabase Google sign-in
+    oauthStore.ts   OAuth AS persistence (mcp_oauth_clients / mcp_oauth_auth_codes), raw
+                    service-role PostgREST, RLS-on-no-policies like api_tokens/share_links
+    supabaseLogin.ts  the Supabase Google-login leg (server-side PKCE, /oauth/callback)
+    tools.ts        render/bundle/project/look/upload/import/delete handlers + registrar
+    schemas.ts      zod input schemas incl. the structured `style` (no store-credential field exists) + panel presets
+    renderer.ts     StripRenderer — boots Vite (hosted) or the static harness (local) + Chromium once, exposes render(input)
+    staticServer.ts  the tiny node:http static server for harness-dist/ (local mode's serve path)
+    lookStore.ts    per-PROJECT looks + projects resolver (ownership enforced in code; D1 record/pinned_record pair)
+    shareEmit.ts    emit_bundle's server-side share-link creation (reuses Phase-2 modules)
+    uploads.ts      Phase 10 — upload slots, ref ownership check, output:'urls' storage
+    screenshotInput.ts  Phase 10 — resolves screenshots[] (inline/ref/url/path) to base64
+    env.ts          loads ../.env.local; MCP_PORT / STUDIO_ORIGIN / MCP_PUBLIC_URL
+    local.ts        the LOCAL (free tier) npx entry point — stdio transport, no auth
+    localDeps.ts     the local ToolDeps fork — static-serve renderer, no-op/bridged persistence
+    hostedBridge.ts  local→hosted bridge (a real MCP client using your shotops_ token)
+  harness/          the browser render page Chromium loads (render.js exposes window.renderStrip)
+  vite.config.mjs   hosted (Vite dev server) harness config — mirrors mockup-mcp's headless-render setup
+  vite.harness.config.mjs  the STATIC harness build (local mode's publish prerequisite) → harness-dist/
+  build.mjs         esbuild bundle of src/local.ts (+ @engine/@api inlined) → dist/local.js
+  Dockerfile        hosted image — Playwright's Chromium base + this repo's 3 npm installs
+  fly.toml          Fly app config (scale-to-zero, /health check) — deploy from repo root
+  verify-mcp.mjs    post-deploy smoke test — real MCP round-trip against a hosted URL
+  verify-mcp-local.ts  local stdio smoke test (tsx src/local.ts, in-repo)
+  static-parity.ts  pixel-diffs the static-serve render against the Vite-dev render (must be 0)
+  pack-smoke.ts     THE publish gate — npm pack, install OUTSIDE the repo, drive a real render
+```