unbrowse

Unbrowse

ホスト型サービス https://unbrowse.ai を使用します。実行、インデックス化されたルート、ウェブサイトのセッションはサーバー側に保持されます。このスキルでは操作方法を案内します。サインインは以下のとおり OAuth で行います。

オンボーディング：OAuth でサインインする

サインインは、本人のブラウザーで OAuth を使って行います。メールで届くサインインリンクを開き、Allow を押します。パスワードは不要で、何かをコピーして貼り付ける必要もありません。チャットで本人にトークンやキーを尋ねてはいけません。

まず状態を確認し、不足しているものだけサインインします。

1. MCP：このセッションのツール一覧に unbrowse_discover があれば、MCP はサインイン済みです。
2. CLI：npx unbrowse whoami を実行します。終了コード 0 はサインイン済み、終了コード 3 は未サインインを意味します。

MCP にサインインします（エージェントホストの場合）：

claude mcp add --transport http unbrowse https://unbrowse.ai/mcp

{"mcpServers":{"unbrowse":{"url":"https://unbrowse.ai/mcp"}}}

ホストが OAuth サインインを自動で実行します（Claude Code では /mcp を開き、unbrowse を選択して Authenticate を実行します）。設定に bearer ヘッダーを追加しないでください。追加すると、ホストは OAuth をスキップします。設定に URL があっても、サインイン済みセッションとは限りません。ホストが OAuth を完了するまでは、Unbrowse のツールは一覧に表示されません。

CLI にサインインします：

npx skills add unbrowse-ai/unbrowse && npx unbrowse login

unbrowse login は、このマシンのブラウザーでサインインページを開きます。本人がメールアドレスを入力し、リンクを開いて Allow を押すと、CLI に Signed in to https://unbrowse.ai (workspace ws_…) と表示され、トークンが ~/.config/unbrowse/cli.json に保存されます（モード 0600、自動更新）。

エージェントのシェルから実行する場合（本人が使うターミナルがない場合）：npx unbrowse login --no-open をバックグラウンドで実行し、表示された https://unbrowse.ai/authorize?… リンクを本人に渡して、Signed in の行が表示されるまで待ちます。このリンクはこのマシンの 127.0.0.1 に戻るため、本人は同じマシン上のブラウザーで開く必要があります。リモート環境またはヘッドレス環境では、npx unbrowse login --device を実行し、任意のデバイスから表示されたコードを承認するか、API キー（以下を参照）を使用します。サインインしていない状態で他のコマンドを実行すると、ターミナルがある場合は同じブラウザーサインインが開始されます。ターミナルがない場合は終了コード 3 で終了し、unbrowse login の実行を求めます。

次に、最初の呼び出しを行います：npx unbrowse run 'top stories on hacker news'。デフォルトでは、サイトへのリクエストは本人の IP アドレスから送信されます。--from-unbrowse を指定すると、Unbrowse から送信されます。

npx unbrowse mcp（stdio MCP が必要なホスト向け）は CLI のサインインを使用します。unbrowse mcp add を実行すると Claude Code と Codex に登録され、同じサインインで動作します。別の方法として、CLI にサインインしていない場合、サーバーが https://unbrowse.ai/api/mcp に追加されていれば、CLI は Claude Code 自身の Unbrowse MCP サインインを使用できます。プラグインと上記のセットアップで使われる URL https://unbrowse.ai/mcp のトークンは REST API では使えないため、その場合は unbrowse login を実行してください。MCP 設定にトークンが書き込まれることはありません。

ブラウザーを使わない自動化や CI では、呼び出し元のシークレットマネージャーから UNBROWSE_API_KEY を設定します（サインイン済みのコンソール https://unbrowse.ai/app でキーを作成します）。コミット対象の設定、プロンプト、コマンド引数、ログにキーを含めないでください。

CLI と SDK：https://github.com/unbrowse-ai/unbrowse

ホストプラグイン

このスキルをバンドルするパッケージ済みインストールは、Unbrowse に接続し、ホスト独自のブラウザーを Unbrowse に切り替えます（https://github.com/unbrowse-ai/unbrowse/tree/main/plugins）。

• Claude Code：claude plugin marketplace add unbrowse-ai/unbrowse を実行し、続いて claude plugin install unbrowse@unbrowse を実行します。
• Codex：codex plugin marketplace add unbrowse-ai/unbrowse を実行し、続いて codex plugin add unbrowse@unbrowse を実行します。組み込み検索を無効にするには、web_search = "disabled" を設定します。
• Grok Build：grok plugin install unbrowse-ai/unbrowse#plugins/grok-build --trust。
• OpenClaw（@unbrowse/openclaw）、Hermes（plugins/hermes）、elizaOS（@unbrowse/plugin-unbrowse）：同じ MCP を介したネイティブツールまたはアクションを使用します。

stdio サーバーが必要なホストでは、npx unbrowse mcp を実行できます。同じ unbrowse_… ツール名を提供します。プラグインをインストールすると、組み込みのウェブ取得、ウェブ検索、ローカル以外の URL へのブラウザーナビゲーションは拒否され、対応する Unbrowse ツールを案内します。UNBROWSE_ALLOW_BUILTIN_BROWSER=1 を設定すると、そのセッション中はこの制限が解除されます。

インターフェースを選択する

• MCP：検出、実行、ページの読み取り、クラウドブラウジング、インデックス作成、保存済みログイン情報のリクエストに使用します。これらの名前はMCPツールです。CLIにはそれぞれに対応するコマンドがあります（以下を参照）。
• CLI：unbrowse discover、run、inspect、resume、scrape <url>（1ページをMarkdownとして取得）、index <url>（サイトを学習。index statusで状態を確認）、registry、site、whoamiを使用します。scrapeとindexにはCLI 12.2.0以降が必要です。unbrowse runはブラウザーでウェブサイトを操作しません（初回サインイン時に開くブラウザーを除きます）。CLI 12.5.0以降では、すべてのMCPツールにコマンドが用意されています。unbrowse map <url>、sites [site]、forget、connect [app]、credits、クラウドブラウザーのunbrowse browse open <url> / browse snapshot <id> / browse act <id> click e1 / browse finish <id> / browse close <id>、credentials list|request|status、replay list|search|get|timeline|askがあります。unbrowse tool <name>を使うと、学習済みサイトのツールなど、一覧にある他のツールを呼び出せます。unbrowse installはありません。unbrowse helpでインストール済みバージョンの説明を確認できます。
• SDK：REST連携とスクリプティングに使用します。対応メソッドについては公開SDKドキュメントを参照してください。MCPツールとRESTメソッドの名前は互換性がありません。

コアMCPツール：unbrowse_discover、unbrowse_run、unbrowse_inspect、unbrowse_resume、unbrowse_cancel、unbrowse_scrape、unbrowse_map、unbrowse_sites、unbrowse_usage、unbrowse_credits、unbrowse_forget、unbrowse_learn、unbrowse_index、unbrowse_index_status、unbrowse_credentials_list、unbrowse_credentials_request、unbrowse_credentials_status、unbrowse_connect（Linear、Notion、GitHubなど、アプリ独自のMCPサーバーに接続して、そのツールをユーザーとして実行します。サインインが必要なアプリの場合、ユーザーが開くリンクが返されます）、unbrowse_import_mcps（このエージェントがすでに使用しているMCPサーバーをUnbrowseに取り込みます。以下を参照）、およびクラウドブラウザーのunbrowse_browse_open、unbrowse_browse_snapshot、unbrowse_browse_act、unbrowse_browse_finish、unbrowse_browse_closeです。

references/tools.jsonには、エクスポートされたコアMCP入力スキーマが含まれています。接続先サーバーのtools/listが正式な情報源です。そこには、このユーザーのワークスペースで利用可能な動的ツールも含まれています。能力IDや入力スキーマを推測してはいけません。

タスクを実行する

1. unbrowse_discover {query} で検出します。返された入力、選択肢、ヒントを確認します。正常に動作する一致した機能を優先します。warm は HTTP リプレイ、rendered はレンダリングが必要という意味です。該当する場合は unbrowse_sites で保存済みのセッションとログイン状態を確認します。公開ツールには、ツールを生成した Unbrowse のバージョン（YYYY.MM.DD）を示す version が付いています。一致度が同じ場合は新しいものが先に表示され、minVersion を指定すると、それより古いものが除外されます。
2. 選択したツールを、記載されたスキーマで呼び出すか、unbrowse_run {capability, input} を実行します。ID を選択していない場合は、自然言語の task でルーティングできます。同じ変更操作には、安定した idempotencyKey を使用します。回答が大きい場合は、select を指定します（MCP の実行ツール、unbrowse_resume、unbrowse_inspect、POST /api/v1/runs）。パスは ["results[].{id,title,price}", "total"] のように指定します。これは検証後に返される内容だけを絞り込み、課金額は変わりません。結果が 40,000 文字を超えると短縮されます（truncated: true）。該当するものがなかったパスは selectMissing に一覧表示されます。
3. 返されたステータスと実際の結果を確認します。input_required は、同じ実行に対して未解決の要件に回答する必要があることを意味します。unbrowse_resume {runId, answers:{field:value}} を使用します。選択肢の場合は、一覧にあるオプションの値を渡します。指定されている場合は、リビジョンの確認を維持します。
4. no_capability は、再利用可能なルートが見つからなかったことを意味します。result.next に従います。tool は unbrowse_index（POST /api/v1/index、続けて GET /api/v1/index/{jobId}。CLI では unbrowse index <url>）です。今すぐ回答するには、代わりにページを読み取ります。unbrowse_scrape（CLI では unbrowse scrape <url>）を使用します。unbrowse_browse_open は、このセッションのツール一覧にその名前がある場合にのみ呼び出します（シェルからは unbrowse browse open <url>、CLI 12.5.0 以降）。POST /api/v1/browse/open は呼び出さないでください。これはルートではありません。サイトがサポート対象外またはブロックされている場合は、正直に報告します。
5. 検証済みの結果が得られた場合にのみ、完了を報告します。outcome_unknown は、変更が行われた可能性があることを意味します。再試行する前に、効果のレシートと変更先を確認します。キャンセルすると以降のディスパッチは停止しますが、完了済みの処理は取り消されません。

HTTP 200、ツールの通信成功、スクリーンショット、生成されたプランから、ビジネス上の成功を推測しないでください。すべてのサイトに常に対応できることや、初回のリクエストから毎回ブラウザーなしで実行できることを約束しないでください。投稿、送信、購入、その他の外部への書き込み操作を行う前に、ユーザーの許可を得てください。

URL の Unbrowse

ユーザーがサイトを指定した場合：

1. このセッションのツール一覧に unbrowse_discover がない場合、MCP にサインインしていません。設定済みの MCP URL を伝えて停止します。リモート MCP ではホスト側の OAuth が必要です。CLI にサインイン済みの場合は、代わりに npx unbrowse mcp add を実行すると、そのサインインを使うサーバーがホストに追加されます（反映されるのは新しいセッションからです）。
2. ホストを検索します（unbrowse_sites、または CLI では unbrowse site <host>）。すでにコンパイル済みのツールがあれば、それを使用して停止します。
3. ツールがない場合は、unbrowse_index {url, focus} または POST /api/v1/index を実行します。unbrowse_index_status または GET /api/v1/index/{jobId} でポーリングします。
4. status: failed かつ error.code: model_unavailable の場合、インデックス作成モデルのクレジットが不足しています。ジョブ ID とメッセージを報告します。代わりにブラウズしたり、同じジョブを繰り返し開始したりしないでください。
5. status: done で indexed: 0 の場合、何も学習されていません。その旨を伝えます。indexed > 0 の場合はツールを 1 つ呼び出し、結果を確認します。

/api/v1/index からの 202 はジョブ ID であり、コンパイル済みツールではありません。

プレーンな HTTP 経由でサイトのツールを利用する

コンパイル済みの各サイトは、エージェントセッションではなくコード向けの REST API でもあります。

• GET https://unbrowse.ai/api/v1/sites/<host>/openapi.json：OpenAPI 3.1 形式で、ツールごとに 1 つのオペレーション、型付きの入力、検証時に使用した example 入力、すべてのステータスとヘッダーを含みます。読み取りにキーは不要です。
• POST https://unbrowse.ai/api/v1/sites/<host>/call/<tool> に、ツールの入力を JSON ボディとして指定し、Authorization: Bearer <key> を付けます。オプション：x-unbrowse-deadline-ms、Idempotency-Key、select。202 は input_required を意味します。504 run_timeout はポーリング用の runId を返します。409 tool_quarantined の場合は、別のツールを使用してください。
• SDK：new Unbrowse().callTool(host, tool, input)。

契約と使用例：https://unbrowse.ai/docs/site-apis.md

サイトを読み取る、または学習する

構造化データやサイト上のタスクには、unbrowse_discover と対応するツール、または unbrowse_run を優先してください。unbrowse_scrape {url} は、静的なページやドキュメントに対する最終手段としてのみ使用し、適切な API や学習済みツールがない場合に限ります。PDF、.docx、.xls、.xlsx の URL は、抽出された Markdown テキストとして返されます（PDF は metadata.pages、スプレッドシートはシート名、行、書式設定された値を保持します）。metadata.truncated は抽出に上限が適用されたことを示します。formats: ["raw"] はドキュメントの正確なバイト列を base64 で返します。unbrowse_map {url} は同じサイト内の URL を見つけます。URL が既知であることや、スクレイプにレンダリング機能があることを理由に、これをデフォルトの方法にしないでください。動的コンテンツ、検索、ページネーション、または対応するルートのない操作には、unbrowse_index または利用可能なクラウドブラウザーツールを使って、サイトの API を学習し再実行してください。

1. unbrowse_browse_open {url,task} は、ページと要素参照を返します。
2. 最新の参照を使って unbrowse_browse_act を呼び出します。通常の入力では、date や query など意味のある name を指定し、タスクに必要なすべてのフィルターを試してください。ページが変わったらスナップショットを更新します。
3. unbrowse_browse_finish {sessionId} を使うと、最終ページが返され、観察したルートがコンパイルされます。異なる入力で 2 つのセッションを実行すると、再利用可能なパラメーターを特定しやすくなります。learnError と newTool を確認してください。ブラウジングに成功しただけでは、再利用可能なルートが存在するとは限りません。
4. 完了したらセッションを閉じます。unbrowse_browse_close は discard:true を指定しない限り、引き続きインデックスを作成します。

必要になる前にサイト全体を網羅するには、unbrowse_index {url, focus?, maxCapabilities?} を使います。バックグラウンドジョブが起動し、Unbrowse 独自のエージェントがサイトの主要な読み取り専用機能を実行し、ブラウザーを使わない再実行でそれぞれの動作を確認して、ツールに追加します。続けて unbrowse_index_status {jobId} を呼び出してください。maxCapabilities は、ジョブがインデックス化するすべてのツール（宣言済みのもの、サイトマップのページタイプ、記録されたフローを合わせたもの）の上限を設定します。focus を指定すると、それに一致するサイトマップのページタイプだけが対象になります。ただし、ページ送り、ページサイズ、フィルター、検索などのフローを指定した場合は、対象はありません。開始 URL のクエリーキー（?page=0&pageSize=100）は、ツールの入力になります。stoppedReason はジョブが終了した理由を示します。ツールの検証中は、時間の上限が一度だけ半分延長されます。

既存の HAR ペアは unbrowse_learn を通じて送信できます。ユーザーが許可した記録のみを送信してください。HAR にはプライベートなデータが含まれている場合があります。ホスト型サービスでは、プライベートな宛先やループバック宛先へのアクセスは拒否されます。

エージェントの MCP サーバーを取り込む

ユーザーが既存の MCP サーバーを Unbrowse に追加したい場合（1 回のサインインで、すべてのエージェントが利用できます）、1 つずつ手動で追加するのではなく、インポートしてください。

• ターミナルから：npx unbrowse mcps を実行すると、このマシンのエージェント設定（Claude Code、Claude Desktop、Cursor、Codex、VS Code、Windsurf、Gemini、Zed）にあるサーバーが一覧表示されます。npx unbrowse mcps import でインポートできます（--dry-run を指定すると計画を表示します）。設定内のキーは、ユーザーが --with-keys を指定しない限り、マシン上に保持されます。
• MCP ツールとして：ホストの MCP 設定を自分で読み取り、unbrowse_import_mcps {servers:[{name, url} | {name, command, args}]} を呼び出します。キー、ヘッダー、環境変数の値は決して渡さないでください。dryRun: true を指定すると計画を表示します。
• リモートサーバーにはアドレスで接続します。ローカル（stdio）サーバーは Unbrowse のクラウドでは実行できません。カタログに同じアプリのホスト版があれば、そちらに接続します。なければ local_only となり、エージェント内に保持されます。sign_in と key の行には、ユーザーが開くリンクが含まれています。インポートする前に計画を表示してください。

ウェブサイトへのサインイン

Unbrowse アカウントへのサインインと、ウェブサイトに保存されたログイン情報は別々です。チャットでパスワードを尋ねたり、通常のツール引数で認証情報を入力したりしないでください。

• ログインページでは、unbrowse_browse_act {sessionId,action:"autofill"} を使用するか、入力アクションで vault:"username"|"email"|"password"|"totp" を指定します。値は保管庫からサイトに直接渡されます。
• ログイン情報がない場合は、返された signIn.url または details.url のログイン保存リンクを提示します。unbrowse_credentials_request でリンクを作成できます。unbrowse_credentials_status で手続きが完了したか確認できます。準備が整ってから再開してください。
• CAPTCHA、MFA、人間による確認を回避しないでください。サポートされている引き継ぎ方法を提示するか、障害があることを報告してください。
• 保存済みのセッションは自動的に再利用されます（ユーザーはサイトごと、またはワークスペース全体でこの設定をオフにできます）。別のタスクが始まったという理由だけで、再度サインインしないでください。

読み取り専用で、シークレットを含まない学習済みルートは、サニタイズしてパブリックレジストリと共有される場合があります。所有者はコンソールで共有をオプトアウトできます。ログイン情報、プライベートなセッション値、書き込み操作は、パブリックなツール定義には含まれません。

多数のユーザーへの提供（組織）

呼び出し元が、ビルダーが自分のユーザー向けに実行するエージェントである場合、組織キーを使用し、すべての呼び出しでユーザーを指定します：X-Unbrowse-End-User: <that user's id>（REST と MCP のヘッダー）。ユーザーごとにログイン情報とセッションが分かれています。

• タスクの対象ユーザーの ID を必ず送信してください。あるユーザーの ID を別のユーザーのタスクに再利用したり、省略したりしないでください。ID を指定しないと、ユーザーではなく組織として呼び出しが実行されます。
• signIn.url（/connect/… リンク）は、そのユーザー専用です。ビルダーや別のユーザーではなく、そのユーザーに渡してください。ユーザーは Unbrowse アカウントなしでそのリンクからログイン情報を保存できます。unbrowse_credentials_status が fulfilled になるまで待ってから、もう一度呼び出してください。
• org__… ツールは組織のユーザー間で共有されます（読み取り専用、ログイン情報なし）。my__… ツールは現在のユーザー専用です。
• クォータエラーは組織の残高に関するものです。ビルダーに報告してください。

ガイド：https://unbrowse.ai/docs/orgs.md

制限と復旧

• 401：OAuth でその接続先に再度サインインしてください。CLI の 401：npx unbrowse login。リモート MCP の 401：そのサーバーに対するホスト側の OAuth（Claude Code の場合：/mcp）。一方へのサインインで、もう一方の問題は解決しません。
• インデックス作成ジョブで model_unavailable が発生した場合：インデックス作成モデルのクレジットが不足しています。ジョブ ID を報告してください。ツールはコンパイルされていません。これは unbrowse_usage のエラーでも、サイト側のエラーでもありません。
• クォータ／支払いエラー：返された上限とコンソールへのリンクを表示してください。支払いをむやみに再試行しないでください。一覧に表示されている場合、unbrowse_credits で無料残高と有料残高を確認でき、ユーザー向けのチェックアウトリンクを取得できます。請求リンクを開いただけでは、支払いは承認されません。
• 認証確認またはログインのブロック：返された引き継ぎ方法を使用してください。チャレンジページをソースコンテンツとして提示しないでください。
• 書き込み時のタイムアウト：再試行する前に、既存の実行状況を確認してください。
• 料金とクォータ：アカウントの現在のプランと unbrowse_usage を確認してください。このスキルで料金が変わることはありません。