Puppeteer Vision Mcp Server

Puppeteer vision MCP 服务

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

现在可通过 npx 轻松运行！

功能

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

使用 NPX 快速入门

推荐通过 npx 使用此服务，这样无需克隆或手动安装，就能确保运行最新版本。

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

2. 环境设置： 服务需要 OPENAI_API_KEY。你可以通过以下两种方式提供该变量及其他可选配置：

   • .env 文件： 在运行 npx 命令的目录中创建 .env 文件。
   • 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 兼容大模型编排器中的工具。以下是一个配置片段示例：

{
  "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（默认）：通过标准输入/输出进行通信。
   • 非常适合与管理进程的大模型工具直接集成。
   • 适用于命令行使用和脚本编写。
   • 不会启动 HTTP 服务。这是默认模式。
2. SSE 模式：通过 HTTP 使用服务器发送事件进行通信。
   • 在环境中设置 TRANSPORT_TYPE=sse 即可启用。
   • 在指定的 PORT 上启动 HTTP 服务（默认值：3001）。
   • 需要通过网络连接到工具时使用。
   • 连接地址：http://localhost:3001/sse
3. HTTP 模式：使用支持会话管理的可流式 HTTP 传输进行通信。
   • 在环境中设置 TRANSPORT_TYPE=http 即可启用。
   • 在指定的 PORT 上启动 HTTP 服务（默认值：3001）。
   • 支持完整的会话管理和可恢复连接。
   • 连接地址：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": "# 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 的 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：调整 Markdown 转换所用的 Turndown 规则。

依赖项

主要依赖项包括：

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