chromium-browser

Chromium ブラウザー

共有ブラウザー内の無関係なタブや認証済みの状態に影響を与えず、設定済みの Chrome DevTools MCP を操作します。

このスキルは、共有 Chromium を通じたレンダリング済みブラウザー UI の操作、検査、自動化、検証を担います。適切な場合は、検索、フェッチ、API、CLI、コネクターを使って情報を取得してください。ブラウザー以外の UI には、ホストのネイティブアプリ用ツールを使用してください。このスキルの共有ブラウザーへのアタッチ、ページ所有権、プライバシーに関するルールを回避する目的で、ネイティブアプリ用ツールを代替手段として使用しないでください。ユーザーが別の利用可能なブラウザー統合を選択した場合は、コントローラーを混在させず、そのツールの契約に従ってください。

環境の契約

• 同梱の scripts/chrome-devtools-mcp.sh ラッパーと、現在のセッションで公開されているツールを、信頼できる情報源として扱ってください。このラッパーはグローバルにインストールされた chrome-devtools-mcp 実行ファイルを実行し、フラグ、ログ記録、ブラウザーへのアタッチを設定します。MCP パッケージを直接実行しないでください。
• MCP は、既存のリモートデバッグ用ブラウザーにアタッチします。アタッチに失敗した場合でも、代替ブラウザーを起動したり、別のプロファイルを作成したりしないでください。
• ブラウザーはユーザーとほかのエージェントが同時に使用する共有済みの認証済み環境として扱ってください。タスクに関連するページのみを確認し、無関係なタブのタイトルや内容を提示しないでください。
• 現在のツール一覧を信頼してください。ツールが存在しない場合、このセッションでは利用できません。トラブルシューティングの手段として、クライアントの MCP 設定の編集を勧めないでください。

リリース済みのツールの動作については、 上流のツールリファレンスを参照してください。 利用可能なツールとパラメーターは、現在のセッションのスキーマによって決まります。

リファレンスの参照方法

Wayback Machine のキャプチャの探索や再生の調査を行う場合は、Wayback へのリクエストを行う前に references/wayback-machine.md を読んでください。それ以外の場合は、読み込まないでください。Chromium の外部で API リクエストを順番に実行してキャプチャを探し、レンダリングされたページの確認によって証拠が得られる場合に限り、選択したリプレイを開いてください。

ページの所有権

1. 操作を始める前に list_pages を呼び出し、初期状態のページを既存のページとして維持してください。
2. 新しいページでタスクを実行できる場合は、background: true を指定した new_page を優先してください。このタスクで作成する各ページについて、返された正確な pageId を記録してください。入力操作のレスポンスに ## Opened pages が記載されている場合は、そのページ ID をこのタスクで作成したものとして記録してください。後からページ一覧を比較して所有権を推測しないでください。
3. ページを対象とするすべてのツールに、明示的な pageId を渡してください。選択中のページの状態に依存しないでください。select_page は、意図的にページを前面に表示する場合、または以下に記載する閉じたページのコンテキストを復元する場合にのみ使用してください。
4. タスクがそのページの現在の状態に明示的に依存している場合に限り、既存のページを移動または変更してください。既存のページを閉じないでください。
5. 選択中の所有ページを閉じる前に、以前に確認した、存続しているページで bringToFront: false を指定して select_page を使用してください。たとえば、このタスクでページを開く前に選択されていたページを使用します。その後、所有するページの ID を指定して close_page を実行してください。閉じる操作が「トラブルシューティング」に記載された閉じたページのエラーを返した場合は、成功した可能性が高いものとして扱い、復元手順を使って一度だけ確認してください。閉じる操作を再試行しないでください。
6. 完了時には、ユーザーがページを開いたままにするよう求めていない限り、このタスクで作成したものとして記録したページのみを閉じてください。

操作と証拠

• 1つのページでは、まず移動します。利用可能な既知のシグナルを待ち、新しいスナップショットを取得します。その後、そのスナップショットに含まれる識別子を使って操作します。移動後、または DOM に意味のある変更があった後は、スナップショットを更新します。
• 構造の確認と自動化には take_snapshot、視覚的な証拠には take_screenshot、アクセシビリティツリーに含まれない情報には evaluate_script を優先して使用します。公開されている場合、ページの状態を変更せずにデータを読み取るスクリプトに限り、waitForStableDom: false を使用します。
• 複数の入力欄、選択欄、チェックボックス、ラジオボタンをまとめて操作する場合は、fill_form を優先して使用します。upload_file では、ブラウザーホスト上にあり、タスクで使用が許可されたファイルを使い、現在の filePaths 配列スキーマに従います。
• CSS のカスケードに関する質問には、新しいスナップショットの UID を使って get_css_styles を使用します。追加の一致ルールや継承ルールを確認するには、pageIdx と pageSize でページネーションします。
• スクリーンショットのラッパーのデフォルト設定を使用します。可逆出力が必要な場合は、format: "png" を指定します。PNG、fullPage、filePath を使っても、ラッパーの幅と高さの上限である 1600 ピクセルは回避できません。全解像度での出力には、許可されたラッパー設定の変更が必要です。
• アクションの応答は小さく保ちます。更新後の状態をすぐに確認する必要がない限り、click と fill では includeSnapshot: false を設定します。includeSnapshot は、これを受け付けない navigate_page に渡さないでください。アクション応答にスナップショットを含めると、コンテキストが約 10 KB 増えることがあります。
• すべての evaluate_script の戻り値を、要約、件数、または最大で約 50 件に制限します。DOM 全体、HTML ドキュメント全体、または大きな配列を返さないでください。
• コンソール、ネットワーク、メモリなど、件数の多い結果はページネーションして絞り込みます。
• resize_page の前に、ウィンドウが通常の状態であることを確認します。最大化または全画面表示のウィンドウでは、Restore window to normal state before setting content size が返されます。このエラーが発生した場合、セッションで使用できるなら viewport を指定して emulate を使用します。それ以外の場合は、サイズ変更をスキップしてユーザーに伝えます。
• Cookie の同意ポップアップが表示された場合は、設定が必要なときも含め、デフォルトで必要な Cookie または必須 Cookie のみを選択します。そのような選択肢がない場合は、すべての Cookie を受け入れて続行します。
• スクリーンショット、スナップショット、トレース、録画、レスポンス本文、大きなスクリプト結果には filePath を使用します。タスクで使用が許可された絶対パスにのみ書き込みます。現在のリポジトリ内の Git で無視される .ai/ ディレクトリ、またはクライアントと合意した別のルートを優先します。Claude Code の /private/tmp 下のスクラッチパッドと /tmp ディレクトリは、許可されたルートではありません。そこへの書き込みは Access denied を返します。このエラーが発生した場合は、<cwd>/.ai/ の下で一度だけ再試行します。パス機能があるからといって、書き込みが許可されているとは限りません。
• 同じ MCP サーバー内の呼び出しは、明示的なページルーティングを指定していても直列化されます。別々のエージェントサーバーもブラウザーの状態を共有します。並行作業では、因果関係の順序とページの所有権を保ちます。

人間による確認

人間による確認とは、CAPTCHA、ログイン、2FA プロンプト、電話番号認証、または外部承認ページのことです。外部承認ページの例として、npm trusted-publisher のプロンプトがあります。人間による確認の段階でターンを終了するのは、早すぎる中断です。

1. 確認が求められているページでの書き込み操作をすべて停止してください。確認を回避しようとしてはいけません。
2. 該当するページと、確認のために必要な操作を正確にユーザーに伝えてください。
3. ユーザーが別の応答時間を指定しない限り、合計で 10 分間待機してください。確認が求められている pageId に対して、timeout が 10000 以下となる wait_for 呼び出しを順番に実行します。確認が完了した後にのみ表示されるテキストを照合してください。例として、ログイン後の見出しや次のフォームラベルがあります。特徴的なテキストがない場合は、短く中断可能なホスト側の待機を挟んでスナップショットを取得してください。未完了の wait_for の後ろに、別のブラウザー呼び出しをキューに入れてはいけません。ホスト側の待機をキャンセルしても、MCP 呼び出しが停止したことにはなりません。
4. ユーザーから返信があったら、再び待機する前に最新のスナップショットを取得してください。確認が完了しても、フォームが別の操作を待っている場合があります。確認が完了したら、同じページ状態から作業を再開してください。サイトによってはフォームの値が消去されるため、まずフォームのフィールドを再確認してください。
5. 合計応答時間が経過してからターンを終了してください。その後、ユーザーが完了させる必要のある正確な手順と、タスクを再開する手順を報告してください。

監査とプロファイリング

現在のセッションでツールが公開されている場合にのみ、これらのワークフローを使用してください。

• Lighthouse 監査では、現在のページ状態を分析するために mode: "snapshot" を選択してください。mode: "navigation" はページを再読み込みします。Lighthouse にはパフォーマンス監査が含まれません。パフォーマンスに関する質問には、パフォーマンストレースを使用してください。
• performance_start_trace の前にページを移動してください。再読み込みせずに操作をプロファイリングするには、reload: false を設定してください。reload: true の場合、キャッシュのない状態で読み込むために ignoreCache: true を設定してください。autoStop: false の場合、失敗したタスク後のクリーンアップ中も含め、測定対象の操作が終わったら performance_stop_trace でトレースを停止してください。このタスクで開始したトレースのみを停止してください。
• ヒープ分析では、take_heapsnapshot でスナップショットを取得してから、get_heapsnapshot_summary を開始してください。オブジェクトやリテイナーのクエリには、対象を絞ったページネーション付きのクエリを使用してください。2 つのスナップショット間の増加には compare_heapsnapshots を、解放済みのキャプチャ値を保持しているクロージャーには analyze_heapsnapshot_contexts を使用してください。このタスクで読み込んだ各スナップショットについて、失敗したタスク後のクリーンアップ中も含め、close_heapsnapshot を呼び出してサーバーのメモリを解放してください。
• 各サーバーで有効にできるスクリーンキャストは 1 つです。このタスクでスクリーンキャストを開始したかどうかを記録し、クリーンアップ時に screencast_stop を呼び出してください。別のタスクの録画を止めて空きを作ってはいけません。

権限とプライバシー

• タスクに必要な認証済み状態の読み取り専用の確認は許可されています。フォームの送信、アカウントの変更、拡張機能のインストール、購入、またはその他の外部への変更を引き起こす操作には、ブラウザーの外部で同じ操作を行う場合と同等の権限が必要です。
• ネットワークヘッダーの秘匿化は、サーバー側で意図的に設けられた境界です。これを回避したり、ページやプロセスのイントロスペクションを通じて認証情報を探したりしてはいけません。

トラブルシューティング

• 所有するページを閉じたときに The selected page has been closed が返され、list_pages でも同じエラーが繰り返される場合は、ページを閉じる操作は成功したものの、MCP が古い選択状態を保持している可能性があります。以前に確認した、まだ存在するページを bringToFront: false で選択してから、list_pages を呼び出し、所有するページ ID が存在しないことを確認します。この復旧操作は、MCP のコンテキストの修復だけを試みます。

  存在するページへの移動、調査、終了は行わないでください。結果から無関係なタイトルとコンテンツを除外してください。選択状態を復旧するために、ページを再度閉じたり、別のタブを作成したりしないでください。

• select_page でも同じページ終了エラーが返される場合は、MCP の復旧操作を中止し、セッションのコンテキストが古くなっていることを報告してください。設定済みのデバッグエンドポイントへの読み取り専用の /json/list リクエストを使うと、タスクページの既知の一意で変更されていない URL が存在しないことを確認できます。ローカルでフィルタリングし、その結果だけを返してください。無関係なターゲットは決して返さないでください。これはページ終了の証拠であり、MCP の復旧でも、別の経路からブラウザーを操作する許可でもありません。MCP の pageId 値は CDP ターゲット ID ではありません。

  所有するページを確実に特定できない場合は、クリーンアップを確認できなかったと報告してください。エンドポイントの一覧から所有権を推測したり、その一覧を使ってタブを閉じたりしないでください。

• 接続またはトランスポートに失敗した場合は、ブラウザーのエンドポイントと MCP プロセスを区別してください。まず、デバッグエンドポイント http://127.0.0.1:${PRB_AGENT_CHROMIUM_PORT:-9222}/json/version を確認します。次に、$XDG_CACHE_HOME/chrome-devtools-mcp/logs/ のプロセスごとの最新ログを調べます。変数が設定されていない場合は、~/.cache/chrome-devtools-mcp/logs/ を確認してください。

• エンドポイントが応答することから確認できるのは、ブラウザープロセスが稼働中であることだけで、レンダラーを起動できることまでは確認できません。new_page がタイムアウトし、タブにクラッシュアイコンまたは Untitled が表示される場合は、作成を繰り返さず、MCP のトランスポート状態とは別にブラウザーの状態を確認してください。作成に失敗すると、pageId が返されないままタブが残ることがあります。後から表示されたページ一覧をもとに所有権を推測したり、特定できないタブを閉じたりしないでください。

• macOS の Homebrew で Chromium をアップグレードした後は、エンドポイントの Browser バージョンと plutil -extract CFBundleShortVersionString raw /Applications/Chromium.app/Contents/Info.plist の出力を比較してください。実行中のプロセスがそのアプリバンドルを使っていることを確認し、起動時刻とバージョン付きのフレームワーク／ヘルパーのパスを調べてください。Homebrew がバンドルを置き換えても、古いプロセスが動き続けることがあります。その結果、新しいレンダラーに必要なヘルパーが削除される場合があります。既存のページや /json/version は引き続き利用できることがあります。バージョンの不一致だけでは、障害の証明にはならず、手がかりにとどまります。

• 失敗したレイヤーと証拠を報告してください。その設定に関する作業の許可なしに、クライアント設定やラッパーのフラグを変更しないでください。通常のブラウジング中やラッパーから、共有ブラウザーを自動的に再起動しないでください。

  ブラウザーの修復を明示的に依頼された場合は、同じプロファイルとデバッグポートを使って、正常な方法で再起動してかまいません。まず、それらの引数を記録してください。セッションを保持してください。chrome://restart は、セッションを復元する再起動を要求します。アップグレード後に古いプロセスが終了しても再起動できない場合は、プロセスの終了を確認してから、記録したプロファイル／ポート引数と --restore-last-session を指定して、インストール済みの実行ファイルを再度開いてください。代替プロファイルは決して使用しないでください。未保存の作業に関する確認には従ってください。

  ライブバージョンを再確認してください。list_pages を呼び出して、新しい ID を取得してください。既存のページが復元されたことを確認してください。所有するページで作成と移動をテストしてから、そのページを閉じてください。

• 要求された機能が利用できない場合は、現在のツール一覧とラッパー設定を確認してから、その制約を報告してください。設定済みのプライバシーや並行処理のデフォルトを損なう代替策を考案しないでください。

完了とするには、要求された結果を示す最新のツール証拠と、タスクで作成したページが閉じられたか、意図的に開いたままにされたことの確認が必要です。