Webscout MCP

🚀 🔍 WebScout MCP

WebScout MCP 是一款強大的模型上下文協議（MCP）服務器，專為逆向工程 Web 應用程序而設計，尤其適用於聊天界面和流式 API。它提供了全面的瀏覽器自動化工具，可用於發現、分析和捕獲複雜 Web 應用程序的網絡流量。

🚀 快速開始

WebScout MCP 能幫助你對 Web 應用進行逆向工程，下面將介紹它的安裝、使用方法以及關鍵特性。

✨ 主要特性

🤖 自動化逆向工程

• 一鍵分析：自動導航到 Web 應用程序並捕獲流式端點
• 智能模式檢測：可高級檢測 SSE、WebSocket、分塊傳輸和自定義流式格式
• 網絡流量捕獲：在 CDP 級別全面監控所有 HTTP 請求、響應和 WebSocket 幀
• 結構化數據輸出：輸出包含 URL、請求負載和響應模式的清晰解析數據

🔐 交互式瀏覽器自動化

• 會話管理：具有 cookie 和身份驗證狀態管理的持久瀏覽器會話
• 身份驗證支持：處理登錄表單、OAuth 流程和多因素身份驗證
• 逐步導航：點擊按鈕、填寫表單並瀏覽複雜的多頁界面
• 可視化反饋：隨時截取屏幕截圖以瞭解頁面狀態和 UI 元素

🎯 高級網絡監控

• 即時捕獲：通過可配置的捕獲窗口即時監控流式響應
• 靈活過濾：捕獲所有流量或按 POST 請求、流式響應或 URL 模式進行過濾
• WebSocket 支持：全面捕獲 WebSocket 幀、消息和連接詳細信息
• 內存管理：可配置捕獲限制，以防止長時間會話期間出現內存問題

🛠️ 開發者友好工具

• 14 種專業工具：提供用於 Web 抓取、測試和 API 發現的綜合工具包
• 無頭或可見模式：可在無頭模式下進行自動化操作，或在可見模式下進行調試
• 錯誤處理：強大的錯誤處理功能，提供詳細的錯誤消息和恢復選項
• 跨平臺：在 macOS、Linux 和 Windows 上具有一致的行為

📋 可用工具

核心逆向工程

• reverse_engineer_chat - 自動分析聊天界面並發現流式端點
• start_network_capture - 開始全面的網絡流量監控
• stop_network_capture - 停止捕獲並檢索所有收集的數據
• get_network_capture_status - 檢查捕獲會話狀態和統計信息
• clear_network_capture - 清除捕獲的數據，而不停止捕獲會話

交互式瀏覽器控制

• initialize_session - 創建一個新的瀏覽器會話以進行交互式操作
• close_session - 清理瀏覽器資源並結束會話
• navigate_to_url - 在會話中導航到不同的 URL
• switch_tab - 在打開的瀏覽器標籤之間切換

用戶交互模擬

• click_element - 點擊按鈕、鏈接或任何交互式元素
• fill_form - 填寫表單字段，並可選擇自動提交
• wait_for_element - 等待動態元素出現後再繼續操作

可視化檢查

• take_screenshot - 捕獲視口、整頁或特定元素的屏幕截圖
• get_current_page_info - 檢索全面的頁面信息和標籤詳細信息

📦 安裝指南

前提條件

• Node.js 18+ - 支持 ES 模塊和現代 JavaScript 特性所需
• npm - 用於依賴項安裝的包管理器

快速設置

# 克隆倉庫
git clone https://github.com/pyscout/webscout-mcp
cd webscout-mcp

# 安裝依賴項
npm install

# 安裝 Playwright 瀏覽器以進行自動化操作
npx playwright install

💻 使用示例

基礎用法

基本聊天界面分析

// 初始化會話並分析聊天界面
const session = await initializeSession("https://chat.example.com");
const analysis = await reverseEngineerChat("https://chat.example.com", "Hello", 8000);

console.log("找到的端點數量:", analysis.length);
await closeSession(session.sessionId);

高級用法

交互式登錄流程

// 處理登錄並導航到受保護的內容
const session = await initializeSession("https://app.example.com/login");

await fillForm(session.sessionId, [
  { selector: 'input[name="email"]', value: "user@example.com" },
  { selector: 'input[name="password"]', value: "password123" }
], 'button[type="submit"]');

await waitForElement(session.sessionId, ".dashboard", 10000);
const screenshot = await takeScreenshot(session.sessionId);

await closeSession(session.sessionId);

網絡流量捕獲

// 監控頁面上的所有網絡活動
const session = await initializeSession("https://api.example.com");

await startNetworkCapture(session.sessionId, {
  capturePostOnly: false,
  captureStreaming: true,
  maxCaptures: 100
});

// 執行產生網絡流量的操作
await navigateToUrl(session.sessionId, "https://api.example.com/data");

const captureData = await stopNetworkCapture(session.sessionId);
console.log("捕獲的請求數量:", captureData.data.requests.length);

await closeSession(session.sessionId);

📚 詳細文檔

🏗️ 架構概述

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ 聊天界面        │───▶│ 瀏覽器自動化     │───▶│ 網絡捕獲        │
│  (目標 URL)     │    │   (Playwright)    │    │  (CDP + 路由)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ 消息輸入檢測    │    │  DOM 交互        │    │ 請求/響應分析  │
│                 │    │    (自動填充)    │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                       │
                                                       ▼
                                            ┌─────────────────┐
                                            │ 結構化數據輸出  │
                                            │  (JSON 格式)    │
                                            └─────────────────┘

工作流程

1. 瀏覽器啟動：在無頭 Playwright 瀏覽器中打開目標 URL
2. 網絡設置：建立 Chrome DevTools 協議（CDP）會話和路由攔截
3. 界面檢測：自動定位聊天輸入元素（文本區域、可編輯內容等）
4. 消息注入：發送測試消息以觸發流式響應
5. 流量捕獲：在指定的時間窗口內監控網絡請求/響應
6. 模式分析：識別捕獲數據中的流式模式
7. 數據處理：將捕獲的數據整理成清晰的 JSON 格式

流式檢測模式

系統可檢測多種流式響應格式：

• 服務器發送事件（SSE）：data: {"content": "..."}
• OpenAI 風格的塊：data: {"choices": [{"delta": {"content": "..."}}]}
• 事件流：event: message\ndata: {...}
• JSON 流式傳輸：包含 token、delta、content 字段的對象
• 自定義格式：f:{...}、0:"..."、e:{...} 模式
• WebSocket 消息：包含流式數據的二進制/文本幀
• 分塊響應：Transfer-encoding: chunked 且包含流式內容

📁 項目結構

webscout-mcp/
├── src/
│   ├── index.js                 # 主 MCP 服務器實現
│   └── tools/                   # 專業工具模塊
│       ├── reverseEngineer.js   # 工具導出和協調
│       ├── reverseEngineerChat.js # 自動聊天分析
│       ├── sessionManagement.js # 瀏覽器會話生命週期管理
│       ├── visualInspection.js  # 屏幕截圖和頁面信息
│       ├── interaction.js       # 點擊和表單填充
│       ├── navigation.js        # URL 導航和標籤切換
│       └── networkCapture.js    # 網絡流量監控
│   └── utilities/               # 共享實用函數
│       ├── browser.js           # 瀏覽器自動化實用工具
│       └── network.js           # 網絡模式檢測
├── package.json                 # 依賴項和腳本
├── mcp-config.json              # MCP 客戶端配置示例
└── README.md                    # 本說明文檔

🔧 配置

環境變量

MCP 配置

更新你的 MCP 客戶端配置文件：

{
  "mcpServers": {
    "webscout-mcp": {
      "command": "npx",
      "args": ["-y", "webscout-mcp"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

或者對於 VS Code MCP 配置（mcp.json）：

{
  "servers": {
    "webscout-mcp": {
      "command": "npx",
      "args": ["-y", "webscout-mcp"],
      "type": "stdio"
    }
  }
}

貢獻代碼

1. 分叉倉庫
2. 創建功能分支：git checkout -b feature-name
3. 進行更改並添加測試
4. 運行測試：npm test
5. 提交拉取請求

開發指南

• 遵循 ES6+ 語法和現代 JavaScript 實踐
• 為新函數添加 JSDoc 註釋
• 使用多個聊天界面測試你的更改
• 為新功能更新文檔
• 確保代碼通過所有測試

📄 許可證

本項目採用 ISC 許可證 - 詳情請參閱 LICENSE 文件。

🙏 致謝

• 基於 Model Context Protocol SDK 構建
• 藉助 Playwright 實現瀏覽器自動化
• 受更好的 Web API 發現和測試工具需求的啟發

⚠️ 重要提示

⚠️ 重要提示

• 道德使用：本工具僅用於 API 分析和集成目的。請始終遵守網站的服務條款和 robots.txt 文件。
• 速率限制：某些聊天界面可能有速率限制或驗證碼，這可能會干擾分析。
• 瀏覽器依賴：Playwright 需要安裝瀏覽器二進制文件才能進行自動化操作。
• 網絡條件：結果可能因網絡速度和目標網站性能而異。

💡 使用建議

若遇到問題或有疑問，可按以下步驟解決：

1. 查看 故障排除 部分。
2. 查看 GitHub 上現有的 問題。
3. 創建一個新的 問題 並提供詳細信息。

🐛 故障排除

常見問題

“未找到瀏覽器”錯誤

# 安裝 Playwright 瀏覽器
npx playwright install

“連接超時”錯誤

• 增加 captureWindowMs 參數
• 檢查網絡連接
• 驗證目標 URL 是否可訪問

“未找到流式端點”

• 嘗試不同的測試消息
• 增加捕獲窗口時間
• 驗證聊天界面是否需要身份驗證

MCP 連接問題

• 驗證 mcp-config.json 中的絕對路徑
• 確保安裝了 Node.js 18+
• 檢查 MCP 客戶端日誌以獲取詳細錯誤信息

WebScout MCP - 你進行 Web 應用程序逆向工程和 API 發現的智能夥伴。

為開發者、安全研究人員和 API 愛好者用心打造 ❤️