JinDaGe - Puppeteer MCP Server MCP Details

article

README

🚀 Puppeteer MCP 服务器文档

Puppeteer MCP 服务器借助 Puppeteer 工具库，通过 WebDriver 协议控制 Chrome 浏览器。它提供了丰富的 API 来操作浏览器，可实现导航、截图、元素操作等功能，为浏览器自动化操作提供了便利。

🚀 快速开始

Puppeteer 是一个由 Google 开发的工具库，用于通过 WebDriver 协议控制 Chrome 浏览器。Puppeteer 提供了丰富的 API 来操作浏览器，包括导航、截图、元素操作等。

✨ 主要特性

支持标准模式和活动标签模式，可灵活启动新浏览器实例或连接现有 Chrome 窗口。
提供多种工具，如连接现有 Chrome 实例、导航、截图、元素点击、表单填写与提交等。
支持自定义浏览器配置和扩展加载，增强浏览器功能。
具备完善的日志记录和错误处理机制。

📦 安装指南

标准安装

运行以下命令以克隆仓库并安装依赖项：

git clone https://github.com/your-repository.git
cd puppeteer-mcp-server
npm install

开发环境配置

确保已安装 Node.js (版本 14 或更高) 和 npm。
安装项目依赖：
```
npm install
```
启动开发服务器：
```
npm run dev
```

生产环境部署

安装项目依赖：
```
npm install --production
```
启动生产服务器：
```
npm start
```

💻 使用示例

标准模式

默认情况下，服务器将启动一个新的浏览器实例。

活动标签模式

要连接到现有 Chrome 窗口：

完全关闭所有现有的 Chrome 实例。

启动 Chrome 时启用远程调试：

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

在 Chrome 中导航到所需的网页。

使用 puppeteer_connect_active_tab 工具连接：

{
  "targetUrl": "https://example.com", // 可选：指定要连接的标签页 URL
  "debugPort": 9222 // 可选：默认为 9222
}

服务器将：

检测并连接到运行中带有远程调试功能的 Chrome 实例。
保持你的 Chrome 实例（不会关闭它）。
查找并连接非扩展标签页。
在连接失败时提供清晰的错误消息。

📚 详细文档

可用工具

puppeteer_connect_active_tab

连接到现有 Chrome 实例，该实例启用了远程调试功能。

可选参数：
- targetUrl：要连接的特定标签页的 URL。
- debugPort：Chrome 调试端口（默认为 9222）。

puppeteer_navigate

导航到指定 URL。

必需参数：
- url：要导航到的 URL。

puppeteer_screenshot

拍摄当前页面或特定元素的截图。

必需参数：
- name：截图的名称。
可选参数：
- selector：用于选择要截图元素的 CSS 选择器。
- width：以像素为单位的宽度（默认为 800）。
- height：以像素为单位的高度（默认为 600）。

puppeteer_click

点击页面上的某个元素。

必需参数：
- selector：要点击的元素的 CSS 选择器。

puppeteer_fill

填写输入字段的内容。

必需参数：
- selector：输入字段的 CSS 选择器。
- value：要填写的值。

puppeteer_submit_form

提交表单。

必需参数：
- selector：表单元素或其父容器的 CSS 选择器。

安全注意事项

在生产环境中，确保服务器运行在安全的网络上，并配置适当的安全策略。
避免将敏感信息明文存储在代码中，建议使用环境变量。
定期更新依赖项以防止已知的安全漏洞。

日志记录

日志级别

debug：调试模式，输出详细日志信息。
info：默认模式，输出一般信息日志。
warn：警告模式，输出潜在问题的日志。
error：错误模式，输出严重错误的日志。

日志格式

{
  "timestamp": "2023-10-26T15:36:40.123Z",
  "level": "info",
  "message": "Server started on port 8080"
}

错误处理

常见错误

无法连接到浏览器实例

Error: Cannot connect to browser instance

解决方法：

确保 Chrome 浏览器正在运行。
检查远程调试端口是否正确配置。

页面未加载完成

Error: Page not loaded

解决方法：

确保目标 URL 可用。
增加等待时间或使用适当的页面加载事件监听。

高级功能

自定义浏览器配置

在启动时自定义浏览器选项：

{
  "executablePath": "/path/to/chrome",
  "args": ["--incognito"],
  "userDataDir": "/path/to/user/data"
}

扩展支持

通过加载扩展来增强浏览器功能：

"extensions": ["/path/to/extension.crx"]

开发指南

贡献代码

创建一个分支用于你的更改。
提交并推送你的更改。
创建一个拉取请求以供审核。

问题报告

打开 Issues 页面。
描述问题的详细信息和复现步骤。

附录

命令行选项

# 启动服务器
npm start -- --port 8081

# 运行测试
npm test

# 打包项目
npm run build

FAQ

问：如何处理 CORS 问题？ 答：在配置中启用跨域资源共享：

"cors": {
  "enabled": true,
  "origin": "*"
}

问：如何捕获浏览器截图？ 答：使用 page.screenshot() 方法，并指定输出路径和格式。

联系方式

如需更多信息，请访问项目主页或联系维护人员。

📄 许可证

本项目遵循 MIT 许可证。详情请查阅 LICENSE 文件。

👏 贡献者

感谢以下贡献者对项目的支持：

张三
李四
王五