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 – 它是什么

Token Optimizer MCP 是一个开源的 Node.js 插件，位于大型语言模型（LLM）客户端（Claude Code、Codex、Gemini 等）与本地文件系统之间。它会监视每一个 MCP（模型-客户端-协议）操作——读取、grep、编辑、写入等——并尝试 避免发送模型已经‘支付过’的 token。它通过以下方式实现：

阻止冗余读取 – 如果文件在当前会话中已被读取，该插件会拒绝原始的 Read 请求，并返回一个模型可直接使用的 diff，从而无需额外消耗 token。
记住结论 – 会话结束后，该工具会构建一个轻量级的项目级知识图谱（包含文件、符号、发现、决策、死胡同等）。当下一个会话再次处理相同代码时，该图谱可直接提供结论，节省数千 token。
测量节省效果 – 每个操作都会被记录，包含之前（本应发送的）和实际（真正发送的）token 数量，因此你可以清楚看到避免了多少上下文。
按客户端归因成本 – 仪表板为每个 LLM 客户端（Claude Code、Codex、Gemini 等）显示独立的行，让你知道哪个代理获益最多。

所有数据都保留在开发者的机器上；没有遥测，没有托管服务，代码采用 MIT 许可证，可在商业环境中使用。

核心概念

概念	作用
MCP 强制执行	插件拦截昂贵的调用（`Read`、`Grep`、`Glob`、`Edit`、`Write`、`cat`、`head` 等），要么拒绝它们（返回缓存的 diff），要么在内容确实为新时允许其通过。
项目级知识图谱	节点 = 文件、符号、任务、发现；边 = `derived_from`、`contains`、`supersedes` 等。该图谱通过工具输出自动填充，也可通过可选的基于模型的“收割”调用补充。
零轮拒绝	当读取被拒绝时，拒绝响应中已包含答案（即 diff），因此模型无需第二轮交互——token 成本从一轮降至零。
仪表板	一个本地 Web UI（`http://localhost:3100`），显示净 token 节省、按客户端的账单、图谱健康状况，以及知识图谱的 3D 探索器。
无遥测	所有日志均本地写入，不包含提示、文件内容或路径，并可通过环境变量进行轮换或禁用。

快速开始（来自 README）

# 安装 MCP 服务器和你的 LLM 客户端插件（例如：Claude Code）
/plugin marketplace add ooples/token-optimizer-mcp
/plugin install token-optimizer@token-optimizer
/reload-plugins

插件激活后，在任意会话中运行审计命令：

token_audit   # 打印最大 token 成本操作的排名列表

要本地运行仪表板：

npm install          # 安装开发依赖
npm run build        # 编译 UI
npm run dashboard    # 打开 http://localhost:3100

仪表板上可以看到的内容（来自 README 的示例）

43 491 个净验证的 MCP 传输 token 被避免（总减少量减去有意扩展）。
486 074 740 个历史 token 被隔离 – 从未进入模型上下文的原始文件扫描数据。
为 Codex、Claude Code、Gemini 等客户端显示的独立行，展示避免的 token 数量以及实际返回的 token 数量。
图谱统计信息——例如，2 648 个节点，6 527 条边，11 个项目中的 58 个发现。
健康面板——挂钩运行次数、失败次数、超时次数、各客户端的延迟百分位数。
“图谱替换潜力”和“因果研究”部分，跟踪提供缓存发现是否真的防止了后续读取。

典型使用场景

情况	Token Optimizer 如何帮助
重复文件读取 – 调试会话反复打开同一个大源文件。	插件拒绝第二次读取，并返回一个极小的 diff，节省数千 token。
重新推导结论 – CI 运行后，你打开新终端并询问模型某个特定 bug 的原因。	知识图谱已存储之前的推理过程（例如，“时钟偏移导致 401 错误”），因此模型可直接回答，无需重新计算。
多客户端项目 – 团队对某些任务使用 Claude Code，对其他任务使用 Gemini。	token 账单按客户端分开，让你清楚哪个模型的性价比最高。
预算成本追踪 – 你需要向财务团队报告 LLM 使用情况。	之前/之后的 token 数量会被持久化，并可导出为 markdown 或 JSON。

限制与注意事项（如 README 所述）

无自动 RAG – 该系统不会检索原始文档；它仅重用已推导出的结论。
基于模型的收割为可选 – 若无凭证（TOKEN_OPTIMIZER_HARVEST_ENDPOINT），语义收割步骤将被禁用，因此仅构建“结构化”图谱。
零轮拒绝要求模型请求文件 – 如果模型从未请求文件，优化器无法介入。
基于图谱的节省单独计量 – 图谱替换的潜在节省会显示，但直到有足够的处理/对照样本存在前，不会计入已验证的标题数据。
仅支持 16 个官方 MCP 客户端 – README 列出了 16 个客户端；使用不受支持的客户端将无法获得相同账单。
仅限本地 – 所有数据保留在机器上；没有云服务用于在开发者之间共享图谱。

哪些人可能需要这个？

构建 AI 辅助编码助手的开发者，希望将 token 费用保持在低位。
运行自托管 LLM 的团队（如 Claude、Gemini），需要一种无需将数据发送到外部的方式审计 token 使用情况。
研究 token 经济学的研究人员——内置的前后测量和对照实验提供可复现的数据集。
有严格数据隐私政策的公司——该工具完全离线运行，且符合 MIT 许可证，可用于商业用途。

总结

Token Optimizer MCP 是一个 实用、以隐私为先的 LLM 驱动开发工作流优化器。通过拒绝冗余读取、在轻量级知识图谱中缓存推导结论，并为每个客户端暴露透明的 token 节省指标，它让你能将更多上下文预算用于新的推理，而不是为模型已做过的任务重复付费。