Hartrace

hartrace

HTTP トラフィックのキャプチャ（HAR ファイル）を分析するための MCP サーバーです。AI エージェントが、キャプチャの生の JSON をコンテキストウィンドウに読み込まずに質問へ回答できるように設計されています。

特徴は値の来歴追跡です。任意のトークン、Cookie、ID、ペイロードのフィールドについて、その値がどこで生成された（どのレスポンスが設定した）か、またどこで使用された（後続のどのリクエストが送信した）かを、簡潔なタイムラインとして再構成します。検索、検査、差分比較など、ほかのすべてのツールも、ハードサイズ上限付きの小さく構造化された結果を返すように設計されているため、キャプチャのサイズにかかわらず分析を低コストに保てます。

load_har("session.har")
trace_value("session", "<csrf token>")
  → set_by:  response #4 body, JSON path data.csrf
  → used_in: request #9 header X-CSRF, request #9 body field token

---

このツールが作られた理由

HAR ファイルは大きく、階層が深く、繰り返しが多く含まれています。AI がこれらを分析する一般的な方法はどちらも問題があります。セッションごとに使い捨ての抽出スクリプトを書くか、生の HAR JSON をコンテキストウィンドウに貼り付ける方法です（遅く、コストがかかり、実際のデータでは容量を超えてしまいます）。100 件のエントリを含むキャプチャは数メガバイトになることがあり、単一の gzip 圧縮レスポンスが数百キロバイトに達することもあります。

hartrace は抽出と関連付けをサーバー側で行います。ツールは要求された内容だけを、上限付きで返します。通常なら多くのエントリを手作業で読む必要がある「この認証トークンはどこから来たのか？」「この Cookie を生成したリクエストはどれか？」「この ID はどこで再利用されているか？」といった質問にも、1 回の呼び出しで回答できます。

---

機能

• 来歴追跡 — trace_value はキャプチャ全体で任意の値を追跡し（レスポンス → リクエスト）、本文のフィールドについて JSON パスを報告します。Cookie だけでなく、トークン、ID、ヘッダー、ペイロードのフィールドにも対応します。
• 検索ツールキット — URL、ヘッダー、リクエスト／レスポンス本文を対象とする正規表現による全文検索、ヘッダー検索、URL／エンドポイント検索、クエリパラメーターの抽出に対応します。
• 検査 — リクエストおよびレスポンスごとのデータを取得できます。base64 と gzip／deflate のデコード、ネストされた JSON の展開、バイナリ判定、サイズ上限に対応します。
• ライフサイクルマップ — cookie_map と token_map は、セッション内で Cookie と高エントロピーのシークレットがどのように流れるかを要約します。
• 差分比較 — (method, url, ordinal) を基準に 2 つのキャプチャを比較し、同じエンドポイントへの呼び出しが繰り返されていても対応付けます。
• 読み込み — ローカルパスまたは http(s) URL から読み込みます（SSRF 対策とサイズ上限付き）。
• 設計上の安全性 — すべてのリスト／検索ツールはサーバー側で制限された上限付きでページネーションを行います。検査結果ではシークレットをマスキングし、どのツールもトランスポートに例外を送出せず、エラーは構造化された値として返します。

---

インストール

Python 3.10 以降が必要です。

# recommended — isolated install
pipx install hartrace

# zero-install with uv
uvx hartrace

# plain pip
pip install hartrace

# from source
git clone https://github.com/rafsanbasunia/hartrace
cd hartrace
pip install -e .

実行時の依存関係は fastmcp のみです。

---

Claude Desktop ですぐに使う

サーバーを claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "hartrace": {
      "command": "uvx",
      "args": ["hartrace"]
    }
  }
}

または、ソースから実行します。

{
  "mcpServers": {
    "hartrace": {
      "command": "python",
      "args": ["/absolute/path/to/hartrace/har_mcp.py"]
    }
  }
}

Claude Desktop を再起動し、自然な言葉で話しかけてください。

「~/captures/login.har を読み込んで、CSRF トークンがどこから来たか教えてください。」 「セッション Cookie を再利用するリクエストはどれですか？」 「before.har と after.har を比較して、何が新しいか教えてください。」

その他の MCP クライアント

hartrace は標準的な stdio MCP サーバーなので、MCP 対応のあらゆるクライアントで利用できます。異なるのは設定ファイルとラッパーキーだけです。

• Cursor（.cursor/mcp.json）と Windsurf では、上記と同じ "mcpServers" ブロックを使用します。

• VS Code（.vscode/mcp.json）では、明示的なタイプを指定した "servers" キーを使用します。

  {
    "servers": {
      "hartrace": { "type": "stdio", "command": "uvx", "args": ["hartrace"] }
    }
  }
  

どの場合も、command／args は Claude Desktop の例と同じです。

---

ツール

hartrace は 19 個のツールを公開します。読み込んだキャプチャは、load_har が返す name で指定してください。

読み込み

ツール	目的
list_har_files(dir)	ディレクトリ内の .har ファイルを一覧表示し、選択できるようにします。
load_har(path)	ローカルパスからキャプチャを読み込みます。割り当てられた name を返します。
load_har_url(url)	http(s) URL からキャプチャを読み込みます（SSRF 対策済み、サイズ上限あり）。
list_hars()	現在読み込まれているキャプチャを一覧表示します。
unload_har(name)	メモリを解放するため、キャプチャを破棄します。

検査

ツール	目的
list_requests(name, filter, …)	概要行を表示します：インデックス、メソッド、URL、ステータス、レスポンスサイズ。
get_request(name, index)	1 件のリクエストをデコードして表示します。シークレットはマスキングされます。
get_response(name, index, max_chars)	1 件のレスポンスボディをデコードして表示します（base64/gzip を展開し、JSON をラップ解除して、文字数を制限します）。
get_headers(name, index)	1 件のエントリのリクエストヘッダーとレスポンスヘッダーを表示します。
get_query_params(name, index)	1 件のリクエストのクエリ文字列を解析します。

検索

ツール	目的
search_regex(name, pattern, scope)	url | req_headers | resp_headers | req_body | resp_body | all を対象に正規表現で検索します。
find_header(name, header_name)	指定したヘッダーを含むすべてのエントリを、未加工の値とともに返します。
find_urls(name, pattern)	URL がパターンに一致するリクエストを検索します。
list_endpoints(name, group_by)	呼び出し回数とともに、一意なエンドポイントを一覧表示します。

出所

ツール	目的
trace_value(name, value)	値が設定された場所と使用された場所を、全タイムラインで追跡します。
trace_header(name, header_name)	ヘッダーの値を特定し、その出所を追跡します。
cookie_map(name)	すべての Cookie の設定・使用履歴と属性を表示します。
token_map(name, all_tokens)	エントロピーの高いシークレットと、その伝播状況を表示します。

比較

ツール	目的
diff_hars(a, b)	各キャプチャにのみ存在するリクエストを表示します。(method, url, ordinal) で照合します。

各ツールの完全な説明（引数の意味や実例を含む）は、MCP プロトコルを通じてモデルが利用できます。

---

出所の追跡の仕組み

最初の追跡時に、hartrace はキャプチャ全体を対象に相関インデックスを構築します（以降の呼び出しではキャッシュを使用します）。指定された値について、該当箇所を次の 2 つに分けます。

• set_by — 値を生成したレスポンスです。Set-Cookie ヘッダー、またはレスポンスボディ（値が解析可能な JSON 内にある場合は JSON パスも含みます）が該当します。
• used_in — 値を送信した後続のリクエストです。リクエストヘッダー、Cookie、リクエストボディのフィールドが該当します（該当する場合は JSON パスも含みます）。

set_by が空の場合、その値はキャプチャされたレスポンスによって生成されたのではなく、クライアントから渡されたことを意味します。たとえば、あらかじめ存在していた OAuth トークンが該当します。origin は最初の生成元で、timeline は対象となったエントリのインデックスを時系列順に並べたリストです。

4 文字未満の値は受け付けません。短い文字列はあらゆる場所に一致しやすく、結果に有用な情報が含まれず、ノイズになるためです。

---

設計と安全性

• stdio トランスポートのみです。 サーバーは MCP 仕様に従って stdin/stdout 経由で通信します。ログはすべて stderr に出力されるため、プロトコルストリームが破損することはありません。ウェブ UI、ポート、バックグラウンドプロセスはありません。
• 出力に上限があります。 リストツールと検索ツールは limit/offset でページネーションし、上限はサーバー側で適用されます（100 万行をリクエストしても、100 万行ではなく上限まで返されます）。レスポンス本文には max_chars の上限があります。これらの上限により、トークン使用量を予測できます。
• メモリ使用量に上限があります。 500 MB または 50,000 件を超えるキャプチャは拒否されます。ネストされた JSON のデコードには、深さとサイズの制限があります。
• 機密情報のマスキング。 検査ツールは、機密性の高いヘッダー値とエントロピーの高いシークレットを <REDACTED len=N> としてマスキングします。設定可能なヘッダーリストと、ベンダー固有のトークン形式に依存しない汎用的なシャノンエントロピーのヒューリスティックを使用します。プロベナンスツールは実際の値で照合しますが、表示するのはマスキングされたプレビューのみです。（find_header は値を抽出して追跡することが目的のため、意図的に生の値を返します。）
• SSRF 対策。 load_har_url は http(s) 以外のスキーム、およびプライベート、ループバック、リンクローカル、予約済み、マルチキャストのいずれかのアドレスに解決されるホスト（クラウドメタデータエンドポイントを含む）を拒否し、ダウンロードにもサイズ上限を適用します。
• 境界を越えて例外を送出しません。 すべてのツールは、失敗時に例外を送出するのではなく、構造化された {error: "..."} を返すため、エージェントには常に対処可能なメッセージが届きます。

サーバーにはベンダー固有のロジックは含まれていません。ネストされた JSON の展開などのヘルパーは汎用的で、どのような深くネストされたレスポンスにも適用できます。

---

開発

pip install -e ".[dev]"
pytest

テストスイートでは、解析とデコード、マスキングとエントロピー検出、プロベナンスの追跡（Cookie 値と Cookie 以外の値、JSON パスの解決）、検索ツールキット、URL の読み込みと SSRF 対策、および実際の FastMCP 呼び出し経路を通じたツールをテストします。

レイアウト：

har_mcp.py      MCP server: tool definitions and the stdio entry point
har_parser.py   Parsing, decoding, redaction, and the in-memory store
provenance.py   Correlation index and the trace / cookie / token tools
search.py       Regex, header, URL, and endpoint search
config.json     Redaction settings (sensitive headers, entropy thresholds)
tests/          pytest suite

---

設定

config.json では、コードを変更せずにマスキングを調整できます。

{
  "sensitive_headers": ["authorization", "cookie", "set-cookie", "x-csrf-token", "x-api-key"],
  "redact_sensitive_headers": false,
  "entropy_min_len": 24,
  "entropy_bits_min": 3.5
}

キー	デフォルト	効果
sensitive_headers	一般的な認証ヘッダー	redact_sensitive_headers が true の場合に値をマスキングするヘッダー名です。このフラグが false の場合、効果はありません。
redact_sensitive_headers	false	false（デフォルト）の場合、ヘッダー値はそのまま返され、検査出力に実際のトークンが表示されます。true に設定すると、sensitive_headers に含まれるヘッダーの値が <REDACTED len=N> としてマスキングされます。出力を共有する場合や、信頼性の低い環境で作業する場合に便利です。
entropy_min_len / entropy_bits_min	24 / 3.5	エントロピーの高い不透明な文字列は、このフラグの設定にかかわらずマスキングされます。エントロピーのチェックは常に有効です。

注：find_header は設計上、常に生の値を返します。値を抽出し、trace_value に渡すことを目的としています。

---

ライセンス

MIT。詳細は LICENSE を参照してください。