contextshrinker

contextshrinker は、Go で書かれた、依存関係ゼロのヘッドレス Model Context Protocol（MCP）サーバーです。ローカルのコードベースを組み込みの Kùzu グラフデータベースにインデックス化し、自律型 AI エージェント（Claude Code、Cursor、Antigravity IDE、Aider、Claude Desktop など）における LLM のトークン肥大化を劇的に削減します。

AI エージェントに生のソースファイルを読ませたり、ぎこちない grep ベースの検索を実行させたりする代わりに、contextshrinker はエージェントがプロジェクトのアーキテクチャ上の依存関係、関数呼び出しチェーン、クラス継承構造のセマンティックグラフを照会できるようにし、入力コンテキストの消費を 90% から 98% 削減します。

🚀 主な機能

• ユニバーサルエージェント互換性: 標準 I/O（stdio）を介して MCP 準拠のあらゆるコーディングツールや IDE にシームレスに接続します。

• ゼロ外部データベース: 完全に自己完結型です。プロジェクトのローカル .contextshrinker/ ディレクトリ内でインプロセスのグラフデータベース（Kùzu）を実行します。

• 自動管理の LSP デーモン: プロジェクトの言語を自動検出し、不足している場合はサンドボックス化された言語サーバー（Go の gopls や Python の pyright など）をプログラムでプロビジョニングし、バックグラウンドでそれらの RPC インターフェースに問い合わせてコールグラフを構築します。

• マルチ言語サポート: Go、Python、JavaScript、TypeScript、Java の完全な AST 構文解析とセマンティックインデックス化を提供します。

• クリーンなプロジェクト分離: 各ワークスペースは、分離された設定ルール（.contextshrinker/ignore）とグラフデータベースファイル（.contextshrinker/db/）を含む独自の .contextshrinker/ ディレクトリを維持します。

• ライブ状態同期: fsnotify を使用してファイルを再帰的に監視します。保存時には、デバウンスされたデルタ更新が古いノードを削除し、変更されたファイルをリアルタイムで再インデックス化します。

• インタラクティブなグラフ可視化: オンデマンドで、Vis.js を搭載したダークモードの美しい HTML コードベース可視化（.contextshrinker/contextshrinker_graph.html）を生成します。

Related MCP server: code-graph-mcp

🛠️ アーキテクチャ: 2 パス取り込み

コードベースをきれいにインデックス化するために、contextshrinker は 2 パスの取り込みシーケンスを実行します。

graph TD
    A[Walk Workspace] -->|Filter via .contextshrinker/ignore| B[Pass 1: Tree-sitter Syntax]
    B -->|Create Nodes| C[(Kùzu Graph DB)]
    C --> D[Pass 2: LSP Semantic Cross-References]
    D -->|Create CALLS / IMPLEMENTS Edges| C

1. パス 1（Tree-sitter AST 抽出）: ソースファイルを高速にスキャンしてエンティティ（関数/メソッド、クラス/構造体、変数）とそれらに関連する docstring を抽出し、ノードとして挿入します。

2. パス 2（LSP セマンティック解決）: バックグラウンドの Language Server Protocol（LSP）デーモンに相互参照を問い合わせて、呼び出し（CALLS）、インポート（IMPORTS）、クラス継承（IMPLEMENTS / EXTENDS）を特定して接続します。

📥 インストール

オプション 1: プリコンパイル済みバイナリ（最速）

Go をインストールしたくない場合は、お使いのプラットフォーム向けのプリコンパイル済みポータブルパッケージをダウンロードできます:

1. Releases ページに移動します。

2. お使いの OS 用のアーカイブ（.tar.gz または .zip）をダウンロードします。

3. アーカイブを解凍します。実行可能ファイル（contextshrinker）とその動的ライブラリ（libkuzu / kuzu_shared）を同じフォルダに置きます。

4. そのディレクトリから実行可能ファイルを実行します:

macOS / Linux:

chmod +x contextshrinker
./contextshrinker --help

Windows:

contextshrinker.exe --help

オプション 2: ソースからビルド（Go が必要）

前提条件

• Go（1.21 以降）

• Node.js & npm（JS/TS および Python LSP を自動インストールするため）

コンパイル

リポジトリをクローンして、次を実行します:

go build -o contextshrinker

システムの PATH に直接インストールするには:

go install

🔌 コーディングエージェントへの統合

contextshrinker は、コーディングエージェントの子プロセスとしてオンデマンドで実行されます。コンパイル済みバイナリへの絶対パスをクライアントに登録してください:

1. Antigravity IDE（Gemini Agent Panel）

1. Antigravity IDE を開きます。

2. Agent Panel の ...（More Options） メニューをクリックします。

3. 「Manage MCP Servers」 $\rightarrow$ 「View raw config」 を選択します。

4. mcp_config.json にサーバーを登録します:

   {
     "mcpServers": {
       "contextshrinker": {
         "command": "/absolute/path/to/contextshrinker"
       }
     }
   }

2. Claude Code（CLI）

サーバーを自動的に追加します:

claude mcp add contextshrinker /absolute/path/to/contextshrinker

3. Cursor IDE

1. Settings $\rightarrow$ Features $\rightarrow$ MCP に移動します。

2. + Add New MCP Server をクリックします。

3. 設定を行います:

   • Name: contextshrinker

   • Type: command

   • Command: /absolute/path/to/contextshrinker

4. Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json に追加します:

{
  "mcpServers": {
    "contextshrinker": {
      "command": "/absolute/path/to/contextshrinker"
    }
  }
}

🧰 公開ツール

設定が完了すると、以下のツールが AI コーディングエージェントで自動的に利用可能になります:

1. search_codebase

   • 引数: query（string）

   • 説明: 全文検索と Cypher クエリを実行して、クラス、関数、変数にわたって構造と docstring を照合します。

2. get_call_chain

   • 引数: target_function（string）、depth（integer、最大 5）

   • 説明: 可変長パスの Cypher クエリを使用して上流の呼び出しチェーンを解決し、呼び出し依存関係をマッピングします。

3. get_file_structure

   • 引数: file_path（string）

   • 説明: 生のテキスト内容をコンテキストウィンドウに送り込むことなく、単一のファイルに含まれる完全な抽象ノード構造（クラス、インターフェース、メソッド、変数）を取得します。

4. visualize_codebase

   • 説明: オンデマンドの HTML エクスポートをトリガーし、.contextshrinker/ ディレクトリ内に contextshrinker_graph.html を保存します。

5. get_architecture_report

   • 説明: God Object、結合のホットスポット、循環、未使用の非公開関数、AI メトリクス（SCR、DCR、BVI、AOI、Call Chain Depth Index - CDI）、および AI システムプロンプトの指示を伴う実行可能なコード品質ガイドライン（Jeff Dean の原則）を含む、完全なコードベースのアーキテクチャ健全性レポートを取得します。

🏛️ コードベースとアーキテクチャの最適化

contextshrinker を使用すると、LLM を活用して結合度を体系的に監査し、ドメイン境界（DDD）を分析し、コードの再構築（モノリスをモジュールに分割するなど）を導くことができます。

最適化ワークフロー

1. アーキテクチャ指標とガイドラインを生成する: ターミナルで分析コマンドを実行して、コードベースのグラフを検査し、レポートを生成します:

   ./contextshrinker analyze

   これにより、God Object（高い外部結合）、Black Hole（高い内部呼び出し）、循環インポートパス、デッドコード（未使用の非公開関数）、AI メトリクス（Call Chain Depth Index - CDI を含む）、および実行可能なコード品質と LLM アーキテクチャのガイドライン（Jeff Dean の原則）に関する指標を含む contextshrinker-report.md が生成されます。

2. システムプロンプトを取得する: CLI からプリンシパルシステムアーキテクトのプロンプトを取得します:

   ./contextshrinker prompt architect

3. LLM で分析する:

   • prompt architect コマンドの出力を LLM のシステムプロンプトとして設定します。

   • 生成された contextshrinker-report.md の内容をコンテキスト / 入力として提供します。

   • LLM に、境界づけられたコンテキストの分割やインターフェース境界を提案するよう依頼します。

4. エージェンティック / ツール使用ワークフロー: MCP 互換エージェント（Antigravity IDE、Claude Code、Cursor など）を使用している場合は、直接次のように依頼できます:

   「contextshrinker の分析レポートを実行し、生成された Markdown を読み、Systems Architect として設計上のホットスポットを監査してください。具体的なモジュール抽出を提案する前に、get_call_chain と get_file_structure ツールを使用して結合度を調査してください。」

⚙️ 設定と無視ルール

ワークスペースのグラフ肥大化を防ぐため、標準ライブラリと依存関係フォルダ（node_modules/、vendor/、.git/ など）はデフォルトで無視されます。

カスタムの無視ルールを追加するには、プロジェクトを初期化し、ワークスペースのルートで次のコマンドを実行して .csignore ファイルを生成します:

contextshrinker init

.csignore の各行は再帰的に照合されます:

# Custom project ignores
*.log
tmp-output/
dist/
.vitepress

💡 大規模プロジェクトのベストプラクティス

中規模から大規模のプロジェクト（数百から数千のファイルなど）で contextshrinker を使用する場合、初期のコードベース取り込みを LLM/エージェントのプロンプト内から直接実行すると（Claude Code や Cursor など）、エージェントのタイムアウト問題が発生する可能性があります。これは、初回のワークスペース解析と LSP 参照解決が完了するのを待つ間、エージェントには厳格なタイムアウト制限（通常 60 秒）があるためです。

これを防ぐには、エージェントを起動する前に、ターミナルで次の最適化ワークフローを実行してください:

1. ワークスペースを初期化する: 初期化コマンドを実行して、設定ディレクトリとデフォルトの無視リストを作成します:

   contextshrinker init

2. 無視ルールを設定する: 生成された .csignore ファイルをワークスペースのルートで開き、除外したい大きなディレクトリ（ドキュメントサイト、テストアセット、ビルド済みフォルダなど）を追加します。

3. データベースをオフラインで構築する: ターミナルで analyze コマンドを 1 回実行して、初期グラフデータベースを構築します:

   contextshrinker analyze

これにより、Tree-sitter 解析と LSP セマンティック相互参照の重い処理がオフラインで実行されます。データベースが構築されると、その後のエージェントリクエストとライブ状態同期は数秒でインクリメンタルに実行されるため、将来のタイムアウトを防げます。

📊 コマンドラインインターフェース（CLI）モード

コードベースのグラフを照会したり、MCP サーバーデーモンを明示的に起動したり、システムアーキテクトのプロンプトを取得したり、健全性分析レポートをターミナルから直接生成したりできます。

1. MCP サーバーを起動

デフォルトでは、引数なしで ./contextshrinker を実行すると MCP サーバーデーモンが起動します。明示的に起動することもできます:

./contextshrinker start

2. コードベースのアーキテクチャ分析を実行

コードベースの構造（God Object、内部呼び出しのホットスポット、循環インポート、デッドコード、Call Chain Depth Index - CDI、LLM コード品質ガイドライン）を分析し、contextshrinker-report.md にレポートを書き込みます:

./contextshrinker analyze

3. プリンシパルシステムアーキテクトのプロンプトを出力

Domain-Driven Design（DDD）のプリンシパルシステムアーキテクトのシステムプロンプトを stdout に出力します:

./contextshrinker prompt architect

4. コードベースを検索

クエリに一致する関数、クラス、変数を見つけます:

./contextshrinker search "IngestWorkspace"

5. コールチェーンを追跡

対象の関数名の上流呼び出し元を追跡します（デフォルトの深さは 3、最大は 5）:

./contextshrinker call-chain "IngestWorkspace" --depth 3

6. ファイル構造を取得

ファイルの完全なテキスト内容を読まずに構造を取得します:

./contextshrinker structure "main.go"

7. インタラクティブな可視化を生成

Vis.js のコードベースグラフ表現を生成します:

./contextshrinker visualize

生成された .contextshrinker/contextshrinker_graph.html を任意のブラウザで開くと、プロジェクトのアーキテクチャをインタラクティブに探索できます。

オプション（グローバルフラグ）

• --workspace <path>: プロジェクトディレクトリを指定します（デフォルトは .）。

• --db <path>: データベースの保存ディレクトリを指定します（デフォルトは .contextshrinker/db）。

• --reindex: クエリを実行する前に、ワークスペース全体の取り込みスキャン（コードの再解析と LSP リレーションシップのマッピング）を強制します。データベースが空の場合は、取り込みが自動的に実行されます。

• 注: Kuzu DB はファイルレベルの排他ロックを確立するため、アクティブなデータベースで CLI コマンドを実行するときは IDE の MCP クライアントを一時停止または停止するか、CLI フラグで別のワークスペース/DB ディレクトリを使用してください。

📄 ライセンス

このプロジェクトは MIT ライセンスの下で提供されています。