Browserloop

Browserloop

开发 TypeScript

🚀 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 
cd browserloop
docker-compose -f docker/docker-compose.yml up

💻 开发安装

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

# 克隆仓库
git clone 
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. 联系维护者了解潜在的替代许可安排 有关许可问题，请打开一个问题或联系维护者。
默认排序 时间排序

0 个评论

« 上一篇
Autobrowser Mcp
下一篇 »
Playwright Agent
  • 0 关注
  • 0 收藏，24 浏览
  • system 提出于 2025-10-05 02:36

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »