🚀 BrowserLoop
BrowserLoopは、Playwrightを使用してウェブページのスクリーンショットを撮影し、コンソールログを読み取るためのModel Context Protocol (MCP)サーバーです。このツールにより、AIエージェントは自動的にスクリーンショットをキャプチャし、ブラウザのコンソール出力を監視できるため、デバッグ、テスト、開発タスクに役立ちます。
⚠️ 重要提示
このリポジトリ内のほとんどのコードは自動生成されています。つまり、あまり信頼しない方が良いかもしれません。ただし、実際に動作しており、私自身も使用しています。
⚠️ 重要提示
ドキュメントが誤っている場合は、教えてください。またはPRを送ってください。このプロジェクトのコードを更新するためにコード生成ツールを使用する場合は、PROJECT_CONTEXT.mdがプロジェクトの様々な部分の概要を提供するためのコンテキストとして使用されています。現在は少し混乱しているかもしれませんが、良い出発点となりますので、更新することも歓迎します。
✨ 主な機能
- 📸 Playwrightを使用した高品質のスクリーンショットキャプチャ
- 📝 ウェブページからのコンソールログの監視と収集
- 🌐 ローカルホストとリモートURLのサポート
- 🍪 保護されたページのクッキーベースの認証
- 🐳 一貫した環境のためのDockerコンテナ化
- ⚡ PNG、JPEG、WebP形式のサポートと品質設定
- 🛡️ セキュアな非ルートコンテナ実行
- 🤖 AI開発ツールとの完全なMCPプロトコル統合
- 🔧 設定可能なビューポートサイズとキャプチャオプション
- 📱 全ページと要素特定のスクリーンショットキャプチャ
- ⚠️ ブラウザの警告とエラーのキャプチャ (Permissions-Policy、セキュリティ警告)
- ⚡ Biomeを使用したTypeScriptによる高速開発
- 🧪 Node.js組み込みテストランナーによる包括的なテスト
🚀 クイックスタート
📦 NPXを使用する (推奨)
最も簡単な開始方法 - インストール不要!
npx playwright install chromium
npx browserloop@latest --version
以上で完了です! BrowserLoopの最新バージョンが自動的にダウンロードされ、実行されます。メンテナンス不要のスクリーンショットを望むMCPユーザーに最適です。
MCPの設定
BrowserLoopをMCP設定ファイル (例: ~/.cursor/mcp.json) に追加します。
{
"mcpServers": {
"browserloop": {
"command": "npx",
"args": ["-y", "browserloop@latest"],
"description": "Playwrightを使用したウェブページのスクリーンショットとコンソールログのキャプチャサーバー"
}
}
}
💡 @latestを使用すると、常に最新の機能とバグ修正を自動的に取得できます。
🚀 Cursorへのワンクリックインストール
このディープリンクを使用して、1クリックでBrowserLoopをCursorに追加します。
🔗 BrowserLoopをCursorに追加
このディープリンクを使用すると、npxと最新バージョンを使用した最適な設定で、自動的にBrowserLoopがCursorのMCP設定に構成されます。
前提条件: 最初にChromiumをインストールしてください。
npx playwright install chromium
ブラウザのインストール要件
🚨 重要: BrowserLoopは、スクリーンショットを撮る前にPlaywrightを介してChromiumをインストールする必要があります。
初回セットアップ (すべてのユーザー)
Chromiumブラウザをインストールする:
npx playwright install chromium
インストールを確認する:
npx playwright --version
npx browserloop@latest --version
🐳 Dockerを使用する場合
コンテナ化された環境用:
docker run --rm --network host browserloop
git clone <repository-url>
cd browserloop
docker-compose -f docker/docker-compose.yml up
💻 開発用のインストール
ソースからビルドしたい貢献者または上級ユーザー向け:
git clone <repository-url>
cd browserloop
npm install
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ツールで自然言語コマンドを使用できます。
スクリーンショット
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
🔐 クッキー認証
BrowserLoopは、開発中にログイン保護されたページのスクリーンショットをキャプチャするためのクッキーベースの認証をサポートしています。
Take a screenshot of http://localhost:3000/admin/dashboard using these cookies: [{"name":"connect.sid","value":"s:session-id.signature","domain":"localhost"}]
📖 クッキーの抽出方法と開発ワークフローについては、以下を参照してください。
📖 クッキー認証ガイド
一般的な開発ユースケース:
- 認証付きのローカル開発サーバー
- ステージング環境のテスト
- APIドキュメントツール (Swagger、GraphQL Playground)
- 開発中のカスタムウェブアプリケーション
- 管理パネルと保護されたルート
📚 ドキュメント
- 🔐 クッキー認証ガイド - 認証付きスクリーンショットの完全なガイド
- 📚 完全な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 |
- |
デフォルトのクッキー (ファイルパスまたはJSON文字列) (詳細はクッキー認証ガイドを参照) |
コンソールログ設定
| 変数 |
デフォルト |
説明 |
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 |
自動クッキーファイル監視を無効にする |
デバッグログ
BROWSERLOOP_DEBUG=trueの場合、詳細なログが/tmp/browserloop.logに書き込まれます。以下の内容が含まれます。
- クッキーファイルの読み込みと自動更新イベント
- ファイル監視の状態と再作成イベント
- スクリーンショット操作の詳細
- 設定の変更とエラー
ログをリアルタイムで監視する:
tail -f /tmp/browserloop.log
注意: ログはコンソールではなくファイルに書き込まれるため、MCPのstdioプロトコルとの互換性が維持されます。
デフォルトクッキーを使用したMCP設定の例
方法1: 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"
トラブルシューティング
一般的な問題
"Executable doesn't exist"エラー
npx playwright install chromium
MCPサーバーが起動しない
- 手動でテストする:
npx browserloop@latest --version
- 要件を確認する:
- Node.js 20+ が必要:
node --version
- npmが必要:
npm --version
- npxが必要:
npx --version
- MCP設定JSONの構文を確認する
スクリーンショットにログインページが表示される
- クッキー認証を使用する (詳細はクッキー認証ガイドを参照)
- クッキーの有効期限とドメイン設定を確認する
コンソールログが空の場合
- 一部の本番ウェブサイトにはコンソール出力がない場合があります (これは正常です)
- コンソールアクティビティのある開発サイトでテストする
- デバッグログを有効にする:
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
npx browserloop@latest --version
デバッグログを有効にする:
MCP設定で BROWSERLOOP_DEBUG=true を設定し、/tmp/browserloop.log を監視します。
📖 詳細なトラブルシューティングについては、docs/API.md#error-handlingを参照してください。
📄 ライセンス
BrowserLoopは、GNU Affero General Public License v3.0以降 (AGPL-3.0-or-later) の下でライセンスされています。
これは何を意味するのか
- ✅ 無料で使用できます - 個人および商用利用が許可されています
- ✅ 自由に変更できます - コードを自分のニーズに合わせて調整できます
- ✅ 自由に配布できます - 他の人とコピーを共有できます
- ✅ 特許保護 - 貢献者は特許許諾を提供します
- ⚠️ 著作権の継承 - 派生作品もAGPL-3.0の下でオープンソースでなければなりません
- ⚠️ ネットワーク条項 - 修正版をサーバー上で実行する場合は、ユーザーにソースコードを提供しなければなりません
ネットワークサービスの場合
重要: BrowserLoopを修正し、ネットワークサービス (例: ウェブアプリ、APIサーバー、またはクラウドサービス) として実行する場合、AGPLにより以下のことが求められます。
- サービスのすべてのユーザーに完全なソースコードを提供する
- ユーザーがソースにアクセスできる方法について目立つ通知を含める
- サービス全体に互換性のあるライセンスを使用する
ライセンスファイル
商用利用
組織は、AGPLの下でBrowserLoopを商用目的で使用できますが、著作権の継承要件を遵守する必要があります。修正内容を非公開にしたい場合は、以下を検討してください。
- 修正せずにBrowserLoopを使用する
- 改善点をコミュニティに貢献する
- 代替ライセンスの取り決めについてメンテナに問い合わせる
ライセンスに関する質問は、issueを開くか、メンテナに連絡してください。