modelcontextprotocol
diff --git a/‎examples/transcript-server/README.md‎
Lines changed: 89 additions & 0 deletions b/‎examples/transcript-server/README.md‎
Lines changed: 89 additions & 0 deletions
diff --git a/‎examples/transcript-server/mcp-app.html‎
Lines changed: 45 additions & 0 deletions b/‎examples/transcript-server/mcp-app.html‎
Lines changed: 45 additions & 0 deletions
diff --git a/‎examples/transcript-server/package.json‎
Lines changed: 44 additions & 0 deletions b/‎examples/transcript-server/package.json‎
Lines changed: 44 additions & 0 deletions
diff --git a/‎examples/transcript-server/server-utils.ts‎
Lines changed: 69 additions & 0 deletions b/‎examples/transcript-server/server-utils.ts‎
Lines changed: 69 additions & 0 deletions
diff --git a/‎examples/transcript-server/server.ts‎
Lines changed: 100 additions & 0 deletions b/‎examples/transcript-server/server.ts‎
Lines changed: 100 additions & 0 deletions
diff --git a/‎examples/transcript-server/src/global.css‎
Lines changed: 12 additions & 0 deletions b/‎examples/transcript-server/src/global.css‎
Lines changed: 12 additions & 0 deletions
@@ -0,0 +1,89 @@
+# Transcript Server
+
+An MCP App Server for live speech transcription using the Web Speech API.
+
+## Features
+
+- **Live Transcription**: Real-time speech-to-text using browser's Web Speech API
+- **Transitional Model Context**: Streams interim transcriptions to the model via `ui/update-model-context`, allowing the model to see what the user is saying as they speak
+- **Audio Level Indicator**: Visual feedback showing microphone input levels
+- **Send to Host**: Button to send completed transcriptions as a `ui/message` to the MCP host
+- **Start/Stop Control**: Toggle listening on and off
+- **Clear Transcript**: Reset the transcript area
+
+## Setup
+
+### Prerequisites
+
+- Node.js 18+
+- Chrome, Edge, or Safari (Web Speech API support)
+
+### Installation
+
+```bash
+npm install
+```
+
+### Running
+
+```bash
+# Development mode (with hot reload)
+npm run dev
+
+# Production build and serve
+npm run start
+```
+
+## Usage
+
+The server exposes a single tool:
+
+### `transcribe`
+
+Opens a live speech transcription interface.
+
+**Parameters:** None
+
+**Example:**
+
+```json
+{
+  "name": "transcribe",
+  "arguments": {}
+}
+```
+
+## How It Works
+
+1. Click **Start** to begin listening
+2. Speak into your microphone
+3. Watch your speech appear as text in real-time (interim text is streamed to model context via `ui/update-model-context`)
+4. Click **Send** to send the transcript as a `ui/message` to the host (clears the model context)
+5. Click **Clear** to reset the transcript
+
+## Architecture
+
+```
+transcript-server/
+├── server.ts          # MCP server with transcribe tool
+├── server-utils.ts    # HTTP transport utilities
+├── mcp-app.html       # Transcript UI entry point
+├── src/
+│   ├── mcp-app.ts     # App logic, Web Speech API integration
+│   ├── mcp-app.css    # Transcript UI styles
+│   └── global.css     # Base styles
+└── dist/              # Built output (single HTML file)
+```
+
+## Notes
+
+- **Microphone Permission**: Requires `allow="microphone"` on the sandbox iframe (configured via `permissions: { microphone: {} }` in the resource `_meta.ui`)
+- **Browser Support**: Web Speech API is well-supported in Chrome/Edge, with Safari support. Firefox has limited support.
+- **Continuous Mode**: Recognition automatically restarts when it ends, for seamless transcription
+
+## Future Enhancements
+
+- Language selection dropdown
+- Whisper-based offline transcription (see TRANSCRIPTION.md)
+- Export transcript to file
+- Timestamps toggle
@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Live Transcript</title>
+</head>
+<body>
+  <main class="transcript-app">
+    <!-- Transcript Area -->
+    <section class="transcript-section">
+      <div class="transcript" id="transcript">
+        <p class="transcript-placeholder">Your speech will appear here...</p>
+      </div>
+    </section>
+
+    <!-- Controls -->
+    <section class="controls">
+      <div class="controls-left">
+        <button class="btn btn-primary" id="start-btn">
+          <svg class="btn-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <polygon points="5 3 19 12 5 21 5 3"/>
+          </svg>
+          Start
+        </button>
+        <div class="level-bar" id="level-bar">
+          <div class="level-fill" id="mic-level"></div>
+        </div>
+        <span class="timer" id="timer">0:00</span>
+      </div>
+      <div class="controls-right">
+        <button class="btn btn-secondary" id="copy-btn" title="Copy transcript">
+          <svg class="btn-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <rect x="9" y="9" width="13" height="13" rx="2" ry="2"/>
+            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>
+          </svg>
+        </button>
+        <button class="btn btn-secondary" id="clear-btn">Clear</button>
+        <button class="btn btn-accent" id="send-btn" disabled>Send</button>
+      </div>
+    </section>
+  </main>
+  <script type="module" src="/src/mcp-app.ts"></script>
+</body>
+</html>
@@ -0,0 +1,44 @@
+{
+  "name": "@modelcontextprotocol/server-transcript",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MCP App Server for live speech transcription",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/modelcontextprotocol/ext-apps",
+    "directory": "examples/transcript-server"
+  },
+  "license": "MIT",
+  "main": "server.ts",
+  "files": [
+    "server.ts",
+    "server-utils.ts",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit && cross-env INPUT=mcp-app.html vite build",
+    "watch": "cross-env INPUT=mcp-app.html vite build --watch",
+    "serve": "bun server.ts",
+    "start": "cross-env NODE_ENV=development npm run build && npm run serve",
+    "dev": "cross-env NODE_ENV=development concurrently 'npm run watch' 'npm run serve'",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^0.3.1",
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/dom-speech-recognition": "^0.0.7",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "concurrently": "^9.2.1",
+    "cors": "^2.8.5",
+    "cross-env": "^10.1.0",
+    "express": "^5.1.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.0.0",
+    "vite-plugin-singlefile": "^2.3.0"
+  }
+}
@@ -0,0 +1,69 @@
+/**
+ * Shared utilities for running MCP servers with Streamable HTTP transport.
+ */
+
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import cors from "cors";
+import type { Request, Response } from "express";
+
+export interface ServerOptions {
+  port: number;
+  name?: string;
+}
+
+/**
+ * Starts an MCP server with Streamable HTTP transport in stateless mode.
+ */
+export async function startServer(
+  createServer: () => McpServer,
+  options: ServerOptions,
+): Promise<void> {
+  const { port, name = "MCP Server" } = options;
+
+  const app = createMcpExpressApp({ host: "0.0.0.0" });
+  app.use(cors());
+
+  app.all("/mcp", async (req: Request, res: Response) => {
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
+
+    res.on("close", () => {
+      transport.close().catch(() => {});
+      server.close().catch(() => {});
+    });
+
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    } catch (error) {
+      console.error("MCP error:", error);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: "2.0",
+          error: { code: -32603, message: "Internal server error" },
+          id: null,
+        });
+      }
+    }
+  });
+
+  const httpServer = app.listen(port, (err) => {
+    if (err) {
+      console.error("Failed to start server:", err);
+      process.exit(1);
+    }
+    console.log(`${name} listening on http://localhost:${port}/mcp`);
+  });
+
+  const shutdown = () => {
+    console.log("\nShutting down...");
+    httpServer.close(() => process.exit(0));
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
@@ -0,0 +1,100 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type {
+  CallToolResult,
+  ReadResourceResult,
+} from "@modelcontextprotocol/sdk/types.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  registerAppTool,
+  registerAppResource,
+  RESOURCE_MIME_TYPE,
+  RESOURCE_URI_META_KEY,
+} from "@modelcontextprotocol/ext-apps/server";
+import { startServer } from "./server-utils.js";
+
+const DIST_DIR = path.join(import.meta.dirname, "dist");
+const RESOURCE_URI = "ui://transcript/mcp-app.html";
+
+/**
+ * Creates a new MCP server instance with tools and resources registered.
+ */
+export function createServer(): McpServer {
+  const server = new McpServer({
+    name: "Transcript Server",
+    version: "1.0.0",
+  });
+
+  // Register the transcribe tool - opens a UI for live speech transcription
+  registerAppTool(
+    server,
+    "transcribe",
+    {
+      title: "Transcribe Speech",
+      description:
+        "Opens a live speech transcription interface using the Web Speech API.",
+      inputSchema: {},
+      _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
+    },
+    async (): Promise<CallToolResult> => {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              status: "ready",
+              message: "Transcription UI opened. Speak into your microphone.",
+            }),
+          },
+        ],
+      };
+    },
+  );
+
+  // Register the UI resource
+  registerAppResource(
+    server,
+    RESOURCE_URI,
+    RESOURCE_URI,
+    { mimeType: RESOURCE_MIME_TYPE, description: "Transcript UI" },
+    async (): Promise<ReadResourceResult> => {
+      const html = await fs.readFile(
+        path.join(DIST_DIR, "mcp-app.html"),
+        "utf-8",
+      );
+
+      return {
+        contents: [
+          {
+            uri: RESOURCE_URI,
+            mimeType: RESOURCE_MIME_TYPE,
+            text: html,
+            _meta: {
+              ui: {
+                // Request microphone for Web Speech API, clipboard for copy button
+                permissions: { microphone: {}, clipboardWrite: {} },
+              },
+            },
+          },
+        ],
+      };
+    },
+  );
+
+  return server;
+}
+
+async function main() {
+  if (process.argv.includes("--stdio")) {
+    await createServer().connect(new StdioServerTransport());
+  } else {
+    const port = parseInt(process.env.PORT ?? "3109", 10);
+    await startServer(createServer, { port, name: "Transcript Server" });
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
@@ -0,0 +1,12 @@
+* {
+  box-sizing: border-box;
+}
+
+html, body {
+  font-family: system-ui, -apple-system, sans-serif;
+  font-size: 1rem;
+  margin: 0;
+  padding: 0;
+  /* No height: 100% - body must grow with content for ResizeObserver to detect changes */
+  background: transparent;
+}