MCP Web Worker 演示

此演示展示了使用共享 Web Worker 架构的模型上下文协议 (MCP) 客户端实现。它演示了如何在浏览器环境中使用 MCP，采用纯 JavaScript 的解耦架构，无需构建步骤。

实现组件

1. Worker 实现 (worker.js)

• 包含 worker 上下文中 MCP 客户端的实现
• 演示了 MCP 的 worker 端消息处理模式
• 实现了一个简化的 MCP 客户端，没有外部依赖

2. 客户端包装器 (mcp-client.js)

• 为主线程提供了一个简化的 API 来与 worker 通信
• 处理连接、初始化和方法调用
• 将通信协议与实际的 MCP 实现分离

3. 模拟服务器 (server.js)

• 用于测试的演示服务器实现
• 提供工具、资源和提示
• 实现 MCP 请求处理程序

4. 演示 UI (index.html)

• 用于测试所有 MCP 功能的交互式界面
• 演示客户端功能，如工具调用、资源读取和提示检索
• 显示连接状态和服务器信息

5. 测试工具

• 最小 Worker (minimal-worker.js) - 用于兼容性测试的简化共享 worker
• 诊断 - 连接状态指示器和详细日志

消息协议

该实现使用自定义消息协议在主线程和 worker 上下文之间进行通信：

1. 连接消息

   • { type: 'connection', connectionId, status } - Worker 到主线程
   • { type: 'init', clientInfo } - 主线程到 worker
   • { type: 'close', connectionId } - 主线程到 worker

2. MCP 消息

   • { type: 'mcp', messageType: 'transport', payload } - 用于原始 MCP 协议消息
   • { type: 'mcp', messageType: 'method', method, params, requestId } - 方法调用
   • { type: 'mcp', messageType: 'result', method, result, requestId } - 方法结果
   • { type: 'mcp', messageType: 'error', error, requestId } - 错误响应
   • { type: 'mcp', messageType: 'status', status } - 状态更新

基于 Worker 架构的优势

1. 性能

   • 将 MCP 处理卸载到后台线程
   • 主 UI 线程在复杂操作期间保持响应

2. 共享状态

   • 单个 worker 实例服务于多个选项卡/窗口
   • 跨浏览器上下文共享连接和状态

3. 解耦设计

   • MCP 实现细节隔离在 worker 中
   • 主线程只需要知道消息传递 API
   • 更容易更新或替换任何组件

4. 安全性

   • MCP 代码在单独的上下文中运行
   • UI 和协议处理之间的资源隔离

如何运行演示

1. 确保 SDK 已构建：

   # 从 typescript-sdk 根目录
   npm run build
   

2. 启动 Web 服务器：

   # 从 typescript-sdk/webworker-demo 目录
   ./start.sh
   

   此脚本在端口 3000 上启动一个简单的 HTTP 服务器。或者，您可以使用：

   # 从 typescript-sdk 根目录
   npx http-server -p 3000
   

3. 打开 Web 浏览器（推荐 Chrome 或 Edge）并导航到：

   http://localhost:3000/webworker-demo/
   

   重要提示： 确保您通过 http://localhost:3000 访问该站点，而不是 file:// 协议。从文件系统加载 SharedWorker 时存在限制。

4. 单击“连接到 MCP”按钮以建立连接

   • 工具、资源和提示应自动加载
   • 如果有任何问题，请检查浏览器的控制台以获取详细日志

5. 使用选项卡浏览不同的 MCP 功能：

   • 工具：列出并调用可用工具（尝试使用您的姓名调用“hello”工具）
   • 资源：列出并读取资源（查看 readme 文件）
   • 提示：列出并检索提示（尝试 greeting 提示）

实现说明

• 此演示使用自包含的实现，没有外部依赖
• 所有代码直接在浏览器中运行，无需构建步骤
• 使用所有现代 JavaScript 功能（ES 模块、async/await 等）
• worker 实现客户端并连接到在同一上下文中运行的模拟服务器

浏览器兼容性要求

此演示严格要求支持以下功能的浏览器：

• 共享 Web Worker - 这是一个硬性要求（已知 Chrome、Edge 和 Opera 可以工作）
• ES 模块
• Async/await
• 其他 ES6+ 功能

如果您的浏览器不支持 SharedWorker，您将看到一条错误消息。与许多演示不同，此实现不提供回退到其他技术 - 它旨在展示使用 SharedWorker for MCP 客户端的特定优势。

已知支持 SharedWorker 的浏览器：

• Chrome
• Edge（基于 Chromium）
• Opera
• Android Chrome

支持有限或不支持的浏览器：

• Firefox（默认禁用，但可以通过 about:config 启用）
• Safari（有限支持）
• iOS Safari（不支持）

故障排除

如果您在运行演示时遇到问题：

1. 无法获取 worker 脚本：

   • 确保您通过 Web 服务器在 http://localhost:3000/webworker-demo/ 访问演示
   • 不要尝试从文件系统 (file://) 加载演示
   • 确保使用主目录中的 npm run build 构建 SDK
   • 检查您的浏览器控制台以获取特定错误消息
   • 演示将自动尝试多个 worker 脚本路径以找到可用的路径

2. 不支持 SharedWorker：

   • 使用具有良好 SharedWorker 支持的 Chrome 或 Edge
   • 如果您的浏览器不支持 SharedWorker，演示将显示明确的错误
   • 演示故意不为不支持的浏览器实现回退

3. 模块导入错误：

   • worker 和服务器使用常规导入，无需外部库
   • 确保您通过 HTTP 服务器访问，而不是直接从文件系统访问
   • 检查浏览器控制台以获取特定导入路径错误

4. 控制台错误：

   • 在浏览器控制台中查找与“SharedWorker”或“MCP”相关的错误
   • 该实现包括用于调试目的的广泛日志记录
   • worker 诊断面板显示连接状态和脚本路径

5. 空白页或未显示任何工具/资源：

   • 检查浏览器控制台（F12 或 Cmd+Option+I）以获取详细的错误消息
   • 确保您的浏览器已启用 JavaScript
   • 尝试清除浏览器缓存并刷新页面

6. 路径解析问题：

   • worker 尝试从多个路径加载：
     1. ./minimal-worker.js - 最小 worker 的相对路径
     2. /webworker-demo/minimal-worker.js - 最小 worker 的绝对路径
     3. ./worker.js - 完整 worker 的相对路径
     4. /webworker-demo/worker.js - 完整 worker 的绝对路径
   • worker 诊断面板将显示哪个路径已成功加载