modelcontextprotocol
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 32 additions & 0 deletions b/‎.github/workflows/ci.yml‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 5 additions & 0 deletions b/‎.gitignore‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 39 additions & 0 deletions b/‎CONTRIBUTING.md‎
Lines changed: 39 additions & 0 deletions
diff --git a/‎examples/basic-host/src/index.tsx‎
Lines changed: 30 additions & 1 deletion b/‎examples/basic-host/src/index.tsx‎
Lines changed: 30 additions & 1 deletion
diff --git a/‎examples/basic-server-react/server.ts‎
Lines changed: 21 additions & 16 deletions b/‎examples/basic-server-react/server.ts‎
Lines changed: 21 additions & 16 deletions
diff --git a/‎examples/basic-server-vanillajs/server.ts‎
Lines changed: 21 additions & 16 deletions b/‎examples/basic-server-vanillajs/server.ts‎
Lines changed: 21 additions & 16 deletions
@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -35,3 +38,32 @@ jobs:
       - run: npm test
 
       - run: npm run prettier
+
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Run E2E tests
+        run: npx playwright test --reporter=list
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 7
@@ -6,3 +6,8 @@ bun.lockb
 .vscode/
 docs/api/
 tmp/
+intermediate-findings/
+
+# Playwright
+playwright-report/
+test-results/
@@ -40,6 +40,45 @@ Or build and run examples:
 npm run examples:start
 ```
 
+## Testing
+
+### Unit Tests
+
+Run unit tests with Bun:
+
+```bash
+npm test
+```
+
+### E2E Tests
+
+E2E tests use Playwright to verify all example servers work correctly with screenshot comparisons.
+
+```bash
+# Run all E2E tests
+npm run test:e2e
+
+# Run a specific server's tests
+npm run test:e2e -- --grep "Budget Allocator"
+
+# Run tests in interactive UI mode
+npm run test:e2e:ui
+```
+
+### Updating Golden Screenshots
+
+When UI changes are intentional, update the golden screenshots:
+
+```bash
+# Update all screenshots
+npm run test:e2e:update
+
+# Update screenshots for a specific server
+npm run test:e2e:update -- --grep "Three.js"
+```
+
+**Note**: Golden screenshots are platform-agnostic. Tests use canvas masking and tolerance thresholds to handle minor cross-platform rendering differences.
+
 ## Code of Conduct
 
 This project follows our [Code of Conduct](CODE_OF_CONDUCT.md). Please review it before contributing.
 
@@ -1,9 +1,30 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import { Component, type ErrorInfo, type ReactNode, StrictMode, Suspense, use, useEffect, useMemo, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
 import { callTool, connectToServer, hasAppHtml, initializeApp, loadSandboxProxy, log, newAppBridge, type ServerInfo, type ToolCallInfo } from "./implementation";
 import styles from "./index.module.css";
 
 
+/**
+ * Extract default values from a tool's JSON Schema inputSchema.
+ * Returns a formatted JSON string with defaults, or "{}" if none found.
+ */
+function getToolDefaults(tool: Tool | undefined): string {
+  if (!tool?.inputSchema?.properties) return "{}";
+
+  const defaults: Record<string, unknown> = {};
+  for (const [key, prop] of Object.entries(tool.inputSchema.properties)) {
+    if (prop && typeof prop === "object" && "default" in prop) {
+      defaults[key] = prop.default;
+    }
+  }
+
+  return Object.keys(defaults).length > 0
+    ? JSON.stringify(defaults, null, 2)
+    : "{}";
+}
+
+
 // Host passes serversPromise to CallToolPanel
 interface HostProps {
   serversPromise: Promise<ServerInfo[]>;
@@ -74,6 +95,14 @@ function CallToolPanel({ serversPromise, addToolCall }: CallToolPanelProps) {
     setSelectedServer(server);
     const [firstTool] = server.tools.keys();
     setSelectedTool(firstTool ?? "");
+    // Set input JSON to tool defaults (if any)
+    setInputJson(getToolDefaults(server.tools.get(firstTool ?? "")));
+  };
+
+  const handleToolSelect = (toolName: string) => {
+    setSelectedTool(toolName);
+    // Set input JSON to tool defaults (if any)
+    setInputJson(getToolDefaults(selectedServer?.tools.get(toolName)));
   };
 
   const handleSubmit = () => {
@@ -96,7 +125,7 @@ function CallToolPanel({ serversPromise, addToolCall }: CallToolPanelProps) {
           <select
             className={styles.toolSelect}
             value={selectedTool}
-            onChange={(e) => setSelectedTool(e.target.value)}
+            onChange={(e) => handleToolSelect(e.target.value)}
           >
             {selectedServer && toolNames.map((name) => (
               <option key={name} value={name}>{name}</option>
 
@@ -7,25 +7,28 @@ import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
+const RESOURCE_URI = "ui://get-time/mcp-app.html";
 
-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.
-{
-  const resourceUri = "ui://get-time/mcp-app.html";
+/**
+ * Creates a new MCP server instance with tools and resources registered.
+ * Each HTTP session needs its own server instance because McpServer only supports one transport.
+ */
+function createServer(): McpServer {
+  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.
   server.registerTool(
     "get-time",
     {
       title: "Get Time",
       description: "Returns the current server time as an ISO 8601 string.",
       inputSchema: {},
-      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
+      _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
     },
     async (): Promise<CallToolResult> => {
       const time = new Date().toISOString();
@@ -36,8 +39,8 @@ const server = new McpServer({
   );
 
   server.registerResource(
-    resourceUri,
-    resourceUri,
+    RESOURCE_URI,
+    RESOURCE_URI,
     {},
     async (): Promise<ReadResourceResult> => {
       const html = await fs.readFile(path.join(DIST_DIR, "mcp-app.html"), "utf-8");
@@ -46,19 +49,21 @@ const server = new McpServer({
         contents: [
           // Per the MCP App specification, "text/html;profile=mcp-app" signals
           // to the Host that this resource is indeed for an MCP App UI.
-          { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
+          { uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html },
         ],
       };
     },
   );
+
+  return server;
 }
 
 async function main() {
   if (process.argv.includes("--stdio")) {
-    await server.connect(new StdioServerTransport());
+    await createServer().connect(new StdioServerTransport());
   } else {
     const port = parseInt(process.env.PORT ?? "3101", 10);
-    await startServer(server, { port, name: "Basic MCP App Server (React-based)" });
+    await startServer(createServer, { port, name: "Basic MCP App Server (React-based)" });
   }
 }
 
 
@@ -7,25 +7,28 @@ import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
+const RESOURCE_URI = "ui://get-time/mcp-app.html";
 
-const server = new McpServer({
-  name: "Basic MCP App Server (Vanilla JS)",
-  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.
-{
-  const resourceUri = "ui://get-time/mcp-app.html";
+/**
+ * Creates a new MCP server instance with tools and resources registered.
+ * Each HTTP session needs its own server instance because McpServer only supports one transport.
+ */
+function createServer(): McpServer {
+  const server = new McpServer({
+    name: "Basic MCP App Server (Vanilla JS)",
+    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.
   server.registerTool(
     "get-time",
     {
       title: "Get Time",
       description: "Returns the current server time as an ISO 8601 string.",
       inputSchema: {},
-      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
+      _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
     },
     async (): Promise<CallToolResult> => {
       const time = new Date().toISOString();
@@ -36,8 +39,8 @@ const server = new McpServer({
   );
 
   server.registerResource(
-    resourceUri,
-    resourceUri,
+    RESOURCE_URI,
+    RESOURCE_URI,
     {},
     async (): Promise<ReadResourceResult> => {
       const html = await fs.readFile(path.join(DIST_DIR, "mcp-app.html"), "utf-8");
@@ -46,19 +49,21 @@ const server = new McpServer({
         contents: [
           // Per the MCP App specification, "text/html;profile=mcp-app" signals
           // to the Host that this resource is indeed for an MCP App UI.
-          { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
+          { uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html },
         ],
       };
     },
   );
+
+  return server;
 }
 
 async function main() {
   if (process.argv.includes("--stdio")) {
-    await server.connect(new StdioServerTransport());
+    await createServer().connect(new StdioServerTransport());
   } else {
     const port = parseInt(process.env.PORT ?? "3102", 10);
-    await startServer(server, { port, name: "Basic MCP App Server (Vanilla JS)" });
+    await startServer(createServer, { port, name: "Basic MCP App Server (Vanilla JS)" });
   }
 }