Puppeteer Vision MCP Server - Specify4IT Configuration

Puppeteer Vision MCP Server - Specify4IT Configuration

这是专为抓取 specify4it.com 而配置的 Puppeteer Vision MCP 服务版本，其中包含用于处理该网站特定结构、动画和交互元素的自定义设置和脚本。

特定功能

• 针对 specify4it.com 的结构和内容进行了配置
• 用于提取以下内容的自定义脚本：
  • 页面内容和结构
  • CSS 动画和过渡效果
  • JavaScript 交互
  • 设计元素和资源
• 为网站重建整理了输出结构

现在可通过 npx 轻松运行！

功能

• 使用 Puppeteer 和隐身模式抓取网页
• 使用 AI 驱动的交互功能自动处理：
  • Cookie 同意横幅
  • CAPTCHA
  • 新闻邮件或订阅提示
  • 付费墙和登录墙
  • 年龄验证提示
  • 插页式广告
  • 阻挡内容的其他任何交互元素
• 使用 Mozilla 的 Readability 提取主要内容
• 将 HTML 转换为格式良好的 Markdown
• 对代码块、表格和其他结构化内容进行特殊处理
• 可通过 Model Context Protocol 使用
• 可通过禁用无头模式，实时查看浏览器交互
• 可轻松作为 npx 包使用。

使用 NPX 快速开始

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

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

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

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

   .env 文件或 Shell 导出示例：

   # 必需
   OPENAI_API_KEY=your_api_key_here
   
   # 可选（显示默认值）
   # VISION_MODEL=gpt-4.1
   # API_BASE_URL=https://api.openai.com/v1   # 取消注释以覆盖默认值
   # USE_SSE=true                             # 取消注释以使用 SSE 模式，而非 stdio
   # PORT=3001                                # 仅用于 SSE 模式
   # DISABLE_HEADLESS=true                    # 取消注释以查看浏览器运行情况
   

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

   npx -y puppeteer-vision-mcp-server
   

   • -y 标志会自动确认 npx 发出的任何提示。
   • 此命令会下载（如果尚未缓存）并运行该服务。
   • 默认情况下，服务以 stdio 模式启动。如果环境中设置了 USE_SSE=true，则会启动 HTTP 服务以进行 SSE 通信。

通过 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",
        // "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 API 的其他提供商（例如 Together.ai、Groq、Anthropic 或本地部署）。
• USE_SSE：（可选）设为 true 可通过 HTTP 启用 SSE 模式。
  • 默认值：false（使用 stdio 模式）。
• PORT：（可选）SSE 模式下 HTTP 服务使用的端口。
  • 默认值：3001。
• DISABLE_HEADLESS：（可选）设为 true 可在可见模式下运行浏览器。
  • 默认值：false（浏览器以无头模式运行）。

通信模式

该服务支持两种通信模式：

1. stdio（默认）：通过标准输入/输出进行通信。
   • 非常适合与管理进程的 LLM 工具直接集成。
   • 适用于命令行使用和脚本编写。
   • 不会启动 HTTP 服务。通过 npx 运行时，除非设置了 USE_SSE=true，否则默认使用此模式。
2. SSE 模式：通过 HTTP 上的 Server-Sent Events 进行通信。
   • 在环境中设置 USE_SSE=true 即可启用。
   • 在指定的 PORT（默认值：3001）上启动 HTTP 服务。
   • 需要通过网络连接到该工具时使用。

工具用法（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 # 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 函数）：更改 Puppeteer 选项。
• src/utils/markdown-formatters.ts：调整 Markdown 转换所用的 Turndown 规则。

依赖项

主要依赖项包括：

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