my-agent-browser

my-agent-browser

chrome-devtools-mcp MCP サーバーを介した AI エージェント向けブラウザー自動化。

リリース 1.2.0。chrome-devtools-mcp 1.11.0 でテスト済みです。Node 24 LTS を推奨します。Chrome を起動せずに、インストール済みのラッパーを確認します。

node <skill-dir>/scripts/start-mcp.js --doctor --json

レポートには、ラッパー、Node、Chrome、MCP バイナリ、設定ファイルのパスが表示されます。 ラッパーとインストール済みのスキルが異なる場合は、ブラウザーのトラブルシューティングを始める前に、このスキルを再インストールしてください。

セットアップの確認

<skill-dir> は、この SKILL.md を含むディレクトリを指します（エージェントに応じて、通常は ~/.agents/skills/my-agent-browser/ または ~/.claude/skills/my-agent-browser/ です）。

ブラウザー MCP ツール（navigate_page、take_snapshot、click、fill）がツール一覧にない場合：

1. インストールします：npm install -g [email protected]

2. 設定を作成します：

   mkdir -p ~/.config/agent-skills/my-agent-browser
   cp <skill-dir>/config.example.json ~/.config/agent-skills/my-agent-browser/config.json
   

3. エージェント／IDE に MCP サーバーを登録します。MCP サーバーのエントリーは次のとおりです：

   • 名前：browser
   • コマンド：node
   • 引数：["<skill-dir>/scripts/start-mcp.js"]（<skill-dir> を実際の絶対パスに置き換えてください）

   登録方法は環境によって異なります。MCP サーバーの設定場所については、エージェントの /help、公式ドキュメント、または設定 UI を確認してください。

4. エージェントのセッションを再起動します

基本的なワークフロー

1. list_pages または new_page { url } — pageId を取得します（ページを対象とするすべてのツールで必須です）
2. navigate_page { pageId, url } — ページに移動します（new_page を実行した直後であれば省略できます）
3. take_snapshot { pageId } — uid 参照付きでページ構造を読み取ります
4. click { pageId, uid } / fill { pageId, uid, value } / press_key { pageId, key } — 操作します
5. 再度 take_snapshot { pageId } を実行します — ページを変更するたびに uid が変わります

スナップショットの読み取り

take_snapshot はインデント付きのアクセシビリティツリーを返します：

uid=1_0 RootWebArea "Sign in" url="https://example.com/login"
  uid=1_5 heading "Sign in" level="1"
  uid=1_7 textbox "Email" focusable required
  uid=1_9 textbox "Password" required
  uid=1_12 button "Sign in"
  uid=1_14 link "Forgot password?" url="..."

各 uid=X_Y は、click、fill、hover などに渡す識別子です。

利用可能なツール

ナビゲーション

• navigate_page { pageId, url } — URL に移動します
• new_page { url } — 新しいタブを開きます（その pageId を返します）
• list_pages — すべてのタブを pageId とともに一覧表示します
• select_page { pageId } — タブにフォーカスします（以降の呼び出しで pageId を渡す必要は引き続きあります）
• close_page { pageId } — タブを閉じます

読み取り

• take_snapshot { pageId } — uid 参照付きのアクセシビリティツリー
• take_screenshot { pageId } — ページの画像をキャプチャします

操作

• click { pageId, uid } — 要素をクリックします
• fill { pageId, uid, value } — フィールドをクリアして値を入力します
• fill_form { pageId, elements: [{uid, value}] } — 複数のフィールドに入力します
• type_text { pageId, text } — 現在のフォーカス位置に入力します（クリアなし、対象指定なし）
• press_key { pageId, key } — キーを押します（Enter、Tab、Escape、ArrowDown など）
• hover { pageId, uid } — 要素にマウスカーソルを合わせます
• drag { pageId, from_uid, to_uid } — 要素間でドラッグします
• upload_file { pageId, uid, filePath } — 入力欄にファイルをアップロードします
• handle_dialog { pageId, action } — ダイアログを承認／解除します

ユーティリティ

• evaluate_script { pageId, function } — JavaScript を実行します
• wait_for { pageId, text[] } — テキストが表示されるまで待機します
• resize_page { pageId, width, height } — ビューポートのサイズを変更します

高度なツール

これらのツールグループはデフォルトで利用可能です。フラグは不要です。詳しいワークフローについては、references/advanced-tools.md を参照してください。

• パフォーマンス：performance_start_trace / performance_stop_trace / performance_analyze_insight — トレース、Core Web Vitals
• ネットワーク：list_network_requests / get_network_request — リクエスト／レスポンスを調査します
• Lighthouse：lighthouse_audit — 監査（ナビゲーション／スナップショット、デスクトップ／モバイル）
• コンソール：list_console_messages / get_console_message — ブラウザーコンソール
• エミュレーション：emulate — ネットワーク／CPU のスロットリング、位置情報、カラースキーム

設定の mcp.flags は chrome-devtools-mcp にそのまま渡されます。これを使ってツールセットを縮小（--no-categoryNetwork / --no-categoryPerformance / --no-categoryEmulation、または 3 つのツールにする --slim）したり、オプトインのグループ（ヒープスナップショット分析用の --memoryDebugging / --experimentalMemory、--categoryExtensions、座標指定の click_at 用の --experimentalVision）を追加したりできます。正式なフラグ一覧：npx [email protected] --help。

重要なルール

• 必ず pageId を渡してください — chrome-devtools-mcp では、ページにスコープされたツール（click、fill、take_snapshot、navigate_page、evaluate_script、wait_for など）に必須です。list_pages または new_page から取得してください。select_page はタブにフォーカスするだけなので、その後の呼び出しにも pageId が必要です。
• UID は一時的なものです — ページが変化するナビゲーションや操作の後は、以前の UID は無効になります。次の操作の前に、必ずもう一度 take_snapshot { pageId } を実行してください。
• 入力には fill を使ってください — 特定の要素を対象にし、最初に内容を消去します。type_text はフォーカスされている場所に入力するため、扱いにくい場合があります。
• 1 回操作したら、再読み込みしてください — 再度スナップショットを取得せずに複数の操作をまとめて実行しないでください。最初の操作で後続の UID が無効になることがあります。
• 重いページでは、ファイルベースのスナップショットを使ってください — 以下を参照してください。

重いページ（重要）

DOM ノードが多いページ（リッチテキストエディター、大きなテーブル、チャット履歴、管理ダッシュボード）で includeSnapshot: true または wait_for を使用すると、クラッシュしたりハングしたりすることがあります。

症状：ブラウザーが応答しなくなる、「target closed」、コンテンツを挿入した後にタイムアウトが繰り返される。

解決策：

1. 重いページで click、fill、hover を使う場合は、includeSnapshot: false を指定します（または省略します）
2. スナップショットをファイルに保存します：take_snapshot { pageId, filePath: "/tmp/snap.txt" }
3. 必要な部分だけを読み取ります：tail -100 /tmp/snap.txt（ダイアログ／モーダルは末尾にあります）
4. 関係のないタブを閉じます — それぞれの DOM がメモリ上に保持されます

発生が予想されるケース：コンテンツを挿入した後の WYSIWYG エディター、200 個以上の繰り返し要素があるページ、数回スクロールした後の無限スクロールページ。クラッシュしてからではなく、クラッシュする前にファイルベースのワークフローへ切り替えてください。

スクレイピングのパターン

シンプル：スナップショットで十分

ナビゲーション → wait_for { pageId, text } → take_snapshot { pageId } → アクセシビリティツリーからテキスト／リンクを直接読み取ります。構造化されたページの大半では JS は不要です。

ページネーションあり：URL ベースを優先

Next ボタンをクリックする代わりに、navigate_page { pageId, url: "...?page=N" } を繰り返し実行します。より確実で、古くなった UID を避けられ、中断後も簡単に再開できます。

動的／遅延読み込みコンテンツ

press_key { pageId, key: "End" } で遅延読み込みをトリガーし、既知のコンテンツを wait_for { pageId, text } で待ってから、take_snapshot { pageId } を実行します。

複雑な抽出：evaluate_script

アクセシビリティツリーでテーブルの行／列の関係や深くネストされたデータを取得できない場合は、JS で抽出します：

evaluate_script { pageId, function: "() => JSON.stringify([...document.querySelectorAll('tr')].map(r => [...r.cells].map(c => c.textContent.trim())))" }

ログインが必要なコンテンツ

オプション A：永続プロファイル — headless: false で一度ログインし、その後 userDataDir を再利用します。 オプション B：自動化 — fill + click + wait_for で認証情報を入力します。 オプション C：既存のセッションに接続 — 設定で browserUrl を指定します。

複数タブのパターン

• new_page { url } はタブを開いてその pageId を返します。以降の呼び出しではその pageId を使い、推測しないでください
• 呼び出しごとに対象タブの pageId を渡してください。select_page はフォーカスを移す、または前面に表示する場合にのみ使用します
• 「新しいタブで開く、抽出する、閉じる、元に戻る」というパターンを使うと、一覧ページでの表示位置を失わずに済みます
• 各タブは独立しています。スナップショット、UID、ページ状態はタブ間で共有されません

JavaScript 実行のヒント

• evaluate_script はブラウザのページコンテキストで実行されます（document、window、ページのライブラリを利用できます）
• 戻り値は JSON でシリアライズ可能である必要があります。オブジェクトや配列には JSON.stringify() を使用してください
• Promise を返すことができます（ポーリングや待機のパターンに便利です）
• DOM の変更は保持されます。ページを変更した後は、新しい UID を取得するためにスナップショットを再取得してください
• よくある用途：スクロール、構造化データの抽出、オーバーレイの削除、遅延読み込みの実行、計算済みスタイルの読み取り

エラーからの復旧

• クリック後に要素が見つからない → ページが変化しています。take_snapshot { pageId } を再実行して、新しい UID を探してください
• wait_for がタイムアウトする → ページに想定したコンテンツが読み込まれていません。take_snapshot { pageId } で実際の状態を確認してください
• MCP の状態が古い → ラッパーが MCP 子プロセスを置き換えて初期化します。実行中の呼び出しは明示的に失敗し、再実行されることはありません。復旧後、list_pages を実行して新しいスナップショットを取得してください。状態を変更する操作を再試行する前に、結果を確認してください
• Chrome がクラッシュした／「target closed」→ 管理対象の遅延モードでは Chrome が再起動されます。list_pages を実行してから、新しい pageId で再度移動してください
• ボット対策による検出 → まず WebGL レンダラーと接続元 IP を確認し、Chrome のフラグは後回しにしてください。references/anti-detection.md を参照してください

例：ログインフロー

1. list_pages → pageId (or new_page { url: "https://app.example.com/login" })
2. navigate_page { pageId, url: "https://app.example.com/login" }  — skip if new_page already loaded it
3. take_snapshot { pageId }
   → uid=1_7 textbox "Email", uid=1_9 textbox "Password", uid=1_12 button "Sign in"
4. fill_form { pageId, elements: [{uid: "1_7", value: "[email protected]"}, {uid: "1_9", value: "secret123"}] }
5. take_snapshot { pageId } → find the current Sign in button, e.g. uid=2_12
6. click { pageId, uid: "2_12" }
7. wait_for { pageId, text: ["Dashboard"] }
8. take_snapshot { pageId } → now on dashboard, new uids

トラブルシューティングのクイックリファレンス

問題	原因	解決策
クリック／入力しても何も起きない	古い UID	take_snapshot { pageId } を再実行し、新しい UID を使用してください
Required at pageId	pageId が省略されている	list_pages／new_page を実行し、ページを対象とするすべての呼び出しでその pageId を渡してください
スナップショットに要素がない	画面の下方／iframe／非同期	先にスクロールするか、wait_for { pageId } を実行するか、evaluate_script { pageId } で確認してください
wait_for がタイムアウトする	テキストが表示されなかった	take_snapshot { pageId } で実際の状態を確認してください
Chrome が起動しない	インストールされていない、またはポートが使用中	which google-chrome を確認し、ポートの競合を確認してください
スナップショットが空／最小限	JavaScript で描画されるコンテンツの準備ができていない	スナップショットの前に wait_for を実行してください
メモリ不足／クラッシュ	DOM が大きい	ファイルベースのスナップショットを使用してください（上記を参照）
ボット検出	通常は WebGL レンダラーまたは接続元 IP、フラグが原因となることはまれです	references/anti-detection.md を参照してください

詳細なトラブルシューティング：references/troubleshooting.md ネットワークデバッグのワークフロー：references/network-debugging.md 高度なスクレイピングのパターン：references/scraping-patterns.md

ドメイン固有のワークフロー

• 学術論文のダウンロード（CNKI、Google Scholar、MDPI）：references/domain/academic-paper-download.md

ナビゲーションとスクリプトの復旧

• navigate_page { pageId, type: "reload" } / { pageId, url } を使って更新または移動します。 location.reload() を呼び出してから処理を待機するスクリプトは、実行コンテキストを失う可能性があります。 ナビゲーションとその後の確認は、別々の呼び出しとして実行してください。
• evaluate_script.function は JavaScript の関数です。例："() => document.title"。 式だけを渡したり、(window as any) のような TypeScript 構文を使ったりしないでください。
• No page found は、list_pages で ID を再取得する必要があることを意味します。古い ID で何度も再試行しないでください。
• HTTP からデータを抽出する場合は、JSON を解析する前に status とレスポンステキストを読み取ってください。空のレスポンスと HTML のエラーページは、それぞれ別に処理する必要があります。JSON の解析エラーだけでは、要求した変更が失敗したとは判断できません。

ブラウザーの依存関係をアップグレードする場合は、テスト済みのバージョン、ランタイム要件、変更されたファイルやツールの動作について、dependency-upgrades.md をお読みください。