reverse-api-engineer

Reverse API Engineer

reverse-api-engineer（rae）は、タスクを実行しながらブラウザーを操作し、ウェブサイトが送信するリクエストを読み取って、API クライアントに変換します。chrome-mcp プロバイダーはユーザー自身の Chrome で動作するため、ログイン状態が引き継がれます。auto プロバイダー（Playwright）は新しいブラウザーを使って HAR ファイルを記録するため、後から再度ブラウザーを操作せずに実行内容をリバースエンジニアリングできます。どちらが使われるかは、ユーザーの設定と rae のバージョンによって異なります。確認方法は手順 3 をご覧ください。

このスキルが提供するのは手順のみです。スクリプト化された JSON 出力コマンドを使って CLI を操作します。

1. インストールを確認する

reverse-api-engineer --version

コマンドが見つからない場合は、何かをインストールする前にユーザーに確認してから、次を実行します。

uv tool install reverse-api-engineer   # or: pipx install reverse-api-engineer

エージェントモードでは、PATH 上に Node.js 20.19+ も必要です（npx を使ってブラウザーツールを起動します）。モデルへのアクセスと設定については、セットアップと設定をご覧ください。

2. 以前のキャプチャがある場合は再利用する

reverse-api-engineer list --search "<site or task>" --json

list には失敗した試行や中断された試行も含まれるため、候補を再利用する前に確認してください。

reverse-api-engineer show <run_id> --json

• file_count > 0 はクライアントが生成済みであることを示します。手順 5 で検証し、タスクに対応していれば再利用してください。
• har_entries > 0 はトラフィックが保存されていることを示します。再度ブラウザーを操作する代わりに、engineer（手順 6）でクライアントを改善できます。chrome-mcp の実行では HAR は保存されないため（mode: "chrome-mcp"）、リバースエンジニアリングはできません。
• それ以外の場合は、手順 3 から再度キャプチャしてください。

3. 事前確認

reverse-api-engineer agent -p "<goal>" -u "<start url>" --dry-run

ブラウザーを開かずに、プロンプト、URL、設定、環境を検証します。実行前に、すべての error チェックを解消してください。SDK が別の方法で認証する場合（ログイン済みの Claude Code など）は、API キーに関する warn は問題ありません。

出力の would_run.agent_provider は、実行で使われるブラウザーを示します。chrome-mcp はユーザー自身の Chrome とそのログイン状態を使います。auto と agent-browser はログイン状態を引き継がず、新しいブラウザーを起動します。タスクでユーザーのログインが必要なのにプロバイダーが chrome-mcp ではない場合は、切り替える前にユーザーに確認してください（セッションをご覧ください）。

chrome-mcp の場合、chrome-mcp:auto-connect チェックでユーザーの Chrome への接続を確認します。

• ok：Chrome に接続できます。実行開始時に、ユーザーが Chrome の接続確認を承認する必要があります。
• error：接続できません。サイトでユーザーのログインが必要な場合は、ユーザーに Chrome 146+ を開き、chrome://inspect/#remote-debugging でリモートデバッグを有効にするよう依頼してください（「Enable auto-connect」）。その後、事前確認を再実行します。公開データの場合は --headless を追加してください。rae はユーザーのセッションを使わず、独自のヘッドレス Chrome を起動して、このチェックをスキップします。
• warn：この rae のバージョンでは接続を確認できません。有効な自動接続を設定した Chrome が開いていることを、画面表示ありの実行前にユーザーへ確認するか、公開データの場合は --headless を使用してください。

クリック操作ではなく、ユーザーが必要とするデータを目的として記述してください。「求人ページから、ページネーションを含めて、募集中の職種の役職名、勤務地、チームを取得する」のように書くと、「求人タブをクリックする」より適切です。

4. キャプチャして生成する

実行には数分かかり、シェルツールのデフォルトのタイムアウトを超えることもよくあります。最初からバックグラウンドで開始してください。シェルツールにバックグラウンド実行オプションがある場合はそれを使い、ない場合は & を付けます。

reverse-api-engineer agent -p "<goal>" -u "<start url>" --json-stream > rae-run.ndjson 2> rae-run.log &
echo $! > rae-run.pid

--json-stream は1行につき1つの NDJSON イベントを書き出し、最後に {"event":"result",...} の行を出力します。rae-run.ndjson にその行が現れるか、rae-run.pid のプロセスが終了したとき（kill -0 "$(cat rae-run.pid)" が失敗するとき）に実行は完了です。tail rae-run.log で進行状況を確認してください。実行中に2つ目のキャプチャを開始しないでください。作業とコストが重複します。

• --headless を指定しない場合、chrome-mcp はユーザーの Chrome で専用のタブを開き、そのタブだけを閉じます。ユーザーのブラウザーを操作するため、開始前に伝え、Chrome に表示される接続確認を承認してもらってください。誰も承認しない場合、クライアントがないままタイムアウトします。
• 公開サイト、またはディスプレイのないマシンでは --headless を追加してください。
• -o <dir> を追加すると、~/.reverse-api/runs 以外の場所に実行結果を書き出せます。
• --json は進行状況を出力せず、最後に同じ結果を単一のオブジェクトとして表示します。シェルが実行全体を待機できる場合にのみ使用してください。
• ログインが必要なサイトやプロバイダーについては、セッションとブロックされたサイトを参照してください。

最終結果の行には、次のフィールドが含まれます。

フィールド	意味
status	ok または error
run_id	engineer、run、show で使用する ID
script_path	生成されたクライアントの場所。<runs>/scripts/<run_id>/ 内の README.md と同じディレクトリにあります
har_path	生のキャプチャ。HAR を保持しない chrome-mcp の実行では null
usage.total_cost_usd	実行にかかったモデルのコスト。ユーザーに伝えてください
error_kind	失敗時に設定されます。トラブルシューティングを参照してください

終了コード：成功は 0、キャプチャまたはエンジニアリングの失敗は 1、誤った使い方は 2 です。

5. クライアントを検証する

生成されたクライアントとその README.md は、実行する前に読んでください。モデルが記述したコードです。その後、実行します。

reverse-api-engineer run <run_id> --ls                       # list generated files
reverse-api-engineer run <run_id> --file <client file> --json -- <script args>

--auto-install は、不足している依存関係を確認なしでインストールします。事前にユーザーに確認してください。出力に 200 ステータスだけでなく、サイトから取得した実際のデータが含まれていることを確認してください。

6. 同じキャプチャで繰り返す

reverse-api-engineer engineer <run_id> -p "add pagination and a typed Job model" --json
reverse-api-engineer engineer <run_id> --fresh -p "only the search endpoint" --json

--fresh を指定しない場合、プロンプトは元の目標と既存のクライアントに追加されます。--fresh を指定すると、HAR からクライアントが再生成されます。engineer には HAR が必要なため、auto または agent-browser プロバイダーによる実行と、手動モードによる実行でのみ動作します。chrome-mcp の実行では error_kind: misuse とともに 2 で終了します。この場合や、キャプチャにエンドポイントが含まれていない場合は、より具体的な目標を指定して再度 agent を実行してください。

7. 引き渡す

クライアントは結果の script_path にあります。real_time_sync が有効な場合（デフォルト）、rae は作業ディレクトリ内の ./scripts/<descriptive_name>/ にもコピーします。そのフォルダーがない場合は、script_path からコピーしてください。名前と型をコードベースに合わせて調整し、生成された README.md は使用方法のメモとして残してください。ラップするエンドポイントと認証の処理方法（Cookie、ベアラートークン、CSRF）をユーザーに伝えてください。キャプチャした認証情報には有効期限があります。

制限事項

• ユーザーにアクセス権のあるサイトのみをキャプチャし、その利用規約とレート制限を遵守してください。
• キャプチャには Cookie やトークンが含まれる場合があります。HAR の内容をチャット、課題、コミットに貼り付けないでください。
• サイトで人間による操作（CAPTCHA、2FA、通常と異なるログイン）が必要な場合は、手動モードでキャプチャするようユーザーに依頼し、その後 engineer を実行してください。セッションとブロックされたサイトを参照してください。