ooples/token-optimizer-mcp

Measure token savings per AI coding agent, optimize context, and share a live local knowledge graph across 16 CLI clients.

Token Optimizer MCP – それは何ですか

Token Optimizer MCP は、大規模言語モデル（LLM）クライアント（Claude Code、Codex、Gemini など）とローカルファイルシステムの間に配置されるオープンソースの Node.js プラグインです。このプラグインは、すべての MCP（Model‑Client‑Protocol）操作（読み取り、grep、編集、書き込みなど）を監視し、モデルがすでに「支払い済み」のトークンを送信することを回避しようとします。その方法は以下の通りです。

重複する読み取りのブロッキング – セッション内ですでに読み込まれたファイルに対して、プラグインは元の Read 要求を拒否し、モデルが追加のトークンを消費せずに使える diff を返します。
結論の記憶 – セッション終了後、ツールは軽量なプロジェクト単位の知識グラフ（ファイル、シンボル、発見、決定、失敗した道筋）を構築します。次のセッションで同じコードに触れる際、このグラフから結論を直接供給できるため、数千トークンの節約が可能になります。
節約量の測定 – すべての操作は、前（送信されるはずだった）と実際（実際に送信された）のトークン数でログに記録され、どの程度のコンテキストが回避されたかを正確に確認できます。
クライアントごとのコストの帰属 – ダッシュボードには、各LLMクライアント（Claude Code、Codex、Gemini、…）ごとに別々の行が表示され、どのエージェントが最も恩恵を受けているかがわかります。

すべてのデータは開発者のマシン上に留まります；テレメトリもホストサービスもありません。コードは MIT ライセンスのため、商用環境でも使用可能です。

コアコンセプト

コンセプト	機能
MCPの強制	高コストな呼び出し（`Read`、`Grep`、`Glob`、`Edit`、`Write`、`cat`、`head` など）をインターセプトし、キャッシュされた差分を返すことで拒否するか、コンテンツが本当に新規の場合に通過させる。
プロジェクト単位の知識グラフ	ノード = ファイル、シンボル、タスク、発見；エッジ = `derived_from`、`contains`、`supersedes` など。このグラフはツール出力から自動的に構築され、オプションのモデルベース「収穫」呼び出しも可能。
ゼロターン拒否	読み取りが拒否された場合、拒否の返答にすでに答え（差分）が含まれているため、モデルは2回目のターンを必要とせず、トークンコストは1ターンからゼロに低下する。
ダッシュボード	ローカルのWeb UI（`http://localhost:3100`）で、ネットトークン節約量、クライアント別会計、グラフの健全性、知識グラフの3Dエクスプローラーを表示。
テレメトリフリー	すべてのログはローカルに記録され、プロンプト、ファイル内容、パスは含まれず、環境変数でローテーションまたは無効化可能。

クイックスタート（READMEから）

# MCPサーバーとLLMクライアント用のプラグインをインストール（例：Claude Code）
/plugin marketplace add ooples/token-optimizer-mcp
/plugin install token-optimizer@token-optimizer
/reload-plugins

プラグインが有効になったら、任意のセッションで監査コマンドを実行します：

token_audit   # 最も高コストな操作のランク付きリストを出力

ローカルでダッシュボードを起動するには：

npm install          # 開発依存関係をインストール
npm run build        # UIをコンパイル
npm run dashboard    # http://localhost:3100 を開く

ダッシュボードで確認できる内容（READMEからの例）

43 491 のネット検証済み MCP トランスポートトークンを回避（総削減量から意図的な拡張量を差し引いたもの）。
486 074 740 の歴史的トークンを隔離 – モデルコンテキストに一度も入らなかった、元のファイルスキャンデータ。
Codex、Claude Code、Gemini などのクライアントごとの行で、回避されたトークンと実際に返されたトークンの両方を表示。
グラフ統計 – 例：2 648 ノード、6 527 エッジ、11プロジェクトにわたる58件の発見。
健全性パネル – フック実行回数、失敗数、タイムアウト、各クライアントごとの遅延パーセンタイル。
「グラフ置換可能性」と「因果研究」セクションでは、キャッシュされた発見を提供することで、後の読み取りが実際に防止されたかを追跡。

一般的な利用シーン

シナリオ	Token Optimizerがどのように役立つか
繰り返しのファイル読み取り – デバッグセッションで同じ大きなソースファイルを何度も開く。	プラグインは2回目の読み取りを拒否し、小さな差分を返すため、数千トークンを節約。
結論の再導出 – CI実行後に新しいターミナルを開き、特定のバグの原因をモデルに尋ねる。	知識グラフに以前の推論（例：「時計のずれが401エラーを引き起こした」）がすでに保存されているため、モデルは再計算せずに回答可能。
マルチクライアントプロジェクト – チームが一部のタスクでは Claude Code、他のタスクでは Gemini を使用。	トークン会計はクライアントごとに分離され、どのモデルが最もコストパフォーマンスが高いかを確認可能。
予算管理のためのコスト追跡 – 財務チームにLLMの使用状況を報告する必要がある。	前後トークン数は永続化され、MarkdownまたはJSONとしてエクスポート可能。

制限事項と注意点（READMEに記載）

自動RAGなし – システムは元のドキュメントを取得しない。すでに導出された結論のみを再利用する。
モデルベースの収穫はオプション – 認証情報（TOKEN_OPTIMIZER_HARVEST_ENDPOINT）がなければ、意味的収穫ステップは無効化され、構造的なグラフのみが構築される。
ゼロターン拒否にはモデルがファイルを要求する必要がある – モデルがファイルを一度も要求しなければ、最適化は介入できない。
グラフベースの節約は別途測定 – グラフ置換による潜在的な節約は表示されるが、十分な処理済み/ホールドアウトサンプルが存在するまでは、検証済みの見出しにはカウントされない。
16の公式サポートクライアントのみ – READMEには16のクライアントがリストアップされている。サポート外のクライアントを使用すると、同じ会計が得られない。
ローカルのみ – すべてのデータはマシン上に留まる。開発者間でグラフを共有するクラウドサービスは存在しない。

どのような人に向いているか？

トークン料金を抑えたい、AI支援コーディングアシスタントを開発している開発者。
オンプレミスでLLMを運用しているチーム（例：Claude、Gemini）で、データを外部に送ることなくトークン使用状況を監査したい人。
トークン経済学を研究している研究者 – 内蔵された前後測定とコントロールアーム実験により、再現可能なデータセットが提供される。
厳格なデータプライバシーポリシーを持つ企業 – ツールは完全にオフラインで動作し、商用利用に適したMITライセンスを遵守。

まとめ

Token Optimizer MCP は、実用的でプライバシーを最優先したLLM駆動開発ワークフローの最適化ツールです。重複する読み取りを拒否し、軽量な知識グラフに導出された結論をキャッシュし、クライアントごとに透明なトークン節約メトリクスを公開することで、モデルがすでに処理した作業を再び支払うのではなく、新しい推論にコンテキスト予算を残すことができます。