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/headroomHeadroom 的 MCP Server 把 Headroom 的压缩、取回与观测能力封装为三个可被任意 MCP 宿主Claude Code、Cursor、Codex 等直接调用的工具headroom_compress、headroom_retrieve、headroom_stats。读完本文你将掌握如何把 Headroom 以无代理模式接入编码工具、理解每个工具的参数与返回契约、弄清本地 CompressionStore 代理回退的双源取回链路以及子 Agent 统计如何通过共享 JSONL 文件跨进程聚合并能在排障时依据源码定位问题。一、MCP Server 定位CCR 管线的 Agent 侧出口Headroom 的核心压缩范式是 CCRCompress-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_URLhttp://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把传入content包装为一条{role: tool, content: content}消息——工具输出是压缩最常见的目标调用 headroom/compress.py 的compress(messages, modelclaude-sonnet-4-5-20250929)走完整压缩管线得到tokens_before/tokens_after与transforms_applied将原文以compression_strategymcp_compress、显式 TTL 3600 秒存入本地 CompressionStore 单例MCP_SESSION_TTL 3600返回哈希savings_percent由(1 - output_tokens / input_tokens) * 100推导且源码注释特意记录了一个历史缺陷修复旧版曾用(1 - compression_ratio)而compression_ratio本身就是已节省比例导致无节省时反而报告 100%。压缩在call_tool分发中以线程池执行run_in_executor因为它是 CPU 密集操作。另外每次有效压缩还会通过 headroom/savings_ledger.py 追加一条持久节省事件sourcemcp使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中实现逻辑与文档描述一致先查本地存储调用CompressionStore.get_entry_status()retrieve()。命中则返回source: local、原文以及original_item_count/compressed_item_count/retrieval_count等元信息再回退代理本地未命中且启用了代理检查时POST {proxy_url}/v1/retrieveJSON 载荷为{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/百万输入 tokenestimated_cost_saved_usd tokens_saved * 3.0 / 1_000_000四舍五入到 4 位小数是一个粗估而非精确账单。_handle_stats的聚合分三层本进程统计 本地存储条目数store字段跨进程聚合读取共享事件文件见下一节把pid不等于自身的其他 MCP 实例通常是子代理的压缩/取回事件汇总进sub_agents与combined代理摘要若代理可达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_READon后出现headroom_read。首次读取文件返回带行号全文并把原文存入 CompressionStorecompressed占位仅 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.jsonlheadroom_stats再跨实例读取汇总。源码要点路径解析在 headroom/paths.pyworkspace_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。安装installheadroom mcp install # 默认安装 headroom mcp install --proxy-url http://host:9000 # 自定义代理 URL headroom mcp install --force # 覆盖已有配置补充源码中的完整选项选项说明--proxy-url URL代理 URL默认http://127.0.0.1:8787写入配置的HEADROOM_PROXY_URL环境变量--agent NAME可多次限定只安装到指定 Agent默认安装到所有已检测到的 Agent--force配置不一致时覆盖已有的 headroom 配置安装前会先验证 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 服务器。状态检查statusheadroom 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}/health2 秒超时判断代理是否存活区分未运行 / 超时 / 非 200 / 不可达多种状态。卸载uninstallheadroom mcp uninstall遍历所有已知 registrar移除headroom及codebase-memory-mcp条目其他 MCP 服务器保持不变无任何条目时提示 Nothing to uninstall.。调试serve --debugheadroom 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--debugDEBUG 级日志注意 stdio 传输下 stdout 是协议通道故非 debug 时仅 WARNING 级--direct已弃用会被忽略并打印警告直接访问 CompressionStore 的旧模式不再支持。七、跨工具兼容性MCP Server 适用于任意 MCP 兼容宿主继承原文档表格工具MCP 支持配置方式Claude Code原生headroom mcp installCursor支持添加到 Cursor 的 MCP 设置Codex若支持配置 MCP server任意 MCP 宿主是指向headroom mcp serve非 stdio 宿主可直接用headroom mcp serve --transport http启动 HTTP 端点。源码中mcp_registry已内置 Claude / Codex / Grok / OpenCode 等多个 registrarheadroom mcp install会逐一探测并在检测到的 Agent 上完成注册。一个命名细节来自 headroom/cli/mcp.py 的 docstringMCP 客户端会把工具显示为mcp__server__tool服务器名是headroom、工具名本身也带headroom_前缀因此 Claude Code 中会看到mcp__headroom__headroom_retrieve这样的headroom重复——这是正常的 MCP 命名空间行为不是 bug代理压缩标记与提示词中引用的始终是裸工具名headroom_retrieve。八、故障排查以下条目继承原文档 Troubleshooting 并补充源码依据MCP SDK not installedpip 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 expiredheadroom_compress压缩的内容本地保存 1 小时会话 TTL对应源码MCP_SESSION_TTL 3600代理压缩的内容按代理侧 CompressionStore 的 CCR 默认 TTL 保存wiki 记录为 5 分钟该 TTL 可通过存储配置/环境变量调整见 headroom/cache/compression_store.py 的default_ttl解析逻辑取回代理侧内容要求代理正在运行。过期返回体会附带hint让 Agent 回到真实数据源重跑命令、重读文件而非重试同一哈希。Claude 看不到 headroom 工具运行headroom mcp status检查 SDK、Agent 配置与代理三项安装 MCP 后重启 Claude Code在 Claude Code 内用/mcp验证——应能看到 3 个 headroom 工具开启HEADROOM_MCP_READon时为 4 个。子代理统计不显示子代理统计只有在其实际执行过压缩后才会出现在headroom_stats的sub_agents/combined字段中确认共享文件位于${HEADROOM_WORKSPACE_DIR}/session_stats.jsonl默认~/.headroom/session_stats.jsonl且事件在 2 小时滚动窗口内。九、延伸阅读关键源码与文档索引主题路径本文核心文档wiki/mcp.mdMCP Server 实现三工具注册、取回回退、统计聚合、stdio/HTTP 传输headroom/ccr/mcp_server.pyCLI 命令组install / status / uninstall / serveheadroom/cli/mcp.py多 Agent 注册器headroom/mcp_registry/压缩管线入口compress()headroom/compress.py本地压缩存储与 TTL 逻辑headroom/cache/compression_store.py持久节省账本headroom/savings_ledger.py路径契约workspace/config 双根、优先级headroom/paths.py、wiki/filesystem-contract.mdMCP 使用示例examples/mcp_demo/【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考