@womp/mcp-ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Womp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# @womp/mcp-ui
+
+Interactive cards for Womp's MCP server, rendered inline in Claude (and any
+other MCP Apps host) instead of the default tool-result thumbnail.
+
+Built with [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) — tools
+declare a `ui://` resource containing an HTML interface, and the host renders it
+in a sandboxed iframe, pushing tool data in over postMessage.
+
+```
+generate_image  ──► ui://womp/image-<version>.html   (280 KB) image card
+image_to_mesh   ──► ui://womp/mesh-<version>.html    (900 KB) 3D GLB viewer
+get_generation  ──► ui://womp/mesh-<version>.html    (copes with either)
+```
+
+## What it exports
+
+The package ships the built HTML **as a string**, not as files:
+
+```ts
+const {
+  IMAGE_APP_URI, IMAGE_APP_CSP, IMAGE_APP_HTML,
+  MESH_APP_URI,  MESH_APP_CSP,  MESH_APP_HTML,
+  APP_MIME_TYPE,
+} = require("@womp/mcp-ui");
+```
+
+No `fs.readFile`, no `__dirname`. That is deliberate: swan-backend runs from
+`build/` on one deploy path and `releases/<sha>/` on another, and a path that
+resolves in one does not resolve in the other.
+
+## Consuming it from swan-backend
+
+```ts
+import {
+  IMAGE_APP_URI, IMAGE_APP_CSP, IMAGE_APP_HTML,
+  MESH_APP_URI,  MESH_APP_CSP,  MESH_APP_HTML,
+  APP_MIME_TYPE,
+} from "@womp/mcp-ui";
+
+for (const card of [
+  { name: "Womp image card", uri: IMAGE_APP_URI, html: IMAGE_APP_HTML, csp: IMAGE_APP_CSP },
+  { name: "Womp 3D mesh card", uri: MESH_APP_URI, html: MESH_APP_HTML, csp: MESH_APP_CSP },
+]) {
+  server.registerResource(card.name, card.uri, { description: card.name }, async () => ({
+    contents: [{ uri: card.uri, mimeType: APP_MIME_TYPE, text: card.html,
+                 _meta: { ui: { csp: card.csp } } }],
+  }));
+}
+```
+
+Then on each tool:
+
+```ts
+_meta: { ui: { resourceUri: IMAGE_APP_URI }, "ui/resourceUri": IMAGE_APP_URI },
+```
+
+`get_generation` additionally needs `visibility: ["model", "app"]` — see below.
+
+The cards consume swan-backend's existing `GENERATION_OUTPUT_SCHEMA`
+(`status` / `generationId` / `operationId` / `imageUrl` / `glbUrl` /
+`previewUrl`) unchanged, so no server contract changes are required.
+
+## Things that will waste your day if you don't know them
+
+Everything here was established empirically against Claude on 2026-09-01.
+
+### The bridge is mandatory, not polish
+
+The host mounts the iframe **hidden** (`visibility: hidden; height: 100px`) and
+reveals it only after the app completes:
+
+```
+host → ui/notifications/sandbox-resource-ready
+app  → ui/initialize
+host → McpUiInitializeResult          (carries theme, styles, displayMode)
+app  → ui/notifications/initialized
+app  → ui/notifications/size-changed  (ResizeObserver)
+```
+
+`app.connect()` does all of it including auto-resize. Skip it and the card
+renders perfectly and is never displayed. A static HTML card **cannot** work.
+
+Handlers must be attached **before** `connect()` or they never fire.
+
+### CSP: two different fields
+
+- `_meta.ui.csp.resourceDomains` — scripts, styles, **images**
+- `_meta.ui.csp.connectDomains` — **fetch/XHR**, needed for the GLB
+
+The mesh card declares both. Missing `connectDomains` looks like a broken
+viewer, not a blocked request.
+
+**Do not** also send the flatter `_meta.ui.resourceDomains` variant that the
+package's SKILL.md prose uses. An unrecognised key under `ui` invalidates the
+resource and the widget stops rendering entirely. Only the shape above works.
+
+### Host theme variables do not exist on the document
+
+Reading `--color-text-primary` off `documentElement` returns nothing. Host
+styles arrive via `onhostcontextchanged` and the app applies them itself
+(`applyHostStyleVariables`). **Every `var()` must ship a fallback.**
+
+The complete set a host may send is `McpUiStyleVariableKeySchema` in
+`@modelcontextprotocol/ext-apps` — anything outside it will never resolve.
+Notably it is `--color-border-primary`, not `--color-border`.
+
+### Hosts cache UI resources per connector
+
+A changed card does **not** reach an existing connector. Bumping the `ui://`
+URI is not enough — the old URI 404'd server-side while Claude still rendered
+its cached copy. The only fix found was **remove and re-add the connector**.
+
+This is why the version is baked into the URI, and why the first published
+version should be one you are happy to live with: users will not reconnect on
+their own.
+
+### Widget-composed messages trigger a security warning
+
+`app.sendMessage()` pre-fills the composer with a red *"Malicious conversation
+content could trick Claude…"* banner. That is correct behaviour — a widget is
+untrusted content — and there is no opt-out.
+
+So there is **no "Make 3D" button**. The affordance lives in `generate_image`'s
+response text instead, nudging the model to offer the conversion in prose. Zero
+friction, intent still lands in the transcript, and you get a separate mesh
+card.
+
+Rule of thumb: apps may call tools to **observe** (the polling below), but
+should send messages to **act** — and acting costs a warning.
+
+### Self-updating cards
+
+`CallToolRequest` is part of `AppRequest`, so a card can call tools through the
+host. The running state uses this: the tool returns immediately with
+`{ status: "running", operationId }`, and the card polls `get_generation`
+itself — 2s backing off to 10s, giving up after 6 minutes, stopping on
+teardown.
+
+This is why the conversation is never blocked by a slow generation, and it
+replaced a day of MCP Tasks work with a polling loop.
+
+**`get_generation` must declare `visibility: ["model", "app"]`.** Without
+`"app"` the host refuses the call and the running state never resolves.
+
+### Display modes
+
+`ctx.displayMode` is `inline` | `fullscreen` | `pip`. Cards are capped narrow
+inline (360px) so they do not wall off the transcript — which made fullscreen
+useless until CSS started keying off `:root[data-display-mode="fullscreen"]`.
+**PiP is untested.**
+
+## Development
+
+swan-backend cannot be run locally, so the repo ships its own harness.
+
+```bash
+yarn install
+yarn build            # build:ui (two vite passes) + build:bake
+yarn dev:mcp          # stub MCP server on :3001 with fake slow generations
+```
+
+`FAKE_DURATION_MS=8000` controls how long a fake generation takes, so the
+running → complete transition is actually exercised.
+
+**Local hosts** (nothing exposed): point VS Code or Postman at
+`http://localhost:3001/mcp`. Proves the card and the bridge — but **not** that
+Claude renders it.
+
+**Claude** needs a public URL, because it connects from Anthropic's cloud and
+cannot reach localhost:
+
+```bash
+ngrok http 3001 --url https://<reserved>.ngrok-free.dev
+# add https://<reserved>.ngrok-free.dev/mcp as a custom connector
+```
+
+Remember to remove and re-add the connector after every rebuild.
+
+There is no console inside the sandboxed iframe, so each card carries a status
+line that names the failing layer instead of going blank. Read it first.
+
+## Build pipeline
+
+`vite-plugin-singlefile` inlines everything into one HTML file — mandatory,
+since the sandboxed iframe cannot fetch sibling assets, and it fails
+**silently** (a blank card, no error). `scripts/bake-html.mjs` refuses to
+publish if any `<script src>` or `<link href>` survived.
+
+The plugin also disables code splitting, which rollup refuses to combine with
+multiple inputs — so the cards build in **two separate passes** driven by a
+`CARD` env var, not one multi-entry build.
+
+## Releasing
+
+1. `yarn lint && yarn build`
+2. bump `version` in `package.json` — this changes both `ui://` URIs, which is
+   what defeats the host cache
+3. `yarn publish` (`prepublishOnly` rebuilds from clean)
+4. bump the dependency in swan-backend and deploy
+5. users must reconnect their connector to see the change
+
+## Known gaps
+
+- **PiP display mode** untested.
+- **Mesh lighting** is three directional/ambient lights, not an HDR
+  environment — an env map means another cross-origin fetch and another CSP
+  entry. PBR materials may read flatter than in the Womp editor.
+- **Mesh card is 900 KB.** Almost all of it is three.js plus ~260 KB of
+  zod/MCP-SDK from the bridge. A hand-rolled bridge (the handshake is ~5
+  messages) would cut that 260 KB from both cards; deferred because three.js
+  dominates anyway.
+- **No corner `…` menu** from swan-frontend's tile.
+- **`edit_image`** does not exist in swan-backend, so no edit affordance.
+- The prose nudge for 3D conversion is **not deterministic** — the model may
+  not always offer it.