WebContainer MCP 运输

此目录包含用于模型上下文协议（MCP）的非官方WebContainer传输实现。此传输允许您在浏览器中的WebContainer环境中运行MCP服务器。

🚀 完整示例：查看具有交互式仪表板的完整工作实现，请访问webcontainer-mcp-browser

概述

WebContainerTransport 类实现了MCP Transport 接口，提供了一种使用WebContainer技术在浏览器中直接运行Node.js MCP服务器的方法。这使得可以在客户端运行MCP应用程序，而无需单独的服务器进程。

传输支持两种模式：

1. 基于文件：挂载自定义文件并运行自己的MCP服务器代码
2. 基于启动：通过命令运行现有的MCP服务器（例如，npx包）

重要提示：等待“运行”状态

⚠️ 关键：在发送任何工具请求或列出工具之前，必须等待状态变为 "running"。过早发送请求会导致错误。

安装（可选，用于类型安全）

npm install @modelcontextprotocol/sdk @webcontainer/api

简单示例

import { WebContainerTransport } from "./webcontainer-transport";

async function runMCPServer() {
  const transport = new WebContainerTransport({
    type: "files",
    files: {
      "index.js": `
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "Demo Server", version: "1.0.0" });

server.tool("echo", { message: z.string() }, async ({ message }) => ({
  content: [{ type: "text", text: message }],
}));

server.tool("add", { a: z.number(), b: z.number() }, async ({ a, b }) => ({
  content: [{ type: "text", text: String(a + b) }],
}));

const transport = new StdioServerTransport();
await server.connect(transport);
      `,
      "package.json": JSON.stringify({
        name: "webcontainer-mcp-server",
        version: "1.0.0",
        type: "module",
        dependencies: {
          "@modelcontextprotocol/sdk": "latest",
          zod: "latest",
        },
      }),
    },
    onStatusChange: (status) => {
      console.log("状态:", status);
      if (status === "running") {
        console.log("✅ 服务器已准备好 - 现在可以发送请求了！");
      }
    },
  });

  // 处理响应
  transport.onmessage = (message) => {
    if ("result" in message) {
      console.log("响应:", message.result);
    } else if ("error" in message) {
      console.log("错误:", message.error);
    }
  };

  transport.onerror = (error) => {
    console.error("传输错误:", error);
  };

  // 启动服务器
  await transport.start();

  // 等待服务器准备就绪
  await new Promise((resolve) => {
    const checkStatus = () => {
      if (transport._initialized) {
        // 或监听onStatusChange以获取"running"状态
        resolve();
      } else {
        setTimeout(checkStatus, 100);
      }
    };
    checkStatus();
  });

  // 现在可以安全地发送请求
  console.log("📤 列出工具...");
  await transport.send({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/list",
    params: {},
  });

  // 调用一个工具
  console.log("📤 调用add工具...");
  await transport.send({
    jsonrpc: "2.0",
    id: 2,
    method: "tools/call",
    params: {
      name: "add",
      arguments: { a: 5, b: 3 },
    },
  });

  // 一段时间后清理
  setTimeout(() => {
    transport.close();
  }, 5000);
}

// 运行示例
runMCPServer();

API 参考

WebContainerTransport

构造函数

new WebContainerTransport(options: WebContainerTransportOptions)

基于文件的选项

{
  type: "files";
  files: Record<string, string>;        // 文件名 -> 内容映射
  entrypoint?: string;                  // 默认为 "index.js"
  onStatusChange?: (status) => void;    // 状态回调
  bootOptions?: BootOptions;            // WebContainer启动选项
}

基于启动的选项

{
  type: "spawn";
  command: string;                      // 例如，"npx"
  args: string[];                       // 例如，["-y", "@modelcontextprotocol/server-filesystem"]
  env?: Record<string, string>;         // 环境变量
  onStatusChange?: (status) => void;    // 状态回调
  bootOptions?: BootOptions;            // WebContainer启动选项
}

方法

• start(): 初始化并启动服务器
• send(message): 发送JSON-RPC消息（仅在状态为 "running" 时）
• close(): 停止服务器并清理

状态值

• "booting": WebContainer正在启动
• "mounting": 挂载文件（仅限基于文件）
• "installing": 安装依赖项（仅限基于文件）
• "running": 服务器已准备好接收请求 ✅
• "unmounting": 卸载文件（仅限基于文件）
• "teardowned": WebContainer已拆除

多文件支持

您可以提供无限数量的文件：

const transport = new WebContainerTransport({
  type: "files",
  files: {
    "package.json": "...",
    "server.js": "...",
    "tools/math.js": "...",
    "tools/string.js": "...",
    "lib/utils.js": "...",
    "README.md": "...",
  },
  entrypoint: "server.js",
});

基于启动的示例

const transport = new WebContainerTransport({
  type: "spawn",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-everything"],
  env: {
    NODE_ENV: "development",
  },
  onStatusChange: (status) => console.log("状态:", status),
});

浏览器兼容性

需要支持WebContainer的现代浏览器（推荐使用Chrome、Edge）。

浏览器要求

要使用WebContainers，您的应用必须使用以下HTTP头服务页面：

  "Cross-Origin-Opener-Policy": "same-origin",
  "Cross-Origin-Embedder-Policy": "require-corp"