Webpage Screenshot MCP

🚀 網頁截圖MCP服務器

這是一個使用Puppeteer進行網頁截圖的MCP（模型上下文協議）服務器。該服務器允許AI代理直觀地驗證網頁應用程序，並在生成網頁應用時查看其進度。

✨ 主要特性

• 全頁截圖：可捕獲整個網頁或僅視口區域。
• 元素截圖：使用CSS選擇器針對特定元素進行截圖。
• 多種格式：支持PNG、JPEG和WebP格式。
• 可定製選項：可設置視口大小、圖像質量、等待條件和延遲時間。
• Base64編碼：以Base64編碼的圖像形式返回截圖，便於集成。
• 認證支持：支持手動登錄和cookie持久化。
• 默認瀏覽器集成：使用系統默認瀏覽器，提供更自然的體驗。
• 會話持久化：在多步驟工作流程中保持瀏覽器會話打開。

📦 安裝指南

要安裝和構建MCP，請執行以下步驟：

# 克隆倉庫（如果尚未克隆）
git clone https://github.com/ananddtyagi/webpage-screenshot-mcp.git
cd webpage-screenshot-mcp

# 安裝依賴
npm install

# 構建項目
npm run build

MCP服務器使用TypeScript構建並編譯為JavaScript。dist文件夾包含編譯後的JavaScript文件。

添加到Claude或Cursor

要將此MCP添加到Claude Desktop或Cursor，請按以下步驟操作：

1. Claude Desktop：

   • 轉到“設置”>“開發者”。
   • 點擊“編輯配置”。
   • 添加以下內容：

   "webpage-screenshot": {
     "command": "node",
     "args": [
       "~/path/to/webpage-screenshot-mcp/dist/index.js"
     ]
   }
   

   • 保存並重新加載Claude。

2. Cursor：

   • 打開Cursor，轉到“Cursor設置”>“MCP”。
   • 點擊“添加新的全局MCP服務器”。
   • 添加以下內容：

   "webpage-screenshot": {
     "command": "node",
     "args": ["~/path/to/webpage-screenshot-mcp/dist/index.js"]
   }
   

   • 保存並重新加載Cursor。

💻 使用示例

工具

此MCP服務器提供了幾個工具：

1. login-and-wait

在可見的瀏覽器窗口中打開網頁以進行手動登錄，等待用戶完成登錄，然後保存cookie。

{
  "url": "https://example.com/login",
  "waitMinutes": 5,
  "successIndicator": ".dashboard-welcome",
  "useDefaultBrowser": true
}

• url（必需）：登錄頁面的URL。
• waitMinutes（可選）：等待登錄的最長分鐘數（默認值：5）。
• successIndicator（可選）：指示登錄成功的CSS選擇器或URL模式。
• useDefaultBrowser（可選）：是否使用系統默認瀏覽器（默認值：true）。

2. screenshot-page

捕獲給定URL的網頁截圖，並以Base64編碼的圖像形式返回。

{
  "url": "https://example.com/dashboard",
  "fullPage": true,
  "width": 1920,
  "height": 1080,
  "format": "png",
  "quality": 80,
  "waitFor": "networkidle2",
  "delay": 500,
  "useSavedAuth": true,
  "reuseAuthPage": true,
  "useDefaultBrowser": true,
  "visibleBrowser": true
}

• url（必需）：要截圖的網頁的URL。
• fullPage（可選）：是否捕獲整個頁面或僅視口區域（默認值：true）。
• width（可選）：視口寬度（像素）（默認值：1920）。
• height（可選）：視口高度（像素）（默認值：1080）。
• format（可選）：圖像格式 - "png"、"jpeg"或"webp"（默認值："png"）。
• quality（可選）：圖像質量（0 - 100），僅適用於jpeg和webp。
• waitFor（可選）：何時認為頁面已加載 - "load"、"domcontentloaded"、"networkidle0"或"networkidle2"（默認值："networkidle2"）。
• delay（可選）：頁面加載後額外的延遲時間（毫秒）（默認值：0）。
• useSavedAuth（可選）：是否使用之前登錄保存的cookie（默認值：true）。
• reuseAuthPage（可選）：是否使用現有的已認證頁面（默認值：false）。
• useDefaultBrowser（可選）：是否使用系統默認瀏覽器（默認值：false）。
• visibleBrowser（可選）：是否顯示瀏覽器窗口（默認值：false）。

3. screenshot-element

使用CSS選擇器捕獲網頁上特定元素的截圖。

{
  "url": "https://example.com/dashboard",
  "selector": ".user-profile",
  "waitForSelector": true,
  "format": "png",
  "quality": 80,
  "padding": 10,
  "useSavedAuth": true,
  "useDefaultBrowser": true,
  "visibleBrowser": true
}

• url（必需）：網頁的URL。
• selector（必需）：要截圖的元素的CSS選擇器。
• waitForSelector（可選）：是否等待選擇器出現（默認值：true）。
• format（可選）：圖像格式 - "png"、"jpeg"或"webp"（默認值："png"）。
• quality（可選）：圖像質量（0 - 100），僅適用於jpeg和webp。
• padding（可選）：元素周圍的填充（像素）（默認值：0）。
• useSavedAuth（可選）：是否使用之前登錄保存的cookie（默認值：true）。
• useDefaultBrowser（可選）：是否使用系統默認瀏覽器（默認值：false）。
• visibleBrowser（可選）：是否顯示瀏覽器窗口（默認值：false）。

4. clear-auth-cookies

清除特定域或所有域的保存的認證cookie。

{
  "url": "https://example.com"
}

• url（可選）：要清除cookie的域的URL。如果未提供，則清除所有cookie。

📚 詳細文檔

默認瀏覽器模式

默認瀏覽器模式允許你使用系統的常規瀏覽器（Chrome、Edge等），而不是Puppeteer捆綁的Chromium。這對於以下情況很有用：

1. 使用現有的瀏覽器會話和擴展程序。
2. 使用保存的憑據手動登錄網站。
3. 在多步驟工作流程中獲得更自然的瀏覽體驗。
4. 使用與用戶相同的瀏覽器環境進行測試。

要啟用默認瀏覽器模式，請在工具參數中設置useDefaultBrowser: true和visibleBrowser: true。

默認瀏覽器模式的工作原理

啟用默認瀏覽器模式時：

1. 工具將嘗試定位系統的默認瀏覽器（Chrome、Edge等）。
2. 它會啟動瀏覽器，並在隨機端口上啟用遠程調試。
3. Puppeteer連接到這個瀏覽器實例，而不是啟動自己的實例。
4. 在會話期間，你現有的配置文件、擴展程序和cookie都可用。
5. 瀏覽器窗口保持可見，以便你可以手動與之交互。

此模式對於需要認證或複雜用戶交互的工作流程特別有用。

瀏覽器持久化

MCP服務器可以在多次工具調用之間保持持久的瀏覽器會話：

1. 使用login-and-wait時，瀏覽器會話保持打開狀態。
2. 後續使用reuseAuthPage: true調用screenshot-page或screenshot-element時，將使用同一頁面。
3. 這允許在多步驟工作流程中無需重新認證。

Cookie管理

訪問的每個域的cookie會自動保存：

1. 使用login-and-wait後，cookie會保存到主文件夾中的.mcp-screenshot-cookies目錄。
2. 使用useSavedAuth: true再次訪問同一域時，這些cookie會自動加載。
3. 你可以使用clear-auth-cookies工具清除cookie。

示例工作流程：受保護頁面截圖

以下是一個對需要認證的頁面進行截圖的示例工作流程：

1. 手動登錄階段

{
  "name": "login-and-wait",
  "parameters": {
    "url": "https://example.com/login",
    "waitMinutes": 3,
    "successIndicator": ".dashboard-welcome",
    "useDefaultBrowser": true
  }
}

這將在默認瀏覽器中打開登錄頁面。你可以手動登錄，完成後（通過檢測成功指示器或離開登錄頁面），會話cookie將被保存。

2. 使用保存的會話進行截圖

{
  "name": "screenshot-page",
  "parameters": {
    "url": "https://example.com/account",
    "fullPage": true,
    "useSavedAuth": true,
    "reuseAuthPage": true,
    "useDefaultBrowser": true,
    "visibleBrowser": true
  }
}

這將使用保存的認證cookie在同一瀏覽器窗口中對賬戶頁面進行截圖。

3. 對特定元素進行截圖

{
  "name": "screenshot-element",
  "parameters": {
    "url": "https://example.com/dashboard",
    "selector": ".user-profile-section",
    "useSavedAuth": true,
    "useDefaultBrowser": true,
    "visibleBrowser": true
  }
}

4. 完成後清除cookie

{
  "name": "clear-auth-cookies",
  "parameters": {
    "url": "https://example.com"
  }
}

此工作流程允許你像普通用戶一樣與受保護頁面進行交互，在默認瀏覽器中完成完整的認證流程。

無頭模式與可見模式

• 無頭模式 (visibleBrowser: false)：速度更快，更適合不需要用戶交互的自動化工作流程。
• 可見模式 (visibleBrowser: true)：顯示瀏覽器窗口，允許用戶交互和手動驗證。使用useDefaultBrowser: true時需要此模式。

平臺支持

默認瀏覽器檢測在以下平臺上有效：

• macOS：可檢測Chrome、Edge和Safari。
• Windows：通過註冊表或常見安裝路徑檢測Chrome和Edge。
• Linux：通過系統命令檢測Chrome和Chromium。

故障排除

常見問題

1. 未找到默認瀏覽器：如果系統無法找到默認瀏覽器，將回退到Puppeteer捆綁的Chromium。
2. 連接問題：如果連接到瀏覽器的調試端口時出現問題，請檢查該端口是否已被其他實例使用。
3. Cookie問題：如果認證不起作用，請嘗試使用clear-auth-cookies工具清除cookie。

調試

出現問題時，MCP服務器會在控制檯記錄有用的錯誤消息。檢查這些消息以獲取故障排除信息。