Token Optimizer MCP

🚀 Token Optimizer MCP

Token Optimizer MCP是一款Model Context Protocol (MCP) 服务器，通过智能缓存、压缩和智能工具替换，能将上下文窗口的使用量减少60 - 90%。该服务器将压缩后的内容存储在SQLite中，并为标准工具提供优化替代方案，帮助你充分利用可用的上下文窗口。

🚀 快速开始

Token Optimizer MCP是一个模型上下文协议（MCP）服务器，通过智能缓存、压缩和智能工具替换，将上下文窗口的使用量减少60 - 90%。在实际使用中，超过38000次操作实现了60 - 90%的令牌减少。

✨ 主要特性

• 智能工具替换：对读取、搜索、文件匹配等操作进行自动优化。
• 上下文窗口优化：将内容存储在外部，释放上下文空间。
• 高压缩率：使用Brotli压缩算法（通常为2 - 4倍，对于重复内容最高可达82倍）。
• 持久缓存：基于SQLite的缓存，跨会话持久化。
• 准确的令牌计数：使用tiktoken进行精确的令牌测量。
• 61种专业工具：包括文件操作、API缓存、数据库优化、监控等。
• 零外部依赖：完全离线操作。
• 生产就绪：使用TypeScript构建，确保可靠性。

📦 安装指南

快速安装（推荐）

Windows

# 以管理员身份运行PowerShell，然后执行以下命令：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 全局安装（钩子会自动安装！）
npm install -g @ooples/token-optimizer-mcp

macOS / Linux

# 全局安装（钩子会自动安装！）
npm install -g @ooples/token-optimizer-mcp

安装完成后，安装后脚本将自动执行以下操作：

1. ✅ 通过npm全局安装token-optimizer-mcp。
2. ✅ 自动检测并配置所有已安装的AI工具（Claude Desktop、Cursor、Cline等）。
3. ✅ 在每次工具调用时设置自动令牌优化。
4. ✅ 配置工作区信任和执行权限。

效果：所有操作实现60 - 90%的令牌减少！

注意：如果自动安装被跳过（例如，在CI环境中），你可以手动运行安装程序：

• Windows：powershell -ExecutionPolicy Bypass -File install-hooks.ps1
• macOS/Linux：bash install-hooks.sh

手动配置

有关特定平台的详细安装说明，请参阅 docs/HOOKS-INSTALLATION.md。

💻 使用示例

基础缓存

// 将大内容缓存以从上下文窗口中移除
const result = await optimize_text({
  text: "Large API response or file content...",
  key: "cache-key",
  quality: 11
});
// 结果：原始令牌被移除，仅保留缓存键（约50个令牌）

// 后续检索
const cached = await get_cached({ key: "cache-key" });
// 结果：恢复完整的原始内容

智能文件读取

// 首次读取：获取完整内容
await smart_read({ path: "/src/app.ts" });

// 后续读取：仅获取更改内容（减少80%）
await smart_read({ path: "/src/app.ts" });

API缓存

// 首次请求：获取并缓存
await smart_api_fetch({
  method: "GET",
  url: "https://api.example.com/data",
  ttl: 300
});

// 后续请求：使用缓存（减少95%）
await smart_api_fetch({
  method: "GET",
  url: "https://api.example.com/data"
});

会话分析

// 查看当前会话的令牌使用情况
await get_session_stats({});
// 结果：按工具、操作和节省情况进行细分

// 分析整个项目
await analyze_project_tokens({
  projectPath: "/path/to/project"
});
// 结果：成本估算和优化机会

📚 详细文档

可用工具（共65个）

核心缓存与优化（8个工具）

// 缓存大内容以从上下文窗口中移除
optimize_text({
  text: "Large API response or file content...",
  key: "api-response-key",
  quality: 11
})
// 结果：减少60 - 90%的令牌

智能文件操作（10个工具）

// 自动缓存读取文件
smart_read({ path: "/path/to/file.ts" })
// 首次读取：获取完整内容
// 后续读取：仅获取差异内容（减少80%）

API与数据库操作（10个工具）

// 自动缓存获取API数据
smart_api_fetch({
  method: "GET",
  url: "https://api.example.com/data",
  ttl: 300
})
// 缓存响应：减少95%的令牌

构建与测试操作（10个工具）

// 运行测试并缓存结果
smart_test({
  onlyChanged: true,  // 仅测试更改的文件
  coverage: true
})

高级缓存（10个工具）

// 配置多级缓存
smart_cache({
  operation: "configure",
  evictionStrategy: "LRU",
  l1MaxSize: 1000,
  l2MaxSize: 10000
})

监控与仪表盘（7个工具）

// 创建警报
alert_manager({
  operation: "create-alert",
  alertName: "high-cpu-usage",
  channels: ["slack", "email"],
  threshold: { type: "above", value: 80 }
})

系统操作（6个工具）

// 查看会话令牌使用情况
get_session_stats({})
// 结果：按工具详细分解令牌使用情况

工作原理

令牌分析（4个工具）

// 获取每个钩子的分析数据
get_hook_analytics({
  startDate: "2025-01-01T00:00:00Z",
  endDate: "2025-12-31T23:59:59Z"
})
// 结果：显示哪些钩子消耗最多的令牌

// 获取每个操作的分析数据
get_action_analytics({})
// 结果：显示哪些工具使用最多的令牌

// 以CSV格式导出分析数据
export_analytics({
  format: "csv",
  hookPhase: "PreToolUse"
})
// 结果：按PreToolUse钩子过滤的CSV导出

全局钩子系统（7阶段优化）

当全局钩子安装后，token-optimizer-mcp会在每次工具调用时自动运行：

┌─────────────────────────────────────────────────────────────┐
│ 阶段1: PreToolUse - 工具替换                               │
│ ├─ Read   → smart_read   (减少80%的令牌)                  │
│ ├─ Grep   → smart_grep   (减少80%的令牌)                  │
│ └─ Glob   → smart_glob   (减少75%的令牌)                  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 阶段2: 输入验证 - 缓存查找                                │
│ └─ get_cached 检查操作是否已经完成                        │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 阶段3: PostToolUse - 输出优化                              │
│ ├─ optimize_text 处理大输出                               │
│ └─ compress_text 处理重复内容                             │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 阶段4: 会话跟踪                                          │
│ └─ 将所有操作记录到 operations-{sessionId}.csv            │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 阶段5: UserPromptSubmit - 提示优化                         │
│ └─ 在将用户提示发送到API之前进行优化                      │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 阶段6: PreCompact - 预压缩优化                            │
│ └─ 在Claude Code压缩对话之前进行优化                      │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 阶段7: 指标与报告                                        │
│ └─ 跟踪令牌减少指标并生成报告                            │
└─────────────────────────────────────────────────────────────┘

生产性能

基于超过38000次的实际操作：

每次会话节省：300K - 700K令牌（按每百万令牌3美元计算，价值0.90 - 2.10美元）

技术栈

• 运行时：Node.js 20+
• 编程语言：TypeScript
• 数据库：SQLite（better-sqlite3）
• 令牌计数：tiktoken（GPT - 4分词器）
• 压缩：Brotli（Node.js内置）
• 缓存：多级LRU/LFU/FIFO缓存
• 协议：MCP SDK (@modelcontextprotocol/sdk)

支持的AI工具

自动安装程序会检测并配置token-optimizer-mcp，支持以下工具：

• ✅ Claude Code - 支持全局钩子集成的命令行工具
• ✅ Claude Desktop - 原生桌面应用程序
• ✅ Cursor IDE - 以AI为核心的代码编辑器
• ✅ Cline - VS Code扩展（原Claude Dev）
• ✅ GitHub Copilot - 支持MCP的VS Code插件
• ✅ Windsurf IDE - 由AI驱动的开发环境

无需手动配置，安装程序会自动检测并配置所有已安装的工具！

性能特征

• 压缩率：通常为2 - 4倍（对于重复内容最高可达82倍）
• 上下文窗口节省：所有操作平均节省60 - 90%
• 缓存命中率：典型使用场景下>80%
• 操作开销：缓存操作<10ms（从50 - 70ms优化而来）
• 压缩速度：每KB文本约1ms
• 钩子开销：每次操作<10ms（通过内存优化提高7倍）

性能优化

通过以下方式，PowerShell钩子的开销从50 - 70ms减少到<10ms：

• 内存会话状态：会话数据保存在内存中，避免每次操作都进行磁盘I/O
• 批量日志写入：操作日志每5秒或100次操作缓冲并刷新一次
• 惰性持久化：仅在必要时进行磁盘写入（会话结束、优化、报告）

环境变量

使用以下环境变量控制钩子行为：

性能控制

• TOKEN_OPTIMIZER_USE_FILE_SESSION（默认值：false）

  • 设置为true以恢复基于文件的会话跟踪（旧模式）
  • 如果在内存会话状态中遇到问题，可以使用此选项
  • 示例：$env:TOKEN_OPTIMIZER_USE_FILE_SESSION = "true"

• TOKEN_OPTIMIZER_SYNC_LOG_WRITES（默认值：false）

  • 设置为true以禁用批量日志写入
  • 强制立即写入磁盘（速度较慢，但更可靠）
  • 用于调试或日志丢失的情况
  • 示例：$env:TOKEN_OPTIMIZER_SYNC_LOG_WRITES = "true"

• TOKEN_OPTIMIZER_DEBUG_LOGGING（默认值：true）

  • 设置为false以禁用DEBUG级别的日志记录
  • 减少日志文件大小，提高性能
  • INFO/WARN/ERROR日志仍会写入
  • 示例：$env:TOKEN_OPTIMIZER_DEBUG_LOGGING = "false"

开发路径

• TOKEN_OPTIMIZER_DEV_PATH
  • 本地开发安装的路径
  • 如果未指定，将自动设置为~/source/repos/token-optimizer-mcp
  • 用于自定义开发路径
  • 示例：$env:TOKEN_OPTIMIZER_DEV_PATH = "C:\dev\token-optimizer-mcp"

性能影响：使用内存模式（默认）可将钩子开销提高7倍：

• 之前：每次钩子操作50 - 70ms
• 之后：每次钩子操作<10ms
• 钩子延迟减少85%

监控令牌节省情况

实时会话监控

要查看实际的令牌节省情况，请使用get_session_stats工具：

// 查看当前会话的统计信息，包括令牌节省情况的细分
await get_session_stats({});

输出包括：

• 总节省的令牌数（这是实际节省的数量！）
• 令牌减少百分比（例如，“减少60%”）
• 缓存命中率和压缩率
• 按工具细分（读取、搜索、文件匹配等）
• 前10个最优化的操作，并提供前后对比

示例输出：

{
  "sessionId": "abc-123",
  "totalTokensSaved": 125430,  // ← 这是你的节省数量！
  "tokenReductionPercent": 68.2,
  "originalTokens": 184000,
  "optimizedTokens": 58570,
  "cacheHitRate": 72.0,
  "byTool": {
    "smart_read": { "saved": 45000, "percent": 80 },
    "smart_grep": { "saved": 32000, "percent": 75 }
  }
}

会话跟踪文件

所有操作都会自动记录在会话数据文件中：

位置：~/.claude-global/hooks/data/current-session.txt

格式：

{
  "sessionId": "abc-123",
  "sessionStart": "20251031-082211",
  "totalOperations": 1250,      // ← 操作次数
  "totalTokens": 184000,         // ← 累计令牌数
  "lastOptimized": 1698765432,
  "savings": {                   // ← 每10次操作自动更新（问题 #113）
    "totalTokensSaved": 125430,  // 压缩节省的令牌数
    "tokenReductionPercent": 68.2,  // 节省的令牌百分比
    "originalTokens": 184000,    // 优化前的原始令牌数
    "optimizedTokens": 58570,    // 优化后的令牌数
    "cacheHitRate": 42.5,        // 缓存命中率百分比
    "compressionRatio": 0.32,    // 压缩效率（越低越好）
    "lastUpdated": "20251031-092500"  // 最后一次节省更新的时间戳
  }
}

v1.x版本的新特性：savings对象现在每10次操作自动更新一次，无需手动调用get_session_stats()进行实时监控。这提供了对令牌优化性能的即时可见性。

工作原理：

• 每10次操作，PowerShell钩子会自动调用get_cache_stats() MCP工具
• 节省指标根据缓存性能数据（压缩率、原始大小与压缩大小对比）计算得出
• 会话文件会原子性地更新为最新的节省数据
• 如果MCP调用失败，更新将优雅地跳过，不会阻塞操作

注意：如需详细的每次操作分析，请使用get_session_stats()。会话文件提供高级汇总指标。

项目范围分析

分析整个项目的令牌使用情况：

// 分析项目的令牌成本
await analyze_project_tokens({
  projectPath: "/path/to/project"
});

提供：

• 总令牌成本估算
• 按令牌数排名的最大文件
• 优化机会
• 当前API费率下的成本预测

缓存性能

监控缓存命中率和存储效率：

// 查看缓存统计信息
await get_cache_stats({});

指标：

• 总条目数
• 缓存命中率（%）
• 平均压缩率
• 总节省的存储空间
• 最常访问的键

🔧 技术细节

常见问题及解决方案

问题：Claude Code设置中出现“无效或格式错误的JSON”

症状：运行安装钩子后，Claude Code显示“无效设置”错误。

原因：settings.json文件中添加了UTF - 8 BOM（字节顺序标记）。

解决方案：升级到v3.0.2+版本，该版本修复了BOM问题：

npm install -g @ooples/token-optimizer-mcp@latest

如果已经是v3.0.2+版本，可以手动移除BOM：

# Windows: 从settings.json中移除BOM
$content = Get-Content "~/.claude/settings.json" -Raw
$content = $content -replace '^\xEF\xBB\xBF', ''
$content | Set-Content "~/.claude/settings.json" -Encoding utf8NoBOM

# Linux: 从settings.json中移除BOM
sed -i '1s/^\xEF\xBB\xBF//' ~/.claude/settings.json

# macOS: 从settings.json中移除BOM（BSD sed需要在 -i 后加空字符串）
sed -i '' '1s/^\xef\xbb\xbf//' ~/.claude/settings.json

问题：安装后钩子不起作用

症状：令牌优化未自动进行。

诊断：

1. 检查钩子是否安装：

   # Windows
   Get-Content ~/.claude/settings.json | ConvertFrom-Json | Select-Object -ExpandProperty hooks
   

   # macOS/Linux
   cat ~/.claude/settings.json | jq .hooks
   

2. 验证dispatcher.ps1是否存在：

   # Windows
   Test-Path ~/.claude-global/hooks/dispatcher.ps1
   

   # macOS/Linux
   [ -f ~/.claude-global/hooks/dispatcher.sh ] && echo "Exists" || echo "Missing"
   

解决方案：重新运行安装程序：

# Windows
powershell -ExecutionPolicy Bypass -File install-hooks.ps1

# macOS/Linux
bash install-hooks.sh

问题：缓存命中率低（<50%）

症状：会话统计显示缓存命中率低于50%。

原因：

1. 处理大量新文件（正常情况）
2. 最近清除了缓存
3. TTL（生存时间）设置过短

解决方案：

1. 在开始工作前预热缓存：

   await cache_warmup({
     paths: ["/path/to/frequently/used/files"],
     recursive: true
   });
   

2. 增加稳定API的TTL：

   await smart_api_fetch({
     url: "https://api.example.com/data",
     ttl: 3600  // 1小时，而不是默认的5分钟
   });
   

3. 检查缓存大小限制：

   await smart_cache({
     operation: "configure",
     l1MaxSize: 2000,  // 从默认的1000增加
     l2MaxSize: 20000  // 从默认的10000增加
   });
   

问题：内存使用过高

症状：Node.js进程使用过多内存。

原因：内存中的大缓存（L1/L2层）。

解决方案：配置缓存限制：

await smart_cache({
  operation: "configure",
  evictionStrategy: "LRU",  // 最近最少使用
  l1MaxSize: 500,  // 减少L1缓存
  l2MaxSize: 5000  // 减少L2缓存
});

或者清除缓存：

await clear_cache({});

问题：首次操作缓慢

症状：初始的读取、搜索、文件匹配操作缓慢。

原因：缓存为空，正在构建索引。

解决方案：这是正常现象，后续操作将快80 - 90%。

要预热缓存：

await cache_warmup({
  paths: ["/src", "/tests", "/docs"],
  recursive: true,
  schedule: "startup"  // 每次会话开始时自动预热
});

问题：Windows上出现“权限被拒绝”错误

症状：无法写入缓存或日志文件。

原因：PowerShell执行策略或文件权限问题。

解决方案：

1. 设置执行策略：

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

2. 检查文件权限：

   icacls "$env:USERPROFILE\.token-optimizer"
   

3. 必要时以管理员身份重新运行安装程序

问题：缓存文件增长过大

症状：~/.token-optimizer/cache.db文件大小超过1GB。

原因：缓存非常大的文件或大量API响应。

解决方案：

1. 清除旧条目：

   await clear_cache({ olderThan: 7 });  // 清除7天前的条目
   

2. 减少缓存保留时间：

   await smart_cache({
     operation: "configure",
     defaultTTL: 3600  // 1小时，而不是7天
   });
   

3. 手动删除缓存（极端情况）：

   rm -rf ~/.token-optimizer/cache.db
   

获取帮助

如果你遇到这里未涵盖的问题：

1. 检查钩子日志：~/.claude-global/hooks/logs/dispatcher.log
2. 检查会话数据：~/.claude-global/hooks/data/current-session.txt
3. 提交问题：GitHub Issues
   • 包括调试日志
   • 包括你的操作系统和Node.js版本
   • 包括get_session_stats的输出

局限性

• 小文本：最适合处理超过500个字符的内容（小片段的缓存开销较大）
• 一次性内容：对于不会再次引用的内容没有优势
• 缓存存储：7天后自动清理，以防止磁盘使用问题
• 令牌计数：使用GPT - 4分词器（对Claude是近似值，但足够接近）

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE。

作者

由ooples团队为Claude Code的最佳令牌效率而构建。