JinDaGe - webscout-mcp MCP Details

article

README

🚀 🔍 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 格式)    │
                                            └─────────────────┘

工作流程

浏览器启动：在无头 Playwright 浏览器中打开目标 URL
网络设置：建立 Chrome DevTools 协议（CDP）会话和路由拦截
界面检测：自动定位聊天输入元素（文本区域、可编辑内容等）
消息注入：发送测试消息以触发流式响应
流量捕获：在指定的时间窗口内监控网络请求/响应
模式分析：识别捕获数据中的流式模式
数据处理：将捕获的数据整理成清晰的 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                    # 本说明文档

🔧 配置

环境变量

| 变量 | 描述 | 默认值 | | ---------- | ---------------- | -------------- | | NODE_ENV | 环境模式 | development | | DEBUG | 启用调试日志记录 | false |

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"
    }
  }
}

贡献代码

分叉仓库
创建功能分支：git checkout -b feature-name
进行更改并添加测试
运行测试：npm test
提交拉取请求

开发指南

遵循 ES6+ 语法和现代 JavaScript 实践
为新函数添加 JSDoc 注释
使用多个聊天界面测试你的更改
为新功能更新文档
确保代码通过所有测试

📄 许可证

本项目采用 ISC 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

基于 Model Context Protocol SDK 构建
借助 Playwright 实现浏览器自动化
受更好的 Web API 发现和测试工具需求的启发

⚠️ 重要提示

⚠️ 重要提示

道德使用：本工具仅用于 API 分析和集成目的。请始终遵守网站的服务条款和 robots.txt 文件。

速率限制：某些聊天界面可能有速率限制或验证码，这可能会干扰分析。

浏览器依赖：Playwright 需要安装浏览器二进制文件才能进行自动化操作。

网络条件：结果可能因网络速度和目标网站性能而异。

💡 使用建议

若遇到问题或有疑问，可按以下步骤解决：

查看故障排除部分。

查看 GitHub 上现有的问题。

创建一个新的问题并提供详细信息。

🐛 故障排除

常见问题

“未找到浏览器”错误

# 安装 Playwright 浏览器
npx playwright install

“连接超时”错误

增加 captureWindowMs 参数
检查网络连接
验证目标 URL 是否可访问

“未找到流式端点”

尝试不同的测试消息
增加捕获窗口时间
验证聊天界面是否需要身份验证

MCP 连接问题

验证 mcp-config.json 中的绝对路径
确保安装了 Node.js 18+
检查 MCP 客户端日志以获取详细错误信息

WebScout MCP - 你进行 Web 应用程序逆向工程和 API 发现的智能伙伴。

为开发者、安全研究人员和 API 爱好者用心打造 ❤️