mcpField
H
http-toolkit-intercept

http-toolkit-intercept

github.com/factory-ai開発117118 回インストール3 日前に更新
リポジトリ

http-toolkit-intercept について

コード変更の検証時に、プログラムのHTTP通信とセッションログを取得して照合するスキルです。複数のランタイムでのプロキシ設定を扱い、HTTP Toolkitのエクスポートを使って送信内容とプログラムの動作を調べます。

主な機能

  1. 01HTTP Toolkitのプロキシ設定
  2. 02ランタイム別のプロキシ設定
  3. 03送信リクエストのエクスポート
  4. 04セッションログとの照合
  5. 05TLS検査の安全ガイド

活用シーン

  1. 01APIリクエストの本文とヘッダーの確認
  2. 02コード変更時の応答処理の追跡
  3. 03プロキシ通信の欠落やTLSエラーの調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/factory-ai/factory-plugins --skill http-toolkit-intercept

インストール後、Claude Code で/http-toolkit-interceptを入力して読み込まれたか確認します。

詳細

HTTP Toolkit のインターセプト

コード変更を検証する際に、プログラムがリモート API に送信した内容と受信した内容について、信頼できる証拠が必要な場合にこのスキルを使用してください。プロセスがプロキシを使用する限り、Node.js、Bun、Deno、Python、Go、Ruby、Java/JVM、.NET、PHP、Rust、シェルスクリプトなど、あらゆるランタイムで動作します。

信頼性の高い手順は次のとおりです。

  1. HTTP Toolkit を正しく起動します。
  2. 機械可読なログを出力するモード（例：--output-format json、デバッグログ、構造化された stdout）で、プログラムをプロキシ経由で実行します。
  3. HTTP Toolkit から送信 HTTP リクエストをエクスポートします。
  4. 送信 HTTP のエクスポートと、受信したプログラムのセッションログを照合します。

リクエストのペイロード、認証ヘッダー、またはワイヤーレベルの動作が問題となる場合は、TUI のスクリーンショットだけに頼らないでください。

前提条件／既知の正常な起動方法

HTTP Toolkit を起動する

Linux／ヘッドレス環境では、通常の httptoolkit はサンドボックス／X11 の問題により失敗することがよくあります。次の方法を推奨します。

xvfb-run --auto-servernum httptoolkit --no-sandbox

ポート 45456/45457 ですでに古いサーバーが実行されている場合は、先に停止します。

pkill -f "HTTP Toolkit Server|httptoolkit|xvfb-run --auto-servernum httptoolkit" || true
プロキシに接続できることを確認する
# HTTP Toolkit's admin API lives on port 45456/45457 by default.
# Treat 200/401/403 as "reachable"; only connection failure means the server is dead.
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:45456/config

クイックスタート

1. プロキシ環境変数を設定してプログラムを起動する

多くのランタイムが使用する標準の環境変数は次のとおりです。

HTTP_PROXY="http://127.0.0.1:8000" \
HTTPS_PROXY="http://127.0.0.1:8000" \
ALL_PROXY="http://127.0.0.1:8000" \
NO_PROXY="" \
<your-program> <args>

ランタイムによっては追加の環境変数またはフラグが必要です。以下の「ランタイム別プロキシ対応表」を参照してください。

HTTP Toolkit の CA がランタイムで信頼されていない場合、TLS 検証に失敗します。以下の「TLS の安全性」を参照してください。TLS 検証の無効化が適切なのは、管理されたローカルデバッグの場合に限られます。

2. 受信したセッションログを取得する

プログラムが機械可読な出力モード（例：--output-format stream-json、--json、--log-level debug、構造化された stdout、またはファイルへの書き込み）に対応している場合は、パイプでファイルに出力します。

<your-program> exec --output-format stream-json "your input" \
  > /tmp/session-stdout.log 2> /tmp/session-stderr.log
3. HTTP Toolkit から送信 HTTP をエクスポートする

次のいずれかを行います。

  • HTTP Toolkit の GUI エクスポートを使用します（File → Export → JSON / HAR）。
  • または、管理 API に直接アクセスします。正確なエンドポイントは HTTP Toolkit のバージョンによって異なります。HTTP Toolkit UI の DevTools を確認し、UI が行うリクエストを調べてください。
4. 2 つのストリームを相互参照する
  • 送信 HTTP（HTTP Toolkit から）：リクエスト本文、ヘッダー、認証トークン、リトライのタイミングを確認するための信頼できる情報源です。
  • 受信したセッションログ（プログラムから）：コードがレスポンスにどう反応したかを確認するための信頼できる情報源です。

両方を組み合わせることで、「何を送信したか」と「レスポンスをどう処理したか」が分かります。

ペイロードの検証で最終的にうまくいった方法

信頼性が確認できた、重要で正しい手順は次のとおりです。

  1. ペイロードの検証では TUI ではなく、非対話モード／exec モードを使用する

    • 対話型 TUI は動作が遅く、分析もはるかに困難です。
    • プログラムでスクリプト実行に使える機能（--output-format、--json、--headless、--batch）を使用してください。

  2. 送信と受信を別々の証拠情報源として扱う

    • HTTP Toolkit では送信 HTTP リクエストを確認できます。
    • プログラムのセッションログでは、受信したアシスタント／ツール／アプリケーションの動作を確認できます。
    • 「リモートから何が返されたか」と「プログラムが実際にどう処理したか」を確認するには、両方が必要です。

  3. 使用するランタイムが対応するプロキシ環境変数を設定する

    • HTTP_PROXY／HTTPS_PROXY はほとんどのランタイムで使用できますが、一部（例：Bun、Java）では追加の環境変数またはフラグが必要です。
    • 以下の「ランタイム別プロキシ対応表」を参照してください。

  4. 必要な場合に限り、管理されたローカルデバッグで TLS 検証を無効にする

    • HTTP Toolkit の CA がローカルで信頼されていない場合は、ランタイム固有の回避策を使って検証をスキップします。
    • 代わりに、OS または言語の信頼ストアで CA を信頼する方法を推奨します。
    • 本番環境の再現テストでは、TLS を決して無効にしないでください。

  5. 実行時間を制限する

    • ネットワーク負荷の高い長時間のセッションには時間がかかることがあります。
    • リクエストの形式を確認するだけでよい場合は、該当するリクエストが確認できた時点でエクスポートしてください。必ずしも完了まで待つ必要はありません。

重要な事実

  • プロキシ環境変数はランタイムごとに異なります — 使用するランタイムがどの環境変数に対応しているか確認してください
  • HTTP Toolkit の管理 API はリクエスト指向です — アウトバウンド HTTP は HTTP Toolkit から取得され、インバウンドの動作はプログラムログから取得されます
  • TLS はデフォルトで検証されます — ランタイム固有のスキップフラグは、ローカル開発用の一時的な回避策としてのみ使用してください

ランタイム別プロキシ一覧

ランタイムプロキシ環境変数／フラグTLS の検証を回避する方法（ローカル開発用のみ）
Node.jsHTTP_PROXY、HTTPS_PROXY、NO_PROXY（ほとんどのライブラリ）。一部の HTTP クライアントでは、--proxy フラグまたは明示的な agent: オプションが必要ですNODE_TLS_REJECT_UNAUTHORIZED=0 または NODE_EXTRA_CA_CERTS=/path/to/ca.pem
BunBUN_CONFIG_PROXY（必須 — HTTP_PROXY／HTTPS_PROXY を設定しても、Bun 自身の fetch では黙って無視されます）NODE_TLS_REJECT_UNAUTHORIZED=0
DenoHTTP_PROXY、HTTPS_PROXY--unsafely-ignore-certificate-errors
Python（requests、httpx）HTTP_PROXY、HTTPS_PROXY、ALL_PROXYHTTP Toolkit の CA を指定する REQUESTS_CA_BUNDLE／SSL_CERT_FILE、またはコード内の verify=False
Python（urllib）同じ環境変数SSL_CERT_FILE またはコンテキストの検証を無効化
Go（net/http）HTTP_PROXY、HTTPS_PROXY、NO_PROXY（http.ProxyFromEnvironment を通じて使用されます）SSL_CERT_FILE またはトランスポートの InsecureSkipVerify: true
RubyHTTP_PROXY、HTTPS_PROXYSSL_CERT_FILE または OpenSSL::SSL::VERIFY_NONE
Java／JVM-Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort=8000 -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=8000。JVM は環境変数を使用しませんCA をトラストストアにインポートし、-Djavax.net.ssl.trustStore=... を渡します
.NET／C#HTTP_PROXY、HTTPS_PROXY、ALL_PROXY（最近のランタイムの場合）、または HttpClient を明示的に設定しますOS のストアで CA を信頼するか、HttpClientHandler.ServerCertificateCustomValidationCallback を使用します
PHP（curl／cli）HTTP_PROXY、HTTPS_PROXY（または呼び出しごとの CURLOPT_PROXY）CURLOPT_SSL_VERIFYPEER => false
Rust（reqwest）HTTP_PROXY、HTTPS_PROXYクライアントの danger_accept_invalid_certs(true)
curl／シェルHTTP_PROXY、HTTPS_PROXY 環境変数、または -x／--proxy フラグ-k／--insecure
Docker コンテナー-e HTTP_PROXY=... で環境変数を渡します。コンテナーからプロキシに接続できるよう、host.docker.internal（Mac／Win）または --network=host（Linux）を使用しますCA をイメージにマウントしてインストールするか、ランタイム固有の回避フラグを使用します

検証を無効にするより、ランタイムまたは OS のトラストストアで HTTP Toolkit の CA を信頼する方法を優先してください。回避フラグはローカル開発用に限って使用してください。

TLS の安全策
  • できる限り、TLS の検証を有効にしておいてください。
  • 検証を無効にする代わりに、ローカルのトラストストアで HTTP Toolkit の CA を信頼する方法を優先してください。
  • ランタイム固有の TLS 検証回避フラグは、開発中の管理されたローカルデバッグでのみ使用してください。
  • 本番環境のトラフィックをインターセプトする際は、TLS を決して無効にしないでください。

キャプチャしたログの確認

関連するイベントのみをフィルタリングする

プログラムが改行区切りの JSON を出力する場合は、jq を使用します。

jq -c 'select(.type == "tool_call" or .type == "message")' /tmp/session-stdout.log

プログラムのイベントスキーマに合わせてフィルターを調整してください。プレーンテキストのログには、rg／grep のパターンを使用します。

アウトバウンド HTTP とインバウンドイベントを照合する

両方のストリームをタイムスタンプ順に並べてから、交互に並べます。通常、次のような順序になります。

outbound POST /api/endpoint        (from HTTP Toolkit)
inbound  event received             (from program log)
inbound  follow-up action           (from program log)
outbound POST /api/endpoint        (next request)

プログラムログにアウトバウンドリクエストが記録されているのに、HTTP Toolkit でキャプチャされていない場合は、プロキシ設定のバグです。

トラブルシューティング

問題原因対処方法
プログラムがハングし、起動後にイベントが発生しないプロキシ環境変数がプロセスに渡されていないか、TLS 検証によりブロックされていますランタイムに適した環境変数を設定して再実行してください（一覧を参照）。必要に応じて、開発時のみランタイムの TLS バイパスを有効にしてください
すべてのリクエストで ECONNRESET / connection reset が発生するランタイム固有のプロキシ環境変数が不足しています（例：Bun の BUN_CONFIG_PROXY、Java の JVM -D フラグ）正しいランタイム固有のプロキシ設定を使用してください
プロキシ経由で TLS 証明書エラーが発生するこのランタイムで MITM CA が信頼されていませんHTTP Toolkit CA をランタイムまたは OS のストアで信頼するか、開発時のみランタイムの TLS バイパスを有効にしてください
/config に対する HTTP Toolkit API の 403 エラー認証が必要な設定エンドポイントです200／401／403 は到達可能として扱ってください。サーバーが停止していることを示すのは接続エラーのみです
エクスポートには送信データがあるのに、対応する受信イベントがないプログラムのログを記録していません起動コマンドに > /tmp/session.log のリダイレクトを追加してください
HTTP Toolkit が最初のリクエストを取りこぼすプロセスの起動後にキャプチャを開始しました先に HTTP Toolkit でキャプチャを開始してから、プログラムを起動してください
コンテナ／VM から 127.0.0.1:8000 に接続できないループバックはコンテナ内に限定されていますhost.docker.internal（Docker Desktop）または --network=host（Linux）を使用してください
プログラムが環境変数をまったく無視するランタイムが環境変数に対応していません（例：JVM）ランタイム固有のフラグを使用してください（JVM の場合は -Dhttp.proxyHost=... など）

コメント

Markdown 対応