fix(plugin): mcp-server-dev — correct APIs against spec, add missing primitives

Corrects fabricated/deprecated APIs: ext-apps App class model (not embedded resources), real MCPB v0.4 manifest (no permissions block exists), registerTool (not server.tool), @anthropic-ai/mcpb package name, CIMD preferred over DCR. Adds missing spec coverage: resources, prompts, elicitation (with capability check + fallback), sampling, roots, tool annotations, structured output, instructions field, progress/cancellation.
2026-03-20 23:43:07 +00:00 · 2026-03-18 22:53:38 +00:00
parent f7ba55786d
commit 48a018f27a
13 changed files with 1195 additions and 409 deletions
--- a/plugins/mcp-server-dev/skills/build-mcp-app/references/widget-templates.md
+++ b/plugins/mcp-server-dev/skills/build-mcp-app/references/widget-templates.md
@@ -2,31 +2,27 @@

 Minimal HTML scaffolds for the common widget shapes. Copy, fill in, ship.

-All templates assume the apps-SDK helper is available at an ESM CDN. They're intentionally framework-free — widgets render in a fresh iframe each time, so React/Vue hydration cost usually isn't worth it for something this small.
+All templates use the `App` class from `@modelcontextprotocol/ext-apps` via ESM CDN. They're intentionally framework-free — widgets are small enough that React/Vue hydration cost usually isn't worth it.

 ---

-## The render helper
+## Serving widget HTML

-Ten lines of string templating. Good enough for almost every case.
+Widgets are static HTML — data arrives at runtime via `ontoolresult`, not baked in. Store each widget as a string constant or read from disk:

 ```typescript
 import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";

-const TEMPLATE_DIR = join(import.meta.dirname, "../widgets");
+const pickerHtml = readFileSync("./widgets/picker.html", "utf8");

-export function renderWidget(name: string, data: unknown): string {
-  const tpl = readFileSync(join(TEMPLATE_DIR, `${name}.html`), "utf8");
-  return tpl.replace(
-    "__DATA__",
-    JSON.stringify(data).replace(/</g, "\\u003c"),
-  );
-}
+registerAppResource(server, "Picker", "ui://widgets/picker.html", {},
+  async () => ({
+    contents: [{ uri: "ui://widgets/picker.html", mimeType: RESOURCE_MIME_TYPE, text: pickerHtml }],
+  }),
+);
 ```

-Every template below hydrates from `<script id="data">__DATA__</script>`. The `<` escape prevents `</script>` injection.
-
 ---

 ## Picker (single-select list)
@@ -34,7 +30,6 @@ Every template below hydrates from `<script id="data">__DATA__</script>`. The `<
 ```html
 <!doctype html>
 <meta charset="utf-8" />
-<script id="data" type="application/json">__DATA__</script>
 <style>
  body { font: 14px system-ui; margin: 0; }
  ul { list-style: none; padding: 0; margin: 0; max-height: 280px; overflow-y: auto; }
@@ -44,20 +39,32 @@ Every template below hydrates from `<script id="data">__DATA__</script>`. The `<
 </style>
 <ul id="list"></ul>
 <script type="module">
-  import { submit } from "https://esm.sh/@modelcontextprotocol/apps-sdk";
-  const { items } = JSON.parse(document.getElementById("data").textContent);
+  import { App } from "https://esm.sh/@modelcontextprotocol/ext-apps@1.2.2";
+
+  const app = new App({ name: "Picker", version: "1.0.0" }, {});
  const ul = document.getElementById("list");
-  for (const it of items) {
-    const li = document.createElement("li");
-    li.innerHTML = `<div>${it.label}</div><div class="sub">${it.sub ?? ""}</div>`;
-    li.onclick = () => submit({ id: it.id });
-    ul.append(li);
-  }
+
+  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>
 ```

-**Data shape:** `{ items: [{ id, label, sub? }] }`
-**Result shape:** `{ id }`
+**Tool returns:** `{ content: [{ type: "text", text: JSON.stringify({ items: [{ id, label, sub? }] }) }] }`

 ---

@@ -66,7 +73,6 @@ Every template below hydrates from `<script id="data">__DATA__</script>`. The `<
 ```html
 <!doctype html>
 <meta charset="utf-8" />
-<script id="data" type="application/json">__DATA__</script>
 <style>
  body { font: 14px system-ui; margin: 16px; }
  .actions { display: flex; gap: 8px; margin-top: 16px; }
@@ -79,17 +85,30 @@ Every template below hydrates from `<script id="data">__DATA__</script>`. The `<
  <button id="confirm" class="danger">Confirm</button>
 </div>
 <script type="module">
-  import { submit } from "https://esm.sh/@modelcontextprotocol/apps-sdk";
-  const { message, confirmLabel } = JSON.parse(document.getElementById("data").textContent);
-  document.getElementById("msg").textContent = message;
-  if (confirmLabel) document.getElementById("confirm").textContent = confirmLabel;
-  document.getElementById("confirm").onclick = () => submit({ confirmed: true });
-  document.getElementById("cancel").onclick = () => submit({ confirmed: false });
+  import { App } from "https://esm.sh/@modelcontextprotocol/ext-apps@1.2.2";
+
+  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>
 ```

-**Data shape:** `{ message, confirmLabel? }`
-**Result shape:** `{ confirmed: boolean }`
+**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.

 ---

@@ -98,7 +117,6 @@ Every template below hydrates from `<script id="data">__DATA__</script>`. The `<
 ```html
 <!doctype html>
 <meta charset="utf-8" />
-<script id="data" type="application/json">__DATA__</script>
 <style>
  body { font: 14px system-ui; margin: 16px; }
  .bar { height: 8px; background: #eee; border-radius: 4px; overflow: hidden; }
@@ -107,34 +125,75 @@ Every template below hydrates from `<script id="data">__DATA__</script>`. The `<
 <p id="label">Starting…</p>
 <div class="bar"><div id="fill" class="fill" style="width:0%"></div></div>
 <script type="module">
-  import { submit, onMessage } from "https://esm.sh/@modelcontextprotocol/apps-sdk";
-  const { jobId } = JSON.parse(document.getElementById("data").textContent);
+  import { App } from "https://esm.sh/@modelcontextprotocol/ext-apps@1.2.2";
+
+  const app = new App({ name: "Progress", version: "1.0.0" }, {});
  const label = document.getElementById("label");
  const fill = document.getElementById("fill");

-  onMessage((msg) => {
-    if (msg.type === "progress") {
-      label.textContent = msg.label;
-      fill.style.width = `${msg.percent}%`;
+  // 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 (msg.type === "done") submit(msg.result);
-  });
+    if (state.done) {
+      label.textContent = "Complete";
+      fill.style.width = "100%";
+    }
+  };
+
+  await app.connect();
 </script>
 ```

-The server pushes updates via the transport's notification channel targeting this widget's session. See `apps-sdk-messages.md` for the server-side push.
+Server side, emit progress via `extra.sendNotification({ method: "notifications/progress", ... })` — see `apps-sdk-messages.md`.

 ---

 ## Display-only (chart / preview)

-Display widgets don't need `submit()` — they render and sit there. Return a text summary **alongside** the widget so Claude can keep reasoning:
+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
-return {
-  content: [
-    { type: "text", text: "Revenue is up 12% MoM. Chart rendered below." },
-    { type: "resource", resource: { uri: "ui://widgets/chart", mimeType: "text/html+skybridge", text: renderWidget("chart", data) } },
-  ],
-};
+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">
+  import { App } from "https://esm.sh/@modelcontextprotocol/ext-apps@1.2.2";
+
+  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>
 ```