Merge main into ochafik/fix-issue-142-bun-optional-deps

Resolve conflicts:
- .github/workflows/ci.yml: Keep both WSL/git-install tests and new e2e tests
- package-lock.json: Accept theirs and regenerate

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ochafik

.github/workflows/ci.yml

@@ -119,3 +119,32 @@ jobs:
           npm install "git+https://github.com/${{ github.repository }}#${{ github.head_ref || github.ref_name }}"
           # Verify the package is usable (ESM import)
           node --input-type=module -e "import { App } from '@modelcontextprotocol/ext-apps'; console.log('Import successful:', typeof App)"
+
+  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

.gitignore

@@ -6,3 +6,8 @@ bun.lockb
 .vscode/
 docs/api/
 tmp/
+intermediate-findings/
+
+# Playwright
+playwright-report/
+test-results/

.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": false,
+  "printWidth": 80,
+  "tabWidth": 2
+}

CONTRIBUTING.md

@@ -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.

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",
@@ -130,17 +130,22 @@ server.registerTool(
   },
 );
 
-server.registerResource(resourceUri, resourceUri, {}, async () => {
-  const html = await fs.readFile(
-    path.join(import.meta.dirname, "dist", "mcp-app.html"),
-    "utf-8",
-  );
-  return {
-    contents: [
-      { uri: resourceUri, mimeType: "text/html;profile=mcp-app", text: html },
-    ],
-  };
-});
+server.registerResource(
+  resourceUri,
+  resourceUri,
+  { mimeType: "text/html;profile=mcp-app" },
+  async () => {
+    const html = await fs.readFile(
+      path.join(import.meta.dirname, "dist", "mcp-app.html"),
+      "utf-8",
+    );
+    return {
+      contents: [
+        { uri: resourceUri, mimeType: "text/html;profile=mcp-app", text: html },
+      ],
+    };
+  },
+);
 
 // Express server for MCP endpoint
 const app = express();

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/index.tsx

@@ -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>

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,35 +1,34 @@
 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 RESOURCE_URI = "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",
+  });
 
-
-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";
-
+  // 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();
@@ -40,66 +39,35 @@ const server = new McpServer({
   );
 
   server.registerResource(
-    resourceUri,
-    resourceUri,
-    {},
+    RESOURCE_URI,
+    RESOURCE_URI,
+    { mimeType: RESOURCE_MIME_TYPE },
     async (): Promise<ReadResourceResult> => {
       const html = await fs.readFile(path.join(DIST_DIR, "mcp-app.html"), "utf-8");
 
       return {
         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 },
         ],
       };
     },
   );
-}
-
-
-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,
-      });
-    }
-  }
-});
+  return server;
+}
 
-const httpServer = app.listen(PORT, (err) => {
-  if (err) {
-    console.error("Error starting server:", err);
-    process.exit(1);
+async function main() {
+  if (process.argv.includes("--stdio")) {
+    await createServer().connect(new StdioServerTransport());
+  } else {
+    const port = parseInt(process.env.PORT ?? "3101", 10);
+    await startServer(createServer, { port, name: "Basic MCP App Server (React-based)" });
   }
-  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.module.css

@@ -3,7 +3,9 @@
   --color-primary-hover: #1d4ed8;
   --color-notice-bg: #eff6ff;
 
-  min-width: 425px;
+  width: 100%;
+  max-width: 425px;
+  box-sizing: border-box;
 
   > * {
     margin-top: 0;