cue-ai 0.4.0 → 0.4.1

package/resources/claude-plugins-official/plugins/mcp-server-dev/skills/build-mcp-app/references/directory-checklist.md

@@ -1,18 +0,0 @@
-# Connector-directory submission checklist
-
-Pre-flight before submitting a remote MCP app to the Claude connector
-directory. Each item is a hard review criterion.
-
-| Area | Requirement |
-|---|---|
-| **Auth** | OAuth (DCR or CIMD) or **`none`** (authless). Static bearer tokens are private-deploy only and block listing. Authless is valid for public-data servers — the server holds any upstream API keys. |
-| **Tool annotations** | Every tool sets `annotations.title` plus the relevant hints: `readOnlyHint: true` for fetch/search tools, `destructiveHint` / `idempotentHint` for writes, `openWorldHint: true` if the tool reaches an external system. |
-| **Tool names** | ≤ 64 characters, snake/kebab case. |
-| **Widget layout** | Inline height ≤ 500px, no nested scroll containers, 44pt minimum touch targets, WCAG-AA contrast in both themes. |
-| **Theming** | `html, body { background: transparent }`, `<meta name="color-scheme" content="light dark">`, adopt host CSS tokens via `applyHostStyleVariables`. |
-| **External links** | Use `app.openLink`. Declare each origin (e.g. `https://api.example.com`) in the connector's *Allowed link URIs* so the link skips the confirm modal. |
-| **Helper tools** | Widget-only tools (geometry/image fetchers) carry `_meta.ui.visibility: ["app"]` so they don't appear in Claude's tool list. |
-| **Screenshots** | 3–5 PNGs, ≥ 1000px wide, cropped to the app response only — no prompt text in frame. |
-
-See `abuse-protection.md` for rate-limit and IP-tiering guidance once the
-authless endpoint is public.

package/resources/claude-plugins-official/plugins/mcp-server-dev/skills/build-mcp-app/references/iframe-sandbox.md

@@ -1,164 +0,0 @@
-# Iframe sandbox constraints
-
-MCP-app widgets run inside a sandboxed `<iframe>` in the host (Claude Desktop,
-claude.ai). The sandbox and CSP attributes lock down what the widget can do.
-Every item below was observed failing with a silent blank iframe until the
-fix was applied — the error only appears in the iframe's own devtools console,
-not the host's.
-
----
-
-## Problem → fix table
-
-| Symptom | Root cause | Fix |
-|---|---|---|
-| Widget renders as blank rectangle, no error | CSP `script-src` blocks esm.sh fetching transitive `@modelcontextprotocol/sdk` deps | Inline the `ext-apps/app-with-deps` bundle into the HTML |
-| `window.open()` does nothing | Sandbox lacks `allow-popups` | Use `app.openLink({ url })` |
-| `<a target="_blank">` does nothing | Same | `e.preventDefault()` + `app.openLink({ url })` on click |
-| External `<img src>` broken | CSP `img-src` + referrer hotlink blocking | Fetch server-side, ship as `data:` URL in the tool result payload |
-| Widget edits don't appear after server restart | Host caches UI resources | Fully quit the host (⌘Q / Alt+F4) and relaunch |
-| Top-level `await` throws | Older iframe contexts | Wrap module body in an async IIFE |
-
----
-
-## Inlining the ext-apps bundle
-
-`@modelcontextprotocol/ext-apps` ships a self-contained browser build at the
-`app-with-deps` export (~300KB). It's minified ESM ending in `export{…}`; to
-use it from an inline `<script type="module">` block, rewrite the export
-statement into a global assignment at build time:
-
-```ts
-import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-const require = createRequire(import.meta.url);
-
-const bundle = readFileSync(
-  require.resolve("@modelcontextprotocol/ext-apps/app-with-deps"),
-  "utf8",
-).replace(/export\{([^}]+)\};?\s*$/, (_, body) =>
-  "globalThis.ExtApps={" +
-  body.split(",").map((pair) => {
-    const [local, exported] = pair.split(" as ").map((s) => s.trim());
-    return `${exported ?? local}:${local}`;
-  }).join(",") + "};",
-);
-
-const widgetHtml = readFileSync("./widgets/widget.html", "utf8")
-  .replace("/*__EXT_APPS_BUNDLE__*/", () => bundle);
-```
-
-Widget side:
-
-```html
-<script type="module">
-/*__EXT_APPS_BUNDLE__*/
-const { App } = globalThis.ExtApps;
-(async () => {
-  const app = new App({ name: "…", version: "…" }, {});
-  // …
-})();
-</script>
-```
-
-The `() => bundle` replacer form (rather than a bare string) is important —
-`String.replace` interprets `$…` sequences in a string replacement, and the
-minified bundle is full of them.
-
----
-
-## Outbound links
-
-```js
-// ✗ blocked
-window.open(url, "_blank");
-// ✗ blocked
-<a href="…" target="_blank">…</a>
-
-// ✓ host-mediated
-await app.openLink({ url });
-```
-
-Intercept anchor clicks:
-
-```js
-el.addEventListener("click", (e) => {
-  e.preventDefault();
-  app.openLink({ url: el.href });
-});
-```
-
----
-
-## External images
-
-CSP `img-src` defaults (plus many CDN referrer policies) block
-`<img src="https://external-cdn/…">` from loading. Inline them server-side in
-the tool handler:
-
-```ts
-async function toDataUrl(url: string): Promise<string | undefined> {
-  try {
-    const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
-    if (!res.ok) return undefined;
-    const buf = Buffer.from(await res.arrayBuffer());
-    const mime = res.headers.get("content-type") ?? "image/jpeg";
-    return `data:${mime};base64,${buf.toString("base64")}`;
-  } catch {
-    return undefined;
-  }
-}
-
-// in the tool handler
-const inlined = await Promise.all(
-  items.map(async (it) =>
-    it.thumb ? { ...it, thumb: await toDataUrl(it.thumb) ?? it.thumb } : it,
-  ),
-);
-```
-
-Add `referrerpolicy="no-referrer"` on the `<img>` as a fallback for any URL
-that survives un-inlined.
-
----
-
-## Theme & host styles
-
-The host renders the iframe inside its own card chrome — paint a **transparent** background and adopt host CSS tokens so the widget blends in across light/dark and across hosts.
-
-```html
-<meta name="color-scheme" content="light dark" />
-```
-
-```css
-:root {
-  --ink:  var(--color-text-primary,   #0f1111);
-  --sub:  var(--color-text-secondary, #5a6270);
-  --line: var(--color-border-default, #e3e6ea);
-}
-html, body { background: transparent; color: var(--ink); }
-:root.dark .thumb { mix-blend-mode: normal; } /* multiply → images vanish in dark */
-```
-
-```js
-const { App, applyHostStyleVariables } = globalThis.ExtApps;
-
-function applyHostContext(ctx) {
-  document.documentElement.classList.toggle("dark", ctx?.theme === "dark");
-  if (ctx?.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
-}
-app.onhostcontextchanged = applyHostContext;
-await app.connect();
-applyHostContext(app.getHostContext());
-```
-
-`applyHostStyleVariables` writes the host's `--color-*` / `--font-*` / `--border-radius-*` tokens onto `:root`; the hex values above are fallbacks for hosts that don't supply them.
-
----
-
-## Debugging
-
-The iframe has its own console. In Claude Desktop, open DevTools (View → Toggle
-Developer Tools), then switch the context dropdown (top-left of the Console
-tab) from "top" to the widget's iframe. CSP violations, uncaught exceptions,
-and import errors all surface there — the host's main console stays silent.

package/resources/claude-plugins-official/plugins/mcp-server-dev/skills/build-mcp-app/references/payload-budgeting.md

@@ -1,54 +0,0 @@
-# Payload budgeting
-
-Hosts cap tool-result text. claude.ai and Claude Desktop truncate at roughly
-**150,000 characters**; Claude Code at ~25k tokens. When a tool result exceeds
-the cap, the host substitutes a file-pointer string in place of your JSON. The
-widget then receives non-JSON in `ontoolresult`, `JSON.parse` throws, and the
-user sees something like *"Bad payload: SyntaxError: Unexpected token 'E'"* —
-with no hint that size was the cause.
-
-## Symptom → cause
-
-| Symptom | Likely cause |
-|---|---|
-| Widget shows a JSON parse error on `content[0].text` | Result over the host cap; host swapped in a file-pointer string |
-| Works for one query, breaks for "all of X" | Row count × column count crossed the cap |
-| Works in MCP Inspector, breaks in Desktop | Inspector has no cap; Desktop does |
-
-## Strategy
-
-Cap your own payload at ~130KB and degrade in order:
-
-1. **Ship full rows** when `JSON.stringify(rows).length` is under the cap.
-2. **Prune columns** to those the rendering spec actually references. Walk the
-   spec for both `field: "..."` keys *and* `datum.X` / `datum['X']` inside
-   expression strings — if the spec aliases a column via a `calculate`
-   transform, the alias appears as `field:` but the source column only appears
-   as `datum.X`, and dropping it leaves the widget with NaN.
-3. **Truncate rows** as a last resort and include `{ truncated: N }` in the
-   payload so the widget can label it.
-
-```ts
-const MAX = 130_000;
-let out = rows;
-if (JSON.stringify(out).length > MAX) {
-  const keep = referencedFields(spec); // field: + datum.X refs
-  out = rows.map((r) => pick(r, keep));
-  if (JSON.stringify(out).length > MAX) {
-    const per = JSON.stringify(out[0] ?? {}).length || 1;
-    out = out.slice(0, Math.floor(MAX / per));
-  }
-}
-```
-
-## Heavy assets go via `callServerTool`, not the result
-
-Geometry, image bytes, or any blob the widget needs but Claude doesn't should
-be served by a separate tool the widget calls after mount:
-
-```js
-const topo = await app.callServerTool({ name: "get-topojson", arguments: { level } });
-```
-
-Mark that helper tool with `_meta.ui.visibility: ["app"]` so it doesn't appear
-in Claude's tool list.

package/resources/claude-plugins-official/plugins/mcp-server-dev/skills/build-mcp-app/references/widget-templates.md

@@ -1,249 +0,0 @@
-# Widget Templates
-
-Minimal HTML scaffolds for the common widget shapes. Copy, fill in, ship.
-
-All templates inline the `App` class from `@modelcontextprotocol/ext-apps` at build time — the iframe's CSP blocks CDN script imports. They're intentionally framework-free; widgets are small enough that React/Vue hydration cost usually isn't worth it.
-
----
-
-## Serving widget HTML
-
-Widgets are static HTML with one placeholder: `/*__EXT_APPS_BUNDLE__*/` gets replaced at server startup with the `ext-apps/app-with-deps` bundle (rewritten to expose `globalThis.ExtApps`).
-
-```typescript
-import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
-
-const require = createRequire(import.meta.url);
-
-const bundle = readFileSync(
-  require.resolve("@modelcontextprotocol/ext-apps/app-with-deps"), "utf8",
-).replace(/export\{([^}]+)\};?\s*$/, (_, body) =>
-  "globalThis.ExtApps={" +
-  body.split(",").map((p) => {
-    const [local, exported] = p.split(" as ").map((s) => s.trim());
-    return `${exported ?? local}:${local}`;
-  }).join(",") + "};",
-);
-
-const pickerHtml = readFileSync("./widgets/picker.html", "utf8")
-  .replace("/*__EXT_APPS_BUNDLE__*/", () => bundle);
-
-registerAppResource(server, "Picker", "ui://widgets/picker.html", {},
-  async () => ({
-    contents: [{ uri: "ui://widgets/picker.html", mimeType: RESOURCE_MIME_TYPE, text: pickerHtml }],
-  }),
-);
-```
-
-Bundle once per server startup (or at build time); reuse the `bundle` string across all widget templates.
-
----
-
-## Picker (single-select list)
-
-```html
-<!doctype html>
-<meta charset="utf-8" />
-<style>
-  body { font: 14px system-ui; margin: 0; }
-  ul { list-style: none; padding: 0; margin: 0; max-height: 280px; overflow-y: auto; }
-  li { padding: 10px 14px; cursor: pointer; border-bottom: 1px solid #eee; }
-  li:hover { background: #f5f5f5; }
-  .sub { color: #666; font-size: 12px; }
-</style>
-<ul id="list"></ul>
-<script type="module">
-/*__EXT_APPS_BUNDLE__*/
-const { App } = globalThis.ExtApps;
-(async () => {
-  const app = new App({ name: "Picker", version: "1.0.0" }, {});
-  const ul = document.getElementById("list");
-
-  app.ontoolresult = ({ content }) => {
-    const { items } = JSON.parse(content[0].text);
-    ul.innerHTML = "";
-    for (const it of items) {
-      const li = document.createElement("li");
-      li.innerHTML = `<div>${it.label}</div><div class="sub">${it.sub ?? ""}</div>`;
-      li.addEventListener("click", () => {
-        app.sendMessage({
-          role: "user",
-          content: [{ type: "text", text: `Selected: ${it.id}` }],
-        });
-      });
-      ul.append(li);
-    }
-  };
-
-  await app.connect();
-})();
-</script>
-```
-
-**Tool returns:** `{ content: [{ type: "text", text: JSON.stringify({ items: [{ id, label, sub? }] }) }] }`
-
----
-
-## Confirm dialog
-
-```html
-<!doctype html>
-<meta charset="utf-8" />
-<style>
-  body { font: 14px system-ui; margin: 16px; }
-  .actions { display: flex; gap: 8px; margin-top: 16px; }
-  button { padding: 8px 16px; cursor: pointer; }
-  .danger { background: #d33; color: white; border: none; }
-</style>
-<p id="msg"></p>
-<div class="actions">
-  <button id="cancel">Cancel</button>
-  <button id="confirm" class="danger">Confirm</button>
-</div>
-<script type="module">
-/*__EXT_APPS_BUNDLE__*/
-const { App } = globalThis.ExtApps;
-(async () => {
-  const app = new App({ name: "Confirm", version: "1.0.0" }, {});
-
-  app.ontoolresult = ({ content }) => {
-    const { message, confirmLabel } = JSON.parse(content[0].text);
-    document.getElementById("msg").textContent = message;
-    if (confirmLabel) document.getElementById("confirm").textContent = confirmLabel;
-  };
-
-  await app.connect();
-
-  document.getElementById("confirm").addEventListener("click", () => {
-    app.sendMessage({ role: "user", content: [{ type: "text", text: "Confirmed." }] });
-  });
-  document.getElementById("cancel").addEventListener("click", () => {
-    app.sendMessage({ role: "user", content: [{ type: "text", text: "Cancelled." }] });
-  });
-})();
-</script>
-```
-
-**Tool returns:** `{ content: [{ type: "text", text: JSON.stringify({ message, confirmLabel? }) }] }`
-
-**Note:** For simple confirmation, prefer **elicitation** over a widget — see `../build-mcp-server/references/elicitation.md`. Use this widget when you need custom styling or context beyond what a native form offers.
-
----
-
-## Progress (long-running)
-
-```html
-<!doctype html>
-<meta charset="utf-8" />
-<style>
-  body { font: 14px system-ui; margin: 16px; }
-  .bar { height: 8px; background: #eee; border-radius: 4px; overflow: hidden; }
-  .fill { height: 100%; background: #2a7; transition: width 200ms; }
-</style>
-<p id="label">Starting…</p>
-<div class="bar"><div id="fill" class="fill" style="width:0%"></div></div>
-<script type="module">
-/*__EXT_APPS_BUNDLE__*/
-const { App } = globalThis.ExtApps;
-(async () => {
-  const app = new App({ name: "Progress", version: "1.0.0" }, {});
-  const label = document.getElementById("label");
-  const fill = document.getElementById("fill");
-
-  // The tool result fires when the job completes — intermediate updates
-  // arrive via the same handler if the server streams them
-  app.ontoolresult = ({ content }) => {
-    const state = JSON.parse(content[0].text);
-    if (state.progress !== undefined) {
-      label.textContent = state.message ?? `${state.progress}/${state.total}`;
-      fill.style.width = `${(state.progress / state.total) * 100}%`;
-    }
-    if (state.done) {
-      label.textContent = "Complete";
-      fill.style.width = "100%";
-    }
-  };
-
-  await app.connect();
-})();
-</script>
-```
-
-Server side, emit progress via `extra.sendNotification({ method: "notifications/progress", ... })` — see `apps-sdk-messages.md`.
-
----
-
-## Display-only (chart / preview)
-
-Display widgets don't call `sendMessage` — they render and sit there. The tool should return a text summary **alongside** the widget so Claude can keep reasoning while the user sees the visual:
-
-```typescript
-registerAppTool(server, "show_chart", {
-  description: "Render a revenue chart",
-  inputSchema: { range: z.enum(["week", "month", "year"]) },
-  _meta: { ui: { resourceUri: "ui://widgets/chart.html" } },
-}, async ({ range }) => {
-  const data = await fetchRevenue(range);
-  return {
-    content: [{
-      type: "text",
-      text: `Revenue is up ${data.change}% over the ${range}. Chart rendered.\n\n` +
-            JSON.stringify(data.points),
-    }],
-  };
-});
-```
-
-```html
-<!doctype html>
-<meta charset="utf-8" />
-<style>body { font: 14px system-ui; margin: 12px; }</style>
-<canvas id="chart" width="400" height="200"></canvas>
-<script type="module">
-/*__EXT_APPS_BUNDLE__*/
-const { App } = globalThis.ExtApps;
-(async () => {
-  const app = new App({ name: "Chart", version: "1.0.0" }, {});
-
-  app.ontoolresult = ({ content }) => {
-    // Parse the JSON points from the text content (after the summary line)
-    const text = content[0].text;
-    const jsonStart = text.indexOf("\n\n") + 2;
-    const points = JSON.parse(text.slice(jsonStart));
-    drawChart(document.getElementById("chart"), points);
-  };
-
-  await app.connect();
-
-  function drawChart(canvas, points) { /* ... */ }
-})();
-</script>
-```
-
----
-
-## Carousel (multi-item display with actions)
-
-For presenting multiple items (product picks, search results) in a horizontal scroll rail. Patterns that tested well:
-
-- **Skip nav chevrons** — users know how to scroll. `scroll-snap-type` can cause a few-px-off-flush initial render; omit it and `scrollLeft = 0` after rendering.
-- **Layout-fork by item count** — `items.length === 1` → detail/PDP layout, `> 1` → carousel. Handle in widget JS, keep the tool schema flat.
-- **Put Claude's reasoning in each item** — a `note` field rendered as a small callout on the card gives users the "why" inline.
-- **Silent state via `updateModelContext`** — cart/selection changes should inform Claude without spamming the chat. Reserve `sendMessage` for terminal actions ("checkout", "done").
-- **Outbound links via `app.openLink`** — `window.open` and `<a target="_blank">` are blocked by the sandbox.
-
-```html
-<style>
-  .rail { display: flex; gap: 10px; overflow-x: auto; padding: 12px; scrollbar-width: none; }
-  .rail::-webkit-scrollbar { display: none; }
-  .card { flex: 0 0 220px; border: 1px solid #ddd; border-radius: 6px; padding: 10px; }
-  .thumb-box { aspect-ratio: 1 / 1; display: grid; place-items: center; background: #f7f8f8; }
-  .thumb { max-width: 100%; max-height: 100%; object-fit: contain; }
-  .note { font-size: 12px; color: #666; border-left: 3px solid orange; padding: 2px 8px; margin: 8px 0; }
-</style>
-<div class="rail" id="rail"></div>
-```
-
-**Images:** the iframe CSP blocks remote `img-src`. Fetch thumbnails server-side in the tool handler, embed as `data:` URLs in the JSON payload, and render from those. Add `referrerpolicy="no-referrer"` as a fallback.