MCP Worker

🚀 MCP Web 工作線程示例演示

本示例演示瞭如何使用共享 Web 工作線程架構實現 Model Context Protocol (MCP) 客戶端。它展示了在瀏覽器環境中運用 MCP 的方法，採用解耦架構，僅使用純 JavaScript，無需任何構建要求。

✨ 主要特性

• 解耦設計：客戶端和工作線程獨立運行，互不影響。
• 自動回退：若共享工作線程不可用，可回退到其他實現方式。
• 模塊化：代碼按功能劃分，便於維護和擴展。
• 廣泛的瀏覽器支持：完全支持 Chrome、Edge (Chromium-based)、Opera、Android Chrome；部分支持 Firefox（需手動啟用）、Safari；不支持 iOS Safari。

📦 安裝指南

先決條件

1. 安裝 Node.js（推薦使用版本 >= 14）。
2. 在項目根目錄運行 npm install。
3. 使用 npm run build 構建生產文件。

啟動步驟

1. 啟動開發服務器：npm start。
2. 打開瀏覽器，訪問 http://localhost:8000/webworker-demo/。
3. 測試不同功能模塊，觀察控制檯日誌和 UI 反饋。

💻 使用示例

基礎用法

本示例通過多個組件協同工作來實現 MCP 客戶端的功能，以下為各組件的簡單介紹：

1. 工人實施（worker.js）

• 包含在工作線程上下文中實現 MCP 客戶端的代碼。
• 演示工作線程端的消息處理模式。
• 實現了一個簡化的 MCP 客戶端，無外部依賴。

2. 客戶端包裝器（mcp-client.js）

• 提供主線程與工作線程通信的簡化 API。
• 處理連接、初始化和方法調用。
• 將通信協議與實際 MCP 實現解耦。

3. 模擬服務器（server.js）

• 測試演示服務器實現。
• 提供工具、資源和提示。
• 實現了 MCP 請求處理程序。

4. 演示 UI（index.html）

• 交互式界面用於測試所有 MCP 功能。
• 顯示加載狀態、連接狀態和日誌信息。
• 包含工作線程診斷面板，顯示加載的腳本路徑和狀態。

5. 最小化工人（minimal-worker.js）

• 最小化的實現版本，僅處理基本連接。
• 用於檢測瀏覽器是否支持共享工作線程。
• 若失敗，會回退到使用 mcp-client.js。

高級用法

客戶端和服務端通過特定的 JSON 格式消息進行通信，具體如下：

客戶端消息

1. "/#/mcp/connect" { "targetUrl": string }：連接到指定的 MCP 目標 URL。
2. "/#/mcp/request" { "requestId": string, "payload": any }：發送帶有唯一標識符和負載的消息。

服務端消息

1. "/#/mcp/connected" { "connectionId": string }：連接成功，返回連接 ID。
2. "/#/mcp/response" { "requestId": string, "payload": any, "error?": string }：發送響應，帶有原始請求 ID 和結果。

📚 詳細文檔

實現組件

1. 工人實施（worker.js）

• 包含在工人上下文中實現 MCP 客戶端的代碼。
• 演示工人端的消息處理模式。
• 實現了一個簡化的 MCP 客戶端，沒有外部依賴。

2. 客戶端包裝器（mcp-client.js）

• 提供了主線程與工人通信的簡化 API。
• 處理連接、初始化和方法調用。
• 將通信協議與實際 MCP 實現解耦。

3. 模擬服務器（server.js）

• 測試演示服務器實現。
• 提供工具、資源和提示。
• 實現了 MCP 請求處理程序。

4. 演示 UI（index.html）

• 交互式界面用於測試所有 MCP 功能。
• 顯示加載狀態、連接狀態和日誌信息。
• 包含工人診斷面板，顯示加載的腳本路徑和狀態。

5. 最小化工人（minimal-worker.js）

• 最小化的實現版本，僅處理基本連接。
• 用於檢測瀏覽器是否支持共享工兵。
• 如果失敗，會回退到使用 mcp-client.js。

消息協議

客戶端和服務端通過以下 JSON 格式的消息進行通信：

客戶端消息

1. "/#/mcp/connect" { "targetUrl": string }
   • 連接到指定的 MCP 目標 URL。
2. "/#/mcp/request" { "requestId": string, "payload": any }
   • 發送帶有唯一標識符和負載的消息。

服務端消息

1. "/#/mcp/connected" { "connectionId": string }
   • 連接成功，返回連接 ID。
2. "/#/mcp/response" { "requestId": string, "payload": any, "error?": string }
   • 發送響應，帶有原始請求 ID 和結果。

架構優勢

瀏覽器支持

• 完全支持：Chrome, Edge (Chromium-based), Opera, Android Chrome。
• 部分支持：Firefox（需要手動啟用），Safari。
• 不支持：iOS Safari。

注意事項

資源加載路徑

工人腳本嘗試從以下路徑加載：

1. ./minimal-worker.js - 相對路徑到最小化工人。
2. /webworker-demo/minimal-worker.js - 絕對路徑到最小化工人。
3. ./worker.js - 相對路徑到完整工人。
4. /webworker-demo/worker.js - 絕對路徑到完整工人。

工人診斷面板

顯示以下信息：

• 加載狀態：成功或失敗。
• 連接狀態：連接中、已連接、斷開。
• 腳本路徑：嘗試加載的路徑和結果。
• 日誌信息：錯誤消息和調試日誌。

故障排除

問題 1：無法獲取工人腳本

• 確保通過 Web 服務器訪問演示頁面，不要直接從文件系統訪問。
• 檢查控制檯是否有具體的錯誤信息。
• 工人診斷面板會顯示嘗試的路徑和結果。

問題 2：共享工兵不支持

• 使用 Chrome 或 Edge 瀏覽器進行測試。
• 瀏覽器控制檯會提示明確的錯誤信息。
• 目前沒有為不支持共享工兵的瀏覽器提供回退方案。

問題 3：模塊導入失敗

• 確保通過 Web 服務器訪問演示頁面，不要直接從文件系統訪問。
• 檢查控制檯是否有具體的導入路徑錯誤。
• 工人診斷面板會顯示嘗試的路徑和結果。

問題 4：空白頁面或無工具/資源顯示

• 打開瀏覽器控制檯（F12 或 Cmd + Option + I）查看詳細錯誤信息。
• 確保 JavaScript 在瀏覽器中已啟用。
• 清除緩存後刷新頁面。

問題 5：路徑解析問題

• 工人嘗試從多個路徑加載腳本，工人診斷面板會顯示結果。
• 如果所有路徑都失敗，請檢查網絡連接和文件存在性。