Puppeteer MCP Server

🚀 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

開發環境配置

1. 確保已安裝 Node.js (版本 14 或更高) 和 npm。
2. 安裝項目依賴：

   npm install
   

3. 啟動開發服務器：

   npm run dev
   

生產環境部署

1. 安裝項目依賴：

   npm install --production
   

2. 啟動生產服務器：

   npm start
   

💻 使用示例

標準模式

默認情況下，服務器將啟動一個新的瀏覽器實例。

活動標籤模式

要連接到現有 Chrome 窗口：

1. 完全關閉所有現有的 Chrome 實例。
2. 啟動 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
   

3. 在 Chrome 中導航到所需的網頁。
4. 使用 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 選擇器。

安全注意事項

1. 在生產環境中，確保服務器運行在安全的網絡上，並配置適當的安全策略。
2. 避免將敏感信息明文存儲在代碼中，建議使用環境變量。
3. 定期更新依賴項以防止已知的安全漏洞。

日誌記錄

日誌級別

• 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"]

開發指南

貢獻代碼

1. 創建一個分支用於你的更改。
2. 提交併推送你的更改。
3. 創建一個拉取請求以供審核。

問題報告

1. 打開 Issues 頁面。
2. 描述問題的詳細信息和復現步驟。

附錄

命令行選項

# 啟動服務器
npm start -- --port 8081

# 運行測試
npm test

# 打包項目
npm run build

FAQ

問：如何處理 CORS 問題？ 答：在配置中啟用跨域資源共享：

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

問：如何捕獲瀏覽器截圖？ 答：使用 page.screenshot() 方法，並指定輸出路徑和格式。

聯繫方式

如需更多信息，請訪問 項目主頁 或聯繫 維護人員。

📄 許可證

本項目遵循 MIT 許可證。詳情請查閱 LICENSE 文件。

👏 貢獻者

感謝以下貢獻者對項目的支持：

• 張三
• 李四
• 王五