From c30a97c671e59762e82dcaa0b692fcbc5aca2b40 Mon Sep 17 00:00:00 2001
From: Ahnaf An Nafee <ahnafnafee@gmail.com>
Date: Mon, 12 Oct 2026 01:51:56 -0400
Subject: [PATCH 1/2] fix(mcp): load skill documents on Windows

loadSkill guards against path traversal by checking that the resolved
path starts with the skills directory followed by "/". On Windows,
path.resolve returns backslash-separated paths, so every skill name
failed the check and all skill resources and prompts threw "Invalid
skill name". Compare against path.sep instead, and cover loading and
traversal rejection in tests.
---
 apps/mcp/src/skills.ts        |  4 ++--
 apps/mcp/tests/skills.test.ts | 12 +++++++++++-
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/apps/mcp/src/skills.ts b/apps/mcp/src/skills.ts
index e578d8a..12d1e96 100644
--- a/apps/mcp/src/skills.ts
+++ b/apps/mcp/src/skills.ts
@@ -1,5 +1,5 @@
 import { readFileSync, readdirSync } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -15,7 +15,7 @@ export function listSkills(): string[] {
 
 export function loadSkill(name: string): string {
   const resolved = resolve(SKILLS_DIR, `${name}.txt`);
-  if (!resolved.startsWith(resolve(SKILLS_DIR) + "/")) {
+  if (!resolved.startsWith(resolve(SKILLS_DIR) + sep)) {
     throw new Error(`Invalid skill name: ${name}`);
   }
   return readFileSync(resolved, "utf-8");
diff --git a/apps/mcp/tests/skills.test.ts b/apps/mcp/tests/skills.test.ts
index 57a35e1..df55a0b 100644
--- a/apps/mcp/tests/skills.test.ts
+++ b/apps/mcp/tests/skills.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { listSkills } from "../src/skills";
+import { listSkills, loadSkill } from "../src/skills";
 
 describe("listSkills", () => {
   it("returns an array containing the bundled skills", () => {
@@ -8,3 +8,13 @@ describe("listSkills", () => {
     expect(skills).toContain("master-agent-playbook");
   });
 });
+
+describe("loadSkill", () => {
+  it("loads a bundled skill by name on every platform", () => {
+    expect(loadSkill("master-agent-playbook").length).toBeGreaterThan(0);
+  });
+
+  it("rejects names that escape the skills directory", () => {
+    expect(() => loadSkill("../package")).toThrow("Invalid skill name");
+  });
+});

From 40c410e848d430262ec9784fa0c3321c6b1ebe57 Mon Sep 17 00:00:00 2001
From: Ahnaf An Nafee <ahnafnafee@gmail.com>
Date: Mon, 12 Oct 2026 01:51:56 -0400
Subject: [PATCH 2/2] feat(mcp): render assemble_document inline as an MCP App

assemble_document returned the assembled page as plain text, so MCP Apps
hosts such as Claude Desktop showed raw HTML instead of rendering it.

- Register a ui://open-generative-ui/document.html view
  (text/html;profile=mcp-app) and link the tool to it through
  _meta.ui.resourceUri, plus the legacy ui/resourceUri key.
- The view applies the design system and the host theme, runs the
  fragment's scripts in order, and maps sendPrompt and openLink to the
  MCP Apps bridge. It loads the pinned ext-apps app-with-deps bundle from
  jsDelivr, which is already on the CDN allowlist, and asks hosts for no
  border.
- Clients that advertise the io.modelcontextprotocol/ui extension get a
  one-line result instead of the roughly 12 KB document, which keeps it
  out of the model's context. Other clients still receive the full
  document.
- Bump @modelcontextprotocol/sdk to ^1.32.1, whose ClientCapabilities
  schema keeps the extensions field.
- Share one CDN allowlist between the iframe CSP and the MCP Apps CSP.
---
 apps/mcp/README.md            |  2 +
 apps/mcp/package.json         |  2 +-
 apps/mcp/src/renderer.ts      | 84 ++++++++++++++++++++++++++++++++---
 apps/mcp/src/server.ts        | 57 +++++++++++++++++++++---
 apps/mcp/tests/server.test.ts | 72 ++++++++++++++++++++++++++++++
 docs/mcp-integration.md       |  1 +
 pnpm-lock.yaml                | 58 +++++++++++++++++++++++-
 7 files changed, 261 insertions(+), 15 deletions(-)
 create mode 100644 apps/mcp/tests/server.test.ts

diff --git a/apps/mcp/README.md b/apps/mcp/README.md
index c4a6c43..d3346f3 100644
--- a/apps/mcp/README.md
+++ b/apps/mcp/README.md
@@ -120,6 +120,8 @@ Then start the HTTP server with `pnpm dev`.
 
 Wraps an HTML fragment with the complete OpenGenerativeUI design system.
 
+In [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) hosts such as Claude Desktop, the tool is linked to the `ui://open-generative-ui/document.html` view, so the fragment renders inline in the conversation. The view applies the design system and the host's theme, runs the fragment's scripts in order, and maps `sendPrompt(text)` and `openLink(url)` to the host. The tool result is then a one-line confirmation, which keeps the document out of the model's context. Clients that do not advertise the `io.modelcontextprotocol/ui` extension receive the complete document as shown below.
+
 **Input:**
 ```typescript
 {
diff --git a/apps/mcp/package.json b/apps/mcp/package.json
index 5dd31a3..6d10310 100644
--- a/apps/mcp/package.json
+++ b/apps/mcp/package.json
@@ -23,7 +23,7 @@
   "license": "MIT",
   "dependencies": {
     "@hono/node-server": "^1",
-    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@repo/design-system": "workspace:*",
     "hono": "^4",
     "zod": "^3.23"
diff --git a/apps/mcp/src/renderer.ts b/apps/mcp/src/renderer.ts
index 8e1400b..81327fa 100644
--- a/apps/mcp/src/renderer.ts
+++ b/apps/mcp/src/renderer.ts
@@ -3,6 +3,21 @@
 
 import { THEME_CSS, SVG_CLASSES_CSS, FORM_STYLES_CSS } from "@repo/design-system";
 
+// Origins generated UI may load scripts and assets from, in both rendering paths.
+export const CDN_ORIGINS = [
+  "https://cdnjs.cloudflare.com",
+  "https://esm.sh",
+  "https://cdn.jsdelivr.net",
+  "https://unpkg.com",
+];
+
+export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+
+// ponytail: the view loads the MCP Apps SDK from jsDelivr when it opens, so rendering
+// needs network access; inline app-with-deps.js into the view if offline hosts matter.
+const EXT_APPS_SDK_URL =
+  "https://cdn.jsdelivr.net/npm/@modelcontextprotocol/ext-apps@2.0.3/dist/src/app-with-deps.js";
+
 const BRIDGE_JS = `
 window.sendPrompt = function(text) {
   window.parent.postMessage({ type: 'send-prompt', text: text }, '*');
@@ -37,11 +52,7 @@ export function assembleDocument(html: string): string {
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <meta http-equiv="Content-Security-Policy" content="
     default-src 'self';
-    script-src 'unsafe-inline' 'unsafe-eval'
-      https://cdnjs.cloudflare.com
-      https://esm.sh
-      https://cdn.jsdelivr.net
-      https://unpkg.com;
+    script-src 'unsafe-inline' 'unsafe-eval' ${CDN_ORIGINS.join(" ")};
     style-src 'unsafe-inline';
     img-src 'self' data: blob:;
     font-src 'self' data:;
@@ -63,3 +74,66 @@ export function assembleDocument(html: string): string {
 </body>
 </html>`;
 }
+
+// MCP Apps view for assemble_document. The host renders it in a sandboxed iframe
+// and delivers the tool arguments, so the fragment arrives as args.html.
+export const MCP_APP_VIEW_HTML = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="light dark">
+  <style>
+    ${THEME_CSS}
+    ${SVG_CLASSES_CSS}
+    ${FORM_STYLES_CSS}
+    .sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+  </style>
+</head>
+<body>
+  <div id="content"></div>
+  <script type="module">
+    import { App, applyDocumentTheme, applyHostStyleVariables, applyHostFonts } from "${EXT_APPS_SDK_URL}";
+
+    const app = new App({ name: "open-generative-ui", version: "0.1.0" });
+    const content = document.getElementById("content");
+
+    window.sendPrompt = (text) =>
+      app.sendMessage({ role: "user", content: [{ type: "text", text: String(text) }] });
+    window.openLink = (url) => app.openLink({ url: String(url) });
+    document.addEventListener("click", (e) => {
+      const a = e.target.closest && e.target.closest("a[href^='http']");
+      if (a) { e.preventDefault(); window.openLink(a.href); }
+    });
+
+    // innerHTML never runs scripts, so each one is recreated in document order.
+    // External classic scripts are awaited so later inline code can use their globals.
+    async function render(html) {
+      content.innerHTML = html;
+      for (const old of content.querySelectorAll("script")) {
+        const script = document.createElement("script");
+        for (const { name, value } of old.attributes) script.setAttribute(name, value);
+        script.textContent = old.textContent;
+        const loaded = script.src && script.type !== "module"
+          ? new Promise((done) => { script.onload = script.onerror = done; })
+          : null;
+        old.replaceWith(script);
+        if (loaded) await loaded;
+      }
+    }
+
+    function applyHostContext(ctx) {
+      if (ctx?.theme) applyDocumentTheme(ctx.theme);
+      if (ctx?.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
+      if (ctx?.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
+    }
+
+    app.ontoolinput = ({ arguments: args }) => {
+      if (typeof args?.html === "string") render(args.html);
+    };
+    app.onhostcontextchanged = applyHostContext;
+    await app.connect();
+    applyHostContext(app.getHostContext());
+  </script>
+</body>
+</html>`;
diff --git a/apps/mcp/src/server.ts b/apps/mcp/src/server.ts
index a2caf8a..ab210d3 100644
--- a/apps/mcp/src/server.ts
+++ b/apps/mcp/src/server.ts
@@ -4,7 +4,15 @@ import {
 } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { listSkills, loadSkill } from "./skills.js";
-import { assembleDocument } from "./renderer.js";
+import {
+  assembleDocument,
+  CDN_ORIGINS,
+  MCP_APP_MIME_TYPE,
+  MCP_APP_VIEW_HTML,
+} from "./renderer.js";
+
+const VIEW_URI = "ui://open-generative-ui/document.html";
+const UI_EXTENSION = "io.modelcontextprotocol/ui";
 
 export function createMcpServer(): McpServer {
   const server = new McpServer({
@@ -97,13 +105,39 @@ export function createMcpServer(): McpServer {
     }),
   );
 
-  // Tool: assemble complete HTML document with design system
+  // MCP Apps view: hosts with the ui extension render assemble_document inline
+  server.registerResource(
+    "document-view",
+    VIEW_URI,
+    {
+      description: "Renders assemble_document fragments inline in MCP Apps hosts",
+      mimeType: MCP_APP_MIME_TYPE,
+    },
+    async () => ({
+      contents: [
+        {
+          uri: VIEW_URI,
+          mimeType: MCP_APP_MIME_TYPE,
+          text: MCP_APP_VIEW_HTML,
+          _meta: {
+            ui: {
+              prefersBorder: false,
+              csp: { resourceDomains: CDN_ORIGINS, connectDomains: CDN_ORIGINS },
+            },
+          },
+        },
+      ],
+    }),
+  );
+
+  // Tool: render (MCP Apps hosts) or assemble (other clients) a design-system document
   server.registerTool(
     "assemble_document",
     {
       description:
-        "Wraps HTML with Open Intelligent UI theme CSS, SVG classes, form styles, and bridge JS. " +
-        "Returns a complete iframe-ready HTML document.",
+        "Renders an HTML fragment for the user with Open Intelligent UI theme CSS variables, " +
+        "SVG c-* classes, form styles, and sendPrompt(text) / openLink(url) globals. " +
+        "MCP Apps hosts show it inline; other clients get the complete iframe-ready HTML document.",
       inputSchema: {
         title: z.string().describe("Short title for the visualization"),
         description: z
@@ -115,10 +149,19 @@ export function createMcpServer(): McpServer {
             "Self-contained HTML fragment with inline <style> and <script>",
           ),
       },
+      _meta: { ui: { resourceUri: VIEW_URI }, "ui/resourceUri": VIEW_URI },
+    },
+    async ({ title, html }) => {
+      // The view already shows the fragment, so UI hosts get a one-liner instead of
+      // echoing ~12 KB of design-system CSS into the model's context on every call.
+      const ui = server.server.getClientCapabilities()?.extensions?.[UI_EXTENSION] as
+        | { mimeTypes?: string[] }
+        | undefined;
+      const text = ui?.mimeTypes?.includes(MCP_APP_MIME_TYPE)
+        ? `Rendered "${title}" inline for the user.`
+        : assembleDocument(html);
+      return { content: [{ type: "text", text }] };
     },
-    async ({ html }) => ({
-      content: [{ type: "text", text: assembleDocument(html) }],
-    }),
   );
 
   return server;
diff --git a/apps/mcp/tests/server.test.ts b/apps/mcp/tests/server.test.ts
new file mode 100644
index 0000000..0972245
--- /dev/null
+++ b/apps/mcp/tests/server.test.ts
@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import type { ClientCapabilities } from "@modelcontextprotocol/sdk/types.js";
+import { createMcpServer } from "../src/server";
+
+const VIEW_URI = "ui://open-generative-ui/document.html";
+const MCP_APP_MIME = "text/html;profile=mcp-app";
+const UI_HOST: ClientCapabilities = {
+  extensions: { "io.modelcontextprotocol/ui": { mimeTypes: [MCP_APP_MIME] } },
+};
+const ARGS = { title: "Demo", description: "A demo", html: "<p id='x'>hi</p>" };
+
+async function connect(capabilities: ClientCapabilities = {}) {
+  const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
+  await createMcpServer().connect(serverSide);
+  const client = new Client({ name: "test", version: "0.0.0" }, { capabilities });
+  await client.connect(clientSide);
+  return client;
+}
+
+async function callText(capabilities?: ClientCapabilities) {
+  const client = await connect(capabilities);
+  const result = await client.callTool({ name: "assemble_document", arguments: ARGS });
+  return (result.content as { type: string; text: string }[])[0].text;
+}
+
+describe("assemble_document as an MCP App", () => {
+  it("links the tool to its ui:// view, including the legacy key", async () => {
+    const { tools } = await (await connect()).listTools();
+    const tool = tools.find((t) => t.name === "assemble_document");
+    expect(tool?._meta).toMatchObject({
+      ui: { resourceUri: VIEW_URI },
+      "ui/resourceUri": VIEW_URI,
+    });
+  });
+
+  it("serves the view with the design system, bridge, and CDN allowlist", async () => {
+    const { contents } = await (await connect()).readResource({ uri: VIEW_URI });
+    const view = contents[0] as { mimeType?: string; text?: string; _meta?: unknown };
+    expect(view.mimeType).toBe(MCP_APP_MIME);
+    expect(view.text).toContain("--color-background-primary");
+    expect(view.text).toContain("window.sendPrompt");
+    expect(view.text).toContain("window.openLink");
+    expect(view.text).toMatch(/\.sr-only\s*\{[^}]*clip:/);
+    expect(view._meta).toMatchObject({
+      ui: {
+        prefersBorder: false,
+        csp: {
+          resourceDomains: expect.arrayContaining([
+            "https://cdnjs.cloudflare.com",
+            "https://esm.sh",
+            "https://cdn.jsdelivr.net",
+            "https://unpkg.com",
+          ]),
+        },
+      },
+    });
+  });
+
+  it("keeps the document out of the model's context on MCP Apps hosts", async () => {
+    const text = await callText(UI_HOST);
+    expect(text).not.toContain("<!DOCTYPE html>");
+    expect(text).toContain("Demo");
+  });
+
+  it("returns the full document to hosts that cannot render MCP Apps", async () => {
+    const text = await callText();
+    expect(text).toContain("<!DOCTYPE html>");
+    expect(text).toContain(ARGS.html);
+  });
+});
diff --git a/docs/mcp-integration.md b/docs/mcp-integration.md
index d7c267b..bb86536 100644
--- a/docs/mcp-integration.md
+++ b/docs/mcp-integration.md
@@ -12,6 +12,7 @@ The MCP server lives in `apps/mcp/`.
 |-----|-------------|
 | `skills://list` | JSON array of available skill names |
 | `skills://{name}` | Full text of an individual skill document |
+| `ui://open-generative-ui/document.html` | MCP Apps view that renders `assemble_document` output inline (Claude Desktop and other MCP Apps hosts) |
 
 ### Prompts
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a8161fe..69c4fcc 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -121,8 +121,8 @@ importers:
         specifier: ^1
         version: 1.19.9(hono@4.11.7)
       '@modelcontextprotocol/sdk':
-        specifier: ^1.25.3
-        version: 1.25.3(@cfworker/json-schema@4.1.1)(hono@4.11.7)(zod@3.25.76)
+        specifier: ^1.32.1
+        version: 1.32.1(@cfworker/json-schema@4.1.1)(zod@3.25.76)
       '@repo/design-system':
         specifier: workspace:*
         version: link:../../packages/design-system
@@ -1119,6 +1119,16 @@ packages:
       '@cfworker/json-schema':
         optional: true
 
+  '@modelcontextprotocol/sdk@1.32.1':
+    resolution: {integrity: sha512-2DdE+SJDtzLEEWzY1ZjY7Q+VcPhcV1KisD3zI4u0XZyktsjHum1mwbMI+JaulUBi2OZk+KJAi2uPXzxichPkdw==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@cfworker/json-schema': ^4.1.1
+      zod: ^3.25 || ^4.0
+    peerDependenciesMeta:
+      '@cfworker/json-schema':
+        optional: true
+
   '@napi-rs/wasm-runtime@0.2.12':
     resolution: {integrity: sha512-ZVWUcfwY4E/yPitQJl481FjFo3K22D6qF0DuFH6Y/nbnE11GY5uguDxZMGXPQ8WQ0128MXQD7TnfHyK4oWoIJQ==}
 
@@ -3177,6 +3187,12 @@ packages:
     peerDependencies:
       express: '>= 4.11'
 
+  express-rate-limit@8.7.1:
+    resolution: {integrity: sha512-2FXbqkygil3mZiXzEtM0IjE/UBmBNot0J1GEVrJT4JbrvwOSoEtqtO+wHbiMQELWe1eNvHoYRg2dkjOid+6JkA==}
+    engines: {node: '>= 16'}
+    peerDependencies:
+      express: '>= 4.11'
+
   express@4.22.1:
     resolution: {integrity: sha512-F2X8g9P1X7uCPZMA3MVf9wcTqlyNp7IhH5qPCI0izhaOIYXaW9L535tGA3qmjRzpH+bZczqq7hVKxTR4NWnu+g==}
     engines: {node: '>= 0.10.0'}
@@ -3594,6 +3610,10 @@ packages:
     resolution: {integrity: sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==}
     engines: {node: '>=12'}
 
+  ip-address@10.7.4:
+    resolution: {integrity: sha512-DWBMKyeM25D70nrIiTkgQth59/G+naKOTep6huF9j+GmeK3DMD60Zvxg5d5qQnz+38AHgou6ean2LECX+lrKDg==}
+    engines: {node: '>= 12'}
+
   ipaddr.js@1.9.1:
     resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
     engines: {node: '>= 0.10'}
@@ -7042,6 +7062,30 @@ snapshots:
       - hono
       - supports-color
 
+  '@modelcontextprotocol/sdk@1.32.1(@cfworker/json-schema@4.1.1)(zod@3.25.76)':
+    dependencies:
+      '@hono/node-server': 1.19.9(hono@4.11.7)
+      ajv: 8.17.1
+      ajv-formats: 3.0.1(ajv@8.17.1)
+      content-type: 1.0.5
+      cors: 2.8.6
+      cross-spawn: 7.0.6
+      eventsource: 3.0.7
+      eventsource-parser: 3.0.6
+      express: 5.2.1
+      express-rate-limit: 8.7.1(express@5.2.1)
+      hono: 4.11.7
+      jose: 6.1.3
+      json-schema-typed: 8.0.2
+      pkce-challenge: 5.0.1
+      raw-body: 3.0.2
+      zod: 3.25.76
+      zod-to-json-schema: 3.25.1(zod@3.25.76)
+    optionalDependencies:
+      '@cfworker/json-schema': 4.1.1
+    transitivePeerDependencies:
+      - supports-color
+
   '@napi-rs/wasm-runtime@0.2.12':
     dependencies:
       '@emnapi/core': 1.8.1
@@ -9240,6 +9284,14 @@ snapshots:
     dependencies:
       express: 5.2.1
 
+  express-rate-limit@8.7.1(express@5.2.1):
+    dependencies:
+      debug: 4.4.3
+      express: 5.2.1
+      ip-address: 10.7.4
+    transitivePeerDependencies:
+      - supports-color
+
   express@4.22.1:
     dependencies:
       accepts: 1.3.8
@@ -9810,6 +9862,8 @@ snapshots:
 
   internmap@2.0.3: {}
 
+  ip-address@10.7.4: {}
+
   ipaddr.js@1.9.1: {}
 
   is-alphabetical@1.0.4: {}