Browserloop

🚀 BrowserLoop

BrowserLoop 是一個基於 Playwright 的模型上下文協議（MCP）服務器，可用於截取網頁截圖並讀取控制檯日誌。該工具允許 AI 代理自動捕獲截圖並監控瀏覽器控制檯輸出，以進行調試、測試和開發任務。

🚀 快速開始

📦 NPX 使用方法（推薦）

這是最簡便的入門方式，無需安裝！

# 安裝 Chromium 瀏覽器（一次性設置）
npx playwright install chromium

# 測試 BrowserLoop 是否正常工作
npx browserloop@latest --version

就這麼簡單！ 最新版本的 BrowserLoop 將自動下載並執行。非常適合希望零維護即可使用截圖功能的 MCP 用戶。

MCP 配置

將 BrowserLoop 添加到你的 MCP 配置文件（例如 ~/.cursor/mcp.json）中：

{
  "mcpServers": {
    "browserloop": {
      "command": "npx",
      "args": ["-y", "browserloop@latest"],
      "description": "使用 Playwright 進行網頁截圖和控制檯日誌捕獲的服務器"
    }
  }
}

💡 使用 @latest 可確保你始終自動獲得最新功能和錯誤修復。

🚀 一鍵安裝到 Cursor

使用此深度鏈接，一鍵將 BrowserLoop 添加到 Cursor： 🔗 將 BrowserLoop 添加到 Cursor 此深度鏈接將使用 npx 和最新版本，自動在你的 Cursor MCP 設置中配置 BrowserLoop。 前提條件： 請確保你首先安裝了 Chromium：

npx playwright install chromium

瀏覽器安裝要求

🚨 重要提示： 在使用 BrowserLoop 進行截圖之前，需要通過 Playwright 安裝 Chromium 瀏覽器。

首次設置（所有用戶）

安裝 Chromium 瀏覽器：

npx playwright install chromium

驗證安裝：

# 檢查 Playwright 安裝情況
npx playwright --version

# 測試 BrowserLoop（如果使用 NPX）
npx browserloop@latest --version

🐳 Docker 替代方案

對於容器化環境：

# 使用 Docker 拉取並運行
docker run --rm --network host browserloop

# 或者在開發時使用 docker-compose
git clone <repository-url>
cd browserloop
docker-compose -f docker/docker-compose.yml up

💻 開發安裝

對於貢獻者或希望從源代碼構建的高級用戶：

# 克隆倉庫
git clone <repository-url>
cd browserloop

# 安裝依賴項
npm install

# 安裝 Playwright 瀏覽器（截圖所需）
npx playwright install chromium
# 或者使用便捷腳本：
npm run install-browsers

# 構建項目
npm run build

開發環境的 MCP 配置

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": [
        "/absolute/path/to/browserloop/dist/src/index.js"
      ],
      "description": "使用 Playwright 進行網頁截圖和控制檯日誌捕獲的服務器"
    }
  }
}

請將 /absolute/path/to/browserloop/ 替換為你實際的項目路徑。

基本用法

配置完成後，你可以在 AI 工具中使用自然語言命令：

截圖

截取 https://example.com 的屏幕截圖
截取寬度為 1920、高度為 1080 的 https://example.com 屏幕截圖
以 95% 的質量截取 JPEG 格式的 https://example.com 屏幕截圖
截取 https://example.com 的全頁屏幕截圖
截取 http://localhost:3000 的屏幕截圖以驗證 UI 更改

讀取控制檯日誌

讀取 https://example.com 的控制檯日誌
檢查 https://example.com 上的控制檯錯誤
監控 http://localhost:3000 的控制檯警告
僅讀取 https://example.com 的錯誤和警告日誌
捕獲 https://example.com 的控制檯輸出以進行調試

🔐 基於 Cookie 的身份驗證

BrowserLoop 支持基於 Cookie 的身份驗證，可在開發過程中截取受登錄保護頁面的屏幕截圖：

使用以下 Cookie 截取 http://localhost:3000/admin/dashboard 的屏幕截圖： [{"name":"connect.sid","value":"s:session-id.signature","domain":"localhost"}]

📖 有關 Cookie 提取方法和開發工作流程，請參閱： 📖 Cookie 身份驗證指南 常見的開發用例包括：

• 具有身份驗證的本地開發服務器
• 暫存環境測試
• API 文檔工具（Swagger、GraphQL Playground）
• 開發過程中的自定義 Web 應用程序
• 管理面板和受保護的路由

✨ 主要特性

• 📸 使用 Playwright 進行高質量截圖捕獲
• 📝 監控和收集網頁的控制檯日誌
• 🌐 支持本地主機和遠程 URL
• 🍪 受保護頁面的基於 Cookie 的身份驗證
• 🐳 Docker 容器化，確保環境一致
• ⚡ 支持 PNG、JPEG 和 WebP 格式，並可配置質量
• 🛡️ 以非根用戶身份安全執行容器
• 🤖 與 AI 開發工具完全集成 MCP 協議
• 🔧 可配置視口大小和捕獲選項
• 📱 支持全頁和特定元素的截圖捕獲
• ⚠️ 捕獲瀏覽器警告和錯誤（Permissions-Policy、安全警告）
• ⚡ 使用 TypeScript 和 Biome 進行快速開發
• 🧪 使用 Node.js 內置測試運行器進行全面測試

💻 使用示例

基礎用法

# 安裝 Chromium 瀏覽器（一次性設置）
npx playwright install chromium

# 測試 BrowserLoop 是否正常工作
npx browserloop@latest --version

高級用法

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": [
        "/absolute/path/to/browserloop/dist/src/index.js"
      ],
      "description": "使用 Playwright 進行網頁截圖和控制檯日誌捕獲的服務器"
    }
  }
}

📚 詳細文檔

• 🔐 Cookie 身份驗證指南 - 經過身份驗證的截圖的完整指南
• 📚 完整 API 參考 - 詳細的參數文檔、示例和響應格式

關鍵 API 參數

屬性	詳情
url	要捕獲的目標 URL（必需）
width	視口寬度（200 - 4000），默認值為 1280
height	視口高度（200 - 4000），默認值為 720
format	圖像格式（webp、png、jpeg），默認值為 webp
quality	圖像質量（1 - 100），默認值為 80
fullPage	是否捕獲全頁，默認值為 false
selector	用於元素捕獲的 CSS 選擇器

📖 有關完整的參數詳細信息、使用示例和配置選項，請參閱 docs/API.md。

🔧 技術細節

配置

BrowserLoop 可以使用環境變量進行配置：

基本配置

變量	默認值	描述
BROWSERLOOP_DEFAULT_WIDTH	1280	默認視口寬度（200 - 4000）
BROWSERLOOP_DEFAULT_HEIGHT	720	默認視口高度（200 - 4000）
BROWSERLOOP_DEFAULT_FORMAT	webp	默認圖像格式（webp、png、jpeg）
BROWSERLOOP_DEFAULT_QUALITY	80	默認圖像質量（0 - 100）
BROWSERLOOP_DEFAULT_TIMEOUT	30000	默認超時時間（毫秒）
BROWSERLOOP_USER_AGENT	-	自定義用戶代理字符串

身份驗證配置

變量	默認值	描述
BROWSERLOOP_DEFAULT_COOKIES	-	默認 Cookie，作為文件路徑或 JSON 字符串（請參閱 Cookie 身份驗證指南）

控制檯日誌配置

變量	默認值	描述
BROWSERLOOP_CONSOLE_LOG_LEVELS	log,info,warn,error,debug	要捕獲的日誌級別，以逗號分隔
BROWSERLOOP_CONSOLE_TIMEOUT	30000	頁面導航超時時間（毫秒，不是日誌收集時間）
BROWSERLOOP_SANITIZE_LOGS	true	啟用/禁用日誌中敏感數據的清理
BROWSERLOOP_CONSOLE_WAIT_NETWORK_IDLE	true	在完成收集之前等待網絡空閒
BROWSERLOOP_MAX_LOG_SIZE	1048576	日誌的最大總大小（字節，1MB）

注意： 控制檯日誌收集在頁面加載後總是精確等待 3 秒以捕獲控制檯消息。超時設置僅影響頁面最初加載的時間。

日誌清理

控制檯日誌清理默認啟用（BROWSERLOOP_SANITIZE_LOGS=true），以保護敏感信息。啟用後，以下模式將自動屏蔽：

模式類型	示例輸入	屏蔽輸出
API 密鑰	sk_live_1234567890abcdef...	[API_KEY_MASKED]
電子郵件地址	user@example.com	[EMAIL_MASKED]
JWT 令牌	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...	[JWT_TOKEN_MASKED]
身份驗證標頭	Bearer abc123token...	[AUTH_HEADER_MASKED]
帶有身份驗證的 URL	https://api.com/data?token=secret123	[URL_WITH_AUTH_MASKED]
秘密變量	password: mySecretPass	password: [VALUE_MASKED]

要禁用清理功能（用於調試）：

BROWSERLOOP_SANITIZE_LOGS=false

注意： 清理功能在屏蔽敏感內容的同時保留日誌結構，使日誌可安全共享和分析。

性能和可靠性

變量	默認值	描述
BROWSERLOOP_RETRY_COUNT	3	失敗操作的重試次數
BROWSERLOOP_RETRY_DELAY	1000	重試之間的延遲（毫秒）

日誌記錄和調試

變量	默認值	描述
BROWSERLOOP_DEBUG	false	啟用調試日誌記錄到 /tmp/browserloop.log
BROWSERLOOP_ENABLE_METRICS	true	啟用錯誤指標收集
BROWSERLOOP_DISABLE_FILE_WATCHING	false	禁用自動 Cookie 文件監控

調試日誌記錄

當 BROWSERLOOP_DEBUG=true 時，詳細日誌將寫入 /tmp/browserloop.log，包括：

• Cookie 文件加載和自動刷新事件
• 文件監控狀態和重新創建事件
• 截圖操作詳細信息
• 配置更改和錯誤

實時監控日誌：

tail -f /tmp/browserloop.log

注意： 日誌寫入文件（而非控制檯），以保持與 MCP 的標準輸入輸出協議的兼容性。

示例 MCP 配置（使用默認 Cookie）

方法 1：JSON 文件（推薦）

創建一個 Cookie 文件：

// ~/.config/browserloop/cookies.json
[
  {
    "name": "connect.sid",
    "value": "s:your-dev-session.signature",
    "domain": "localhost"
  }
]

在 MCP 配置中引用：

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "/home/username/.config/browserloop/cookies.json",
        "BROWSERLOOP_DEFAULT_FORMAT": "webp",
        "BROWSERLOOP_DEFAULT_QUALITY": "85"
      }
    }
  }
}

方法 2：JSON 字符串（舊方法）

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "[{\"name\":\"session_id\",\"value\":\"your_session_value\",\"domain\":\"example.com\"},{\"name\":\"auth_token\",\"value\":\"your_auth_token\"}]",
        "BROWSERLOOP_DEFAULT_FORMAT": "webp",
        "BROWSERLOOP_DEFAULT_QUALITY": "85"
      }
    }
  }
}

控制檯日誌配置示例

# 僅捕獲警告和錯誤
BROWSERLOOP_CONSOLE_LOG_LEVELS="warn,error"

# 調試模式，記錄所有日誌，不進行清理
BROWSERLOOP_DEBUG="true"
BROWSERLOOP_SANITIZE_LOGS="false"
BROWSERLOOP_CONSOLE_LOG_LEVELS="log,info,warn,error,debug"

🔍 故障排除

常見問題

“可執行文件不存在”錯誤

# 安裝 Chromium 瀏覽器（最常見的修復方法）
npx playwright install chromium

MCP 服務器無法啟動

1. 手動測試：npx browserloop@latest --version
2. 驗證要求：
   • Node.js 20+：node --version
   • npm：npm --version
   • npx：npx --version
3. 檢查 MCP 配置 JSON 語法

截圖顯示登錄頁面

• 使用基於 Cookie 的身份驗證（請參閱 Cookie 身份驗證指南）
• 檢查 Cookie 過期時間和域名設置

控制檯日誌為空

• 一些生產網站沒有控制檯輸出（這是正常的）
• 使用有控制檯活動的開發網站進行測試
• 啟用調試日誌：BROWSERLOOP_DEBUG=true，並檢查 /tmp/browserloop.log
• 檢查日誌級別過濾：BROWSERLOOP_CONSOLE_LOG_LEVELS=log,info,warn,error,debug

控制檯日誌收集時間

• 收集總是在頁面加載後精確等待 3 秒
• BROWSERLOOP_CONSOLE_TIMEOUT 控制頁面加載超時時間，而非日誌收集時間
• 快速網站總共仍需要約 3 - 4 秒（加載 + 3 秒收集 + 處理）

網絡/連接問題

• 首先使用外部 URL 進行測試：https://example.com
• 對於本地主機：確保你的開發服務器正在運行
• 檢查防火牆設置

更新 BrowserLoop

• NPX：使用 @latest 自動使用最新版本，無需手動更新！
• 檢查當前版本：npx browserloop@latest --version

快速診斷

# 測試完整設置
node --version && npm --version
npx playwright --version

# 測試 BrowserLoop
npx browserloop@latest --version

啟用調試日誌： 在你的 MCP 配置中設置 BROWSERLOOP_DEBUG=true，並監控 /tmp/browserloop.log 📖 有關詳細的故障排除信息，請參閱 docs/API.md#error-handling。

📄 許可證

BrowserLoop 採用 GNU Affero 通用公共許可證 v3.0 或更高版本（AGPL - 3.0 - or - later） 進行許可。

這意味著：

• ✅ 免費使用 - 允許個人和商業使用
• ✅ 免費修改 - 你可以根據需要調整代碼
• ✅ 免費分發 - 可以與他人共享副本
• ✅ 專利保護 - 貢獻者提供專利授權
• ⚠️ Copyleft - 衍生作品也必須在 AGPL - 3.0 下開源
• ⚠️ 網絡條款 - 如果你在服務器上運行修改後的版本，必須向用戶提供源代碼

對於網絡服務

重要提示： 如果你修改了 BrowserLoop 並將其作為網絡服務運行（例如，Web 應用程序、API 服務器或雲服務），AGPL 要求你：

1. 向服務的所有用戶提供完整的源代碼
2. 顯著通知用戶如何訪問源代碼
3. 對整個服務使用兼容的許可證

許可證文件

• LICENSE - 完整的許可證文本

商業使用

組織可以在 AGPL 許可下將 BrowserLoop 用於商業目的，但必須遵守 Copyleft 要求。如果你需要保留修改的隱私性，可以考慮：

1. 使用未修改的 BrowserLoop
2. 將改進貢獻回社區
3. 聯繫維護者瞭解潛在的替代許可安排 有關許可問題，請打開一個問題或聯繫維護者。