Token Optimizer MCP

🚀 Token Optimizer MCP

Token Optimizer MCPは、Claude CodeやClaude Desktopで使用するトークンを、キャッシュ、圧縮、スマートツールによって最適化することができるシステムです。

🚀 クイックスタート

Token Optimizer MCPは、Model Context Protocol (MCP) サーバーで、インテリジェントなキャッシュ、圧縮、スマートツールの置き換えにより、コンテキストウィンドウの使用量を60-90%削減します。圧縮されたコンテンツをSQLiteに外部保存し、標準ツールの最適化された代替手段を提供することで、利用可能なコンテキストウィンドウを最大限に活用することができます。

実運用結果: 実際の使用で38,000以上の操作で60-90%のトークン削減

✨ 主な機能

• スマートツール置き換え: Read、Grep、Globなどの自動最適化
• コンテキストウィンドウ最適化: コンテンツを外部に保存してコンテキスト空間を解放
• 高圧縮率: 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"
});
// 結果: コスト見積もりと最適化の機会

高度な使用法

各種ツールの詳細な使用例は、以下の各セクションを参照してください。

コアキャッシュと最適化 (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: メトリクスとレポート                                │
│ └─ トークン削減メトリクスを追跡し、レポートを生成       │
└─────────────────────────────────────────────────────────────┘

本番環境でのパフォーマンス

実際の使用で38,000以上の操作に基づく結果：

セッションごとの節約: 300K-700Kトークン (3ドル/Mトークンで0.90-2.10ドル相当)

技術スタック

サポートされるAIツール

自動インストーラーは、以下のAIツールに対してtoken-optimizer-mcpを検出して設定します：

• ✅ Claude Code - グローバルフック統合付きのCLI
• ✅ 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から最適化)
• 圧縮速度: テキスト1KBあたり約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%削減")
• キャッシュヒット率と圧縮率
• ツールごとの内訳 (Read、Grep、Globなど)
• 最も最適化された上位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操作ごとに自動更新 (Issue #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」エラー

症状: install-hooksを実行した後、Claude Codeが「無効な設定」エラーを表示する

原因: settings.jsonファイルにUTF-8 BOM (Byte Order Mark) が追加された

解決策: BOM問題を修正したv3.0.2+にアップグレードします：

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 (time-to-live) が短すぎる

解決策:

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  // デフォルトの5分から1時間に変更
   });
   

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({});

問題: 初回操作が遅い

症状: 最初のRead/Grep/Glob操作が遅い

原因: キャッシュが空で、インデックスを構築している

解決策: これは予想される動作です。それ以降の操作は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  // 7日から1時間に変更
   });
   

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
   • デバッグログを含める
   • OSとNode.jsのバージョンを含める
   • get_session_statsの出力を含める

制限事項

• 短いテキスト: 500文字以上のコンテンツに最適 (短いスニペットではキャッシュのオーバーヘッドが大きい)
• 一度だけのコンテンツ: 再度参照されないコンテンツには効果がない
• キャッシュストレージ: ディスク使用量の問題を防ぐため、7日後に自動的にクリーンアップ
• トークンカウント: GPT-4トークナイザーを使用 (Claudeには近似値ですが、十分に近い)

📄 ライセンス

MITライセンス - 詳細は LICENSE を参照してください。

作者

ooplesチームによって、Claude Codeのトークン効率を最適化するために構築されました。