feat(examples): Add video-resource-server example

Demonstrates serving binary content (video) via MCP resources using the base64 blob pattern: 1. Server fetches video from CDN 2. Returns as base64 blob via `videos://{id}` resource template 3. Widget fetches resource and plays in `<video>` element Includes multiple video sizes for testing (1MB to 150MB). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-17 15:14:19 +00:00 · 2025-12-17 15:14:19 +00:00 · ba45157d55
commit ba45157d55
parent d925af5257
10 changed files with 554 additions and 0 deletions
--- a/examples/video-resource-server/README.md
+++ b/examples/video-resource-server/README.md
@ -0,0 +1,22 @@
+# Video Resource Server
+
+Demonstrates serving binary content (video) via MCP resources using the base64 blob pattern.
+
+## Quick Start
+
+```bash
+npm install
+npm run dev
+```
+
+## Tools
+
+- **play_video** - Plays a video loaded via MCP resource
+  - `videoId`: Choose from various sizes (`bunny-1mb`, `bunny-5mb`, `bunny-10mb`, etc.)
+
+## How It Works
+
+1. The `play_video` tool returns a `videoUri` pointing to an MCP resource
+2. The widget fetches the resource via `resources/read`
+3. The server fetches the video from CDN and returns it as a base64 blob
+4. The widget decodes the blob and plays it in a `<video>` element
--- a/examples/video-resource-server/mcp-app.html
+++ b/examples/video-resource-server/mcp-app.html
@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="color-scheme" content="light dark">
+  <title>Video Resource Player</title>
+</head>
+<body>
+  <main class="main">
+    <div id="loading" class="loading">
+      <div class="spinner"></div>
+      <p id="loading-text">Waiting for video...</p>
+    </div>
+
+    <div id="error" class="error" style="display: none;">
+      <p class="error-title">Error loading video</p>
+      <p id="error-message"></p>
+    </div>
+
+    <div id="player" class="player" style="display: none;">
+      <video id="video" controls></video>
+      <p id="video-info" class="video-info"></p>
+    </div>
+  </main>
+  <script type="module" src="/src/mcp-app.ts"></script>
+</body>
+</html>
--- a/examples/video-resource-server/package.json
+++ b/examples/video-resource-server/package.json
@ -0,0 +1,30 @@
+{
+  "name": "video-resource-server",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "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'"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "../..",
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "concurrently": "^9.2.1",
+    "cors": "^2.8.5",
+    "cross-env": "^7.0.3",
+    "express": "^5.1.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.0.0",
+    "vite-plugin-singlefile": "^2.3.0"
+  }
+}
--- a/examples/video-resource-server/server.ts
+++ b/examples/video-resource-server/server.ts
@ -0,0 +1,187 @@
+/**
+ * Video Resource Server
+ *
+ * Demonstrates serving binary content (video) via MCP resources.
+ * The server fetches videos from CDN and serves them as base64 blobs.
+ */
+import {
+  McpServer,
+  ResourceTemplate,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type {
+  CallToolResult,
+  ReadResourceResult,
+} from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+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 "../shared/server-utils.js";
+
+const DIST_DIR = path.join(import.meta.dirname, "dist");
+const RESOURCE_URI = "ui://video-player/mcp-app.html";
+
+/**
+ * Video library with different sizes for testing.
+ */
+const VIDEO_LIBRARY: Record<string, { url: string; description: string }> = {
+  "bunny-1mb": {
+    url: "https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_1MB.mp4",
+    description: "1MB",
+  },
+  "bunny-5mb": {
+    url: "https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_5MB.mp4",
+    description: "5MB",
+  },
+  "bunny-10mb": {
+    url: "https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/720/Big_Buck_Bunny_720_10s_10MB.mp4",
+    description: "10MB",
+  },
+  "bunny-20mb": {
+    url: "https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/720/Big_Buck_Bunny_720_10s_20MB.mp4",
+    description: "20MB",
+  },
+  "bunny-30mb": {
+    url: "https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/1080/Big_Buck_Bunny_1080_10s_30MB.mp4",
+    description: "30MB",
+  },
+  "bunny-50mb": {
+    url: "https://sample-videos.com/video321/mp4/720/big_buck_bunny_720p_50mb.mp4",
+    description: "50MB",
+  },
+  "bunny-150mb": {
+    url: "https://cdn.jsdelivr.net/npm/big-buck-bunny-1080p@0.0.6/video.mp4",
+    description: "~150MB (full 1080p)",
+  },
+};
+
+function createServer(): McpServer {
+  const server = new McpServer({
+    name: "Video Resource Server",
+    version: "1.0.0",
+  });
+
+  // Register video resource template
+  // This fetches video from CDN and returns as base64 blob
+  server.resource(
+    "video",
+    new ResourceTemplate("videos://{id}", { list: undefined }),
+    {
+      description: "Video served via MCP resource (base64 blob)",
+      mimeType: "video/mp4",
+    },
+    async (uri, { id }): Promise<ReadResourceResult> => {
+      const idStr = Array.isArray(id) ? id[0] : id;
+      const video = VIDEO_LIBRARY[idStr];
+
+      if (!video) {
+        throw new Error(
+          `Video not found: ${idStr}. Available: ${Object.keys(VIDEO_LIBRARY).join(", ")}`,
+        );
+      }
+
+      console.error(`[video-resource] Fetching: ${video.url}`);
+
+      const response = await fetch(video.url);
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch video: ${response.status} ${response.statusText}`,
+        );
+      }
+
+      const buffer = await response.arrayBuffer();
+      const base64 = Buffer.from(buffer).toString("base64");
+
+      console.error(
+        `[video-resource] Size: ${buffer.byteLength} bytes -> ${base64.length} base64 chars`,
+      );
+
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "video/mp4",
+            blob: base64,
+          },
+        ],
+      };
+    },
+  );
+
+  // Register the video player tool
+  registerAppTool(
+    server,
+    "play_video",
+    {
+      title: "Play Video via Resource",
+      description: `Play a video loaded via MCP resource.
+Available videos:
+${Object.entries(VIDEO_LIBRARY)
+  .map(([id, v]) => `- ${id}: ${v.description}`)
+  .join("\n")}`,
+      inputSchema: {
+        videoId: z
+          .enum(Object.keys(VIDEO_LIBRARY) as [string, ...string[]])
+          .describe(
+            `Video ID to play. Available: ${Object.keys(VIDEO_LIBRARY).join(", ")}`,
+          ),
+      },
+      _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
+    },
+    async ({ videoId }): Promise<CallToolResult> => {
+      const video = VIDEO_LIBRARY[videoId];
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              videoUri: `videos://${videoId}`,
+              description: video.description,
+            }),
+          },
+        ],
+      };
+    },
+  );
+
+  // Register the MCP App resource (the UI)
+  registerAppResource(
+    server,
+    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: [
+          { uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: html },
+        ],
+      };
+    },
+  );
+
+  return server;
+}
+
+async function main() {
+  if (process.argv.includes("--stdio")) {
+    await createServer().connect(new StdioServerTransport());
+  } else {
+    const port = parseInt(process.env.PORT ?? "3105", 10);
+    await startServer(createServer, { port, name: "Video Resource Server" });
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
--- a/examples/video-resource-server/src/global.css
+++ b/examples/video-resource-server/src/global.css
@ -0,0 +1,10 @@
+* {
+  box-sizing: border-box;
+}
+
+html, body {
+  font-family: system-ui, -apple-system, sans-serif;
+  font-size: 1rem;
+  margin: 0;
+  padding: 0;
+}
--- a/examples/video-resource-server/src/mcp-app.css
+++ b/examples/video-resource-server/src/mcp-app.css
@ -0,0 +1,54 @@
+.main {
+  width: 100%;
+  max-width: 640px;
+}
+
+.loading {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 2rem;
+  gap: 1rem;
+  color: #6b7280;
+}
+
+.spinner {
+  width: 48px;
+  height: 48px;
+  border: 4px solid #e5e7eb;
+  border-top-color: #3b82f6;
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+.error {
+  padding: 1rem;
+  color: #dc2626;
+}
+
+.error-title {
+  font-weight: 600;
+  margin: 0 0 0.5rem 0;
+}
+
+.error p {
+  margin: 0;
+}
+
+.player video {
+  width: 100%;
+  max-height: 480px;
+  border-radius: 8px;
+  background-color: #000;
+}
+
+.video-info {
+  margin-top: 0.5rem;
+  font-size: 0.875rem;
+  color: #6b7280;
+}
--- a/examples/video-resource-server/src/mcp-app.ts
+++ b/examples/video-resource-server/src/mcp-app.ts
@ -0,0 +1,124 @@
+/**
+ * Video Resource Player
+ *
+ * Demonstrates fetching binary content (video) via MCP resources.
+ * The video is served as a base64 blob and converted to a data URI for playback.
+ */
+import { App } from "@modelcontextprotocol/ext-apps";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { ReadResourceResultSchema } from "@modelcontextprotocol/sdk/types.js";
+import "./global.css";
+import "./mcp-app.css";
+
+const log = {
+  info: console.log.bind(console, "[VIDEO]"),
+  error: console.error.bind(console, "[VIDEO]"),
+};
+
+// Get element references
+const loadingEl = document.getElementById("loading")!;
+const loadingTextEl = document.getElementById("loading-text")!;
+const errorEl = document.getElementById("error")!;
+const errorMessageEl = document.getElementById("error-message")!;
+const playerEl = document.getElementById("player")!;
+const videoEl = document.getElementById("video") as HTMLVideoElement;
+const videoInfoEl = document.getElementById("video-info")!;
+
+// Parse tool result to get video URI
+function parseToolResult(
+  result: CallToolResult,
+): { videoUri: string; description: string } | null {
+  const text = result.content
+    ?.filter((c): c is { type: "text"; text: string } => c.type === "text")
+    .map((c) => c.text)
+    .join("");
+
+  if (!text) return null;
+
+  try {
+    return JSON.parse(text) as { videoUri: string; description: string };
+  } catch {
+    return null;
+  }
+}
+
+// Show states
+function showLoading(text: string) {
+  loadingTextEl.textContent = text;
+  loadingEl.style.display = "flex";
+  errorEl.style.display = "none";
+  playerEl.style.display = "none";
+}
+
+function showError(message: string) {
+  errorMessageEl.textContent = message;
+  loadingEl.style.display = "none";
+  errorEl.style.display = "block";
+  playerEl.style.display = "none";
+}
+
+function showPlayer(dataUri: string, info: string) {
+  videoEl.src = dataUri;
+  videoInfoEl.textContent = info;
+  loadingEl.style.display = "none";
+  errorEl.style.display = "none";
+  playerEl.style.display = "block";
+}
+
+// Create app instance
+const app = new App({ name: "Video Resource Player", version: "1.0.0" });
+
+// Handle tool result - this is called when the tool execution completes
+app.ontoolresult = async (result) => {
+  log.info("Received tool result:", result);
+
+  const parsed = parseToolResult(result);
+  if (!parsed) {
+    showError("Invalid tool result - could not parse video URI");
+    return;
+  }
+
+  const { videoUri, description } = parsed;
+  log.info("Video URI:", videoUri, "Description:", description);
+
+  showLoading("Fetching video from MCP resource...");
+
+  try {
+    log.info("Requesting resource:", videoUri);
+
+    const resourceResult = await app.request(
+      { method: "resources/read", params: { uri: videoUri } },
+      ReadResourceResultSchema,
+    );
+
+    log.info(
+      "Resource received, blob size:",
+      resourceResult.contents[0]?.blob?.length,
+    );
+
+    const content = resourceResult.contents[0];
+    if (!content?.blob) {
+      throw new Error("Resource response did not contain blob data");
+    }
+
+    showLoading("Converting to data URI...");
+
+    const mimeType = content.mimeType || "video/mp4";
+    const dataUri = `data:${mimeType};base64,${content.blob}`;
+
+    log.info("Data URI created, length:", dataUri.length);
+
+    showPlayer(dataUri, `Loaded via MCP resource (${description})`);
+  } catch (err) {
+    log.error("Error fetching resource:", err);
+    showError(err instanceof Error ? err.message : String(err));
+  }
+};
+
+app.onerror = (err) => {
+  log.error("App error:", err);
+  showError(err instanceof Error ? err.message : String(err));
+};
+
+// Connect to host
+app.connect();
--- a/examples/video-resource-server/tsconfig.json
+++ b/examples/video-resource-server/tsconfig.json
@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "outDir": "dist",
+    "lib": ["ESNext", "DOM"]
+  },
+  "include": ["server.ts", "src/**/*"]
+}
--- a/examples/video-resource-server/vite.config.ts
+++ b/examples/video-resource-server/vite.config.ts
@ -0,0 +1,24 @@
+import { defineConfig } from "vite";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+const INPUT = process.env.INPUT;
+if (!INPUT) {
+  throw new Error("INPUT environment variable is not set");
+}
+
+const isDevelopment = process.env.NODE_ENV === "development";
+
+export default defineConfig({
+  plugins: [viteSingleFile()],
+  build: {
+    sourcemap: isDevelopment ? "inline" : undefined,
+    cssMinify: !isDevelopment,
+    minify: !isDevelopment,
+
+    rollupOptions: {
+      input: INPUT,
+    },
+    outDir: "dist",
+    emptyOutDir: false,
+  },
+});
--- a/package-lock.json
+++ b/package-lock.json
@ -523,6 +523,62 @@
      "dev": true,
      "license": "MIT"
    },
+    "examples/video-resource-server": {
+      "version": "1.0.0",
+      "dependencies": {
+        "@modelcontextprotocol/ext-apps": "../..",
+        "@modelcontextprotocol/sdk": "^1.24.0",
+        "zod": "^4.1.13"
+      },
+      "devDependencies": {
+        "@types/cors": "^2.8.19",
+        "@types/express": "^5.0.0",
+        "@types/node": "^22.0.0",
+        "concurrently": "^9.2.1",
+        "cors": "^2.8.5",
+        "cross-env": "^7.0.3",
+        "express": "^5.1.0",
+        "typescript": "^5.9.3",
+        "vite": "^6.0.0",
+        "vite-plugin-singlefile": "^2.3.0"
+      }
+    },
+    "examples/video-resource-server/node_modules/@types/node": {
+      "version": "22.19.3",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.3.tgz",
+      "integrity": "sha512-1N9SBnWYOJTrNZCdh/yJE+t910Y128BoyY+zBLWhL3r0TYzlTmFdXrPwHL9DyFZmlEXNQQolTZh3KHV31QDhyA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "examples/video-resource-server/node_modules/cross-env": {
+      "version": "7.0.3",
+      "resolved": "https://registry.npmjs.org/cross-env/-/cross-env-7.0.3.tgz",
+      "integrity": "sha512-+/HKd6EgcQCJGh2PSjZuUitQBQynKor4wrFbRg4DtAgS1aWO+gU52xpH7M9ScGgXSYmAVS9bIJ8EzuaGw0oNAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cross-spawn": "^7.0.1"
+      },
+      "bin": {
+        "cross-env": "src/bin/cross-env.js",
+        "cross-env-shell": "src/bin/cross-env-shell.js"
+      },
+      "engines": {
+        "node": ">=10.14",
+        "npm": ">=6",
+        "yarn": ">=1"
+      }
+    },
+    "examples/video-resource-server/node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    },
    "examples/wiki-explorer-server": {
      "version": "1.0.0",
      "dependencies": {
@ -7145,6 +7201,10 @@
        "node": ">= 0.8"
      }
    },
+    "node_modules/video-resource-server": {
+      "resolved": "examples/video-resource-server",
+      "link": true
+    },
    "node_modules/vite": {
      "version": "6.4.1",
      "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.1.tgz",