便利なソフトをAIが実際に動かしてわかりやすくレポート

🤖 AI自動レポート column

AIのコード読み込みを99%削減！構造インデックスMCPサーバー「token-savior」でトークン消費を激減させる

タグ columnコラムlinuxLinuxmacwindowsWindowspythonmcpGitHubオープンソースMibayytoken-savior
📦 GitHubで見る 📥 デモスクリプトをダウンロード (.sh)
🚀 今すぐ試せます！ デモスクリプトをダウンロードして、解凍後にターミナルで bash ファイル名.sh を実行してください（中身を一度確認してから実行すると安心です）。 （macOS / Linux 環境が必要）

AIのコード読み込みを99%削減！構造インデックスMCPサーバー「token-savior」でトークン消費を激減させる

ひとことでいうと

token-savior は、AIエージェントがコードを調べる際のトークン消費を劇的に減らすMCPサーバーです。従来のAIコーディング支援では、エージェントが grep や cat でファイルを次々と読み込み、コンテキストウィンドウをすぐ圧迫してしまいます。token-savior はコードベースを事前に構造インデックス化し、「このシンボルはどこにある？」「この変更の影響範囲は？」という問いにミリ秒・最小文字数で答えます。READMEに記載された実測値では782セッションの集計で99%のトークン削減（664MB相当の読み込みを6MBに圧縮）が報告されており、APIコストと回答精度の両方を改善できるツールです。

こんな人におすすめ

1. AIコーディング支援を日常的に使っている開発者 Claude CodeやCursorなどのAIアシスタントを多用していて、トークン消費コストや回答精度の低下が気になっている方に最適です。コンテキストウィンドウが圧迫されるほど回答が劣化する問題を、インデックス構造で根本から解消できます。

2. 大規模リポジトリを扱うチームリーダー・シニアエンジニア 「この変更を加えたら、どこが壊れる可能性があるか？」をAIに素早く把握させたい場面に向いています。Djangoクラス規模（37万行超）以上のコードベースでも、インデックス構築後はサブミリ秒レベルで全体の依存グラフを取得できます。

3. MCPエコシステムを開発・研究している方 MCP対応ツールを自作・評価している方にとっては、39ツールのスキーマ設計の好例になります。Pythonの標準ライブラリのみで実装されており、コードリーディングも容易です。

インストール・使い方

Step 1: リポジトリを取得して仮想環境をセットアップする

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]"

Python 3.11以上が必要です。[mcp] オプションを指定することでMCPサーバー機能が有効になります。開発ツールも使いたい場合は [dev,mcp] に変えてください。仮想環境をホームディレクトリ配下に作ることで、複数プロジェクトをまたいで同じインストールを使い回せます。

Step 2: .mcp.json にサーバー設定を追加する

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

WORKSPACE_ROOTS に対象プロジェクトのパスを指定します。カンマ区切りで複数パスを列挙することもでき、1つのサーバーインスタンスで複数リポジトリを同時管理できます。

Step 3: CLAUDE.md に必須指示を記載する

## Codebase Navigation — MANDATORY

You MUST use token-savior MCP tools FIRST.

- ALWAYS start with: find_symbol, get_function_source, get_change_impact
- Only fall back to Read/Grep when token-savior tools genuinely don't cover it

AIは明示的な指示がなければ慣れ親しんだ grep に戻りがちです。CLAUDE.md（またはCursorの .cursorrules など）に強制ルールとして記述することが公式に推奨されています。この一文があるだけで、AIの行動が大きく変わります。

動かしてみた

Python 3.12.13 環境での pip インストールが正常に完了することを確認しました。pyproject.toml を含むプロジェクト一式が取得でき、tests/ ディレクトリには40本以上のテストファイルが揃っています（test_markup_python.py・test_git_ops.py・test_query_api.py など、各機能に対応したテストが網羅されています）。

プログラマティックAPIを使った基本動作の確認は以下のように行えます。

from token_savior.project_indexer import ProjectIndexer
from token_savior.query_api import create_project_query_functions

indexer = ProjectIndexer("/path/to/project")
index = indexer.index()
query = create_project_query_functions(index)

# プロジェクト概要を取得
print(query["get_project_summary"]())

# シンボルの定義場所を検索
print(query["find_symbol"]("MyClass"))

# 変更影響を分析
print(query["get_change_impact"]("send_message"))

インデックスは .codebase-index-cache.json に保存されます。次回起動時はキャッシュから読み込むため、CPythonのような大規模プロジェクトでも初回56秒→キャッシュヒット1秒未満という速度改善が公式ベンチマークで報告されています。

対応言語はPython・TypeScript/JS・Go・Rust・C#・Markdown・JSON・設定ファイルと幅広く、ゼロ依存（Pythonの標準ライブラリのみ）で動作する点も実用上のハードルが低い要因です。

実践：はじめの一歩はプロジェクト概要から

MCPサーバーとして起動したあと、最初に呼ぶべきツールは get_project_summary です。ファイル数・パッケージ一覧・主要クラス/関数の俯瞰図が一度に返ってくるため、AIがプロジェクト全体像を把握するコストをほぼゼロにできます。

その後の作業では以下の順番を意識すると効率的です。

  • シンボルを特定する: find_symbol("関数名") で定義ファイル・行番号・20行プレビューを即取得。grep による複数ファイル走査を1回の呼び出しに圧縮できます。
  • 編集コンテキストをまとめて取得する: get_edit_context で「ソース＋依存関係＋呼び出し元」を1コールで取得します。通常3コール分の情報を1回にまとめられます。
  • 編集前にチェックポイントを作る: create_checkpoint でスナップショットを取っておくと、restore_checkpoint で瞬時にロールバックできます。編集に失敗しても安心して試行錯誤できます。
  • 影響範囲を確認してから変更する: get_change_impact("シンボル名") で直接依存・推移的依存を一覧取得してから編集に進むと、予期せぬ破壊を防げます。
  • git と自動連携する: ブランチ切り替えや git pull 後も手動での再インデックスは不要です。クエリ実行前に git diff / git status を自動確認し、変更ファイルをインクリメンタルに再インデックスします。

ブラウザで試す（デモ）

ブラウザ上でサンプルコード（users.py）をインデックス化し、find_symbol・get_change_impact・get_dependencies などのクエリをインタラクティブに試せます。実際にどれだけ少ない文字数で有用な情報が得られるかを体感できます。

活用アイデア

  • レビュー支援: summarize_patch_by_symbol でdiffをテキスト行ではなくシンボル単位の変更概要に変換し、レビュアーが全差分を読まずに要点を把握できるワークフローを構築する
  • テスト絞り込みでCI高速化: find_impacted_test_files で変更シンボルに関連するテストだけを特定し、run_impacted_tests で必要最小限のテストのみ実行することでCI時間を短縮する
  • マルチプロジェクト横断検索: WORKSPACE_ROOTS=/root/api,/root/frontend,/root/docs のように複数ルートを設定し、1つのMCPサーバーで複数リポジトリをまたいだ影響分析を行う
  • ドキュメント自動生成: get_class_source や get_functions でシンボルを収集し、AIに渡してAPI仕様書を自動生成するバッチワークフローを構築する
  • 大規模リファクタリングの安全化: クラス・関数名の変更前に get_change_impact で影響件数を把握し、apply_symbol_change_validate_with_rollback で変更・テスト・ロールバックを一括実行する
  • 新規参画者のオンボーディング: 大規模コードベースに入ったばかりのメンバーが get_project_summary → find_symbol の流れでコード全体像を素早く把握するための補助ツールとして活用する

用語とポイント解説

MCP（Model Context Protocol） AIアシスタントとツール群を接続する標準プロトコルです。Claude Code・Cursor・Windsurfなど多くのAIコーディングツールが対応しており、MCPサーバーを追加するだけでAIがそのツールを自動的に利用できるようになります。

構造インデックス（Structural Index） ファイルをテキストではなくAST（抽象構文木）で解析し、関数・クラス・インポート・呼び出し関係を構造化データとして保持する仕組みです。grep によるテキスト検索と異なり、「この関数を呼んでいるすべての呼び出し元」を正確にたどることができます。

AST（抽象構文木） ソースコードを木構造で表現したデータ形式です。「コードをデータとして理解する」ための基盤であり、コンパイラやリンターも内部的にASTを使っています。token-savior はASTを使うことで、変数名・関数名・クラス名の意味を正確に区別しながらインデックスを構築します。

推移的依存（Transitive Dependencies） A → B → C のように、直接依存していない間接的な依存関係のことです。LSPは直接参照しか返しませんが、get_change_impact はBFS（幅優先探索）でグラフ全体を走査し、推移的依存を全列挙します。これにより「リファクタリングの全影響範囲」をAIが一度で把握できます。

コンテキストウィンドウ AIが一度に参照できるテキストの最大量です。この上限に達すると、AIは古い情報を「忘れた」状態で応答するため回答精度が低下します。token-savior は返答を最小文字数に圧縮することで、コンテキストウィンドウを有効に使い続けられるようにします。

LSP（Language Server Protocol） VS CodeなどのエディタがIDEの補完・定義ジャンプ機能を実現するために使うプロトコルです。「参照を探す」点クエリには優れていますが、推移的依存グラフの俯瞰はLSP単体では困難です。token-savior はこのギャップを埋める役割を担っています。

WORKSPACE_ROOTS インデックス化するプロジェクトのルートパスを指定する環境変数です。カンマ区切りで複数パスを列挙でき、1つのMCPサーバーインスタンスで複数リポジトリを一元管理できます。

チェックポイント（Checkpoint） create_checkpoint で作成するコードのスナップショットです。restore_checkpoint を呼ぶと編集前の状態に即座に戻せるため、AIによる自動編集を安心して試せる安全網として機能します。

インクリメンタル再インデックス ファイル全体を再処理するのではなく、変更のあったファイルだけを差分更新する仕組みです。git の変更検知と連動しており、git pull やブランチ切り替え後も手動操作なしでインデックスが最新状態に保たれます。

ぜひ大規模リポジトリのリファクタリング支援やCIテストの絞り込みなどに活用してみてはいかがでしょうか。