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. 联系维护者了解潜在的替代许可安排 有关许可问题，请打开一个问题或联系维护者。