BrowserLoop

BrowserLoop

⚠️ 已归档： 此项目已归档，不会再收到任何更新。随着 Chrome DevTools MCP 发布，它提供了更全面的浏览器交互功能，包括屏幕截图、控制台监控等，因此已不再需要专门用于浏览器自动化的 MCP 服务。

一个使用 Playwright 对网页截图并读取控制台日志的模型上下文协议（MCP）服务。此工具可让 AI Agent 自动捕获屏幕截图并监控浏览器控制台输出，用于调试、测试和开发任务。

注意： 此仓库中的几乎所有代码都是自动生成的。这意味着你可能不应过于信任它。不过，它确实能用，而且我自己也在使用。

注意： 如果文档有误，请告知我或提交 PR。如果你也想使用代码生成工具来更新此项目的代码，可以将 PROJECT_CONTEXT.md 用作上下文，以全面了解项目的各个部分。它现在可能有点杂乱，但仍是一个不错的起点，欢迎你更新它。

功能

• 📸 使用 Playwright 捕获高质量屏幕截图
• 📝 监控并收集网页控制台日志
• 🌐 支持 localhost 和远程 URL
• 🍪 使用 Cookie 对受保护的页面进行身份验证
• 🐳 使用 Docker 容器化，确保环境一致
• ⚡ 支持 PNG、JPEG 和 WebP 格式，可配置质量
• 🛡️ 以非 root 用户安全运行容器
• 🤖 与 AI 开发工具全面集成 MCP 协议
• 🔧 可配置视口大小和捕获选项
• 📱 支持整页截图和指定元素截图
• ⚠️ 捕获浏览器警告和错误（Permissions-Policy、安全警告）
• ⚡ 使用 TypeScript 和 Biome 加速开发
• 🧪 使用 Node.js 内置测试运行器进行全面测试

快速开始

📦 NPX 用法（推荐）

最简单的上手方式——无需安装！

# Install Chromium browser (one-time setup)
npx playwright install chromium

# Test that BrowserLoop works
npx browserloop@latest --version

就这样！ BrowserLoop 的最新版本将自动下载并运行。非常适合希望零维护地截取屏幕截图的 MCP 用户。

MCP 配置

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

{
  "mcpServers": {
    "browserloop": {
      "command": "npx",
      "args": ["-y", "browserloop@latest"],
      "description": "Screenshot and console log capture server for web pages using Playwright"
    }
  }
}

💡 使用 @latest 可确保自动获取最新功能和错误修复。

🚀 Cursor 一键安装

使用此深层链接，只需单击一次即可将 BrowserLoop 添加到 Cursor：

🔗 将 BrowserLoop 添加到 Cursor

此深层链接将使用 npx 和最新版本，以最佳配置自动在 Cursor MCP 设置中配置 BrowserLoop。

前置条件： 请先确保已安装 Chromium：

npx playwright install chromium

浏览器安装要求

🚨 重要： 必须先通过 Playwright 安装 Chromium，BrowserLoop 才能截取屏幕截图。

首次设置（所有用户）

安装 Chromium 浏览器：

npx playwright install chromium

验证安装：

# Check Playwright installation
npx playwright --version

# Test BrowserLoop (if using NPX)
npx browserloop@latest --version

🐳 Docker 替代方案

适用于容器化环境：

# Pull and run with Docker
docker run --rm --network host browserloop

# Or use docker-compose for development
git clone <repository-url>
cd browserloop
docker-compose -f docker/docker-compose.yml up

💻 开发环境安装

适用于贡献者或希望从源代码构建的高级用户：

# Clone the repository
git clone <repository-url>
cd browserloop

# Install dependencies
npm install

# Install Playwright browsers (required for screenshots)
npx playwright install chromium
# OR use the convenient script:
npm run install-browsers

# Build the project
npm run build

开发环境的 MCP 配置

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": [
        "/absolute/path/to/browserloop/dist/src/index.js"
      ],
      "description": "Screenshot and console log capture server for web pages using Playwright"
    }
  }
}

将 /absolute/path/to/browserloop/ 替换为你的实际项目路径。

基本用法

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

截图

Take a screenshot of https://example.com
Take a screenshot of https://example.com with width 1920 and height 1080
Take a screenshot of https://example.com in JPEG format with 95% quality
Take a full page screenshot of https://example.com
Take a screenshot of http://localhost:3000 to verify the UI changes

读取控制台日志

Read console logs from https://example.com
Check for console errors on https://example.com
Monitor console warnings from http://localhost:3000
Read only error and warning logs from https://example.com
Capture console output from https://example.com for debugging

🔐 Cookie 身份验证

BrowserLoop 支持基于 Cookie 的身份验证，可在开发期间截取受登录保护的页面：

Take a screenshot of http://localhost:3000/admin/dashboard using these cookies: [{"name":"connect.sid","value":"s:session-id.signature","domain":"localhost"}]

📖 如需了解 Cookie 提取方法和开发工作流，请参阅：

📖 Cookie 身份验证指南

常见开发用例：

• 带身份验证的本地开发服务器
• 暂存环境测试
• API 文档工具（Swagger、GraphQL Playground）
• 开发期间的自定义 Web 应用
• 管理面板和受保护的路由

文档

• 🔐 Cookie 身份验证指南 - 身份验证截图完整指南
• 📚 完整 API 参考 - 详细的参数文档、示例和响应格式

主要 API 参数

参数	类型	描述	默认值
url	string	要截取的目标 URL（必填）	-
width	number	视口宽度（200-4000）	1280
height	number	视口高度（200-4000）	720
format	string	图像格式（webp、png、jpeg）	webp
quality	number	图像质量（1-100）	80
fullPage	boolean	截取整个页面	false
selector	string	用于截取元素的 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]
电子邮件地址	[email protected]	[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 的标准输入输出协议兼容。

使用默认 Cookie 的 MCP 配置示例

方法 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"
      }
    }
  }
}

控制台日志配置示例

# Only capture warnings and errors
BROWSERLOOP_CONSOLE_LOG_LEVELS="warn,error"

# Debug mode with all logs, no sanitization
BROWSERLOOP_DEBUG="true"
BROWSERLOOP_SANITIZE_LOGS="false"
BROWSERLOOP_CONSOLE_LOG_LEVELS="log,info,warn,error,debug"

故障排除

常见问题

“Executable doesn't exist”错误

# Install Chromium browser (most common fix)
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 Authentication Guide）
• 检查 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
• 对于 localhost：确保开发服务正在运行
• 检查防火墙设置

更新 BrowserLoop

• NPX：使用 @latest 自动获取最新版本，无需手动更新！
• 检查当前版本：npx browserloop@latest --version

快速诊断

# Test complete setup
node --version && npm --version
npx playwright --version

# Test BrowserLoop
npx browserloop@latest --version

启用调试日志： 在 MCP 配置中设置 BROWSERLOOP_DEBUG=true，并监控 /tmp/browserloop.log

📖 详细故障排除说明，请参阅 docs/API.md#error-handling。

许可证

BrowserLoop 根据 GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later) 授权。

这意味着：

• ✅ 免费使用 - 允许个人和商业用途
• ✅ 免费修改 - 可以根据需要调整代码
• ✅ 免费分发 - 与他人分享副本
• ✅ 专利保护 - 贡献者授予专利许可
• ⚠️ 著佐权 - 衍生作品也必须依据 AGPL-3.0 开源
• ⚠️ 网络条款 - 如果在服务器上运行修改后的版本，必须向用户提供源代码

网络服务

重要提示：如果修改 BrowserLoop 并将其作为网络服务（例如 Web 应用、API 服务器或云服务）运行，AGPL 要求你：

1. 向服务的所有用户提供完整的源代码
2. 显著告知用户如何获取源代码
3. 为整个服务使用兼容的许可证

许可证文件

• LICENSE - 完整的许可证文本

商业用途

组织可以依据 AGPL 将 BrowserLoop 用于商业目的，但必须遵守著佐权要求。如果需要对修改保密，可以考虑：

1. 使用未修改的 BrowserLoop
2. 将改进贡献回社区
3. 联系维护者，了解是否有其他许可安排

如有许可相关问题，请提交 issue 或联系维护者。