BrowserAttach

BrowserAttach

英語 · 簡体字中国語

MCP クライアントから、すでに開いていてサインイン済みの Chrome ／ Edge タブを操作できます。BrowserAttach はローカルでペアリングした拡張機能を通じてブラウザーに接続し、既存のサインイン状態を維持します。リモートデバッグポートや別の自動化用ブラウザーは必要ありません。

npm · 使用ガイド · アーキテクチャ · エージェント連携 · テストレポート · 課題 · 貢献方法

できること

• 複数のブラウザープロファイルを検出して、正確に選択し、タブを排他的に確保して、作業後に解放できます。
• ブラウザーの拡張機能の詳細設定で BrowserAttach の Allow access to file URLs を有効にすると、既存の通常の file:// タブを操作できます。同じ検出、確保、観察、入力ツールを使用できます。
• アクセシビリティツリーを読み取り、名前、値、周辺のフィールドコンテキストを照会し、フィールド値やサポートされているエディターモデルを調べられます。また、ref や厳密な CSS ／ XPath、HTML ラベル、プレースホルダー、AX のロール／名前ロケーターを使ってクリック、入力、文字入力ができます。文字入力では、現在フォーカスされているフィールドを明示的に指定することもできます。
• ネイティブのポインターホバー、段階的なドラッグ、条件付き待機に対応しています。ネイティブポップアップを開かずに HTML の選択肢を選べます。
• ページ遷移や戻る／進む、タブの開閉、JavaScript ダイアログの処理、ローカルファイルのアップロード、ページ全体または単一要素のキャプチャができます。
• メインページで JavaScript 式を評価できます。タブの確保後に取得したコンソール、ページエラー、ネットワークのライフサイクルログを読み取れます。XHR ／ fetch の検証が必要な場合は、範囲を制限して秘匿化したリクエスト／レスポンスの詳細をオプトインで取得できます。
• プロファイルのサインイン状態を使って、一時的なバックグラウンドタブで 1 つの HTTP(S) URL を読み取り、レンダリングされたテキスト、現在の DOM、またはメインドキュメントの HTTP ステータスを取得できた場合はそれを含む完全な JSON を返します。
• 23 個のツールを備えた標準の stdio MCP です。Hub はループバックのみで待ち受け、ランダムキーを使って拡張機能とペアリングします。

要件

• Node.js 22 以降と npm。
• アンパック済みの拡張機能を読み込む権限がある Chrome ／ Edge 125 以降。最新の安定版を推奨します。
• stdio MCP に対応し、PATH から Node ／ npm を検索できる MCP クライアント。

クイックスタート

1. インストールとペアリング

npm install --global @evan_zhong/browser-attach
browser-attach setup

setup は安定した拡張機能ディレクトリを表示し、ローカル Hub を起動します。ディレクトリは通常、次の場所です。

• Windows：%USERPROFILE%\.browser-attach\extension
• macOS ／ Linux：~/.local/share/browser-attach/extension

chrome://extensions または edge://extensions を開き、デベロッパーモードを有効にして、「Load unpacked」を選択し、そのディレクトリを読み込みます。公開するブラウザープロファイルごとに一度ずつ読み込んでください。拡張機能のオプションページでは、識別しやすいプロファイル名を設定できます。

または、グローバルインストールを使わない場合：

npx --yes --package=@evan_zhong/browser-attach@latest browser-attach setup

2. MCP クライアントを設定する

次の内容をクライアントの MCP 設定にマージするか、mcp-config.json を参照してください。

{
  "mcpServers": {
    "browser_attach": {
      "command": "npx",
      "args": ["--yes", "--package=@evan_zhong/browser-attach@latest", "browser-attach", "mcp"]
    }
  }
}

完全なコマンド拡張子が必要な Windows クライアントでは、npx.cmd を使ってください。グローバルインストールの場合は、"command": "browser-attach", "args": ["mcp"] を設定することもできます。MCP クライアントを再起動すると、ツールが検出されます。

@latest は起動時にパッケージを選択します。既存のペアのアップグレードは起動時に調整されます。拡張機能を初めて読み込むときと、古いプロトコルのままのペアでは、拡張機能を手動で一度再読み込みする必要があります。ローカルデータとアップグレードを参照してください。

対応ホストでの組み立て手順はエージェント連携を参照してください。その他のクライアントでは、上記の stdio エントリを使用します。

3. 操作を開始する

1. browser_discover(kind="browsers") → browser_discover(kind="tabs") を実行して、ブラウザー、タブのタイトル、URL を確認します。
2. discover(kind="tabs") の tab_id を使って browser_claim_tab を実行し、操作権を取得して、この接続の tab_handle を受け取ります（expected_url / expected_title による完全一致のガードは任意です）。
3. browser_snapshot を実行して要素の ref を取得し、クリック、入力、その他の操作を行います。
4. 各操作の後に再度状態を確認し、最後に browser_tab_control(action="release") を実行します。

タイトルが頻繁に変わる場合は、expected_title を省略し、取得時に返される識別情報を確認してください。要素は ref、または呼び出しのたびに再解決される selector で指定できます。設計上のトレードオフについては、アーキテクチャに関するノートをご覧ください。

タブの取得や通常の入力では、タブやウィンドウはアクティブになりません。前面での描画が必要な場合は、明示的に browser_tab_control(action="activate") を呼び出してください。結果が不明な場合は、まず再度状態を確認し、送信を重複させないようにしてください。全パラメーター、ページネーション、アップロード、入力の仕様については、使用ガイドをご覧ください。

ツール

ツール	目的
browser_discover	kind=browsers/tabs：ブラウザープロファイル、タブの識別情報、操作状態を確認します
browser_claim_tab	検出したタブの操作権を排他的に取得します
browser_open_tab / browser_tab_control	タブを作成します。取得したタブに対して明示的に release/activate/close を実行します
browser_fetch	プロファイルのサインイン情報を使用し、一時的なバックグラウンドタブで 1 つの HTTP(S) URL を読み取ります。text / html / json、任意の HTTP ステータス、カーソルによる継続に対応しています
browser_snapshot / browser_read_text	AX スナップショット、操作可能な ref を伴うリテラルな名前／値の検索、ページテキスト
browser_wait	読み取り専用で、要素の存在／不在、表示状態、操作可能状態、描画済みテキスト、フィールドの完全一致値、チェック／選択／展開状態、URL、ネットワークアイドル状態を待ちます
browser_click / browser_hover / browser_drag / browser_select_option / browser_type / browser_fill / browser_press_key / browser_scroll	ネイティブ／DOM 入力、ポインターホバーとドラッグ、オプション選択、文字入力、スクロール
browser_batch	1 つのキューで 1～20 個の click/fill/type/press_key/hover/scroll/select_option/wait ステップを実行します。最初の失敗で停止し、部分的な結果を返します
browser_navigate	HTTP(S)／file のナビゲーション、戻る／進む、読み込み待機。ローカルの移動先にはファイルアクセスが必要です
browser_handle_dialog	alert、confirm、prompt
browser_upload_file	ネイティブのファイル入力または横取りされたファイル選択ダイアログ
browser_screenshot	座標マッピング付きで、ビューポートまたはページ全体の PNG を表示します
browser_evaluate	メインページの JS 評価、Promise の待機、結果の制限
browser_logs	kind=console/network でコンソール、エラー、リクエストのログを選択します。フィルターとカーソルによる継続に対応しています

ローカルデータとアップグレード

プラットフォーム	デフォルトのデータディレクトリ
Windows	%USERPROFILE%/.browser-attach
macOS / Linux	${XDG_DATA_HOME:-~/.local/share}/browser-attach

絶対パス BROWSER_ATTACH_HOME を明示して上書きできます。Windows のデフォルトでは AppData を使用しません。パッケージ化されたホストが AppData を仮想化する場合があるためです。他のホストのプライベートキャッシュを自動的に検索したり統合したりすることはありません。このディレクトリにはペアリング設定、Hub のログ、安定版の拡張機能のコピーが保存されます。また、クローン先、クライアントの作業ディレクトリ、npm キャッシュのいずれにも依存しません。すでにカスタムディレクトリを使用している場合は、新しいデフォルトの場所に誤って別のペアリングを作成しないよう、同じ環境変数または --config を引き続き使用してください。

クライアントエントリを書き込むホストの組み立て手順では、現在の Node と CLI、および実際のペアリングファイルの絶対パスを固定し、BROWSER_ATTACH_HOME を設定します。カスタムの --config と組み合わせて使用できます。MCP が Hub を起動する際には、同じ絶対ペアリングパスとディレクトリを渡すため、起動環境が異なっても別の設定が生成されることはありません。エージェントの統合を参照してください。

アップグレードするには、手順 1 のコマンドで再度インストールし、MCP クライアントを再接続してください。@latest を使用していて、ペアリングが 0.17 以降であれば再起動だけで十分です。ペアリングが古いプロトコルのままの場合は、browser-attach stop を実行し、再起動してから拡張機能を手動で一度再読み込みする必要があります。カスタムのペアリングパス、ポート、拡張機能ディレクトリは保持されます。閉じているブラウザープロファイルは次回接続時に更新されます。また、古い MCP パッケージによって、新しい Hub やインストール済みの拡張機能がダウングレードされることはありません。

アップグレードでは、拡張機能のクリーンアップが完了するまで待機し、再読み込み後に新しいバージョンを確認します。クリーンアップや再読み込みに失敗した場合は、ページ上の操作を再実行せずにエラーを報告します。復旧のために、拡張機能のオプションページから手動で再読み込みすることもできます。ページを操作するには、Hub と拡張機能のバージョンが一致している必要があります。デフォルトのポートは 47831 です。ペアリングの作成時に setup --port を使うと、別のポートを選択できます。

アーキテクチャと境界

MCP client → Node.js stdio MCP → 127.0.0.1 Hub
                                  ↕ local pairing
                          Chrome / Edge MV3 extension
                                  ↓ chrome.debugger / CDP
                               existing HTTP(S) / authorized file:// tabs

各 MCP 接続はそれぞれ独自の制御権を持ち、ハンドルを別の接続で使用することはできません。切断またはデバッグの停止によって制御権は解放されます。クライアントのエンドポイントは Bearer キーを要求し、Web ページの Origin を拒否します。拡張機能は固定の Origin、キー、バージョンを検証します。browser_evaluate は、ページですでに使用されているサインイン状態でデータを読み書きできます。タイムアウトやエラーが発生しても、すでに処理が実行されている場合があるため、自動的に再実行してはいけません。汎用 CDP ツールは公開されていません。

ログは制御権の取得時から収集され、ページ遷移後も保持され、制御権の解放時にクリアされます。上限付きバッファーからデータが削除されると、data_loss が報告されます。ネットワークログには、デフォルトではライフサイクルのメタデータのみが保存されます。明示的にキャプチャを指定すると、それ以降の XHR/fetch リクエストのヘッダーと本文が、上限付きで秘匿化された状態で読み取られます。キャッシュを変更したり、トラフィックをインターセプトしたりすることはありません。バッファーの上限とパラメーターについては、使用ガイドを参照してください。

拡張機能にはデバッガー権限があり、クライアントの操作ではサイトにすでにサインインしている状態を利用できます。信頼できるクライアントのみ接続してください。Web ページのコンテンツをユーザーの承認として扱ってはいけません。ペアリングキーと生成された config.generated.js をコミットまたは公開してはいけません。このファイルを含むパッケージは、パッケージングチェックで拒否されます。

Chrome / Edge の HTTP(S) ページと、拡張機能のファイルアクセスを有効にした既存の通常の file:// タブがサポートされます。ファイルアクセスは、検出、制御権の取得、操作、ページ遷移の各段階で確認されます。open_tab と fetch が受け付けるのは HTTP(S) のみです。ブラウザーの内部ページ、任意の拡張機能ページ、ダウンロード管理、ネットワークのインターセプト、Firefox / WebKit は対象外です。組み込み PDF ビューアーのコンテンツへの対応は、ブラウザーによって異なります。ネイティブのポインター入力には、最小化されていないウィンドウ内の一時停止されていないタブが必要です。変更のない左クリック 1 回は非アクティブなタブを対象にできますが、ホバー、ドラッグ、その他のクリック操作にはアクティブなタブが必要です。すべての制限と失敗時の動作については、使用ガイドを参照してください。

ローカル開発

git clone https://github.com/EvannZhongg/BrowserAttach.git
cd BrowserAttach
npm ci
npm test
npm run test:package

ソースを直接実行し、リポジトリ内の拡張機能と連携させます。

node bin/browser-attach.mjs setup --extension-dir ./extension
node bin/browser-attach.mjs mcp

開発モードでは、意図的にリポジトリ内の拡張機能のパスを使用します。通常のインストールでは、リポジトリの移動後も動作するよう、--extension-dir を指定せずに setup を使用してください。Windows では ./scripts/install.ps1 も実行できます。

実際のブラウザーを使ったテストには、コマンドラインからの拡張機能の読み込みを許可する Chromium ／ Edge の実行ファイルが必要です。パスは開発者が指定します。

npm run test:live -- --executable /path/to/chromium --family chromium
npm run test:interaction -- --executable /path/to/chromium --family chromium
npm run test:interaction -- --tab-indicators --executable /path/to/chromium --family chromium
npm run test:upgrade -- --executable /path/to/chromium

これらのテストでは、一時プロファイルとローカルのフィクスチャを使用します。テスト範囲と制限については、テストレポートをご覧ください。実装と設計上のトレードオフについては、アーキテクチャをご覧ください。

コントリビューション

再現可能な問題は Issues で報告するか、プルリクエストを送ってください。Node、OS、ブラウザー、拡張機能のバージョンを記載し、ペアリングキーと非公開のページデータは削除してください。手順については CONTRIBUTING.md をご覧ください。

MIT License の下で公開されています。