BrowserLoop

BrowserLoop

⚠️ アーカイブ済み： このプロジェクトはアーカイブされており、今後更新される予定はありません。Chrome DevTools MCP のリリースにより、ブラウザー自動化専用の MCP サーバーは不要になりました。このプロジェクトでは、スクリーンショットやコンソール監視など、より包括的なブラウザー操作機能が提供されるためです。

Playwright を使用してウェブページのスクリーンショットを撮影し、コンソールログを読み取るための Model Context Protocol（MCP）サーバーです。このツールを使うと、AI エージェントがデバッグ、テスト、開発タスクのためにスクリーンショットを自動で撮影し、ブラウザーのコンソール出力を監視できます。

注： このリポジトリのコードのほぼすべては自動生成されています。そのため、あまり信用しすぎないほうがよいでしょう。とはいえ、実際に動作しており、私自身も使っています。

注： ドキュメントに誤りがあれば、お知らせいただくか、PR をお送りください。このプロジェクトのコード更新にコード生成ツールを使いたい場合は、プロジェクトの各部分について概要を把握できるよう、コンテキストとして PROJECT_CONTEXT.md を使用しています。現在は少しまとまりがないかもしれませんが、出発点として役立ちますので、ぜひ更新してください。

特長

• 📸 Playwright を使用した高品質なスクリーンショット撮影
• 📝 ウェブページのコンソールログの監視と収集
• 🌐 localhost とリモート URL に対応
• 🍪 保護されたページでの Cookie ベース認証
• 🐳 一貫した環境を実現する Docker コンテナ化
• ⚡ 品質を設定できる PNG、JPEG、WebP 形式に対応
• 🛡️ コンテナを非 root ユーザーで安全に実行
• 🤖 AI 開発ツールとの MCP プロトコル完全統合
• 🔧 ビューポートサイズと撮影オプションを設定可能
• 📱 ページ全体および特定の要素のスクリーンショット撮影
• ⚠️ ブラウザーの警告とエラーをキャプチャ（Permissions-Policy、セキュリティ警告）
• ⚡ 高速な開発を実現する、Biome を使用した TypeScript
• 🧪 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

ブラウザーのインストール要件

🚨 重要： BrowserLoop でスクリーンショットを撮影するには、事前に Playwright 経由で Chromium をインストールする必要があります。

初回セットアップ（すべてのユーザー）

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	-	ファイルパスまたは JSON 文字列として指定するデフォルトの Cookie（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 の stdio プロトコルとの互換性を保つため、ログはコンソールではなくファイルに書き込まれます。

デフォルト 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 認証ガイドを参照）
• Cookie の有効期限とドメイン設定を確認します

コンソールログが空

• 本番環境の Web サイトにはコンソール出力がない場合があります（これは正常です）
• コンソールに出力がある開発用サイトでテストします
• デバッグログを有効にします：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 を変更してネットワークサービス（例：ウェブアプリ、API サーバー、クラウドサービス）として実行する場合、AGPL により次のことが求められます。

1. サービスのすべてのユーザーに完全なソースコードを提供する
2. ユーザーがソースにアクセスする方法を目立つ形で告知する
3. サービス全体に互換性のあるライセンスを適用する

ライセンスファイル

• LICENSE - ライセンス全文

商用利用

組織は BrowserLoop を AGPL の下で商用目的に利用できますが、コピーレフト要件を遵守する必要があります。変更を非公開にする必要がある場合は、次の方法を検討してください。

1. BrowserLoop を変更せずに使用する
2. 改善点をコミュニティに還元する
3. 代替ライセンスの可能性についてメンテナーに問い合わせる

ライセンスに関する質問は、issue を作成するか、メンテナーにお問い合わせください。