chore: merge main into release-0.3.0

Merge latest changes from main including:
- Vue, Svelte, Preact, and Solid basic server examples (#141)
- safeAreaInsets support (#202)
- E2E test fixes (#206)
- npm publishing for examples (#184)
- ui.resourceUri optional (#210)
- Method names as consts (#192)
- toolInfo.id optional (#216)
- PostMessageTransport security fixes (#207, #208)
- Server-utils.ts refactoring

Author: ochafik

.github/workflows/npm-publish.yml

@@ -83,3 +83,47 @@ jobs:
       - run: npm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }}
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_SECRET }}
+
+  publish-examples:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    environment: Release
+    needs: [publish]
+
+    permissions:
+      contents: read
+      id-token: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        example:
+          - basic-server-react
+          - basic-server-vanillajs
+          - budget-allocator-server
+          - cohort-heatmap-server
+          - customer-segmentation-server
+          - scenario-modeler-server
+          - system-monitor-server
+          - threejs-server
+          - wiki-explorer-server
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci
+
+      - name: Build example
+        run: npm run build --workspace examples/${{ matrix.example }}
+
+      - name: Publish example
+        run: npm publish --workspace examples/${{ matrix.example }} --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_SECRET }}

.github/workflows/publish.yml

@@ -20,4 +20,16 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run build
-      - run: npx pkg-pr-new publish
+      - run: npm run examples:build
+      - run: |
+          npx pkg-pr-new publish \
+            . \
+            ./examples/basic-server-react \
+            ./examples/basic-server-vanillajs \
+            ./examples/budget-allocator-server \
+            ./examples/cohort-heatmap-server \
+            ./examples/customer-segmentation-server \
+            ./examples/scenario-modeler-server \
+            ./examples/system-monitor-server \
+            ./examples/threejs-server \
+            ./examples/wiki-explorer-server

.prettierignore

@@ -1,6 +1,4 @@
 examples/basic-host/**/*.ts
 examples/basic-host/**/*.tsx
-examples/basic-server-react/**/*.ts
-examples/basic-server-react/**/*.tsx
-examples/basic-server-vanillajs/**/*.ts
-examples/basic-server-vanillajs/**/*.tsx
+examples/basic-server-*/**/*.ts
+examples/basic-server-*/**/*.tsx

README.md

@@ -47,9 +47,13 @@ Or edit your `package.json` manually:
 
 Start with these foundational examples to learn the SDK:
 
-- [`examples/basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs) — Example MCP server with tools that return UI Apps (vanilla JS)
-- [`examples/basic-server-react`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react) — Example MCP server with tools that return UI Apps (React)
-- [`examples/basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) — Bare-bones example of hosting MCP Apps
+- [`examples/basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs) — MCP server + MCP App using vanilla JS
+- [`examples/basic-server-react`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react) — MCP server + MCP App using [React](https://github.com/facebook/react)
+- [`examples/basic-server-vue`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vue) — MCP server + MCP App using [Vue](https://github.com/vuejs/vue)
+- [`examples/basic-server-svelte`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-svelte) — MCP server + MCP App using [Svelte](https://github.com/sveltejs/svelte)
+- [`examples/basic-server-preact`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-preact) — MCP server + MCP App using [Preact](https://github.com/preactjs/preact)
+- [`examples/basic-server-solid`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-solid) — MCP server + MCP App using [Solid](https://github.com/solidjs/solid)
+- [`examples/basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) — MCP host application supporting MCP Apps
 
 The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples) directory contains additional demo apps showcasing real-world use cases.
 

examples/basic-host/src/index.tsx

@@ -350,7 +350,27 @@ class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
 async function connectToAllServers(): Promise<ServerInfo[]> {
   const serverUrlsResponse = await fetch("/api/servers");
   const serverUrls = (await serverUrlsResponse.json()) as string[];
-  return Promise.all(serverUrls.map((url) => connectToServer(new URL(url))));
+
+  // Use allSettled to be resilient to individual server failures
+  const results = await Promise.allSettled(
+    serverUrls.map((url) => connectToServer(new URL(url)))
+  );
+
+  const servers: ServerInfo[] = [];
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+    if (result.status === "fulfilled") {
+      servers.push(result.value);
+    } else {
+      console.warn(`[HOST] Failed to connect to ${serverUrls[i]}:`, result.reason);
+    }
+  }
+
+  if (servers.length === 0 && serverUrls.length > 0) {
+    throw new Error(`Failed to connect to any servers (${serverUrls.length} attempted)`);
+  }
+
+  return servers;
 }
 
 createRoot(document.getElementById("root")!).render(

examples/basic-host/src/sandbox.ts

@@ -16,6 +16,12 @@ if (!document.referrer.match(ALLOWED_REFERRER_PATTERN)) {
   );
 }
 
+// Extract the expected host origin from the referrer for origin validation.
+// This is the origin we expect all parent messages to come from.
+const EXPECTED_HOST_ORIGIN = new URL(document.referrer).origin;
+
+const OWN_ORIGIN = new URL(window.location.href).origin;
+
 // Security self-test: verify iframe isolation is working correctly.
 // This MUST throw a SecurityError -- if `window.top` is accessible, the sandbox
 // configuration is dangerously broken and untrusted content could escape.
@@ -79,8 +85,18 @@ function buildCspMetaTag(csp?: { connectDomains?: string[]; resourceDomains?: st
 
 window.addEventListener("message", async (event) => {
   if (event.source === window.parent) {
-    // NOTE: In production you'll also want to validate `event.origin` against
-    // your Host domain.
+    // Validate that messages from parent come from the expected host origin.
+    // This prevents malicious pages from sending messages to this sandbox.
+    if (event.origin !== EXPECTED_HOST_ORIGIN) {
+      console.error(
+        "[Sandbox] Rejecting message from unexpected origin:",
+        event.origin,
+        "expected:",
+        EXPECTED_HOST_ORIGIN
+      );
+      return;
+    }
+
     if (event.data && event.data.method === RESOURCE_READY_NOTIFICATION) {
       const { html, sandbox, csp } = event.data.params;
       if (typeof sandbox === "string") {
@@ -112,14 +128,25 @@ window.addEventListener("message", async (event) => {
       }
     }
   } else if (event.source === inner.contentWindow) {
+    if (event.origin !== OWN_ORIGIN) {
+      console.error(
+        "[Sandbox] Rejecting message from inner iframe with unexpected origin:",
+        event.origin,
+        "expected:",
+        OWN_ORIGIN
+      );
+      return;
+    }
     // Relay messages from inner frame to parent window.
-    window.parent.postMessage(event.data, "*");
+    // Use specific origin instead of "*" to prevent message interception.
+    window.parent.postMessage(event.data, EXPECTED_HOST_ORIGIN);
   }
 });
 
 // Notify the Host that the Sandbox is ready to receive Guest UI HTML.
+// Use specific origin instead of "*" to ensure only the expected host receives this.
 window.parent.postMessage({
   jsonrpc: "2.0",
   method: PROXY_READY_NOTIFICATION,
   params: {},
-}, "*");
+}, EXPECTED_HOST_ORIGIN);

examples/basic-server-preact/README.md

@@ -0,0 +1,30 @@
+# Example: Basic Server (Preact)
+
+An MCP App example with a Preact UI.
+
+> [!TIP]
+> Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)!
+
+## Overview
+
+- Tool registration with a linked UI resource
+- Preact UI using the [`App`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html) class
+- App communication APIs: [`callServerTool`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#callservertool), [`sendMessage`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendmessage), [`sendLog`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#sendlog), [`openLink`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#openlink)
+
+## Key Files
+
+- [`server.ts`](server.ts) - MCP server with tool and resource registration
+- [`mcp-app.html`](mcp-app.html) / [`src/mcp-app.tsx`](src/mcp-app.tsx) - Preact UI using `App` class
+
+## Getting Started
+
+```bash
+npm install
+npm run dev
+```
+
+## How It Works
+
+1. The server registers a `get-time` tool with metadata linking it to a UI HTML resource (`ui://get-time/mcp-app.html`).
+2. When the tool is invoked, the Host renders the UI from the resource.
+3. The UI uses the MCP App SDK API to communicate with the host and call server tools.

examples/basic-server-preact/mcp-app.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="color-scheme" content="light dark">
+  <title>Get Time App</title>
+  <link rel="stylesheet" href="/src/global.css">
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/mcp-app.tsx"></script>
+</body>
+</html>

examples/basic-server-preact/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@modelcontextprotocol/server-basic-preact",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Basic MCP App Server example using Preact",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/modelcontextprotocol/ext-apps",
+    "directory": "examples/basic-server-preact"
+  },
+  "license": "MIT",
+  "main": "server.ts",
+  "files": [
+    "server.ts",
+    "server-utils.ts",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit && cross-env INPUT=mcp-app.html vite build",
+    "watch": "cross-env INPUT=mcp-app.html vite build --watch",
+    "serve": "bun server.ts",
+    "start": "cross-env NODE_ENV=development npm run build && npm run serve",
+    "dev": "cross-env NODE_ENV=development concurrently 'npm run watch' 'npm run serve'",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^0.2.2",
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "preact": "^10.0.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@preact/preset-vite": "^2.0.0",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "concurrently": "^9.2.1",
+    "cors": "^2.8.5",
+    "cross-env": "^10.1.0",
+    "express": "^5.1.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.0.0",
+    "vite-plugin-singlefile": "^2.3.0"
+  }
+}

examples/basic-server-preact/server-utils.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared utilities for running MCP servers with Streamable HTTP transport.
+ */
+
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import cors from "cors";
+import type { Request, Response } from "express";
+
+export interface ServerOptions {
+  port: number;
+  name?: string;
+}
+
+/**
+ * Starts an MCP server with Streamable HTTP transport in stateless mode.
+ *
+ * @param createServer - Factory function that creates a new McpServer instance per request.
+ * @param options - Server configuration options.
+ */
+export async function startServer(
+  createServer: () => McpServer,
+  options: ServerOptions,
+): Promise<void> {
+  const { port, name = "MCP Server" } = options;
+
+  const app = createMcpExpressApp({ host: "0.0.0.0" });
+  app.use(cors());
+
+  app.all("/mcp", async (req: Request, res: Response) => {
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
+
+    res.on("close", () => {
+      transport.close().catch(() => {});
+      server.close().catch(() => {});
+    });
+
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    } catch (error) {
+      console.error("MCP error:", error);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: "2.0",
+          error: { code: -32603, message: "Internal server error" },
+          id: null,
+        });
+      }
+    }
+  });
+
+  const httpServer = app.listen(port, () => {
+    console.log(`${name} listening on http://localhost:${port}/mcp`);
+  });
+
+  const shutdown = () => {
+    console.log("\nShutting down...");
+    httpServer.close(() => process.exit(0));
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}