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的最佳令牌效率而構建。