token-lens

token-lens-mcp

コンテキストウィンドウのトークン使用量を分析・最適化する MCP サーバーです。MCP ツールの定義は、ユーザーの作業を始める前にコンテキストウィンドウの 40～72% を消費します。このサーバーを使えば、その無駄を測定、圧縮、削減できます。

インストール

npx token-lens-mcp

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "token-lens": {
      "command": "npx",
      "args": ["token-lens-mcp"]
    }
  }
}

Claude Code

claude mcp add token-lens -- npx token-lens-mcp

ツール

audit_context_budget

MCP ツール定義のトークンコストを分析します。JSON 定義全体に対する chars/4 の近似値を使って、ツールごとのトークン数を推定します。

パラメーター：

• tools — {name, description, schema} オブジェクトの配列

戻り値： ツールごとのトークンコスト（コスト順）、合計トークン数、128K／200K／1M のコンテキストウィンドウに対する割合。

optimize_tool_loading

タスクの説明を基に、必要最小限のツールセットを推奨します。キーワードマッチングとカテゴリ関連性スコアを使用します。

パラメーター：

• task_description — 実現したいこと
• available_tools — {name, description, category?} の配列

戻り値： 関連性順に並べた推奨ツール、除外されたツール、推定削減トークン数。

compress_schema

冗長なツールスキーマを圧縮して、トークン使用量を削減します。

パラメーター：

• tool_name — ツール名
• schema — 圧縮する JSON Schema オブジェクト
• level — "light" | "medium" | "aggressive"

レベル：

• light — 20 文字未満の説明を削除します
• medium — 説明を 50 文字に短縮し、例を削除します
• aggressive — すべての説明を削除し、型と必須フィールドのみを残します

戻り値： 圧縮後のスキーマ、圧縮前後のトークン数、削減率。

analyze_session_usage

セッション中に実際に呼び出されたツールと、読み込まれたツールを追跡します。

パラメーター：

• session_id — 一意のセッション識別子
• action — "register_tool" | "log_call" | "report"
• tool_name — ツール名（register_tool／log_call では必須）
• tool_tokens — トークンコスト（register_tool 用。デフォルトは 50）

レポートの戻り値： 読み込み済みと使用済みの件数、無駄の割合、トークンコスト順に並べた未使用ツール。

suggest_removals

使用パターンに基づいて、安全に削除できるツールを特定します。

パラメーター：

• usage_history — {tool_name, call_count, last_used_days_ago} の配列

スコアリング： never_used（優先度 3）> not_used_30_days（優先度 2）> rarely_used（優先度 1）

戻り値： 理由と推定トークン削減数を含む、削除候補。

get_optimization_report

監査、削除候補の提案、圧縮の推奨事項を組み合わせた、コンテキストウィンドウの総合ヘルスチェックです。

パラメーター：

• tools — ツール定義の配列
• usage_history — 任意の使用履歴配列

戻り値： ヘルスグレード（excellent／good／fair／poor）、監査結果、削除候補、圧縮の機会、実行可能な推奨事項を含む概要。

リソース

token-lens://tips

スキーマ設計のヒント、トークン予算のガイドライン、動的なツール読み込みの戦略など、MCP のコンテキストウィンドウの肥大化を抑えるベストプラクティスガイドです。

開発

npm install
npm test
npm run dev  # watch mode

ライセンス

MIT