Headroom

社区

面向 AI Agent 的本地上下文压缩层

分类: 开发工具第 121 / 438
Stars: ★ 75.9k 非常热门
传输方式: stdio（本地进程）
运行环境: Python 3.10+
凭据: 无需凭据
许可证: Apache-2.0
最近提交: 9 天前
工具数: 3

60FMRS · C

来源显示 Headroom 是 Apache-2.0 开源项目提供的本地 MCP 服务器，版本 0.32.0，包含 headroom_compress、headroom_retrieve 和 headroom_stats。证据支持 stdio 部署及 uvx 安装；未提供特定 MCP 客户端完整兼容性清单或认证信息。

最强项 · 文档质量 15/20 最弱项 · 可靠性 9/20

可靠性

9/20

安全与权限

11/20

维护活跃度

12/20

文档质量

15/20

安装易用性

13/20

查看各项评分依据

可靠性 9/20: Manifest 提供了明确的 PyPI、uvx、stdio 启动契约，README 也声明了三个 MCP 工具；但未提供服务器源码、提交的测试或 CI 工作流内容来验证初始化、工具列表、参数和错误路径。依赖模型下载、ONNX 运行时及多种可选后端也增加了失败面，因此仅给出中低分。
安全与权限 11/20: README 声称本地运行且数据留在本机，未发现凭据窃取、恶意软件或默认远程命令等红线行为；但文档涉及代理转发、外部 TLS 下载、共享记忆、CCR 本地缓存以及写入 CLAUDE/AGENTS 等文件，未充分说明权限边界、敏感数据生命周期、访问控制或危险操作确认机制，因此扣分。
维护活跃度 12/20: 项目声明 Apache-2.0，提供明确仓库、网站和 PyPI 版本 0.32.0，且非归档；README 还显示较高关注度和持续发布线索。但仅凭提示材料无法验证近期提交、实际 CI、依赖更新、漏洞响应流程或维护者责任渠道，故不能接近满分。
文档质量 15/20: README 覆盖安装、MCP 配置、代理、平台限制、可选依赖、TLS 故障排查、功能边界和若干性能数据，信息层次较完整。扣分原因是没有可审查的 MCP 工具参数/返回结构、认证与权限说明、资源与隐私策略；仓库标识和部分链接还出现 headroomlabs-ai 与 chopratejas 不一致。
安装易用性 13/20: Manifest 给出了 PyPI 包、uvx、stdio、固定版本和启动参数，README 也提供了 Codex 的绝对路径配置示例，主路径较清晰。扣分原因是需要 Python/uv、可选 extras、模型和 ONNX 运行时下载，平台兼容性及 Intel macOS、企业 TLS 等情况较复杂；没有文件级执行证据证明端到端连接可用。

静态评测 · 未实际运行收录于 2026-07-29

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件访问网络

适合谁

经常使用 AI 编码 Agent 的开发者
希望本地处理数据并减少 LLM 上下文开销的用户
使用多个 Agent 或 MCP 工具的工作流

不适合谁

无法运行本地进程的沙箱环境
只依赖单一供应商原生上下文压缩且不需要跨 Agent 功能的用户

所需权限

需要 MCP 主机启动本地 Headroom 进程
需要处理传入的工具输出、日志、文件、RAG 片段或会话上下文
可在本地缓存可逆压缩所需的原始内容

风险与副作用

压缩会改变发送给 LLM 的内容形式；项目声称在保持答案的同时减少 token，但实际效果取决于输入
本地缓存可能包含工具输出、文件或日志中的敏感信息
部分功能可能需要从 cdn.pyke.io 或 huggingface.co 获取运行时或模型资产
Python、平台架构或 AVX2 条件不满足时，部分功能可能回退或安装失败

安装接入

准备工作

运行环境：Python 3.10+

其他可选配置项（14 个）

HEADROOM_OUTPUT_SHAPER 可选设为 1 启用输出 token 削减（冗长引导与推理力度路由），默认关闭。

HEADROOM_OUTPUT_HOLDOUT 可选设为 0-1 之间的小数，保留部分会话作为对照组以实测输出节省。

HEADROOM_EMBEDDER_RUNTIME 可选设为 pytorch_mps 时在 Apple GPU 上做内存嵌入器卸载。

HEADROOM_UPDATE_CHECK 可选设为 off 关闭启动时的 PyPI 更新检查。

HEADROOM_TLS_STRICT 可选设为 0 可在 SSL 检查环境中放宽 Python 3.13 的严格 TLS 校验（仅关闭 VERIFY_X509_STRICT）。

ORT_STRATEGY 可选设为 system 时使用系统安装的 ONNX Runtime 而非下载的二进制。

ORT_LIB_LOCATION 可选指向系统 ONNX Runtime 的 lib/ 目录，配合 ORT_STRATEGY=system 使用。

ORT_DYLIB_PATH 可选运行时 dlopen 的 libonnxruntime.dylib 绝对路径。

ORT_PREFER_DYNAMIC_LINK 可选设为 1 时强制动态链接 ONNX Runtime。

HF_HUB_OFFLINE 可选设为 1 时使用预下载的 kompress 压缩模型而不访问 HuggingFace。

HF_ENDPOINT 可选设为可信的 HuggingFace 镜像地址，用于下载压缩模型。

REQUESTS_CA_BUNDLE 可选指向包含企业 CA 的证书包，供 requests/huggingface_hub 下载使用。

SSL_CERT_FILE 可选企业 SSL 检查环境下的 CA 证书文件路径。

CURL_CA_BUNDLE 可选企业 SSL 检查环境下的 CA 证书包路径。

使用支持 uvx 的 MCP 客户端，将命令设置为 uvx，并将参数设置为 --from headroom-ai[mcp] headroom mcp serve。也可先安装 headroom-ai[mcp]，再运行 headroom mcp serve。需要 Python 3.10+；MCP 传输为 stdio。

MCP 配置 · JSON

{"command":"uvx","args":["--from","headroom-ai[mcp]","headroom","mcp","serve"]}

适用于使用 mcpServers 字段的客户端。VS Code 等使用其他字段的客户端，可用下方配置生成器转换。

.vscode/mcp.json

{
  "command": "uvx",
  "args": [
    "--from",
    "headroom-ai[mcp]",
    "headroom",
    "mcp",
    "serve"
  ]
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

生成并校验客户端配置

验证是否装好

在 MCP 客户端的工具列表中确认出现 headroom_compress、headroom_retrieve 和 headroom_stats 三个工具；调用 headroom_stats 返回压缩统计数据即证明连接正常。

常见排障

确认已安装 Python 3.10+ 及 headroom-ai[mcp]
确认客户端能找到 uvx，必要时使用绝对路径
检查 MCP 配置中的包参数是否为 --from headroom-ai[mcp] headroom mcp serve
若安装出现 TLS 或企业证书错误，检查企业 CA、REQUESTS_CA_BUNDLE、SSL_CERT_FILE 或 SSL 检查环境
若 x86 主机缺少 AVX2，检查是否触发了非 ONNX 回退路径

试试这样问

连接成功后，可以直接对 AI 助手这样说：

压缩这段工具输出的 JSON，减少 token 消耗
取回刚才被压缩内容的原始版本（CCR 检索）
显示当前压缩统计信息，看看节省了多少 token

工具能力 3

headroom_compress 只读

压缩输入内容以减少发送给 LLM 的 token 数量。

headroom_retrieve 只读

按需检索可逆压缩缓存中的原始内容。

headroom_stats 只读

查看 Headroom 的压缩和节省统计。

使用场景

压缩 MCP 工具输出、日志、文件和 RAG 结果

在编码 Agent 工作流中减少上下文 token

需要按需恢复原文的可逆压缩场景

查看压缩效果和 token 节省统计

详细介绍

Headroom MCP 服务器为 MCP 兼容主机提供压缩、检索和统计功能。它可在内容到达 LLM 前处理工具输出、日志、文件和 RAG 片段，并支持可逆压缩与本地原文检索。