AI导哈

网页抓取转Markdown工具

一个基于Puppeteer和AI的网页抓取工具，能够自动处理交互元素并将网页内容转换为Markdown格式。

  • by djannot
  • TypeScript
  • 本地部署
  • 48 星标
  • 更新于
在 GitHub 查看 djannot/puppeteer-vision-mcp

使用说明

木偶视觉MCP服务器

此模型上下文协议（MCP）服务器提供了一种工具，用于抓取网页并使用Puppeteer、Readability和Turndown将其转换为markdown格式。它具有人工智能驱动的交互功能，可以自动处理Cookie、验证码和其他交互元素。

现在可以通过以下方式轻松运行 npx!

特性

  • 使用隐藏模式的Puppeter抓取网页
  • 使用AI驱动的交互来自动处理：
    • Cookie同意横幅
    • 验证码
    • 通讯或订阅提示
    • 付费墙和登录墙
    • 年龄验证提示
    • 插播式广告
    • 任何其他阻止内容的交互元素
  • 使用Mozilla的可读性提取主要内容
  • 将HTML转换为格式良好的Markdown
  • 代码块、表和其他结构化内容的特殊处理
  • 可通过模型上下文协议访问
  • 通过禁用无头模式实时查看浏览器交互的选项
  • 易于消费 npx 包裹。

NPX快速入门

建议使用此服务器的方式是通过 npx，这确保您运行的是最新版本，而无需克隆或手动安装。

  1. 先决条件： 确保你已经安装了Node.js和npm。

  2. 环境设置： 服务器需要 OPENAI_API_KEY。您可以通过两种方式提供此配置和其他可选配置：

    • .env 文件： 创建一个 .env 您将运行的目录中的文件 npx 命令。
    • Shell环境变量： 导出终端会话中的变量。

    示例 .env 文件或shell导出：

    # Required
OPENAI_API_KEY=your_api_key_here

# Optional (defaults shown)
# VISION_MODEL=gpt-4.1
# API_BASE_URL=https://api.openai.com/v1   # Uncomment to override
# TRANSPORT_TYPE=stdio                     # Options: stdio, sse, http
# USE_SSE=true                             # Deprecated: use TRANSPORT_TYPE=sse instead
# PORT=3001                                # Only used in sse/http modes
# DISABLE_HEADLESS=true                    # Uncomment to see the browser in action

  3. 运行服务器： 打开终端并运行：

    npx -y puppeteer-vision-mcp-server
    • 这 -y 标志会自动确认来自的任何提示 npx.
    • 此命令将下载（如果尚未缓存）并执行服务器。
    • 默认情况下，它从开始 stdio 模式。集 TRANSPORT_TYPE=sse 或 TRANSPORT_TYPE=http 对于HTTP服务器模式。

使用NPX作为MCP工具

该服务器被设计为集成在MCP兼容的LLM编排器中的工具。以下是一个示例配置片段：

{
  "mcpServers": {
    "web-scraper": {
      "command": "npx",
      "args": ["-y", "puppeteer-vision-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        // Optional:
        // "VISION_MODEL": "gpt-4.1",
        // "API_BASE_URL": "https://api.example.com/v1",
        // "TRANSPORT_TYPE": "stdio", // or "sse" or "http"
        // "DISABLE_HEADLESS": "true" // To see the browser during operations
      }
    }
    // ... other MCP servers
  }
}

当以这种方式配置时，MCP编排器将管理 puppeteer-vision-mcp-server 过程。

环境配置详细信息

无论您如何运行服务器（NPX或本地开发），它都会使用以下环境变量：

  • OPENAI_API_KEY：（必需）用于访问视觉模型的API密钥。
  • VISION_MODEL：（可选）用于视觉分析的模型。
    • 违约： gpt-4.1
    • 可以是任何具有视觉能力的模型。
  • API_BASE_URL：（可选）自定义API终结点URL。
    • 使用此选项连接到其他兼容OpenAI的提供商（例如Together.ai、Groq、Anthropic、本地部署）。
  • TRANSPORT_TYPE：（可选）要使用的传输协议。
    • 选项： stdio （默认）， sse, http
    • stdio：直接过程通信（建议用于大多数用例）
    • sse：服务器通过HTTP发送事件（传统模式）
    • http：具有会话管理的可流化HTTP传输
  • USE_SSE：（可选，已弃用）设置为 true 通过HTTP启用SSE模式。
    • 弃用：使用 TRANSPORT_TYPE=sse 相反。
  • PORT：（可选）SSE或HTTP模式下HTTP服务器的端口。
    • 违约： 3001.
  • DISABLE_HEADLESS：（可选）设置为 true 以可见模式运行浏览器。
    • 违约： false （浏览器以无头模式运行）。

通信模式

服务器支持三种通信模式：

  1. stdio（默认）：通过标准输入/输出进行通信。
    • 非常适合与管理流程的LLM工具直接集成。
    • 非常适合命令行使用和脚本编写。
    • 没有启动HTTP服务器。这是默认模式。
  2. SSE模式：通过HTTP上的服务器发送事件进行通信。
    • 通过设置启用 TRANSPORT_TYPE=sse 在您的环境中。
    • 在指定的服务器上启动HTTP服务器 PORT （默认值：3001）。
    • 当您需要通过网络连接到该工具时使用。
    • 连接到： http://localhost:3001/sse
  3. HTTP模式：通过Streamable HTTP传输与会话管理进行通信。
    • 通过设置启用 TRANSPORT_TYPE=http 在您的环境中。
    • 在指定的服务器上启动HTTP服务器 PORT （默认值：3001）。
    • 支持完整的会话管理和可恢复的连接。
    • 连接到： http://localhost:3001/mcp

工具使用（MCP调用）

服务器提供 scrape-webpage 工具。

刀具参数：

  • url （string，必填）：要抓取的网页的URL。
  • autoInteract （boolean，可选，默认值：true）：是否自动处理交互元素。
  • maxInteractionAttempts （number，可选，默认值：3）：AI交互尝试的最大次数。
  • waitForNetworkIdle （boolean，可选，默认值：true）：是否等待网络空闲后再进行处理。

响应格式：

该工具以结构化格式返回结果：

  • content：一个数组，包含一个带有抓取网页原始标记的文本对象。
  • metadata：包含其他信息：
    • message：状态消息。
    • success：表示成功的布尔值。
    • contentSize：内容的大小（以字符为单位）（成功时）。

成功响应示例：

{
  "content": [
    {
      "type": "text",
      "text": "# Page Title\n\nThis is the content..."
    }
  ],
  "metadata": {
    "message": "Scraping successful",
    "success": true,
    "contentSize": 8734
  }
}

错误响应示例：

{
  "content": [
    {
      "type": "text",
      "text": ""
    }
  ],
  "metadata": {
    "message": "Error scraping webpage: Failed to load the URL",
    "success": false
  }
}

运作原理

AI驱动的交互

该系统使用具有视觉功能的AI模型（可通过以下方式配置 VISION_MODEL 和 API_BASE_URL)分析网页截图，并决定点击、打字或滚动等操作，以绕过叠加和同意书。此过程重复到 maxInteractionAttempts.

内容提取

交互后，Mozilla的可读性提取主要内容，然后使用Turndown对其进行净化并转换为Markdown，并为代码块和表制定自定义规则。

安装和开发（用于修改代码）

如果您想贡献、修改服务器或运行本地开发版本：

  1. 克隆存储库：

    git clone https://github.com/djannot/puppeteer-vision-mcp.git
cd puppeteer-vision-mcp

  2. 安装依赖关系：

    npm install

  3. 构建项目：

    npm run build

  4. 设置环境： 创建一个 .env 项目根目录中的文件 OPENAI_API_KEY 以及任何其他所需的配置（见上文“环境配置详细信息”）。

  5. 为发展而奔跑：

    npm start # Starts the server using the local build

    或者，对于更改后的自动重建：

    npm run dev

定制（针对开发人员）

您可以通过编辑来修改刮刀的行为：

  • src/ai/vision-analyzer.ts (analyzePageWithAI 功能）：自定义AI提示。
  • src/ai/page-interactions.ts (executeAction 函数）：添加新的动作类型。
  • src/scrapers/webpage-scraper.ts (visitWebPage 功能）：更改木偶选项。
  • src/utils/markdown-formatters.ts：调整Markdown转换的调低规则。

依赖项

关键依赖关系包括：

  • @modelcontextprotocol/sdk
  • puppeteer, puppeteer-extra
  • @mozilla/readability, jsdom
  • turndown, sanitize-html
  • openai （或用于视觉模型的兼容API）
  • express （用于SSE模式）
  • zod

相关 MCP