Merge main into swift-sdk

Author: ochafik

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -30,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
@@ -70,3 +72,32 @@ jobs:
       - name: Test Kotlin SDK
         working-directory: kotlin
         run: ./gradlew test
+
+  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/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;
+      }
+    }
   }
 }