ooples/token-optimizer-mcp

Measure token savings per AI coding agent, optimize context, and share a live local knowledge graph across 16 CLI clients.

Token Optimizer MCP – 它是什么

@ooples/token-optimizer-mcp 是一个 npm 包，可插入大型语言模型（LLM）工作流，并尝试 减少模型必须读取的 token 数量。它通过以下方式实现：

阻止昂贵的读取 – 当代理请求 Read 一个大文件时，插件拒绝该请求并返回一个 diff，仅包含自上次读取以来的更改。
在每项目知识图谱中缓存结果 – 代理已经得出的发现会被存储并自动重用，避免重新推导的需要。
测量实际成本 – 该工具记录每个请求的 之前/之后 token 计数（“MCP” – 测量的每次请求成本），并显示每个代理和每个操作的节省实时仪表板。
归因流量 – 仪表板按客户端（Claude、Gemini 等）和操作类型（读取、grep、编辑等）对节省进行分组。

核心思想是，大多数 LLM 代理在它们已经见过的数据上浪费了大量上下文。通过将这些读取转换为廉价的差异并记住先前的推理，优化器可以 降低 token 账单，同时保持相同的输出质量。

工作原理

块引擎 – 默认模式完全在本地运行。它压缩请求负载，用指向磁盘上文件的微小标记替换已移除的块，并且从不向模型发送原始字节。
代理模式 – 可选代理可以放置在模型（例如 Claude Code）前面。它的行为类似于块引擎，但也会将大块溢出到临时文件并发送标记（<<ccr:hash,kind,size>>）。模型可以在需要时稍后检索该块，为检索轮次支付少量额外 token 成本。
预设模式 – 块引擎带有可配置阈值（spillWholeBlockBelow），决定何时将块溢出到文件。
遥测 – 仅可选。两个环境变量控制本地聚合（TOKEN_OPTIMIZER_TELEMETRY=1）和可选上传（TOKEN_OPTIMIZER_BEACON=1）。所有上传都是匿名的，仅包含数字/标志，并且可以通过 DO_NOT_TRACK=1 禁用。

基准测试与结果（如 README 中所述）

该仓库附带一个 基准测试工具，将优化器与某些 LLM 提供商使用的“HeadRoom”压缩器进行比较。关键要点：

工作负载	Token 减少（我们的）	Token 减少（HeadRoom）	成本因子（我们的）
agentic‑conversation	30.8 %	33.4 %	0.52 × (代理)
agent‑loop	59.1 %	54.3 %	0.92 × (代理)
rag‑conversation	83.2 %	0.1 %	0.99 × (代理)
…（共 18 个工作负载）

在 18 个真实世界负载中，优化器在代理模式下运行时 平均移除 82% 的字符和 91% 的 token，在没有取回溢出块的情况下，每一行都优于竞争对手。当取回块时，它仍然在 18 行中的 17 行获胜。

会话级测试显示，对于 10 轮和 20 轮对话，总 token 成本降低 5–9%，端到端任务套件（16 个任务）显示中位成本因子为 0.926×，且 质量无损失（平均得分 0.994 对比 0.994）。

快速开始

# 安装包
npm i @ooples/token-optimizer-mcp

# 运行内置医生以查看配置
npx token-optimizer-mcp doctor

典型用法是将优化器作为插件添加到您正在使用的 LLM 客户端（Claude、Gemini 等）。README 指向一个 install_doctor 脚本，该脚本打印哪些遥测标志处于活动状态以及排队了多少事件。

许可证与商业使用

代码在 MIT 许可证 下发布，并明确允许商业使用。不需要托管服务或账户 – 您可以在自己的环境中本地运行优化器。

谁可能受益？

构建 自主代理 的开发人员，这些代理反复读取大型代码库或日志。
运行 长时间运行的 LLM 会话（例如代码助手、数据分析机器人）并希望保持低 token 成本的团队。
任何想要 透明、可复现的测量 通过缓存和基于差异的读取节省了多少 token 的人。

底线

Token Optimizer MCP 是一个 真实的、开源的工具，针对 LLM 驱动的代理中的一个具体低效问题：不必要地重新读取未更改的数据。通过用微小的差异替换完整读取，在知识图谱中缓存结果，并提供公共成本仪表板，它可以在典型代理工作负载上将 token 账单削减约 10%–30%，同时保持输出质量。该项目积极进行基准测试、CI 测试，并采用 MIT 许可，可不受限制地使用。