Headroom MCP Server 实战：让编码 Agent 按需压缩、按哈希取回原文并观测会话节省

Headroom MCP Server 实战：让编码 Agent 按需压缩、按哈希取回原文并观测会话节省

【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom

Headroom 的 MCP Server 把 Headroom 的压缩、取回与观测能力封装为三个可被任意 MCP 宿主（Claude Code、Cursor、Codex 等）直接调用的工具：headroom_compress、headroom_retrieve、headroom_stats。读完本文，你将掌握如何把 Headroom 以"无代理"模式接入编码工具、理解每个工具的参数与返回契约、弄清"本地 CompressionStore + 代理回退"的双源取回链路，以及子 Agent 统计如何通过共享 JSONL 文件跨进程聚合，并能在排障时依据源码定位问题。

一、MCP Server 定位：CCR 管线的 Agent 侧出口

Headroom 的核心压缩范式是 CCR（Compress-Cache-Retrieve）：先压缩大体积工具输出/文件/搜索结果，把原文存入带 TTL 的本地压缩存储并返回哈希；Agent 需要细节时凭哈希取回。MCP Server 就是把这条范式做成标准 MCP 工具，使 LLM 能在推理过程中主动触发压缩，而不必依赖代理在 HTTP 层自动改写流量。

服务器实现在 headroom/ccr/mcp_server.py，模块 docstring 明确列出了三个工具：

• headroom_compress— 按需压缩内容（无需代理）；
• headroom_retrieve— 凭哈希取回原文（本地存储优先，可回退代理）；
• headroom_stats— 会话压缩统计。

传输层默认使用 stdio（由 MCP 宿主以子进程方式拉起headroom mcp serve），也支持 Streamable HTTP 传输，见 headroom/cli/mcp.py 中serve命令的--transport {stdio,http}选项。

二、快速开始：从安装到工具就绪

最轻量的接入只需三步（对应 wiki 文档 Quick Start 一节）：

# 安装（MCP 随 proxy 附带，也可单独安装） pip install "headroom-ai[proxy]" # Proxy + MCP 工具 pip install "headroom-ai[mcp]" # 仅 MCP 工具（轻量） # 注册到 Claude Code（一次性） headroom mcp install # 启动 Claude Code —— 此时已拥有 headroom 工具 claude

完成后 Claude Code 就能按需压缩内容、按哈希取回原文、查看会话统计，全程不依赖代理。

从源码看，headroom mcp install会把["headroom", "mcp", "serve"]这一命令写入 Agent 的 MCP 配置。headroom/cli/mcp.py 中的get_headroom_command()返回该命令；find_headroom_registration()会依次检查~/.claude.json、~/.claude/mcp.json与项目内./.mcp.json三处注册位置，因此status检查不会只看单一文件而产生误判。

若要所有流量自动压缩，再叠加代理（文档中给出的双终端用法）：

# 终端 1 headroom proxy # 终端 2 ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude

此时请求经代理自动压缩，MCP 工具仍可叠加使用，二者互不干扰（详见架构一节）。

三、三个核心工具逐一拆解

3.1 headroom_compress — 按需压缩

工具描述与输入 schema 在 headroom/ccr/mcp_server.py 的list_tools()注册：

工具: headroom_compress 参数: - content（必填）: 待压缩文本（文件内容、JSON、日志、搜索结果、代码等） 返回: - compressed: 压缩后文本 - hash: 供后续取回原文的哈希键 - original_tokens / compressed_tokens / savings_percent - transforms: 实际应用的压缩变换列表

文档示例中 Claude 读入大文件后调用压缩：

Claude: Let me compress this large output to save context space. → headroom_compress(content="[5000 lines of grep results...]") ← { "compressed": "[key matches with context...]", "hash": "a1b2c3d4e5f6...", "original_tokens": 12000, "compressed_tokens": 3200, "savings_percent": 73.3, "transforms": ["router:search:0.27"] }

源码链路（HeadroomMCPServer._compress_content）：

1. 把传入content包装为一条{"role": "tool", "content": content}消息——工具输出是压缩最常见的目标；
2. 调用 headroom/compress.py 的compress(messages, model="claude-sonnet-4-5-20250929")走完整压缩管线，得到tokens_before/tokens_after与transforms_applied；
3. 将原文以compression_strategy="mcp_compress"、显式 TTL = 3600 秒存入本地 CompressionStore 单例（MCP_SESSION_TTL = 3600），返回哈希；
4. savings_percent由(1 - output_tokens / input_tokens) * 100推导，且源码注释特意记录了一个历史缺陷修复：旧版曾用(1 - compression_ratio)，而compression_ratio本身就是"已节省比例"，导致无节省时反而报告 100%。

压缩在call_tool分发中以线程池执行（run_in_executor），因为它是 CPU 密集操作。另外，每次有效压缩还会通过 headroom/savings_ledger.py 追加一条持久节省事件（source="mcp"），使headroom savings跨进程重启仍能记账；该写入是尽力而为，失败不会中断工具本身。

原文在本地按会话保留 1 小时（TTL 1 小时，与 MCP 进程寿命对齐）。若之后需要完整内容，Claude 调用headroom_retrieve。

3.2 headroom_retrieve — 按哈希取回原文

工具: headroom_retrieve 参数: - hash（必填）: 压缩时返回的哈希键 - query（可选）: 在原文中搜索并仅返回匹配项 返回: - original_content（完整取回）或 results（搜索） - source: "local" 或 "proxy"

取回顺序在_retrieve_content中实现，逻辑与文档描述一致：

1. 先查本地存储：调用CompressionStore.get_entry_status()+retrieve()。命中则返回source: "local"、原文，以及original_item_count/compressed_item_count/retrieval_count等元信息；
2. 再回退代理：本地未命中且启用了代理检查时，POST {proxy_url}/v1/retrieve，JSON 载荷为{"hash": ...}，超时 15 秒；404 时返回 "Not found in proxy store"。命中标记source: "proxy"。

因此无论是headroom_compress压的内容还是代理自动压缩的内容，哈希对同一取回入口都透明可用。

两点与源码对照的补充：

• 过期诊断：若本地条目存在但已过期，返回体带status: "expired"、ttl_seconds、age_seconds，并附明确提示"Do not retry the same hash. Re-run the source command or re-read the source file"，引导 Agent 回到真实数据源重新生成，而不是反复重试同一哈希；
• 当前注册 schema：从源码结构看，call_tool注册的headroom_retrieve输入 schema 目前只声明了必填的hash参数（"query" 搜索入参在当前版本未出现在注册 schema 中），实际以仓库中 headroom/ccr/mcp_server.py 的list_tools()为准。

3.3 headroom_stats — 会话统计

工具: headroom_stats 返回: - compressions, retrievals, tokens_saved, savings_percent - estimated_cost_saved_usd - recent_events（最近 10 条压缩/取回事件） - sub_agents（子代理 MCP 实例的统计，如有） - combined（主会话 + 子代理合计） - proxy（请求数、缓存命中、节省成本 —— 若代理在运行）

源码中SessionStats数据结构维护压缩次数、取回次数、输入/输出 token 总量，内存中只保留最近 50 条事件，recent_events输出最近 10 条。成本估算采用源码注释中的混合费率（约 $3/百万输入 token）：estimated_cost_saved_usd = tokens_saved * 3.0 / 1_000_000（四舍五入到 4 位小数），是一个粗估而非精确账单。

_handle_stats的聚合分三层：

1. 本进程统计+ 本地存储条目数（store字段）；
2. 跨进程聚合：读取共享事件文件（见下一节），把pid不等于自身的其他 MCP 实例（通常是子代理）的压缩/取回事件汇总进sub_agents与combined；
3. 代理摘要：若代理可达，GET {proxy_url}/stats取完整统计；当代理返回了summary时，headroom_stats会改用_format_session_summary()输出格式化的"Window-Scoped Session Summary"，涵盖压缩率、未压缩请求原因（如 prefix_frozen、too_small <500 tokens、passthrough）、成本对比（without/with Headroom）与跨会话的 Lifetime Savings。代理不可达时则通过/livez探测并在返回体中给出warning。

3.4 扩展能力：headroom_read（特性开关后）

除文档所述的三个工具外，源码中还注册了一个受特性开关控制的第四个工具：设置环境变量HEADROOM_MCP_READ=on后出现headroom_read。首次读取文件返回带行号全文并把原文存入 CompressionStore（compressed占位仅 5 token）；同一文件内容未变且缓存条目未过期时，后续读取只返回一个约 20 token 的缓存标记（status: "cached"加 hash），需要全文时再用headroom_retrieve取回。这是"读文件缓存"场景下把重复读取成本压到极低的实现，见 headroom/ccr/mcp_server.py 的_handle_read。

四、架构：MCP Only 与 MCP + Proxy 两种部署

4.1 MCP Only（无代理）

┌─────────────────────────────────────────────┐ │ Claude Code / Cursor / Codex │ │ │ │ LLM calls headroom_compress on demand │ │ ↓ │ │ Compression happens locally in MCP process │ │ Original stored in local CompressionStore │ │ ↓ │ │ LLM calls headroom_retrieve when needed │ └─────────────────────────────────────────────┘

压缩与取回全部发生在 MCP 进程内，零外部依赖，适合只想"按需压缩"的轻量场景。

4.2 MCP + Proxy（完整配置）

┌─────────────────────────────────────────────┐ │ Claude Code │ │ │ │ 1. Sends request ──→ Proxy (auto-compress) │ │ 2. Gets response with compressed outputs │ │ 3. Can call headroom_compress for more │ │ 4. headroom_retrieve checks: │ │ local store → proxy store │ └──────────────┬──────────────────────────────┘ │ MCP (stdio) ▼ ┌─────────────────────────────────────────────┐ │ Headroom MCP Server │ │ ├── headroom_compress (local compression) │ │ ├── headroom_retrieve (local + proxy) │ │ └── headroom_stats (aggregated stats) │ └─────────────────────────────────────────────┘

不会发生双重压缩：代理在 HTTP 层压缩（LLM 看到内容之前），MCP 工具作用于 LLM 已接收的内容，两者不触碰同一份数据。取回路径也因此天然统一——本地哈希查本地存储，代理哈希查代理/v1/retrieve，同一工具入口透明完成。

可靠性细节：run_stdio()中并行运行了一个父进程死亡看门狗（每 5 秒轮询os.getppid()）。当启动 MCP 服务的客户端被 SIGKILL 时，stdin EOF 可能永远不会到达，SDK 的阻塞式 stdin 读线程会卡死server.run()，使 MCP 进程孤儿化；看门狗在进程被重新挂载到 init 后主动以os._exit(0)清理自身。

五、子 Agent 统计聚合与文件系统契约

子代理统计的聚合依赖一个共享统计文件：每个 MCP 服务器实例（主会话与子代理各起一个进程）都会把事件追加写入${HEADROOM_WORKSPACE_DIR}/session_stats.jsonl（默认~/.headroom/session_stats.jsonl），headroom_stats再跨实例读取汇总。

源码要点：

• 路径解析在 headroom/paths.py：workspace_dir()按$HEADROOM_WORKSPACE_DIR（裁剪、展开 tilde）→~/.headroom的顺序解析；session_stats_path()返回workspace_dir() / session_stats.jsonl；
• 写入用fcntl.flock排他锁保证跨进程安全（仅追加单行 JSON，附带pid字段）；Windows 下无fcntl，统计退化为尽力而为，注释明确"绝不因统计破坏压缩"；
• 读取时只保留最近2 小时（SESSION_WINDOW_SECONDS = 7200）内的事件，并把过期行原地剪除。

该路径属于 Headroom 的"workspace 桶"（运行时读写状态），完整的路径契约、Docker 容器内行为与HEADROOM_WORKSPACE_DIR/HEADROOM_CONFIG_DIR两个根变量的优先级规则，见 wiki/filesystem-contract.md。

六、CLI 命令全解

以下命令均出自headroom mcp命令组（headroom/cli/mcp.py）。

安装（install）

headroom mcp install # 默认安装 headroom mcp install --proxy-url http://host:9000 # 自定义代理 URL headroom mcp install --force # 覆盖已有配置

补充源码中的完整选项：

安装前会先验证 MCP SDK 可用（import mcp），缺失则提示pip install 'headroom-ai[mcp]'。实际注册由 headroom/mcp_registry/ 下的各 registrar 完成（当前包含 Claude、Codex、Grok、OpenCode 等注册器与统一的install_everywhere逻辑）。安装成功后 CLI 会打印下一步：启动代理 → 以ANTHROPIC_BASE_URL={proxy_url}启动 Agent → 重启已在运行的 Agent 以加载新 MCP 服务器。

状态检查（status）

headroom mcp status

文档中的示例输出：

Headroom MCP Status ======================================== MCP SDK: ✓ Installed Claude Config: ✓ Configured /Users/you/.claude/mcp.json Proxy URL: http://127.0.0.1:8787 Proxy Status: ✓ Running at http://127.0.0.1:8787

当前实现的检查项：MCP SDK 是否安装；逐个已检测 Agent 的配置状态（从各 registrar 读取headroom服务器配置，并从中提取实际HEADROOM_PROXY_URL）；最后用 httpx 请求{proxy_url}/health（2 秒超时）判断代理是否存活，区分"未运行 / 超时 / 非 200 / 不可达"多种状态。

卸载（uninstall）

headroom mcp uninstall

遍历所有已知 registrar，移除headroom（及codebase-memory-mcp）条目，其他 MCP 服务器保持不变；无任何条目时提示 "Nothing to uninstall."。

调试（serve --debug）

headroom mcp serve --debug

手动调试用；完整选项包括：

• --transport stdio|http：默认 stdio（由 Agent 调用）；http 即 Streamable HTTP，配合--host（默认127.0.0.1）、--port（默认8788）、--path（默认/mcp）供非 stdio 的 MCP 宿主接入；
• --proxy-url：默认取环境变量HEADROOM_PROXY_URL，否则http://127.0.0.1:8787；
• --debug：DEBUG 级日志（注意 stdio 传输下 stdout 是协议通道，故非 debug 时仅 WARNING 级）；
• --direct：已弃用，会被忽略并打印警告（直接访问 CompressionStore 的旧模式不再支持）。

七、跨工具兼容性

MCP Server 适用于任意 MCP 兼容宿主（继承原文档表格）：

非 stdio 宿主可直接用headroom mcp serve --transport http启动 HTTP 端点。源码中mcp_registry已内置 Claude / Codex / Grok / OpenCode 等多个 registrar，headroom mcp install会逐一探测并在检测到的 Agent 上完成注册。

一个命名细节（来自 headroom/cli/mcp.py 的 docstring）：MCP 客户端会把工具显示为mcp__<server>__<tool>，服务器名是headroom、工具名本身也带headroom_前缀，因此 Claude Code 中会看到mcp__headroom__headroom_retrieve这样的"headroom"重复——这是正常的 MCP 命名空间行为，不是 bug；代理压缩标记与提示词中引用的始终是裸工具名headroom_retrieve。

八、故障排查

以下条目继承原文档 Troubleshooting 并补充源码依据：

"MCP SDK not installed"

pip install "headroom-ai[mcp]"

install/serve都会先import mcp校验，失败即退出并给出该安装命令。

"Proxy not running"（使用代理功能时）

headroom proxy # 在另一个终端

注意：代理未运行不影响纯 MCP 压缩（本地压缩+取回），仅影响代理侧取回回退与headroom_stats中的代理摘要；此时 compress 返回体会带proxy: unreachable与warning字段，由_probe_proxy_unreachable()经/livez探测生成。

"Entry not found or expired"

• headroom_compress压缩的内容：本地保存 1 小时（会话 TTL，对应源码MCP_SESSION_TTL = 3600）；
• 代理压缩的内容：按代理侧 CompressionStore 的 CCR 默认 TTL 保存（wiki 记录为 5 分钟；该 TTL 可通过存储配置/环境变量调整，见 headroom/cache/compression_store.py 的default_ttl解析逻辑）；
• 取回代理侧内容要求代理正在运行。

过期返回体会附带hint：让 Agent 回到真实数据源（重跑命令、重读文件）而非重试同一哈希。

Claude 看不到 headroom 工具

1. 运行headroom mcp status检查 SDK、Agent 配置与代理三项；
2. 安装 MCP 后重启 Claude Code；
3. 在 Claude Code 内用/mcp验证——应能看到 3 个 headroom 工具（开启HEADROOM_MCP_READ=on时为 4 个）。

子代理统计不显示

子代理统计只有在其实际执行过压缩后才会出现在headroom_stats的sub_agents/combined字段中；确认共享文件位于${HEADROOM_WORKSPACE_DIR}/session_stats.jsonl（默认~/.headroom/session_stats.jsonl），且事件在 2 小时滚动窗口内。

九、延伸阅读：关键源码与文档索引

【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom