Browserloop

🚀 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を使用する (推奨)

最も簡単な開始方法 - インストール不要！

# 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へのワンクリックインストール

このディープリンクを使用して、1クリックでBrowserLoopをCursorに追加します。

🔗 BrowserLoopをCursorに追加

このディープリンクを使用すると、npxと最新バージョンを使用した最適な設定で、自動的にBrowserLoopがCursorのMCP設定に構成されます。

前提条件: 最初に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ツールで自然言語コマンドを使用できます。

スクリーンショット

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パラメータ

📖 完全なパラメータの詳細、使用例、および設定オプションについては、docs/API.mdを参照してください。

🔧 設定

BrowserLoopは、環境変数を使用して設定できます。

基本設定

認証設定

コンソールログ設定

注意: コンソールログの収集は、ページの読み込み後に常に正確に3秒間待機して、コンソールメッセージをキャプチャします。タイムアウト設定は、ページが最初に読み込まれるまでの時間のみに影響します。

ログのサニタイズ

コンソールログのサニタイズは、デフォルトで有効 (BROWSERLOOP_SANITIZE_LOGS=true) です。有効にすると、以下のパターンが自動的にマスクされます。

サニタイズを無効にするには (デバッグ用):

BROWSERLOOP_SANITIZE_LOGS=false

注意: サニタイズは、ログの構造を維持しながら機密コンテンツをマスクするため、ログを安全に共有して分析することができます。

パフォーマンスと信頼性

ロギングとデバッグ

デバッグログ

BROWSERLOOP_DEBUG=trueの場合、詳細なログが/tmp/browserloop.logに書き込まれます。以下の内容が含まれます。

• クッキーファイルの読み込みと自動更新イベント
• ファイル監視の状態と再作成イベント
• スクリーンショット操作の詳細
• 設定の変更とエラー

ログをリアルタイムで監視する:

tail -f /tmp/browserloop.log

注意: ログはコンソールではなくファイルに書き込まれるため、MCPのstdioプロトコルとの互換性が維持されます。

デフォルトクッキーを使用したMCP設定の例

方法1: JSONファイル (推奨)

クッキーファイルを作成します。

// ~/.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"

トラブルシューティング

一般的な問題

"Executable doesn't exist"エラー

# 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の構文を確認する

スクリーンショットにログインページが表示される

• クッキー認証を使用する (詳細はクッキー認証ガイドを参照)
• クッキーの有効期限とドメイン設定を確認する

コンソールログが空の場合

• 一部の本番ウェブサイトにはコンソール出力がない場合があります (これは正常です)
• コンソールアクティビティのある開発サイトでテストする
• デバッグログを有効にする: 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 General Public License v3.0以降 (AGPL-3.0-or-later) の下でライセンスされています。

これは何を意味するのか

• ✅ 無料で使用できます - 個人および商用利用が許可されています
• ✅ 自由に変更できます - コードを自分のニーズに合わせて調整できます
• ✅ 自由に配布できます - 他の人とコピーを共有できます
• ✅ 特許保護 - 貢献者は特許許諾を提供します
• ⚠️ 著作権の継承 - 派生作品もAGPL-3.0の下でオープンソースでなければなりません
• ⚠️ ネットワーク条項 - 修正版をサーバー上で実行する場合は、ユーザーにソースコードを提供しなければなりません

ネットワークサービスの場合

重要: BrowserLoopを修正し、ネットワークサービス (例: ウェブアプリ、APIサーバー、またはクラウドサービス) として実行する場合、AGPLにより以下のことが求められます。

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

ライセンスファイル

• LICENSE - 完全なライセンステキスト

商用利用

組織は、AGPLの下でBrowserLoopを商用目的で使用できますが、著作権の継承要件を遵守する必要があります。修正内容を非公開にしたい場合は、以下を検討してください。

1. 修正せずにBrowserLoopを使用する
2. 改善点をコミュニティに貢献する
3. 代替ライセンスの取り決めについてメンテナに問い合わせる

ライセンスに関する質問は、issueを開くか、メンテナに連絡してください。