MCP Web Worker Demo

MCP Web Worker 演示

此演示展示了使用 Shared Web Worker 架构实现的 Model Context Protocol（MCP）客户端。它演示了如何在浏览器环境中使用 MCP，采用纯 JavaScript 实现解耦架构，无需构建。

实现组件

1. Worker 实现（worker.js）

• 包含在 Worker 上下文中实现 MCP 客户端的代码
• 展示 MCP 的 Worker 端消息处理模式
• 实现不依赖外部依赖项的简化版 MCP 客户端

2. 客户端封装（mcp-client.js）

• 为主线程提供与 Worker 通信的简化 API
• 处理连接、初始化和方法调用
• 将通信协议与实际的 MCP 实现解耦

3. 模拟服务端（server.js）

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

4. 演示界面（index.html）

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

5. 测试工具

• Minimal 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 已构建：

   # From the typescript-sdk root directory
   npm run build
   

2. 启动 Web 服务：

   # From the typescript-sdk/webworker-demo directory
   ./start.sh
   

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

   # From the typescript-sdk root directory
   npx http-server -p 3000
   

3. 打开 Web 浏览器（推荐使用 Chrome 或 Edge），并访问：

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

   重要： 请确保通过 http://localhost:3000 访问网站，而不是使用 file:// 协议。SharedWorker 从文件系统加载时会受到限制。

4. 点击“Connect to MCP”按钮建立连接

   • 工具、资源和提示词应会自动加载
   • 如果遇到问题，请查看浏览器控制台中的详细日志

5. 使用标签页探索不同的 MCP 功能：

   • Tools：列出并调用可用工具（尝试使用“hello”工具并输入你的姓名）
   • Resources：列出并读取资源（查看 readme 文件）
   • Prompts：列出并获取提示词（尝试使用 greeting 提示词）

实现说明

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

浏览器兼容性要求

此演示严格要求使用支持以下特性的浏览器：

• Shared Web Workers —— 这是硬性要求（已知 Chrome、Edge 和 Opera 可正常运行）
• ES 模块
• Async/await
• 其他 ES6+ 特性

如果浏览器不支持 SharedWorker，您会看到一条错误消息。与许多演示不同，此实现不会回退到其他技术，而是旨在展示使用 SharedWorker 作为 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 诊断面板会显示成功加载的路径