Hartrace

hartrace

用于分析 HTTP 流量捕获文件（HAR 文件）的 MCP 服务 — 让 AI Agent 无需将原始 JSON 读入上下文窗口，也能回答有关捕获内容的问题。

其独特功能是值来源追踪：给定任意令牌、Cookie、ID 或载荷字段，hartrace 会重建该值的生成位置（哪个响应设置了它）和使用位置（后续哪些请求发送了它），并以精简时间线呈现。其他所有工具 — 搜索、检查、比较 — 都旨在返回受严格大小限制的小型结构化结果，因此无论捕获文件有多大，分析成本都很低。

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 条记录的捕获文件可能有数 MB；单个 gzip 压缩响应就可能有数百 KB。

hartrace 将提取和关联工作交给服务端处理。工具只返回请求的内容，并设有大小上限。通常需要手动阅读多条记录才能回答的问题 — 这个身份验证令牌从何而来？哪个请求生成了这个 Cookie？这个 ID 在哪里被重复使用？ — 现在一次调用即可解答。

---

功能

• 来源追踪 — trace_value 会追踪任意值在捕获内容中的流转（响应 → 请求），并报告正文内容的 JSON 路径。适用于令牌、Cookie、ID、标头和载荷字段，而不仅限于 Cookie。
• 搜索工具集 — 在 URL、标头以及请求／响应正文中进行完整的正则表达式搜索；查找标头、URL／端点；提取查询参数。
• 检查 — 获取单个请求和响应，并支持 base64 + gzip/deflate 解码、嵌套 JSON 展开、二进制内容检测和大小限制。
• 生命周期映射 — cookie_map 和 token_map 汇总 Cookie 和高熵机密在会话中的流转情况。
• 比较 — 按 (method, url, ordinal) 比较两个捕获文件，使对同一端点的重复调用能够对齐。
• 加载 — 从本地路径或 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)	获取一条已解码的请求；机密信息会被隐藏。
get_response(name, index, max_chars)	获取一条已解码的响应正文（解码 base64/gzip）、展开 JSON，并限制字符数。
get_headers(name, index)	获取一条记录的请求和响应标头。
get_query_params(name, index)	解析一条请求的查询字符串。

搜索

工具	用途
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 会为捕获文件构建关联索引（后续调用会使用缓存）。对于查询的值，系统会将命中项分为两类：

• set_by — 生成该值的响应：Set-Cookie 标头，或响应正文（如果该值位于可解析的 JSON 中，还会提供 JSON 路径）。
• used_in — 后续发送该值的请求：请求标头、Cookie 或请求正文中的字段（适用时也会提供 JSON 路径）。

set_by 为空表示该值由客户端提供，而非任何已捕获的响应生成，例如预先存在的 OAuth 令牌。origin 是最早生成该值的位置；timeline 是按顺序排列的受影响记录索引列表。

长度不足 4 个字符的值会被拒绝，因为短字符串会匹配到各处，产生的结果只是噪声而非有效信号。

---

设计与安全

• 仅使用 stdio 传输。 服务按照 MCP 规范通过 stdin/stdout 通信。所有日志都写入 stderr，因此不会干扰协议流。没有 Web UI、端口或后台进程。
• 限制输出大小。 列表和搜索工具使用 limit/offset 分页，且服务端会限制上限（请求一百万行时只会返回上限数量，而不是一百万行）。响应正文受 max_chars 限制。这些限制使 token 用量可预测。
• 限制内存用量。 超过 500 MB 或包含 50,000 个条目的捕获数据会被拒绝；嵌套 JSON 解码也设有深度和大小限制。
• 脱敏。 检查工具会将敏感标头值和高熵密钥屏蔽为 <REDACTED len=N>，依据的是可配置的标头列表和通用的香农熵启发式算法，而非特定供应商的 token 格式。来源追踪工具会根据真实值进行关联，但只显示脱敏后的预览。（find_header 会按设计返回原始值，因为其用途是提取值以便追踪。）
• SSRF 防护。 load_har_url 会拒绝非 http(s) 协议，以及解析到私有、环回、链路本地、保留或多播地址的任何主机（包括云元数据端点），并限制下载文件的大小。
• 不会跨边界抛出异常。 工具在失败时都会返回结构化的 {error: "..."}，而不是抛出异常，因此 Agent 始终能收到可执行的消息。

服务不包含任何特定供应商的逻辑。嵌套 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（默认值）时，标头值会原样返回——检查输出中会显示真实 token。设为 true 后，sensitive_headers 中任何标头的值都会被屏蔽为 <REDACTED len=N>，适合分享输出或在信任度较低的环境中工作时使用。
entropy_min_len / entropy_bits_min	24 / 3.5	无论此标志的值如何，高熵的不透明字符串都会被脱敏。熵检查始终启用。

注意：find_header 按设计始终返回原始值——它专门用于提取值，以便将其传递给 trace_value。

---

许可证

MIT。请参阅 LICENSE。