适合谁
- 长时间、多轮次的编码代理会话
- 同时使用多个 CLI 客户端的开发者
- 需要本地运行、无遥测、可商用许可的团队
- 希望用可复现基准而不是厂商自述来验证压缩效果的团队
T
64FMRS · C
Token Optimizer MCP 是一个范围相当大、且极少见的自证型项目：它不只声明节省令牌，还把基准脚本、失败案例、被排除的数据和未达标的实验一并发布在仓库中。它的核心价值在于两点——在工具结果进入模型前进行上下文压缩与智能读取，以及一个从真实代理流量中自行积累的本地知识图谱。相比同类工具，它明确区分「直接节省」与「因果图谱证据」，并把无法测量的部分标为 unknown 而不是 0。
需要清醒认识的是：README 中大量对竞争对手（HeadRoom）的对比是其自行复现对方设计的离线估算，并非对方实际二进制的结果；作者本人也多次声明未能建立全面优越性，部分确认研究因额度或上游 503 而未完成。知识图谱的因果收益至今仍处于 Collecting 状态。此外，它会主动拒绝你的工具调用，并会把被省略的载荷写入本地临时文件，这两点对工作流和安全边界都有实际影响。适合愿意接受更激进集成、并能自行运行基准来核验的开发者。
Token Optimizer MCP 是一个本地运行的 MCP 服务器，用于优化 AI 编码代理的上下文窗口。它通过缓存、压缩和智能文件工具，在工具结果进入模型之前减少不必要的令牌消耗，官方 README 称可削减 60–90% 的令牌。
它同时提供一个跨会话的本地知识图谱：为文件、符号、任务和发现建立节点，用 derived_from、contains、supersedes、contradicts、related 等边连接，并在代理访问相关文件时把已有结论反馈回去，避免重复推导。图谱数据保存在本地，无账号、无遥测、无托管服务。
该服务器通过 stdio 传输，以 npm 包 @ooples/token-optimizer-mcp 发布，许可证为 MIT，允许商业使用。README 给出 16 个客户端的安装方式，并区分「强制层」（10 个具有预执行钩子、可拒绝昂贵内置调用的客户端）与「规则层」（6 个只能通过强制规则路由的客户端）。所有基准数据都随仓库一同发布，可用 node bench/compression/proof.mjs 等命令复现。
工具能力
smart_read
读取文件并返回压缩或差异化的内容，避免重复读取未变更的文件。
smart_grep
执行搜索并以压缩形式返回匹配结果，保留偏离常规形状的关键行。
smart_glob
按模式查找文件，并以精简形式返回结果。
smart_edit
以受优化的方式编辑文件，减少上下文中的冗余内容。
expand
从按内容寻址的存储中展开此前被省略的内容，不会重新运行原命令。
wiki_write
由当前模型写入一条持久结论（发现、决策或死路）到项目知识图谱。
wiki_read
读取当前项目或即将访问文件相关的已有知识。
wiki_query
直接查询图谱：按键取单条发现、对结论做 BM25 排序搜索、取节点及其邻居，或查看图谱自身的审计信息。
token_audit
返回一个按会话成本排序的队列，列出最耗资源的项及对应修复方式。
waste_audit
把检测到的浪费转化为可持续、可衡量、可回滚的修复建议（如跳过规则）。
fleet_audit
按实测成本对本机所有项目排序，并按内容哈希在项目之间传递已验证的修复。
安装接入
Claude Code：执行 /plugin marketplace add ooples/token-optimizer-mcp，再执行 /plugin install token-optimizer@token-optimizer，最后 /reload-plugins。
仅安装 MCP 服务器（任何客户端均可）：npx -y @ooples/token-optimizer-mcp@latest。可选设置环境变量 TOKEN_OPTIMIZER_CACHE_DIR 指定缓存目录，默认 ~/.token-optimizer-mcp。
Codex：codex plugin marketplace add ooples/token-optimizer-mcp，然后 codex plugin add token-optimizer@token-optimizer；或用 codex mcp add token-optimizer -- npx -y @ooples/token-optimizer-mcp@latest。
安装后用 npx token-optimizer-doctor 验证钩子是否真正生效（会喂入合成载荷，断言大文件读取被拒绝、小文件读取不被拒绝）。十六个客户端的现成配置位于仓库 integrations/ 目录。
claude_desktop_config.json
{
"mcpServers": {
"token-optimizer": {
"command": "npx",
"args": ["-y", "@ooples/token-optimizer-mcp@latest"],
"env": {
"TOKEN_OPTIMIZER_CACHE_DIR": "/path/to/cache"
}
}
}
}
选型与风险
不适合谁
- 只想安装一个纯 MCP 服务器、不希望客户端安装钩子或插件的人（README 明确说明仅加服务器无法执行强制拒绝）
- 不希望任何请求内容被写入本地磁盘的场景（代理会把被省略的载荷写入临时目录的 spill 文件）
- 需要托管服务或云端账号的用户
- 无法运行 Node.js 22+ 的环境
所需权限
- 读写项目文件（智能读写与差异比较）
- 在客户端中安装并运行生命周期钩子，用于在工具执行前进行拦截或改写路由
- 在本地磁盘写入缓存、知识图谱、日志与省略内容的 spill 文件
- 可选地在本机回环地址启动一个压缩代理进程
- 读取本地 CLI 的使用账目以进行令牌计量与定价
风险与副作用
- 服务器会拒绝或改写内置工具调用（如 Read、Grep、Glob、Edit、Write 以及 shell 中的 cat/head/grep -r），在 enforce 模式下可能打断既有工作流
- 被省略的可恢复内容会以 0600 权限写入操作系统临时目录的 token-optimizer-spill/ 下，代理运行期间不会删除；若进程被强杀或断电，目录会残留，需手动清理
- 代理不会检查所写内容是否包含密钥，若对话中含有敏感信息，可能随 spill 文件落盘
- 知识图谱与缓存保存在本地，涉及项目结构、文件内容哈希与发现的结论
- README 中多项对比结果为开发阶段或未完成的研究，其自身说明未能建立全面优越性，聚合区间仍跨过 1.0
常见排障
- 若感觉没有任何效果，通常是没有安装生命周期钩子包：MCP 服务器进程无法修改宿主，且 npm 11 默认限制 lifecycle scripts，需按客户端安装插件或钩子
- 运行 npx token-optimizer-doctor，它会向真实的钩子二进制喂入合成载荷，验证大文件读取被拒绝
- 启用代理后无法启动代理进程：检查端口占用与回环绑定，并确认 Node.js 版本 ≥22
- 知识图谱的语义采集显示 off:no-key 时表示未配置模型凭据，可指向本地模型端点以保持离线；用 npx token-optimizer-doctor 查看当前状态
- 想排查钩子运行状况时运行 npm run diagnostics，可加 --hours 与 --output 参数；原始事件行需显式开启且上限 1000 条
- 需要临时关闭时设置 TOKEN_OPTIMIZER_MODE=off；关闭代理路由可设置 TOKEN_OPTIMIZER_PROXY=0
使用场景
减少编码代理重复读取未变更文件所消耗的令牌
压缩工具输出、搜索日志与构建日志后再送入模型
跨会话保留代理已经推导出的结论、决策与死路
按客户端与操作归因令牌消耗，定位成本最高的项目
在多个本地项目之间复用已验证的优化修复
支持客户端
Claude Code完整支持
Codex完整支持
GitHub Copilot CLI完整支持
Gemini CLI完整支持
Qwen Code完整支持
Cursor完整支持
Cline完整支持
OpenCode完整支持
Kilo完整支持
Windsurf完整支持
Roo Code部分支持
Zed部分支持
Amp部分支持
Continue部分支持
Crush部分支持
Droid部分支持