Merge branch 'main' into ochafik/e2e-tests

Author: ochafik

.github/workflows/ci.yml

@@ -33,7 +33,6 @@ jobs:
       - name: Verify generated schemas are up-to-date
         run: |
           npm run generate:schemas
-          npm run prettier:fix
           git diff --exit-code src/generated/ || (echo "Generated schemas are out of date. Run 'npm run generate:schemas' and commit." && exit 1)
 
       - run: npm test

docs/quickstart.md

@@ -102,7 +102,7 @@ import cors from "cors";
 import express from "express";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { z } from "zod";
+import * as z from "zod";
 
 const server = new McpServer({
   name: "My MCP App Server",

examples/basic-host/package.json

@@ -15,7 +15,7 @@
     "@modelcontextprotocol/sdk": "^1.22.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "zod": "^3.25.0"
+    "zod": "^4.1.13"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",

examples/basic-host/src/implementation.ts

@@ -186,11 +186,19 @@ export async function initializeApp(
   log.info("Sending tool call input to MCP App:", input);
   appBridge.sendToolInput({ arguments: input });
 
-  // Schedule tool call result to be sent to MCP App
-  resultPromise.then((result) => {
-    log.info("Sending tool call result to MCP App:", result);
-    appBridge.sendToolResult(result);
-  });
+  // Schedule tool call result (or cancellation) to be sent to MCP App
+  resultPromise.then(
+    (result) => {
+      log.info("Sending tool call result to MCP App:", result);
+      appBridge.sendToolResult(result);
+    },
+    (error) => {
+      log.error("Tool call failed, sending cancellation to MCP App:", error);
+      appBridge.sendToolCancelled({
+        reason: error instanceof Error ? error.message : String(error),
+      });
+    },
+  );
 }
 
 /**

examples/basic-host/src/index.module.css

@@ -92,10 +92,32 @@
     flex-direction: column;
     margin: 0;
     font-size: 1.5rem;
+    position: relative;
 
     .toolName {
       font-family: monospace;
     }
+
+    .closeButton {
+      position: absolute;
+      top: 0;
+      right: 0;
+      width: 1.5rem;
+      height: 1.5rem;
+      padding: 0;
+      border: none;
+      border-radius: 4px;
+      background: #e0e0e0;
+      font-size: 1.25rem;
+      line-height: 1;
+      color: #666;
+      cursor: pointer;
+
+      &:hover {
+        background: #d0d0d0;
+        color: #333;
+      }
+    }
   }
 }
 

examples/basic-host/src/index.tsx

@@ -29,17 +29,41 @@ function getToolDefaults(tool: Tool | undefined): string {
 interface HostProps {
   serversPromise: Promise<ServerInfo[]>;
 }
+
+type ToolCallEntry = ToolCallInfo & { id: number };
+let nextToolCallId = 0;
+
 function Host({ serversPromise }: HostProps) {
-  const [toolCalls, setToolCalls] = useState<ToolCallInfo[]>([]);
+  const [toolCalls, setToolCalls] = useState<ToolCallEntry[]>([]);
+  const [destroyingIds, setDestroyingIds] = useState<Set<number>>(new Set());
+
+  const requestClose = (id: number) => {
+    setDestroyingIds((s) => new Set(s).add(id));
+  };
+
+  const completeClose = (id: number) => {
+    setDestroyingIds((s) => {
+      const next = new Set(s);
+      next.delete(id);
+      return next;
+    });
+    setToolCalls((calls) => calls.filter((c) => c.id !== id));
+  };
 
   return (
     <>
-      {toolCalls.map((info, i) => (
-        <ToolCallInfoPanel key={i} toolCallInfo={info} />
+      {toolCalls.map((info) => (
+        <ToolCallInfoPanel
+          key={info.id}
+          toolCallInfo={info}
+          isDestroying={destroyingIds.has(info.id)}
+          onRequestClose={() => requestClose(info.id)}
+          onCloseComplete={() => completeClose(info.id)}
+        />
       ))}
       <CallToolPanel
         serversPromise={serversPromise}
-        addToolCall={(info) => setToolCalls([...toolCalls, info])}
+        addToolCall={(info) => setToolCalls([...toolCalls, { ...info, id: nextToolCallId++ }])}
       />
     </>
   );
@@ -164,23 +188,51 @@ function ServerSelect({ serversPromise, onSelect }: ServerSelectProps) {
 
 interface ToolCallInfoPanelProps {
   toolCallInfo: ToolCallInfo;
+  isDestroying?: boolean;
+  onRequestClose?: () => void;
+  onCloseComplete?: () => void;
 }
-function ToolCallInfoPanel({ toolCallInfo }: ToolCallInfoPanelProps) {
+function ToolCallInfoPanel({ toolCallInfo, isDestroying, onRequestClose, onCloseComplete }: ToolCallInfoPanelProps) {
+  const isApp = hasAppHtml(toolCallInfo);
+
+  // For non-app tool calls, close immediately when isDestroying becomes true
+  useEffect(() => {
+    if (isDestroying && !isApp) {
+      onCloseComplete?.();
+    }
+  }, [isDestroying, isApp, onCloseComplete]);
+
   return (
-    <div className={styles.toolCallInfoPanel}>
+    <div
+      className={styles.toolCallInfoPanel}
+      style={isDestroying ? { opacity: 0.5, pointerEvents: "none" } : undefined}
+    >
       <div className={styles.inputInfoPanel}>
         <h2>
           <span>{toolCallInfo.serverInfo.name}</span>
           <span className={styles.toolName}>{toolCallInfo.tool.name}</span>
+          {onRequestClose && !isDestroying && (
+            <button
+              className={styles.closeButton}
+              onClick={onRequestClose}
+              title="Close"
+            >
+              ×
+            </button>
+          )}
         </h2>
         <JsonBlock value={toolCallInfo.input} />
       </div>
       <div className={styles.outputInfoPanel}>
         <ErrorBoundary>
           <Suspense fallback="Loading...">
             {
-              hasAppHtml(toolCallInfo)
-                ? <AppIFramePanel toolCallInfo={toolCallInfo} />
+              isApp
+                ? <AppIFramePanel
+                    toolCallInfo={toolCallInfo}
+                    isDestroying={isDestroying}
+                    onTeardownComplete={onCloseComplete}
+                  />
                 : <ToolResultPanel toolCallInfo={toolCallInfo} />
             }
           </Suspense>
@@ -202,9 +254,12 @@ function JsonBlock({ value }: { value: object }) {
 
 interface AppIFramePanelProps {
   toolCallInfo: Required<ToolCallInfo>;
+  isDestroying?: boolean;
+  onTeardownComplete?: () => void;
 }
-function AppIFramePanel({ toolCallInfo }: AppIFramePanelProps) {
+function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppIFramePanelProps) {
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const appBridgeRef = useRef<ReturnType<typeof newAppBridge> | null>(null);
 
   useEffect(() => {
     const iframe = iframeRef.current!;
@@ -215,11 +270,34 @@ function AppIFramePanel({ toolCallInfo }: AppIFramePanelProps) {
       // `toolCallInfo`.
       if (firstTime) {
         const appBridge = newAppBridge(toolCallInfo.serverInfo, iframe);
+        appBridgeRef.current = appBridge;
         initializeApp(iframe, appBridge, toolCallInfo);
       }
     });
   }, [toolCallInfo]);
 
+  // Graceful teardown: wait for guest to respond before unmounting
+  // This follows the spec: "Host SHOULD wait for a response before tearing
+  // down the resource (to prevent data loss)."
+  useEffect(() => {
+    if (!isDestroying) return;
+
+    if (!appBridgeRef.current) {
+      // Bridge not ready yet (e.g., user closed before iframe loaded)
+      onTeardownComplete?.();
+      return;
+    }
+
+    log.info("Sending teardown notification to MCP App");
+    appBridgeRef.current.sendResourceTeardown({})
+      .catch((err) => {
+        log.warn("Teardown request failed (app may have already closed):", err);
+      })
+      .finally(() => {
+        onTeardownComplete?.();
+      });
+  }, [isDestroying, onTeardownComplete]);
+
   return (
     <div className={styles.appIframePanel}>
       <iframe ref={iframeRef} />

examples/basic-server-react/package.json

@@ -15,7 +15,7 @@
     "@modelcontextprotocol/sdk": "^1.22.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "zod": "^3.25.0"
+    "zod": "^4.1.13"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",

examples/basic-server-react/server.ts

@@ -1,22 +1,18 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
-import cors from "cors";
-import express, { type Request, type Response } from "express";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import { startServer } from "../shared/server-utils.js";
 
-const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3001;
 const DIST_DIR = path.join(import.meta.dirname, "dist");
 
-
 const server = new McpServer({
   name: "Basic MCP App Server (React-based)",
   version: "1.0.0",
 });
 
-
 // MCP Apps require two-part registration: a tool (what the LLM calls) and a
 // resource (the UI it renders). The `_meta` field on the tool links to the
 // resource URI, telling hosts which UI to display when the tool executes.
@@ -57,49 +53,16 @@ const server = new McpServer({
   );
 }
 
-
-const app = express();
-app.use(cors());
-app.use(express.json());
-
-app.post("/mcp", async (req: Request, res: Response) => {
-  try {
-    const transport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: undefined,
-      enableJsonResponse: true,
-    });
-    res.on("close", () => { transport.close(); });
-
-    await server.connect(transport);
-
-    await transport.handleRequest(req, res, req.body);
-  } catch (error) {
-    console.error("Error handling MCP request:", error);
-    if (!res.headersSent) {
-      res.status(500).json({
-        jsonrpc: "2.0",
-        error: { code: -32603, message: "Internal server error" },
-        id: null,
-      });
-    }
+async function main() {
+  if (process.argv.includes("--stdio")) {
+    await server.connect(new StdioServerTransport());
+  } else {
+    const port = parseInt(process.env.PORT ?? "3101", 10);
+    await startServer(server, { port, name: "Basic MCP App Server (React-based)" });
   }
-});
-
-const httpServer = app.listen(PORT, (err) => {
-  if (err) {
-    console.error("Error starting server:", err);
-    process.exit(1);
-  }
-  console.log(`Server listening on http://localhost:${PORT}/mcp`);
-});
-
-function shutdown() {
-  console.log("\nShutting down...");
-  httpServer.close(() => {
-    console.log("Server closed");
-    process.exit(0);
-  });
 }
 
-process.on("SIGINT", shutdown);
-process.on("SIGTERM", shutdown);
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

examples/basic-server-react/src/mcp-app.tsx

@@ -1,7 +1,7 @@
 /**
  * @file App that demonstrates a few features using MCP Apps SDK + React.
  */
-import type { App } from "@modelcontextprotocol/ext-apps";
+import type { App, McpUiResourceTeardownResult } from "@modelcontextprotocol/ext-apps";
 import { useApp } from "@modelcontextprotocol/ext-apps/react";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { StrictMode, useCallback, useEffect, useState } from "react";
@@ -35,6 +35,12 @@ function GetTimeApp() {
     appInfo: IMPLEMENTATION,
     capabilities: {},
     onAppCreated: (app) => {
+      app.onteardown = async () => {
+        log.info("App is being torn down");
+        await new Promise((resolve) => setTimeout(resolve, 500)); // Simulate cleanup work
+        log.info("App teardown complete");
+        return {};
+      };
       app.ontoolinput = async (input) => {
         log.info("Received tool call input:", input);
       };

examples/basic-server-vanillajs/package.json

@@ -13,7 +13,7 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "../..",
     "@modelcontextprotocol/sdk": "^1.22.0",
-    "zod": "^3.25.0"
+    "zod": "^4.1.13"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",