Name: 无头浏览器自动化服务
Author: axo-mvo

使用说明

木偶MCP服务器

使用Next.js和Puppeteer构建的无头Chrome自动化服务器，设计用于在Vercel上运行，具有多种云浏览器选项。该项目提供RESTful API端点，用于web抓取、屏幕截图捕获、PDF生成和性能监控。

🔗 GitHub存储库： https://github.com/axo-mvo/puppeteer-mcp-server
🌐 现场演示： https://puppeteer-mcp-server.vercel.app
🎮 交互式演示： https://puppeteer-mcp-server.vercel.app/demo

快速测试

立即尝试API：

# Take a screenshot
curl "https://puppeteer-mcp-server.vercel.app/api/screenshot-chromium?url=https://example.com" -o screenshot.png

# Extract text content
curl -X POST "https://puppeteer-mcp-server.vercel.app/api/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","action":"text"}'

项目结构

puppeteer-vercel/
├── app/
│   ├── api/
│   │   ├── screenshot-browserless/     # Browserless.io API endpoint
│   │   │   └── route.ts
│   │   ├── screenshot-chromium/        # @sparticuz/chromium API endpoint
│   │   │   └── route.ts
│   │   ├── scrape/                     # Advanced scraping API endpoint
│   │   │   └── route.ts
│   │   └── mcp/                        # Model Context Protocol endpoint
│   │       └── route.ts
│   ├── demo/                           # Interactive demo page
│   │   └── page.tsx
│   ├── page.tsx                        # Main landing page
│   ├── layout.tsx                      # Root layout
│   └── globals.css                     # Global styles
├── package.json                        # Dependencies and scripts
├── next.config.ts                      # Next.js configuration
├── tailwind.config.ts                  # Tailwind CSS configuration
└── README.md                           # Project documentation

架构决策

浏览器执行选项

该项目实现了两种在无服务器环境中运行无头Chrome的方法：

@sparticuz/铬 (/api/screenshot-chromium)
- 自带Chromium二进制包
- 不需要外部依赖
- 捆绑尺寸更大，但更可靠
- 在Vercel的功能大小限制范围内工作
浏览器.io (/api/screenshot-browserless)
- 连接到云中托管的无头Chrome实例
- 需要 BLESS_TOKEN 环境变量
- 功能尺寸更小
- 更适合高容量使用

API设计

RESTful端点 用于不同的功能
TypeScript接口 用于请求/响应验证
全面的错误处理 具有正确的HTTP状态代码
缓存标头 为了提高性能
灵活的选择 用于定制

安装说明

先决条件

Node.js 18+
npm、yarn或pnpm

地方发展

克隆和安装依赖关系：

git clone https://github.com/axo-mvo/puppeteer-mcp-server.git
cd puppeteer-mcp-server
npm install

设置环境变量（适用于Browserless.io）： 创建 .env.local 文件：
```
BLESS_TOKEN=your_browserless_api_token_here
```
运行开发服务器：
```
npm run dev
```
访问应用程序：
- 主页：http://localhost:3000
- 演示页面：http://localhost:3000/demo

部署到Vercel

推送到GitHub：

git init
git add .
git commit -m "Initial commit"
git remote add origin <your-github-repo-url>
git push -u origin main

部署到Vercel：
- 在Vercel仪表板中导入您的GitHub存储库
- 如果使用Browserless.io，请添加环境变量：
  - BLESS_TOKEN您的 Browserless.io API 令牌

配置功能超时（可选）： 增添 vercel.json:

{
  "functions": {
    "app/api/**/route.ts": {
      "maxDuration": 30
    }
  }
}

MCP（模型上下文协议）支持

此服务器现在支持 模型上下文协议（MCP），允许它在Cursor、Claude Desktop和其他MCP兼容客户端等AI助手中用作工具服务器。

MCP端点

网址： /api/mcp （光标、克劳德桌面等功能齐全） 网址： /api/mcp-compliant （ChatGPT兼容版本有限制）

MCP端点提供以下工具：

工具名称	描述	参数
`take_screenshot`	对网页进行截图	`url`, `fullPage?`, `viewport?`, `waitFor?`
`generate_pdf`	从网页生成PDF	`url`, `format?`, `landscape?`, `waitFor?`
`extract_text`	从网页中提取文本内容	`url`, `selector?`, `waitFor?`
`extract_html`	从网页中提取HTML内容	`url`, `selector?`, `waitFor?`
`get_performance_metrics`	获取网页的性能指标	`url`, `waitFor?`

添加到AI助手

适用于Cursor/Claude桌面（完整版）

添加到您的 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "puppeteer-mcp": {
      "url": "https://puppeteer-mcp-server.vercel.app/api/mcp",
      "transport": "sse"
    }
  }
}

适用于ChatGPT（兼容版本）

使用功能受限的兼容端点：

转到ChatGPT设置→ 连接器→ 创建
添加MCP服务器URL: https://puppeteer-mcp-server.vercel.app/api/mcp-compliant
仅指定工具 search 和 retrieve 可用（OpenAI要求）
出于安全考虑，访问仅限于批准的域

使用MCP工具

配置后，您可以在Cursor中使用自然语言命令：

“截取example.com的屏幕截图”
“生成主页的PDF”
“从本网站提取标题文本”
“获取此URL的性能指标”

API终点

截图API

获取 `/api/screenshot-chromium`

使用@sparticuz/cromin截取屏幕截图。

参数：

url （必填）：要捕获的URL

例子：

curl "https://your-app.vercel.app/api/screenshot-chromium?url=https://example.com"

获取 `/api/screenshot-browserless`

使用Browserless.io截取屏幕截图。

参数：

url （必填）：要捕获的URL

要求： BLESS_TOKEN 环境变量

例子：

curl "https://your-app.vercel.app/api/screenshot-browserless?url=https://example.com"

高级报废API

发布 `/api/scrape`

具有多种操作的全面抓取端点。

请求正文：

{
  url: string;
  action: 'screenshot' | 'pdf' | 'text' | 'html' | 'performance';
  options?: {
    fullPage?: boolean;
    selector?: string;
    format?: 'A4' | 'Letter';
    landscape?: boolean;
    waitFor?: number;
    viewport?: {
      width: number;
      height: number;
    };
  };
}

示例：

带有自定义视口的屏幕截图：

curl -X POST "https://your-app.vercel.app/api/scrape" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "action": "screenshot",
    "options": {
      "fullPage": true,
      "viewport": {"width": 1200, "height": 800}
    }
  }'

生成PDF：

curl -X POST "https://your-app.vercel.app/api/scrape" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "action": "pdf",
    "options": {
      "format": "A4",
      "landscape": false
    }
  }'

提取文本内容：

curl -X POST "https://your-app.vercel.app/api/scrape" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "action": "text",
    "options": {
      "selector": "h1"
    }
  }'

环境变量

变量	必填	描述
`BLESS_TOKEN`	无*	Browserless.io API令牌（*对于无浏览器端点是必需的）

特性

✅ 屏幕截图（整页或视口）
✅ 从网页生成PDF
✅ 文本和HTML内容提取
✅ 绩效指标收集
✅ 自定义视口和等待选项
✅ RESTful API端点
✅ MCP（模型上下文协议）支持
✅ TypeScript支持
✅ 交互式演示界面
✅ 多种浏览器执行选项
✅ 全面的错误处理
✅ AI助手集成（Cursor、Claude Desktop）

局限性

功能超时： Vercel免费等级有10秒超时
功能大小： @sparticuz/铬为功能增加了约50MB
内存使用情况： Chrome需要大量内存分配
并发执行： 考虑生产使用的速率限制

故障排除

常见问题

函数超时错误（Function_INVOCATION_timeout）：
- 已在最新版本中修复：优化了Chrome参数，页面加载速度更快
- 用途 domcontentloaded 而不是 networkidle0 为了更快的装载
- 将功能超时时间增加到60秒 vercel.json
- 添加了适当的浏览器清理功能，以防止内存泄漏
内存错误：
- 正确关闭浏览器实例（自动处理）
- 避免对同一功能的并发请求
- 配置中功能存储器设置为1024MB
无浏览器.io连接错误：
- 验证 BLESS_TOKEN 设置正确
- 检查Browserless.io服务状态

性能优化

最新版本包括几个Vercel特定的优化：

更快的Chrome启动 具有优化的参数
减少页面加载时间 使用 domcontentloaded
更好的错误处理 具有自动浏览器清理功能
超时时间增加 对于复杂页面（60秒功能超时）
内存优化 使用单进程Chrome模式

贡献

分叉存储库
创建要素分支
进行更改并在本地进行测试
提交拉取请求

更改日志

2025-06-05：使用Next.js 15和Puppeteer集成进行初始项目设置
2025-06-05：添加了@sparticuz/cromium支持，以实现自包含的浏览器执行
2025-06-05：为云浏览器实例实现了Browserless.io集成
2025-06-05：创建了具有多种操作类型的全面刮削API
2025-06-05：构建具有实时测试功能的交互式演示界面
2025-06-05：添加了TypeScript接口和全面的错误处理
2025-06-05：更新了主登录页面，包括功能概述和设置说明
2025-06-05：通过优化Chrome参数和更快的加载速度修复了Vercel超时问题
2025-06-05：将功能超时时间增加到60秒，并改进了错误处理
2025-06-05：添加了生产URL存储和全面的测试套件
2025-06-05：修复了文件下载问题-pdf和图像现在可以下载正确的扩展名（.pdf、.png），而不是通用的.file扩展名
2025-06-05：添加了模型上下文协议（MCP）支持，并为AI助手集成提供了全面的工具定义
2025-06-05：创建了具有安全限制和批准的域白名单的ChatGPT兼容MCP端点

测试

生产测试

运行综合测试套件：

./test-production.sh

或测试单个端点：

# Health check
npm run test:prod

# Screenshot test
npm run test:screenshot

# Open demo page
npm run test:demo

手动测试

实时端点：

主网站： https://puppeteer-mcp-server.vercel.app/
演示页面： https://puppeteer-mcp-server.vercel.app/demo
屏幕截图API： https://puppeteer-mcp-server.vercel.app/api/screenshot-chromium?url=https://example.com
高级刮擦： POST https://puppeteer-mcp-server.vercel.app/api/scrape