令牌优化器MCP

通过缓存、压缩和智能工具对Claude Code和Claude Desktop进行智能令牌优化

概述

令牌优化器MCP是一种模型上下文协议（MCP）服务器，通过智能缓存、压缩和智能工具替换，将上下文窗口的使用率降低了60-90%。通过在SQLite中外部存储压缩内容并提供标准工具的优化替代方案，服务器可以帮助您最大限度地利用可用的上下文窗口。

生产结果在实际使用中，38000多个操作中的代币减少了60-90%。

主要特点

智能工具更换：Read、Grep、Glob等的自动优化
上下文窗口优化：将内容存储在外部以释放上下文空间
高压缩：肉汤压缩（通常为2-4x，重复内容可达82x）
持久缓存：基于SQLite的缓存，跨会话持久
精确的令牌计数：使用tiktoken进行精确的令牌测量
61专用工具：文件操作、API缓存、数据库优化、监控等等
零外部依赖：完全离线操作
生产就绪：使用TypeScript构建以提高可靠性

安装

快速安装（推荐）

视窗

# Run PowerShell as Administrator, then:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Install globally (hooks install automatically!)
npm install -g @ooples/token-optimizer-mcp

macOS/Linux

# Install globally (hooks install automatically!)
npm install -g @ooples/token-optimizer-mcp

就是这样！安装后脚本将自动执行以下操作：

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

结果：所有操作中令牌减少60-90%！

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

窗户： powershell -ExecutionPolicy Bypass -File install-hooks.ps1
macOS/Linux： bash install-hooks.sh

手动配置

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

可用工具（共65个）

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

Click to expand

optimize_text -压缩和缓存文本（减少标记的主要工具）
get_cached -检索以前缓存的文本
compress_text -使用Brotli压缩文本
解压缩文本 -解压缩Brotli压缩文本
count_tokes -使用tiktoken（GPT-4标记器）计数令牌
分析优化 -分析文本并获得优化建议
get_ache_stats -查看缓存命中率和压缩比
clear_cache -清除所有缓存数据

用法示例:

// Cache large content to remove it from context window
optimize_text({
  text: "Large API response or file content...",
  key: "api-response-key",
  quality: 11
})
// Result: 60-90% token reduction

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

Click to expand

通过智能缓存和基于差异的更新优化了标准文件工具的替代品：

smart_read -通过缓存和差异读取令牌减少80%的文件
smart_write -写入具有验证和更改跟踪功能的文件
smart_edit -基于行的文件编辑，仅支持差异输出（减少90%）
smart_grep -使用仅匹配输出搜索文件内容（减少80%）
smart_glob -与仅路径匹配的文件模式结果（减少75%）
smart_diff -Git差异，仅输出差异（减少85%）
智能牧场 -使用结构化JSON的Git分支列表（减少60%）
smart_log -使用智能过滤的Git提交历史记录（减少75%）
smart_arge -Git合并管理与冲突分析（减少80%）
智能状态 -Git状态，仅输出状态（减少70%）

用法示例:

// Read a file with automatic caching
smart_read({ path: "/path/to/file.ts" })
// First read: full content
// Subsequent reads: only diff (80% reduction)

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

Click to expand

外部数据源的智能缓存和优化：

smart_api_fetch -具有缓存和重试逻辑的HTTP请求（缓存命中率降低83%）
smart_ache_api -API响应缓存，具有TTL/ETag/基于事件的策略
智能数据库 -使用连接池和缓存的数据库查询（减少83%）
smart_sql -带有优化建议的SQL查询分析（减少83%）
smart_schema -基于智能缓存的数据库模式分析
smart_graphql -GraphQL查询优化与复杂性分析（减少83%）
smart_rest -REST API分析和端点发现（减少83%）
smart_arm -具有N+1检测的ORM查询优化（减少83%）
智能迁移 -数据库迁移跟踪（减少83%）
智能websocket -带消息跟踪的WebSocket连接管理

用法示例:

// Fetch API with automatic caching
smart_api_fetch({
  method: "GET",
  url: "https://api.example.com/data",
  ttl: 300
})
// Cached responses: 95% token reduction

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

Click to expand

使用智能缓存优化开发工作流程：

智能建筑 -TypeScript构建基于diff的更改检测
smart_test -使用增量测试选择执行测试
smart_list -ESLint，具有增量分析和自动修复功能
smart_typecheck -使用缓存进行TypeScript类型检查
智能安装 -带有依赖性分析的软件包安装
智能锁定器 -带层分析的Docker操作
智能日志 -带有模式过滤的日志聚合
智能网络 -具有异常检测功能的网络诊断
智能流程 -过程监控与资源跟踪
smart_system_metrics -系统资源监控及性能建议

用法示例:

// Run tests with caching
smart_test({
  onlyChanged: true,  // Only test changed files
  coverage: true
})

高级缓存（10个工具）

Click to expand

企业级缓存策略，令牌减少87-92%：

智能缓存 -多层缓存（L1/L2/L3），具有6种驱逐策略（减少90%）
cache_warmup -支持调度的智能缓存预热（减少87%）
缓存分析 -实时仪表盘和趋势分析（减少88%）
缓存基准标记 -性能测试和策略比较（减少89%）
缓存压缩 -6种自适应选择的压缩算法（减少89%）
缓存验证 -依赖跟踪和基于模式的失效（减少88%）
缓存优化器 -基于机器学习的推荐和瓶颈检测（减少89%）
缓存分区 -分片和一致散列（减少87%）
缓存复制 -具有冲突解决功能的分布式复制（减少88%）
predictive_cache -基于机器学习的ARIMA/LSTM预测缓存（减少91%）

用法示例:

// Configure multi-tier cache
smart_cache({
  operation: "configure",
  evictionStrategy: "LRU",
  l1MaxSize: 1000,
  l2MaxSize: 10000
})

监控和仪表板（7个工具）

Click to expand

通过智能缓存实现全面监控，令牌减少88-92%：

alert_manager -带路由的多渠道警报（电子邮件、Slack、webhook）（减少89%）
度量收集器 -具有多源支持的时间序列指标（减少88%）
监控_集成 -外部平台集成（普罗米修斯、Grafana、Datadog）（减少87%）
定制小部件 -带有模板缓存的仪表板小部件（减少88%）
数据可视化器 -SVG优化交互式可视化（减少92%）
健康监视器 -使用状态压缩进行系统健康检查（减少91%）
log_dashboard -带模式检测的日志分析（减少90%）

用法示例:

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

系统操作（6个工具）

Click to expand

使用智能缓存的系统级操作：

smart_cron -计划任务管理（cron/Windows任务计划程序）（减少85%）
smart_user -跨平台的用户和权限管理（减少86%）
smart_ast_grep -使用AST索引进行结构代码搜索（减少83%）
get_session_stats -会话级令牌使用统计
分析项目标记 -项目范围内的代币分析和成本估算
优化会话 -压缩当前会话中的大文件操作

用法示例:

// View session token usage
get_session_stats({})
// Result: Detailed breakdown of token usage by tool

运作原理

代币分析（4个工具）

Click to expand

用于精确定位优化机会的粒度令牌使用分析：

get_cook_analytics -按挂钩阶段（PreToolUse、PostToolUse等）划分的令牌使用情况
get_action_analytics -按工具/操作（读取、写入、擦除等）分列的令牌使用情况
get_mcp_server_analytics -按MCP服务器（令牌优化器、文件系统等）划分的令牌使用情况
出口分析 -以JSON或CSV格式导出分析数据，并进行过滤

用法示例:

// Get per-hook analytics
get_hook_analytics({
  startDate: "2025-01-01T00:00:00Z",
  endDate: "2025-12-31T23:59:59Z"
})
// Result: Shows which hooks consume the most tokens

// Get per-action analytics
get_action_analytics({})
// Result: Shows which tools use the most tokens

// Export analytics as CSV
export_analytics({
  format: "csv",
  hookPhase: "PreToolUse"
})
// Result: CSV export filtered by PreToolUse hook

主要特点:

每个钩子阶段跟踪（PreToolUse、PostToolUse、SessionStart等）
按动作跟踪（读取、写入、计数标记等）
每MCP服务器跟踪（令牌优化器、文件系统、GitHub等）
日期范围过滤
JSON和CSV导出
SQLite的持久存储
零性能影响（异步批处理写入）

全局挂钩系统（7相优化）

安装全局挂钩后，令牌优化器mcp会自动运行 每次工具调用:

┌─────────────────────────────────────────────────────────────┐
│ Phase 1: PreToolUse - Tool Replacement                      │
│ ├─ Read   → smart_read   (80% token reduction)             │
│ ├─ Grep   → smart_grep   (80% token reduction)             │
│ └─ Glob   → smart_glob   (75% token reduction)             │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 2: Input Validation - Cache Lookups                   │
│ └─ get_cached checks if operation was already done          │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 3: PostToolUse - Output Optimization                  │
│ ├─ optimize_text for large outputs                          │
│ └─ compress_text for repeated content                       │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 4: Session Tracking                                   │
│ └─ Log all operations to operations-{sessionId}.csv         │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 5: UserPromptSubmit - Prompt Optimization             │
│ └─ Optimize user prompts before sending to API              │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 6: PreCompact - Pre-Compaction Optimization           │
│ └─ Optimize before Claude Code compacts the conversation    │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 7: Metrics & Reporting                                │
│ └─ Track token reduction metrics and generate reports       │
└─────────────────────────────────────────────────────────────┘

生产性能

基于现实世界中38000多次操作：

工具类别	平均令牌减少	缓存命中率
文件操作	60-90%	>80%
API响应	83-95%	>75%
数据库查询	83-90%	>70%
构建/测试输出	70-85%	>65%

每节课节省：300K-700K代币（按3/M代币计算，价值0.90-2.10美元）

使用示例

基本缓存

// Cache large content to remove from context window
const result = await optimize_text({
  text: "Large API response or file content...",
  key: "cache-key",
  quality: 11
});
// Result: Original tokens removed, only cache key remains (~50 tokens)

// Retrieve later
const cached = await get_cached({ key: "cache-key" });
// Result: Full original content restored

智能文件读取

// First read: full content
await smart_read({ path: "/src/app.ts" });

// Subsequent reads: only changes (80% reduction)
await smart_read({ path: "/src/app.ts" });

API缓存

// First request: fetch and cache
await smart_api_fetch({
  method: "GET",
  url: "https://api.example.com/data",
  ttl: 300
});

// Subsequent requests: cached (95% reduction)
await smart_api_fetch({
  method: "GET",
  url: "https://api.example.com/data"
});

会话分析

// View token usage for current session
await get_session_stats({});
// Result: Breakdown by tool, operation, and savings

// Analyze entire project
await analyze_project_tokens({
  projectPath: "/path/to/project"
});
// Result: Cost estimation and optimization opportunities

技术栈

运行时：Node.js 20+
语言：TypeScript
数据库：SQLite（更好的平方3）
令牌计数：tiktoken（gpt-4托克宁器）
压缩：Brotli（内置Node.js）
缓存：多层LRU/LFU/FIFO缓存
协议：MCP SDK（@modelcontextprotocol/SDK）

支持的AI工具

自动安装程序检测并配置令牌优化器mcp，用于：

✅ 克劳德代码 -具有全局挂钩集成的CLI
✅ 克劳德桌面 -本机桌面应用程序
✅ 光标IDE -AI第一代码编辑器
✅ 克莱恩 -VS代码扩展（前身为Claude Dev）
✅ GitHub Copilot -支持MCP的VS代码
✅ Windsurf IDE -人工智能驱动的开发环境

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

文档

详细工具参考 -所有61个工具的完整文档
安装指南 -平台特定安装说明
贡献指南 -开发设置和贡献指南

性能特征

压缩比：典型值为2-4x（重复内容最高可达82x）
上下文窗口节省：所有运营平均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级别日志记录 - 减小日志文件大小并提高性能 - 信息/警告/错误日志仍在写入 - 例子： $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 工具：

// View current session statistics with token savings breakdown
await get_session_stats({});

输出包括：

已保存的令牌总数 （这是实际节省的金额！）
代币减少百分比 （例如，“减少60%”）
缓存命中率 和 压缩比
按工具细分 （阅读、Grep、Glob等）
十大优化操作 前后对比

输出示例：

{
  "sessionId": "abc-123",
  "totalTokensSaved": 125430,  // ← THIS is your savings!
  "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,      // ← Number of operations
  "totalTokens": 184000,         // ← Cumulative token COUNT
  "lastOptimized": 1698765432,
  "savings": {                   // ← Auto-updated every 10 operations (Issue #113)
    "totalTokensSaved": 125430,  // Tokens saved by compression
    "tokenReductionPercent": 68.2,  // Percentage of tokens saved
    "originalTokens": 184000,    // Original token count before optimization
    "optimizedTokens": 58570,    // Token count after optimization
    "cacheHitRate": 42.5,        // Cache hit rate percentage
    "compressionRatio": 0.32,    // Compression efficiency (lower is better)
    "lastUpdated": "20251031-092500"  // Last savings update timestamp
  }
}

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

运作原理:

每执行10次操作，PowerShell挂钩就会自动调用 get_cache_stats() MCP工具
节省指标是根据缓存性能数据（压缩比、原始大小与压缩大小）计算的
会话文件会自动更新为最新的节省数据
如果MCP调用失败，则会优雅地跳过更新，而不会阻止操作

备注：有关详细的每次操作分析，请使用 get_session_stats()会话文件提供高级聚合度量。

项目范围分析

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

// Analyze project token costs
await analyze_project_tokens({
  projectPath: "/path/to/project"
});

提供：

代币总成本估算
按令牌计数的最大文件数
优化机会
按当前API价格进行的成本预测

高速缓存性能

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

// View cache statistics
await get_cache_stats({});

韵律学：

条目总数
缓存命中率（%）
平均压缩比
已保存的总存储空间
最常访问的密钥

故障排除

常见问题及解决方法

问题：Claude代码设置中的“JSON无效或格式错误”

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

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

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

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

如果您已经使用v3.0.2+，请手动删除BOM：

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

# Linux: Remove BOM from settings.json
sed -i '1s/^\xEF\xBB\xBF//' ~/.claude/settings.json

# macOS: Remove BOM from settings.json (BSD sed requires empty string after -i)
sed -i '' '1s/^\xef\xbb\xbf//' ~/.claude/settings.json

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

症状：令牌优化不会自动发生

诊断:

检查挂钩是否安装：

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

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

验证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%

原因:

处理许多新文件（预期）
缓存最近已清除
TTL（生存时间）太短

解决方案:

预热缓存 开始工作前：

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

增加TTL 对于稳定的API：

   await smart_api_fetch({
     url: "https://api.example.com/data",
     ttl: 3600  // 1 hour instead of default 5 minutes
   });

检查缓存大小限制:

   await smart_cache({
     operation: "configure",
     l1MaxSize: 2000,  // Increase from default 1000
     l2MaxSize: 20000  // Increase from default 10000
   });

问题：内存使用率高

症状：Node.js进程占用了过多内存

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

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

await smart_cache({
  operation: "configure",
  evictionStrategy: "LRU",  // Least Recently Used
  l1MaxSize: 500,  // Reduce L1 cache
  l2MaxSize: 5000  // Reduce L2 cache
});

或者清除缓存：

await clear_cache({});

问题：首次操作缓慢

症状：初始读取/Grep/Glob操作缓慢

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

解决方案：这是预期的行为。后续操作将快80-90%。

要预热缓存，请执行以下操作：

await cache_warmup({
  paths: ["/src", "/tests", "/docs"],
  recursive: true,
  schedule: "startup"  // Auto-warm on every session start
});

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

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

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

解决方案:

设置执行策略:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

检查文件权限:

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

以管理员身份重新运行安装程序 如有需要

问题：缓存文件增长太大

症状: ~/.token-optimizer/cache.db 大于1GB

原因：缓存非常大的文件或许多API响应

解决方案:

清除旧条目:

   await clear_cache({ olderThan: 7 });  // Clear entries older than 7 days

减少缓存保留:

   await smart_cache({
     operation: "configure",
     defaultTTL: 3600  // 1 hour instead of 7 days
   });

手动删除缓存 （核选项）：

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

获取帮助

如果您遇到此处未涵盖的问题：

检查吊钩日志: ~/.claude-global/hooks/logs/dispatcher.log
检查会话数据: ~/.claude-global/hooks/data/current-session.txt
提交问题:

- 包括调试日志 - 包含您的操作系统和Node.js版本 - 包括以下输出 get_session_stats

局限性

小文本：最适合大于500个字符的内容（小片段的缓存开销）
一次性内容：不会再次引用的内容没有任何好处
高速缓冲存储器：7天后自动清理，以防止磁盘使用问题
令牌计数：使用GPT-4标记器（与Claude近似，但足够接近）

许可证

MIT许可证-请参阅许可证详情

作者

由ooples团队为优化Claude Code代币效率而构建。

Token Optimizer MCP

快速接入

详细介绍

令牌优化器MCP

概述

主要特点

安装

快速安装（推荐）

视窗

macOS/Linux

手动配置

可用工具（共65个）

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

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

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

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

高级缓存（10个工具）

监控和仪表板（7个工具）

系统操作（6个工具）

运作原理

代币分析（4个工具）

全局挂钩系统（7相优化）

生产性能

使用示例

基本缓存

智能文件读取

API缓存

会话分析

技术栈

支持的AI工具

文档

性能特征

性能优化

环境变量

性能控制

发展路径

监控令牌节省

实时会话监控

会话跟踪文件

项目范围分析

高速缓存性能

故障排除

常见问题及解决方法

问题：Claude代码设置中的“JSON无效或格式错误”

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

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

问题：内存使用率高

问题：首次操作缓慢

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

问题：缓存文件增长太大

获取帮助

局限性

许可证

作者

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP