exploring-browser

ブラウザー探索スキル

リアルタイムの探索とフロー記録に対応した、インタラクティブなブラウザー自動化です。robomotion-browser-mcp サーバーによって提供されます。

組み合わせて使うもの： reversing-network — ネットワークトラフィックを取得したら、クリーンな API が公開されている場合は、ブラウザー自動化から HTTP に切り替えます。

概要

このスキルでは、ブラウザーを使ったペアプログラミングができます。あなたと Claude が一緒にウェブサイトを探索し、セレクターを見つけて、自動化フローを作成します。最後に、Robomotion SDK TypeScript に直接対応するJSON フローシーケンスが生成されます。

ワークフロー

ステップ 0 — ツールスキーマを読み込みます。 Claude Code では、mcp__browser__* ツールは遅延読み込みされます（スキーマを読み込むまでは、カタログに名前だけが表示されます）。準備なしに browser_open を呼び出すと、stdio 経由で空または不正な JSON が送信され、robomotion-browser-mcp がクラッシュします。その結果、セッション終了まで、すべてのブラウザーツールがブラックリストに登録されます。claude mcp list では ✓ Connected と表示されていても、以降 ToolSearch は「該当する遅延読み込みツールがありません」と返します（これは新しいプローブの結果であり、セッション内のパイプはすでに切断されています）。最初の呼び出しの前に、次を実行してください。

ToolSearch query="select:mcp__browser__browser_open,mcp__browser__browser_navigate,mcp__browser__browser_snapshot,mcp__browser__browser_type,mcp__browser__browser_click,mcp__browser__browser_close,mcp__browser__browser_get_sequence,mcp__browser__browser_set_flow_name"

（必要に応じて、browser_wait、browser_select、browser_query、browser_start_network_capture なども追加してください。）サーバーが切断された後に復旧するには、Claude Code を再起動するしかありません。セッション内から接続を再アタッチすることはできません。他のランタイムを使用するエージェントは、それぞれの MCP 呼び出し方式に置き換えてください。

1. ブラウザーを開く — browser_open で起動します（デフォルトでステルスモードが有効です）。
2. 移動する — browser_navigate で対象の URL に移動します。
3. スナップショットを取得する — browser_snapshot を使って、ref 付きのページ構造を確認します（主な探索ツールです）。
4. 操作する — スナップショットの ref を使います。例：browser_click @e3、browser_type @e5（XPath とともに自動記録されます）。
5. スナップショットを再取得する — クリックや移動などでページが変わった後は、新しいスナップショットを取得します。
6. ブラウザーを閉じる — 探索が完了したら、必ず browser_close を呼び出してください。フローシーケンスの JSON が返され、ブラウザーが解放されます。
7. ユーザーに確認する — プラン／シーケンスを提示し、AskUserQuestion を使ってフローの作成に進むかどうかを尋ねます。
8. 変換する — ユーザーの承認後に限り、JSON を robomotion-sdk 用の TypeScript に変換します。

重要： すべての探索ステップが完了したら、必ずブラウザーを閉じてください（browser_close）。コードの作成や変更中にブラウザーを開いたままにしないでください。また、フローコードの作成や変更に進む前に、必ず AskUserQuestion でユーザーに確認してください。

探索は読み取り専用です

探索中、サイトは利用者が実際に使っているシステムです。内容を読むだけにし、変更は加えないでください。

• データを変更するボタンは決してクリックしないでください。統合、承認、拒否、削除、取り除く、支払い、送信、公開、アーカイブ、転送、確定が該当します。こうしたボタンの数を確認し、ラベルと隣の行を読み取ったら、そこで停止してください。
• ダイアログを開くことは、ほかの操作をする前にキャンセルボタンで閉じる場合に限り問題ありません。クリックすると同時に確定される場合は、クリックしないでください。
• 変更操作そのものはフローに含めます。ステップを作成し、利用者がフローを実行したときにロボットが操作するようにしてください。求められているのは、あなたではなくロボットによるクリックです。
• そのようなボタンを押した後の動作（確認ページや次の状態）を確認する必要がある場合は、クリックする前に AskUserQuestion で利用者に確認し、データが変更されることを明確に伝えてください。そのようなスクリプトを browser_eval は拒否し、該当する操作名が付いた要素のスナップショット ref を browser_click に渡した場合も拒否します。利用者の許可を得た後、confirmSideEffect: true を付けてもう一度呼び出してください。
• 誤って何かを変更してしまった場合は、ほかのことをする前に、同じターン内で何が変更されたかを利用者に伝えてください。

主な概念

スナップショット優先の探索（必須）

新しい URL またはページに切り替わるたびに、最初のアクションとして必ず browser_snapshot を実行してください。 これは必須です。スナップショットの使用トークン数は約 50〜100 トークンで、スクリーンショットの約 500〜2000 トークンと比べて少なくて済みます。

GOOD: browser_navigate → browser_snapshot → read tree → browser_click @e3
BAD:  browser_navigate → browser_screenshot → browser_query → browser_query → ...
BAD:  browser_navigate → browser_query → browser_query → browser_query → ...

ルール：

• ナビゲーションの後（browser_navigate、新しいページを読み込む browser_click、browser_reload、browser_go_back）に行う最初の呼び出しは、必ず browser_snapshot にしてください
• スナップショットの ref（@e1、@e2 など）をアクションツールのセレクターとして使用してください
• ページが切り替わるアクション（クリック、フォーム送信）の後は、すぐに新しいスナップショットを取得してください
• ページの探索に browser_screenshot を使用しないでください。使用トークン数が 10〜40 倍になります。スナップショットの ref だけでは先に進めず、行き詰まった場合（例：視覚的なレイアウトの問題、画像の確認）に限り、最後の手段として使用してください
• ページの探索に browser_query を使用しないでください。スナップショットにはインタラクティブな要素がすべて表示されます。特定のセレクターを対象にした確認に限り使用してください
• ページを「探索」するために、browser_query を連続して複数回呼び出すことは絶対にしないでください。そのためにスナップショットがあります

ref — 軽量な要素参照

スナップショットでは、インタラクティブな要素に @e1、@e2 などの ref が割り当てられます。これらの ref は、すべてのアクションツールのセレクターとして機能します。

browser_click selector=@e3          → clicks the element, records its XPath
browser_type selector=@e5 text=hello → types into the element, records its XPath

ref は一時的なもので、ナビゲーション、再読み込み、または戻る操作で無効になります。ページが切り替わった後は、新しいスナップショットを取得して新しい ref を取得してください。

記録には ref ではなく、解決済みの XPath/CSS セレクターが常に保存されます。これにより、RPA ロボットは安定したセレクターを取得できます。

探索モード

• explore=true（クエリのデフォルト）：アクションを記録せず、探索のみを行います
• explore=false（アクションのデフォルト）：フローシーケンスにアクションを記録します

ツールの種類	explore のデフォルト	動作
スナップショット（browser_snapshot）	—	探索のみ（記録されません）
クエリ（browser_query、browser_get_text）	true	探索のみ。記録されません
アクション（browser_click、browser_type）	false	フローに記録されます
ナビゲーション（browser_navigate）	false	フローに記録されます
スクリーンショット	true	デフォルトでは記録されません

セレクター

ref（推奨）、XPath、または CSS セレクターを使用してください。

# Refs (from browser_snapshot) — PREFERRED
@e1, @e2, @e3

# XPath examples
//button[@id='submit']
//input[@name='email']

# CSS examples
#submit
input[name='email']

利用可能なツール

ライフサイクル

• browser_open - ブラウザーを起動します（ユーザーが見られるように headless: false を指定します。ステルス機能、ビューポートオプション）
• browser_close - ブラウザーを閉じ、フローシーケンスの JSON を返します

ナビゲーション

• browser_navigate - URL に移動します
• browser_reload - ページを再読み込みします
• browser_go_back - 前のページに戻ります

探索

• browser_snapshot - 必ず最初に使用してください — ref（@e1、@e2 など）を含むアクセシビリティツリーです。ナビゲーションのたびに必須です。
• browser_screenshot - 最後の手段としてのみ使用してください — 画面をキャプチャします。行き詰まり、スナップショットの ref では不十分な場合に限り使用してください。
• browser_query - 対象要素を確認します（スナップショットにすでにすべて表示されるため、使用は控えてください）
• browser_get_text - 要素のテキストコンテンツを取得します
• browser_get_value - 入力値を取得します
• browser_get_attr - 属性値を取得します

アクション（自動記録）

• browser_click - 要素をクリックします
• browser_type - 入力欄に入力します
• browser_select - ドロップダウンのオプションを選択します
• browser_wait - 要素が表示されるまで待機します
• browser_scroll - 要素までスクロールします
• browser_hover - 要素にマウスカーソルを合わせます

コンテキスト

• browser_switch_iframe - iframe に切り替えます
• browser_switch_main - メインページに戻ります

セッション

• browser_get_sequence - 現在の JSON シーケンスを取得します
• browser_clear_sequence - 新しいシーケンスを開始します
• browser_set_flow_name - フローに名前を付けます

Cookie

• browser_get_cookies - Cookie を取得します（ドメインによる絞り込みは任意）
• browser_set_cookie - 1 つの Cookie を設定します
• browser_set_cookies - 複数の Cookie を設定します
• browser_clear_cookies - Cookie を削除します（ドメインの指定は任意）

ネットワークキャプチャ（API の検出）

• browser_start_network_capture - リクエスト／レスポンスのキャプチャを開始します
• browser_get_requests - キャプチャしたリクエストを取得します（メソッド／URLで絞り込み）
• browser_get_responses - キャプチャしたレスポンスを取得します（ステータス／URLで絞り込み）
• browser_get_request_response - IDでリクエストとレスポンスのペアを取得します
• browser_stop_network_capture - キャプチャを停止します
• browser_clear_network_capture - キャプチャしたデータを消去します

コンソールキャプチャ（デバッグ）

• browser_start_console_capture - コンソールログのキャプチャを開始します
• browser_get_console_logs - キャプチャしたログを取得します（種類で絞り込み）
• browser_clear_console_logs - キャプチャしたログを消去します
• browser_stop_console_capture - キャプチャを停止します

セッションの永続化

• browser_export_session - Cookie、localStorage、URLをJSONとしてエクスポートします
• browser_import_session - 以前にエクスポートしたセッションをインポートします
• browser_save_session - セッションをファイルに保存します
• browser_load_session - ファイルからセッションを読み込みます

要素ピッカー（インタラクティブな選択）

• browser_start_element_picker - インタラクティブな要素ピッカーを開始します（ホバー時に赤く強調表示）
• browser_get_picked_element - Ctrl+Xでユーザーが選択した要素を取得します
• browser_stop_element_picker - ピッカーを停止し、強調表示を解除します

セッションの例

User: Automate login to example.com

Claude: I'll open a browser and explore the login page.
[browser_open stealth=true]
[browser_navigate url="https://example.com/login"]
[browser_snapshot]
// Returns:
//   - textbox "Email" [ref=e1]
//   - textbox "Password" [ref=e2] [type=password]
//   - button "Sign In" [ref=e3]

Now I'll perform the login actions using refs:
[browser_type selector=@e1 text="[email protected]"]
[browser_type selector=@e2 text="secret123"]
[browser_click selector=@e3]

// Page changed — take a new snapshot to see what happened
[browser_snapshot]

// Done exploring — CLOSE THE BROWSER to get the flow sequence
[browser_close]
// Returns flow sequence JSON with resolved XPath selectors (not refs)

Claude: Here's the plan I recorded:
1. Open Browser → Navigate to login page
2. Type email → Type password → Click Sign In

[AskUserQuestion: "Should I build the TypeScript flow from this sequence?"]

// Only after user says yes:
Here's the TypeScript flow:
// ... generated code ...

ヒント

1. まず必ずスナップショットを取得します — browser_snapshotを1回実行すると、すべてのインタラクティブ要素が参照情報付きで表示されます。
2. ページの変更後はスナップショットを再取得します — ナビゲーションやクリックによって参照情報は無効になります。
3. 作業が終わったらブラウザーを閉じます — 必ずbrowser_closeを実行してください。コードを書いている間、ブラウザーを開いたままにしないでください。

記録されたJSONからTypeScriptへの変換はcreating-flowの担当です。このスキルの役割はシーケンスJSONまでです。ブラウザー固有のSDKパターン（プロキシ設定、セレクターのヒント）については、./docs/patterns/browser.mdを参照してください。

---

ペアプログラミングのワークフロー

要素が見つからない場合 — 要素ピッカーを使います！

何度か試しても要素が見つからない場合は、ユーザーに手動で調べてもらうのではなく、インタラクティブな要素ピッカーを使ってください。

1. Take a screenshot to see current state
2. Try 2-3 different selector strategies
3. Check if element is in an iframe (browser_switch_iframe)
4. If still not found, START THE ELEMENT PICKER:
   [browser_start_element_picker]
   "I can't find the element. I've enabled the element picker -
    please hover over the element you want and press Ctrl+X to select it.
    Press Escape to cancel."
5. Wait for user, then retrieve the element:
   [browser_get_picked_element]
6. Use the recommended selectors from the result

ワークフローの例：

Claude: I'm looking for the login button but can't find it with the usual selectors.
        Let me enable the element picker so you can show me exactly which element you mean.

[browser_start_element_picker]

Result: Element picker started. User should hover over elements (red highlight)
        and press Ctrl+X to select.

Claude: Please hover over the button you want me to click and press Ctrl+X.
        You'll see a red highlight around elements as you hover.

--- User hovers and presses Ctrl+X ---

[browser_get_picked_element]

Result: {
  "picked": true,
  "element": {
    "tagName": "button",
    "className": "btn-primary submit-form",
    "text": "Sign In",
    "recommendedSelectors": [
      { "type": "xpath", "selector": "//button[contains(text(),'Sign In')]", "confidence": 80, "reason": "Contains text" },
      { "type": "xpath", "selector": "//button[@class='btn-primary submit-form']", "confidence": 70, "reason": "Class match" }
    ]
  }
}

Claude: Got it! The button has text "Sign In". I'll use this selector:
[browser_click selector="//button[contains(text(),'Sign In')]"]

API検出のためのネットワーク分析

ページが使用するAPIを把握するには、ネットワークキャプチャを使います。

1. browser_start_network_capture capture_body=true
2. Perform the action (login, form submit, etc.)
3. browser_get_requests method=POST
4. Analyze the API endpoints found
5. Suggest: "Instead of browser automation, you could use
   Core.Net.HttpRequest directly with this endpoint"

ワークフローの例：

Claude: Let me capture network traffic to see what API this uses...
[browser_start_network_capture capture_body=true]

Claude: Now I'll fill in the login form...
[browser_type selector="//input[@name='email']" text="[email protected]"]
[browser_type selector="//input[@name='password']" text="password"]
[browser_click selector="//button[@type='submit']"]

Claude: Let me check what API calls were made...
[browser_get_requests method=POST]

Result: Found POST to /api/auth/login with JSON body:
{
  "email": "[email protected]",
  "password": "password"
}

Claude: I found the login API endpoint. Instead of browser automation,
you could create a simpler flow using Core.Net.HttpRequest:
- POST to /api/auth/login
- Store the auth token from response
- Use token for subsequent API calls

Would you prefer the API-based approach?

コンソールログを使ったデバッグ

操作が期待どおりに動作しない場合：

1. browser_start_console_capture types=["error","warn"]
2. Retry the failing action
3. browser_get_console_logs type=error
4. Report findings and adjust approach

ワークフローの例：

Claude: The click didn't seem to work. Let me check for JavaScript errors...
[browser_start_console_capture types=["error","warn"]]
[browser_click selector="//button[@id='submit']"]
[browser_get_console_logs type=error]

Result: Error: "Cannot read property 'validate' of undefined" at form.js:42

Claude: Found a JavaScript error - the page has a bug in its validation code.
Let me try waiting for the form to fully load first...
[browser_wait selector="//form[@data-ready='true']"]

認証のためのセッション永続化

認証が必要なサイトで作業する場合：

1. Complete login manually or via automation
2. browser_export_session - save for later
3. Close browser, do other work
4. browser_open, browser_import_session - restore auth

ワークフローの例：

Claude: Let me save your authenticated session for later use...
[browser_export_session]

Session exported with 5 cookies and current URL.

Claude: I'll save this to a file so you can reuse it:
[browser_save_session path="/tmp/myapp-session.json"]

--- Later ---

Claude: Let me restore your previous session...
[browser_open]
[browser_load_session path="/tmp/myapp-session.json"]

Session restored - you're logged in as [email protected]

ブラウザーとHTTPリクエストの使い分け

シナリオ	推奨事項
エンドポイントが既知のシンプルなAPI	Core.Net.HttpRequestを使います
ログインフローで認証Cookieが必要	ブラウザーを使い、その後セッションをエクスポートします
JavaScriptでレンダリングされる複雑なコンテンツ	ブラウザー自動化を使います
CSRFトークンを使うフォーム	ブラウザーを使います（トークンを自動的に処理します）
ページ分割されたデータのスクレイピング	ブラウザーから始め、APIが見つかったら切り替えます
ファイルのダウンロード	認証にはブラウザーを、ダウンロードにはAPIを使います

判断のワークフロー：

1. ネットワークキャプチャから始めます
2. クリーンなREST APIが見つかった場合 → HTTPRequestを提案します
3. 複雑な認証／CSRFがある場合 → ブラウザーを使い続けます
4. 両方が必要な場合 → 認証にはブラウザーを、データ取得にはAPIを使います