Merge remote-tracking branch 'origin/main' into feat/update-context

Author: idosal

.gitattributes

@@ -1 +1,5 @@
+# Force LF line endings for all text files (for consistent prettier formatting)
+* text=auto eol=lf
+
 package-lock.json linguist-generated=true
+src/generated/** linguist-generated=true

.github/workflows/ci.yml

@@ -6,33 +6,145 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   build:
-    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            name: Linux x64
+          - os: ubuntu-24.04-arm
+            name: Linux ARM64
+          - os: windows-latest
+            name: Windows x64
+          - os: windows-11-arm
+            name: Windows ARM64
+          - os: macos-latest
+            name: macOS ARM64
+
+    name: Build (${{ matrix.name }})
+    runs-on: ${{ matrix.os }}
+
     steps:
       - uses: actions/checkout@v4
 
       - name: Verify no private URLs in package-lock.json
+        shell: bash
         run: '! grep -E "\"resolved\": \"https?://" package-lock.json | grep -v registry.npmjs.org'
 
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
 
       - run: npm install
 
-      - run: npm run build:all
+      - run: npm run build
+
+      - run: npm run examples:build
 
       - name: Verify generated schemas are up-to-date
+        shell: bash
         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
 
       - 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
+
+  # Test build in Windows WSL (Ubuntu)
+  build-wsl:
+    name: Build (Windows WSL)
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: Vampire/setup-wsl@v5
+        with:
+          distribution: Ubuntu-24.04
+
+      - name: Install Node.js in WSL
+        shell: wsl-bash {0}
+        run: |
+          sudo apt-get update
+          curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+          sudo apt-get install -y nodejs
+
+      - name: Build and test in WSL
+        shell: wsl-bash {0}
+        run: |
+          npm install
+          npm run build
+          npm run examples:build
+          npm test
+          npm run prettier
+
+  # Test that the package can be installed from git (triggers prepare script)
+  test-git-install:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            name: Linux x64
+          - os: ubuntu-24.04-arm
+            name: Linux ARM64
+          - os: windows-latest
+            name: Windows x64
+          - os: windows-11-arm
+            name: Windows ARM64
+          - os: macos-latest
+            name: macOS ARM64
+
+    name: Test git install (${{ matrix.name }})
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Create test project and install from git
+        shell: bash
+        run: |
+          mkdir test-project
+          cd test-project
+          npm init -y
+          # Install from the PR branch (use head repo for fork PRs)
+          npm install "git+https://github.com/${{ github.event.pull_request.head.repo.full_name || 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)"

.gitignore

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

.husky/pre-commit

@@ -1,3 +1,10 @@
+# Verify no private registry URLs in package-lock.json
+if grep -E '"resolved": "https?://' package-lock.json | grep -v registry.npmjs.org > /dev/null; then
+  echo "ERROR: package-lock.json contains non-npmjs.org URLs"
+  echo "Run: docker run --rm -i -v \$PWD:/src -w /src node:latest npm i --registry=https://registry.npmjs.org/"
+  exit 1
+fi
+
 npm run build:all
 npm run prettier:fix
 

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

README.md

@@ -55,7 +55,7 @@ The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/exa
 
 To run all examples together:
 
-```
+```bash
 npm install
 npm run examples:start
 ```

build.bun.ts

@@ -23,13 +23,20 @@ function buildJs(entrypoint: string, opts: Record<string, any> = {}) {
 }
 
 await Promise.all([
-  buildJs("src/app.ts", { outdir: "dist/src" }),
+  buildJs("src/app.ts", {
+    outdir: "dist/src",
+    external: ["@modelcontextprotocol/sdk"],
+  }),
   buildJs("src/app-bridge.ts", {
     outdir: "dist/src",
     external: ["@modelcontextprotocol/sdk"],
   }),
   buildJs("src/react/index.tsx", {
     outdir: "dist/src/react",
-    external: ["react", "react-dom"],
+    external: ["react", "react-dom", "@modelcontextprotocol/sdk"],
+  }),
+  buildJs("src/server/index.ts", {
+    outdir: "dist/src/server",
+    external: ["@modelcontextprotocol/sdk"],
   }),
 ]);

docs/quickstart.md

@@ -97,12 +97,15 @@ Create `server.ts`:
 ```typescript
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { RESOURCE_URI_META_KEY } from "@modelcontextprotocol/ext-apps";
+import {
+  RESOURCE_MIME_TYPE,
+  type McpUiToolMeta,
+} from "@modelcontextprotocol/ext-apps";
 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",
@@ -119,7 +122,7 @@ server.registerTool(
     description: "Returns the current server time.",
     inputSchema: {},
     outputSchema: { time: z.string() },
-    _meta: { [RESOURCE_URI_META_KEY]: resourceUri }, // Links tool to UI
+    _meta: { ui: { resourceUri } as McpUiToolMeta }, // Links tool to UI
   },
   async () => {
     const time = new Date().toISOString();
@@ -130,17 +133,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/index.html

@@ -3,6 +3,7 @@
   <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="color-scheme" content="light dark">
     <title>MCP Apps Host</title>
     <link rel="stylesheet" href="/src/global.css">
   </head>