⚔ token-savior

AIにコードベース全体を読み込ませるのはやめましょう。代わりにメスを与えてください。

Python 3.11+ MCP

コードベースを構造的にインデックス化し、外科的なクエリツールを提供するMCPサーバーです。AIエージェントは200ファイルではなく200文字を読むだけで済みます。

find_symbol("send_message")           →  67 chars    (was: 41M chars of source)
get_change_impact("LLMClient")        →  16K chars   (154 direct + 492 transitive deps)
get_function_source("compile")        →  4.5K chars  (exact source, no grep, no cat)
analyze_config()                      →  finds duplicates, secrets, orphan keys

782件の実際のセッションで測定：99%のトークン削減。

なぜこれが必要なのか

AIコーディングセッションはいつも同じ方法で始まります。エージェントは cat や grep を使い、1つの関数を見つけるために十数個のファイルを読み込み、他に何が壊れる可能性があるかを理解しようとしてコンテキストを肥大化させます。最終的に、最初の編集を行う前にトークン予算の半分が消費されてしまいます。

token-savior はそのパターンを完全に置き換えます。一度構造的インデックスを構築し、Gitと自動的に同期を保ち、「Xはどこにあるか」「Xを呼び出しているのは何か」「Xを変更すると何が壊れるか」という問いにサブミリ秒で回答します。回答はコードベース全体ではなく、答えに必要なサイズで返されます。

数値

実際のセッションにおけるトークン削減量

プロジェクト	セッション	クエリ	使用文字数	文字数 (単純計算)	削減率
project-alpha	35	360	4,801,108	639,560,872	99%
project-beta	26	189	766,508	20,936,204	96%
project-gamma	30	232	410,816	3,679,868	89%
合計	92	782	5,981,476	664,229,092	99%

「文字数 (単純計算)」= エージェントが cat/grep で読み込んだであろう全ファイルの合計ソースサイズ。この削減はモデルに依存しません。プロバイダーに関係なく、インデックスがコンテキストウィンドウの圧迫を軽減します。

クエリ応答時間 (110万行でサブミリ秒)

クエリ	RMLPlus	FastAPI	Django	CPython
`find_symbol`	0.01ms	0.01ms	0.03ms	0.08ms
`get_dependencies`	0.00ms	0.00ms	0.00ms	0.01ms
`get_change_impact`	0.02ms	0.00ms	2.81ms	0.45ms
`get_function_source`	0.01ms	0.02ms	0.03ms	0.10ms

インデックス構築パフォーマンス

プロジェクト	ファイル数	行数	インデックス時間	メモリ
小規模プロジェクト	36	7,762	0.9s	2.4 MB
FastAPI	2,556	332,160	5.7s	55 MB
Django	3,714	707,493	36.2s	126 MB
CPython	2,464	1,115,334	55.9s	197 MB

永続キャッシュを使用すると、再起動後のフルビルドはスキップされます。CPythonの場合、キャッシュヒットで56秒から1秒未満に短縮されます。

対応範囲

言語 / フォーマット	ファイル	抽出内容
Python	`.py`, `.pyw`	関数、クラス、メソッド、インポート、依存関係グラフ
TypeScript / JS	`.ts`, `.tsx`, `.js`, `.jsx`	関数、アロー関数、クラス、インターフェース、型エイリアス
Go	`.go`	関数、メソッド (レシーバー)、構造体、インターフェース、型エイリアス
Rust	`.rs`	関数、構造体、列挙型、トレイト、implブロック、macro_rules
C#	`.cs`	クラス、インターフェース、構造体、列挙型、メソッド、XMLドキュメントコメント
Markdown / Text	`.md`, `.txt`, `.rst`	見出し検出によるセクション
JSON	`.json`	深さ4までのネストされたキー構造、$refによる相互参照
YAML	`.yaml`, `.yml`	ネストされたキー階層、配列マーカー、深さ制限4
TOML	`.toml`	テーブル、キーと値のペア、ネストされた構造
INI / Properties	`.ini`, `.cfg`, `.properties`	セクション、キーと値のペア
Environment	`.env`	変数名、値 (シークレットのマスキングあり)
XML / Plist / SVG	`.xml`, `.plist`, `.svg`, `.xhtml`	要素階層、属性
HCL / Terraform	`.hcl`, `.tf`	ブロック、ネストされたリソース、キーと値のペア
Conf	`.conf`	キーと値のペア、ブロック構造
Dockerfile	`Dockerfile`, `*.dockerfile`	命令、マルチステージビルド、FROM/RUN/COPY/ENV
その他すべて	`*`	行数 (汎用フォールバック)

51個のツール

ツール	説明
`find_symbol`	シンボルの定義場所 — ファイル、行、型、20行のプレビュー
`get_function_source`	関数またはメソッドの完全なソース
`get_class_source`	クラスの完全なソース
`get_functions`	ファイルまたはプロジェクト内の全関数
`get_classes`	メソッドと基底クラスを含む全クラス
`get_imports`	モジュール、名前、行を含む全インポート
`get_structure_summary`	ファイルまたはプロジェクト構造の概要
`list_files`	インデックス化されたファイル (オプションのglobフィルタ付き)
`get_project_summary`	ファイル数、パッケージ、主要なクラス/関数
`search_codebase`	インデックス化された全ファイルに対する正規表現検索
`reindex`	強制的なフル再インデックス (通常は不要)

コンテキストと発見

ツール	説明
`get_edit_context`	オールインワン: シンボルソース + 依存関係 + 呼び出し元を1回の呼び出しで取得 (3回分を節約)
`get_feature_files`	機能キーワードに関連する全ファイルを検索し、インポートを推移的に追跡
`get_routes`	APIルートとページを検出 (Next.js App Router, Express, pages/api)
`get_components`	`.tsx`/`.jsx` ファイル内のReactコンポーネント (JSXを返す関数) を検出
`get_env_usage`	コードベース全体で環境変数の全参照を検索

影響分析

ツール	説明
`get_dependencies`	シンボルが呼び出し/使用しているもの
`get_dependents`	シンボルを呼び出し/使用しているもの
`get_change_impact`	直接的 + 推移的な依存関係を1回の呼び出しで取得
`get_call_chain`	2つのシンボル間の最短依存パス (BFS)
`get_file_dependencies`	指定されたファイルによってインポートされているファイル
`get_file_dependents`	指定されたファイルをインポートしているファイル

Gitとdiff

ツール	説明
`get_git_status`	ブランチ、進捗状況、ステージング済み、未ステージング、追跡対象外
`get_changed_symbols`	変更されたファイルをdiffではなくシンボルレベルの概要として取得
`get_changed_symbols_since_ref`	任意のGit参照以降のシンボルレベルの変更
`summarize_patch_by_symbol`	コンパクトなレビュービュー — テキストdiffではなくシンボル単位
`build_commit_summary`	変更されたファイルからのコンパクトなコミット概要

安全な編集

ツール	説明
`replace_symbol_source`	ファイルの他の部分に触れずにシンボルのソースを置換
`insert_near_symbol`	シンボルの前後にコンテンツを挿入
`create_checkpoint`	編集前にファイルセットのスナップショットを作成
`restore_checkpoint`	チェックポイントから復元
`compare_checkpoint_by_symbol`	チェックポイントと現在の状態をシンボルレベルで比較
`list_checkpoints`	利用可能なチェックポイントを一覧表示

テストと実行

ツール	説明
`find_impacted_test_files`	変更されたシンボルから影響を受ける可能性のあるpytestファイルを推論
`run_impacted_tests`	影響を受けるテストのみを実行 — 生ログではなくコンパクトな概要
`apply_symbol_change_and_validate`	編集 + 影響を受けるテストの実行を1回の呼び出しで実行
`apply_symbol_change_validate_with_rollback`	編集 + 検証 + 失敗時の自動ロールバック
`discover_project_actions`	プロジェクトファイルからテスト/lint/ビルド/実行コマンドを検出
`run_project_action`	制限付き出力で検出されたアクションを実行

設定分析

ツール	説明
`analyze_config`	設定ファイルの重複、シークレット、タイプミス、孤立したキーをスキャン

3つのチェックを実行します (checks パラメータで個別に切り替え可能):

Duplicates — 同じファイル内で同じキーが2回定義されている場合、およびレーベンシュタイン距離に基づくタイプミス検出 (例: db_hsot vs db_host)
Secrets — 既知のシークレット形式 (APIキー、トークン、秘密鍵) の正規表現パターン、および高エントロピー文字列に対するシャノンエントロピー分析
Orphans — 設定キーと実際のコード使用状況を相互参照。コードが一度も読み取っていないキーや、コードが期待しているが設定されていない環境変数を検出。os.environ, process.env, os.Getenv, std::env::var などを理解します。

対応フォーマット: .yaml, .yml, .toml, .ini, .cfg, .properties, .env, .xml, .plist, .hcl, .tf, .conf, .json

コード品質

ツール	説明
`find_dead_code`	呼び出し元がゼロの関数/クラスを検索 (エントリーポイント、テスト、デコレータ付きルートを除く)
`find_hotspots`	複雑度スコア (行数、分岐、ネスト、パラメータ数) で関数をランク付け
`detect_breaking_changes`	現在の関数シグネチャをGit参照と比較 — 削除/名前変更されたパラメータ、変更されたデフォルト値をフラグ付け

Docker

ツール	説明
`analyze_docker`	Dockerfileの監査: ベースイメージ、公開ポート、ENV/ARGの相互参照、`latest` タグの警告

マルチプロジェクト

ツール	説明
`find_cross_project_deps`	プロジェクト間のインポートを相互参照し、共有依存関係を検索

統計

ツール	説明
`get_usage_stats`	セッションごとのプロジェクト別の累積トークン削減量

LSPとの比較

LSPは「これはどこで定義されているか？」に答えますが、token-savior は「これを変更すると何が壊れるか？」に答えます。

LSPはポイントクエリです。1つのシンボル、1つのファイル、1つの位置。LLMClient がどこで定義され、誰が直接参照しているかは見つけられます。「LLMClient をリファクタリングすると推移的に何が壊れるか？」と尋ねても、LSPには何もありません。AIは参照検索を再帰的に何十回も連鎖させ、ステップごとにファイルを読み込む必要があります。

CPythonで get_change_impact("TestCase") を実行すると、0.45msで154の直接依存関係と492の推移的依存関係を見つけ、41MBを読み込む代わりに16KBの文字を返します。また、LSPとは異なり、言語サーバーを一切必要としません。1つのバイナリでPython + TS/JS + Go + Rust + C# + 設定ファイル + Dockerfileをすぐにカバーします。

インストール

git clone https://github.com/Mibayy/token-savior
cd token-savior
python3 -m venv ~/.local/token-savior-venv
~/.local/token-savior-venv/bin/pip install -e ".[mcp]"

設定

Claude Code / Cursor / Windsurf / Cline

プロジェクトルートの .mcp.json に追加します:

{
  "mcpServers": {
    "token-savior": {
      "command": "/path/to/.local/token-savior-venv/bin/token-savior",
      "env": {
        "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
        "TOKEN_SAVIOR_CLIENT": "claude-code"
      }
    }
  }
}

Hermes Agent

~/.hermes/config.yaml に追加します:

mcp_servers:
  token-savior:
    command: ~/.local/token-savior-venv/bin/token-savior
    env:
      WORKSPACE_ROOTS: /path/to/project1,/path/to/project2
      TOKEN_SAVIOR_CLIENT: hermes
    timeout: 120
    connect_timeout: 30

TOKEN_SAVIOR_CLIENT はオプションですが、ライブダッシュボードでクライアントごとの削減量を属性付けできるようになります。

エージェントに実際に使わせる

AIアシスタントは、より優れたツールが利用可能であってもデフォルトで grep や cat を使用します。ソフトな指示は合理化されて無視されがちです。CLAUDE.md または同等のファイルに以下を追加してください:

## Codebase Navigation — MANDATORY

You MUST use token-savior MCP tools FIRST.

- ALWAYS start with: find_symbol, get_function_source, get_class_source,
  search_codebase, get_dependencies, get_dependents, get_change_impact
- Only fall back to Read/Grep when token-savior tools genuinely don't cover it
- If you catch yourself reaching for grep to find code, STOP

マルチプロジェクトワークスペース

1つのサーバーインスタンスでマシン上のすべてのプロジェクトをカバーします:

WORKSPACE_ROOTS=/root/myapp,/root/mybot,/root/docs token-savior

各ルートは独自の分離されたインデックスを持ち、初回使用時に遅延読み込みされます。list_projects は登録されている全ルートを表示し、switch_project はアクティブなプロジェクトを設定します。

同期を保つ方法

サーバーはクエリのたびに git diff と git status をチェックします (~1-2ms)。変更されたファイルはインクリメンタルに再解析されます。編集、ブランチ切り替え、プル後に手動で reindex する必要はありません。

token-savior