Puppeteer 视觉 MCP 服务器

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

现在可以通过 npx 轻松运行！

功能

• 使用 Puppeteer 的隐身模式抓取网页
• 使用人工智能驱动的交互自动处理：
  • Cookie 同意横幅
  • 验证码
  • 新闻订阅或订阅提示
  • 支付墙和登录墙
  • 年龄验证提示
  • 中间页广告
  • 任何其他阻止内容的交互元素
• 使用 Mozilla 的 Readability 提取主要内容
• 将 HTML 转换为格式良好的 Markdown
• 特别处理代码块、表格和其他结构化内容
• 可通过模型上下文协议访问
• 通过禁用无头模式实时查看浏览器交互
• 可作为 npx 包轻松消费。

使用 NPX 快速开始

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

1. 前提条件： 确保已安装 Node.js 和 npm。

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

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

   示例 .env 文件或终端导出：

   # 必需
   OPENAI_API_KEY=your_api_key_here
   
   # 可选（显示默认值）
   # VISION_MODEL=gpt-4.1
   # API_BASE_URL=https://api.openai.com/v1   # 注释掉以覆盖
   # TRANSPORT_TYPE=stdio                     # 选项：stdio, sse, http
   # USE_SSE=true                             # 已弃用：改为使用 TRANSPORT_TYPE=sse
   # PORT=3001                                # 仅在 sse/http 模式下使用
   # DISABLE_HEADLESS=true                    # 注释掉以查看浏览器操作
   

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

   npx -y puppeteer-vision-mcp-server
   

   • -y 标志会自动确认 npx 的任何提示。
   • 此命令将下载（如果尚未缓存）并执行服务器。
   • 默认情况下，它将以 stdio 模式启动。要使用 HTTP 服务器模式，请设置 TRANSPORT_TYPE=sse 或 TRANSPORT_TYPE=http。

作为 MCP 工具使用 NPX

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

{
  "mcpServers": {
    "web-scraper": {
      "command": "npx",
      "args": ["-y", "puppeteer-vision-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        // 可选：
        // "VISION_MODEL": "gpt-4.1",
        // "API_BASE_URL": "https://api.example.com/v1",
        // "TRANSPORT_TYPE": "stdio", // 或 "sse" 或 "http"
        // "DISABLE_HEADLESS": "true" // 在操作期间查看浏览器
      }
    }
    // ... 其他 MCP 服务器
  }
}

当这样配置时，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 启用。
   • 在指定的 PORT（默认：3001）上启动 HTTP 服务器。
   • 当需要通过网络连接到工具时使用。
   • 连接到：http://localhost:3001/sse
3. HTTP 模式：通过具有会话管理的流式 HTTP 传输进行通信。
   • 通过在环境中设置 TRANSPORT_TYPE=http 启用。
   • 在指定的 PORT（默认：3001）上启动 HTTP 服务器。
   • 支持完整的会话管理和可恢复连接。
   • 连接到：http://localhost:3001/mcp

工具使用（MCP 调用）

服务器提供了一个 scrape-webpage 工具。

工具参数：

• url（字符串，必需）：要抓取的网页的 URL。
• autoInteract（布尔值，可选，默认值：true）：是否自动处理交互元素。
• maxInteractionAttempts（数字，可选，默认值：3）：最大 AI 交互尝试次数。
• waitForNetworkIdle（布尔值，可选，默认值：true）：是否在网络空闲前等待处理。

响应格式：

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

• content：包含单个文本对象的数组，其中包含抓取网页的原始 Markdown。
• metadata：包含额外信息：
  • message：状态消息。
  • success：布尔值，指示成功与否。
  • contentSize：内容大小（字符数，成功时）。

示例成功响应：

{
  "content": [
    {
      "type": "text",
      "text": "# 页面标题\n\n这是内容..."
    }
  ],
  "metadata": {
    "message": "抓取成功",
    "success": true,
    "contentSize": 8734
  }
}

示例错误响应：

{
  "content": [
    {
      "type": "text",
      "text": ""
    }
  ],
  "metadata": {
    "message": "抓取网页失败：无法加载 URL",
    "success": false
  }
}

工作原理

人工智能驱动的交互

系统使用具有视觉能力的人工智能模型（可通过 VISION_MODEL 和 API_BASE_URL 配置）来分析网页截图，并决定采取点击、输入或滚动等行动以绕过覆盖层和同意表单。此过程最多重复 maxInteractionAttempts 次。

内容提取

在交互之后，Mozilla 的 Readability 提取主要内容，然后使用 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 # 使用本地构建启动服务器
   

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

   npm run dev
   

自定义（开发者）

您可以通过编辑以下文件来修改抓取器的行为：

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

依赖项

关键依赖项包括：

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