Merge origin/main into ochafik/e2e-tests

Author: ochafik

.github/workflows/ci.yml

@@ -30,6 +30,12 @@ jobs:
 
       - run: npm run build:all
 
+      - 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
 
       - run: npm run prettier

.github/workflows/docs.yml

@@ -25,4 +25,4 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs
           publish_branch: gh-pages
-          force_orphan: true
+          keep_files: true

.husky/pre-commit

@@ -1,2 +1,5 @@
 npm run build:all
 npm run prettier:fix
+
+# Stage any changes to generated files (they may have been reformatted by prettier)
+git add src/generated/

README.md

@@ -1,6 +1,6 @@
 # @modelcontextprotocol/ext-apps
 
-[![API Documentation](https://img.shields.io/badge/docs-API%20Reference-blue)](https://modelcontextprotocol.github.io/ext-apps/api/)
+[![npm version](https://img.shields.io/npm/v/@modelcontextprotocol/ext-apps.svg)](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) [![API Documentation](https://img.shields.io/badge/docs-API%20Reference-blue)](https://modelcontextprotocol.github.io/ext-apps/api/)
 
 This repo contains the SDK and [specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) for MCP Apps Extension ([SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)).
 

examples/run-all.ts

@@ -9,7 +9,7 @@
  */
 
 import { readdirSync, statSync, existsSync } from "fs";
-import { spawn, type ChildProcess } from "child_process";
+import concurrently from "concurrently";
 
 const BASE_PORT = 3101;
 const BASIC_HOST = "basic-host";
@@ -36,57 +36,9 @@ const command = process.argv[2];
 
 if (!command || !COMMANDS.includes(command)) {
   console.error(`Usage: bun examples/run-all.ts <${COMMANDS.join("|")}>`);
-
   process.exit(1);
 }
 
-const processes: ChildProcess[] = [];
-
-// Handle cleanup on exit
-function cleanup() {
-  for (const proc of processes) {
-    proc.kill();
-  }
-}
-process.on("SIGINT", cleanup);
-process.on("SIGTERM", cleanup);
-
-// Spawn a process and track it
-function spawnProcess(
-  cmd: string,
-  args: string[],
-  env: Record<string, string> = {},
-  prefix: string,
-): ChildProcess {
-  const proc = spawn(cmd, args, {
-    env: { ...process.env, ...env },
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-
-  proc.stdout?.on("data", (data) => {
-    const lines = data.toString().trim().split("\n");
-    for (const line of lines) {
-      console.log(`[${prefix}] ${line}`);
-    }
-  });
-
-  proc.stderr?.on("data", (data) => {
-    const lines = data.toString().trim().split("\n");
-    for (const line of lines) {
-      console.error(`[${prefix}] ${line}`);
-    }
-  });
-
-  proc.on("exit", (code) => {
-    if (code !== 0 && code !== null) {
-      console.error(`[${prefix}] exited with code ${code}`);
-    }
-  });
-
-  processes.push(proc);
-  return proc;
-}
-
 // Build the SERVERS environment variable (JSON array of URLs)
 const serversEnv = JSON.stringify(servers.map((s) => s.url));
 
@@ -96,25 +48,34 @@ console.log(
 );
 console.log("");
 
+// Build command list for concurrently
+const commands: Parameters<typeof concurrently>[0] = [
+  // Server examples
+  ...servers.map(({ dir, port }) => ({
+    command: `npm run --workspace examples/${dir} ${command}`,
+    name: dir,
+    env: { PORT: String(port) },
+  })),
+  // Basic host with SERVERS env
+  {
+    command: `npm run --workspace examples/${BASIC_HOST} ${command}`,
+    name: BASIC_HOST,
+    env: { SERVERS: serversEnv },
+  },
+];
+
 // If dev mode, also run the main library watcher
 if (command === "dev") {
-  spawnProcess("npm", ["run", "watch"], {}, "lib");
+  commands.unshift({
+    command: "npm run watch",
+    name: "lib",
+  });
 }
 
-// Run each server example
-for (const { dir, port } of servers) {
-  spawnProcess(
-    "npm",
-    ["run", "--workspace", `examples/${dir}`, command],
-    { PORT: String(port) },
-    dir,
-  );
-}
+const { result } = concurrently(commands, {
+  prefix: "name",
+  // For build command, we want all to complete; for start/dev, kill all on failure
+  killOthersOnFail: command !== "build",
+});
 
-// Run basic-host with the SERVERS env var
-spawnProcess(
-  "npm",
-  ["run", "--workspace", `examples/${BASIC_HOST}`, command],
-  { SERVERS: serversEnv },
-  BASIC_HOST,
-);
+result.catch(() => process.exit(1));

examples/wiki-explorer-server/README.md

@@ -0,0 +1,66 @@
+# Example: Wiki Explorer
+
+Visualizes Wikipedia link graphs using a force-directed layout. Explore how Wikipedia pages are connected by expanding nodes to reveal first-degree links.
+
+<table>
+  <tr>
+    <td><a href="https://modelcontextprotocol.github.io/ext-apps/screenshots/wiki-explorer-server/01-zoomed.png"><img src="https://modelcontextprotocol.github.io/ext-apps/screenshots/wiki-explorer-server/01-zoomed.png" alt="Zoomed" width="100%"></a></td>
+    <td><a href="https://modelcontextprotocol.github.io/ext-apps/screenshots/wiki-explorer-server/02-pop-up.png"><img src="https://modelcontextprotocol.github.io/ext-apps/screenshots/wiki-explorer-server/02-pop-up.png" alt="Pop-up" width="100%"></a></td>
+    <td><a href="https://modelcontextprotocol.github.io/ext-apps/screenshots/wiki-explorer-server/03-expanded-graph.png"><img src="https://modelcontextprotocol.github.io/ext-apps/screenshots/wiki-explorer-server/03-expanded-graph.png" alt="Expanded graph" width="100%"></a></td>
+  </tr>
+</table>
+
+## Features
+
+- **Force-directed graph visualization**: Interactive graph powered by [`force-graph`](https://github.com/vasturiano/force-graph)
+- **Node expansion**: Click any node to expand and see all pages it links to
+- **Visual state tracking**: Nodes change color based on state (blue = default, green = expanded, red = error)
+- **Direct page access**: Open any Wikipedia page in your browser
+
+## Running
+
+1. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+2. Build and start the server:
+
+   ```bash
+   npm run start:http  # for Streamable HTTP transport
+   # OR
+   npm run start:stdio  # for stdio transport
+   ```
+
+3. View using the [`basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) example or another MCP Apps-compatible host.
+
+### Tool Input
+
+To test the example, call the `get-first-degree-links` tool with a Wikipedia URL:
+
+```json
+{
+  "url": "https://en.wikipedia.org/wiki/Graph_theory"
+}
+```
+
+Click nodes in the graph to **Open** (view in browser) or **Expand** (visualize linked pages).
+
+## Architecture
+
+### Server (`server.ts`)
+
+MCP server that fetches Wikipedia pages and extracts internal links.
+
+Exposes one tool:
+
+- `get-first-degree-links` - Returns links to other Wikipedia pages from a given page
+
+### App (`src/mcp-app.ts`)
+
+Vanilla TypeScript app using force-graph for visualization that:
+
+- Receives tool inputs via the MCP App SDK
+- Renders an interactive force-directed graph
+- Supports node expansion to explore link relationships

examples/wiki-explorer-server/mcp-app.html

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Wiki Explorer</title>
+</head>
+<body>
+  <div id="graph"></div>
+  <div id="popup">
+    <div class="popup-title"></div>
+    <div class="popup-error"></div>
+    <div class="popup-buttons">
+      <button id="open-btn">Open</button>
+      <button id="expand-btn">Expand</button>
+    </div>
+  </div>
+  <div id="controls">
+    <button id="reset-graph" title="Reset graph">&#x21BA;</button>
+    <div id="zoom-controls">
+      <button id="zoom-in" title="Zoom in">+</button>
+      <button id="zoom-out" title="Zoom out">−</button>
+    </div>
+  </div>
+  <script type="module" src="/src/mcp-app.ts"></script>
+</body>
+</html>

examples/wiki-explorer-server/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "wiki-explorer-server",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "INPUT=mcp-app.html vite build",
+    "watch": "INPUT=mcp-app.html vite build --watch",
+    "serve:http": "bun server.ts",
+    "serve:stdio": "bun server.ts --stdio",
+    "start": "npm run start:http",
+    "start:http": "NODE_ENV=development npm run build && npm run serve:http",
+    "start:stdio": "NODE_ENV=development npm run build && npm run serve:stdio",
+    "dev": "NODE_ENV=development concurrently 'npm run watch' 'npm run serve:http'"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "../..",
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "cheerio": "^1.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "bun": "^1.3.2",
+    "concurrently": "^9.2.1",
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "force-graph": "^1.49.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.0.0",
+    "vite-plugin-singlefile": "^2.3.0"
+  }
+}