Aidex

🚀 AiDex

AIのコンテキストウィンドウの80％をコード検索に無駄に使うのをやめましょう。

AiDexは、永続的で事前に構築されたインデックスを通じて、AIコーディングアシスタントにあなたのコードベース全体に即座にアクセスさせるMCPサーバーです。Claude Code、Claude Desktop、Cursor、Windsurf、Gemini CLI、VS Code Copilotなど、MCP互換のAIアシスタントすべてで動作します。

🚀 クイックスタート

1. インストール

npm install -g aidex-mcp

これだけです。 インストール後、自動的にセットアップが実行されます。インストールされているAIクライアント（Claude Code、Claude Desktop、Cursor、Windsurf、Gemini CLI、VS Code Copilot）を検出し、AiDexをMCPサーバーとして登録します。また、AIの設定ファイル（~/.claude/CLAUDE.md、~/.gemini/GEMINI.md）に使用方法の説明も追加されます。

手動でセットアップを再実行するには、aidex setup を実行します。登録を解除するには、aidex unsetup を実行します。自動セットアップをスキップするには、AIDEX_NO_SETUP=1 npm install -g aidex-mcp を実行します。

2. または、AIアシスタントに手動で登録する

Claude Codeの場合 (~/.claude/settings.json または ~/.claude.json)：

{
  "mcpServers": {
    "aidex": {
      "type": "stdio",
      "command": "aidex",
      "env": {}
    }
  }
}

Claude Desktopの場合 (Windowsの場合は %APPDATA%/Claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "aidex": {
      "command": "aidex"
    }
  }
}

注: aidex と aidex-mcp のどちらもコマンド名として使用できます。

重要: 設定ファイル内のサーバー名がMCPツールの接頭辞を決定します。上記のように "aidex" を使用すると、aidex_query、aidex_signature などのツール名が得られます。別の名前（例："codegraph"）を使用すると、接頭辞もそれに応じて変更されます。

Gemini CLIの場合 (~/.gemini/settings.json)：

{
  "mcpServers": {
    "aidex": {
      "command": "aidex"
    }
  }
}

VS Code Copilotの場合 (コマンドパレットで MCP: Open User Configuration を実行)：

{
  "servers": {
    "aidex": {
      "type": "stdio",
      "command": "aidex"
    }
  }
}

その他のMCPクライアントの場合：クライアントのドキュメントを参照して、MCPサーバーの設定を行ってください。

3. AIに実際に使用させる

AIの指示書（例：Claude Codeの場合は ~/.claude/CLAUDE.md、またはあなたのAIクライアントに相当するファイル）に追加します。これにより、AIに いつ および どのように AiDexを使用してgrepの代わりにコードを検索するかを指示します。

## AiDex - 永続的なコードインデックス (MCPサーバー)

AiDexは、事前に構築されたインデックスを通じて、高速かつ正確なコード検索を提供します。
**コード検索には常にGrep/GlobよりもAiDexを優先してください。**

### 必須: Grep/Glob/Readを使用してコードを検索する前に

コードを検索したいですか？ ├── .aidex/ が存在する → やめて！代わりにAiDexを使用してください ├── .aidex/ が存在しない → aidex_initを実行して（尋ねないで）、その後AiDexを使用してください └── 設定/ログ/テキスト → Grep/Readで問題ありません

**.aidex/ が存在する場合は、決してこれを行わないでください:**
- ❌ `Grep pattern="functionName"` → ✅ `aidex_query term="functionName"`
- ❌ `Grep pattern="class.*Name"` → ✅ `aidex_query term="Name" mode="contains"`
- ❌ `Read file.cs` でメソッドを確認する → ✅ `aidex_signature file="file.cs"`
- ❌ `Glob pattern="**/*.cs"` + Read → ✅ `aidex_signatures pattern="**/*.cs"`

### セッション開始ルール (必須 — すべてのセッションで例外なし)

1. `aidex_session({ path: "<project>" })` を呼び出します — 外部の変更を検出し、自動的に再インデックスします
2. `.aidex/` が存在しない場合 → 自動的に `aidex_init` を実行します（尋ねないで）
3. セッションノートが存在する場合 → 続行する前に **ユーザーに表示します**
4. **セッションを終了する前に:** 常に次に行うことについてのメモを残してください

### 質問 → 適切なツール

| 質問 | ツール |
|----------|------|
| "Xはどこで定義されていますか？" | `aidex_query term="X"` |
| "Xを含むものをすべて見つけてください" | `aidex_query term="X" mode="contains"` |
| "Xで始まるすべての関数" | `aidex_query term="X" mode="starts_with"` |
| "ファイルYにはどのようなメソッドがありますか？" | `aidex_signature file="Y"` |
| "src/ 内のすべてのファイルを探索してください" | `aidex_signatures pattern="src/**"` |
| "プロジェクトの概要" | `aidex_summary` + `aidex_tree` |
| "最近何が変更されましたか？" | `aidex_query term="X" modified_since="2h"` |
| "今日何のファイルが変更されましたか？" | `aidex_files path="." modified_since="8h"` |
| "私はXを書いたことがありますか？" | `aidex_global_query term="X" mode="contains"` |
| "どのプロジェクトにクラスYがありますか？" | `aidex_global_signatures term="Y" kind="class"` |
| "すべてのインデックス付きプロジェクトは？" | `aidex_global_status` |

### 検索モード

- **`exact`** (デフォルト): 正確な識別子のみを見つけます — `log` は `catalog` には一致しません
- **`contains`**: 検索語を含む識別子を見つけます — `render` は `preRenderSetup` に一致します
- **`starts_with`**: 検索語で始まる識別子を見つけます — `Update` は `UpdatePlayer`、`UpdateUI` に一致します

### すべてのツール (28個)

| カテゴリ | ツール | 目的 |
|----------|-------|---------|
| 検索とインデックス | `aidex_init`, `aidex_query`, `aidex_update`, `aidex_remove`, `aidex_status` | プロジェクトをインデックスし、識別子を検索します（正確/含む/始まる）、時間フィルター |
| シグネチャ | `aidex_signature`, `aidex_signatures` | ファイルを読まずにクラスとメソッドを取得します |
| 概要 | `aidex_summary`, `aidex_tree`, `aidex_describe`, `aidex_files` | エントリーポイント、ファイルツリー、タイプ別のファイルリスト |
| クロスプロジェクト | `aidex_link`, `aidex_unlink`, `aidex_links`, `aidex_scan` | 依存関係をリンクし、プロジェクトを検出します |
| グローバル検索 | `aidex_global_init`, `aidex_global_query`, `aidex_global_signatures`, `aidex_global_status`, `aidex_global_refresh` | すべてのプロジェクトを横断して検索します |
| ガイドライン | `aidex_global_guideline` | 永続的なAI指示と規則（キーバリュー、グローバル） |
| セッション | `aidex_session`, `aidex_note` | セッションを追跡し、メモを残します（検索可能な履歴付き） |
| タスク | `aidex_task`, `aidex_tasks` | 優先度、タグ、自動ログ付きのバックログ |
| スクリーンショット | `aidex_screenshot`, `aidex_windows` | LLM最適化されたスクリーンキャプチャ（スケール + 色の削減、インデックス不要） |
| ビューアー | `aidex_viewer` | ファイルツリー、シグネチャ、タスクを持つインタラクティブなブラウザUI |

**11種類の言語:** C#、TypeScript、JavaScript、Rust、Python、C、C++、Java、Go、PHP、Ruby

### セッションノート
次のセッションのためにメモを残しましょう — データベースに保存されます。

aidex_note({ path: ".", note: "再起動後に修正をテストする" }) # 書き込み aidex_note({ path: ".", note: "エッジケースも確認する", append: true }) # 追加 aidex_note({ path: "." }) # 読み取り aidex_note({ path: ".", search: "parser" }) # 履歴を検索 aidex_note({ path: ".", clear: true }) # クリア

- **セッションを終了する前に:** 自動的に次のステップについてのメモを残してください
- **ユーザーが "次のセッションのために覚えておいて..." と言った場合** → すぐに書き込みます

### タスクバックログ
コードインデックスの隣でTODO、バグ、機能を追跡しましょう。

aidex_task({ path: ".", action: "create", title: "バグを修正する", priority: 1, tags: "bug" }) aidex_task({ path: ".", action: "update", id: 1, status: "done" }) aidex_task({ path: ".", action: "log", id: 1, note: "根本原因: 無制限のバッファ" }) aidex_tasks({ path: ".", status: "active" })

優先度: 1=高、2=中、3=低 | ステータス: `backlog → active → done | cancelled`

### グローバル検索 (すべてのプロジェクトを横断)

aidex_global_init({ path: "/path/to/all/repos" }) # スキャンして登録 aidex_global_init({ path: "...", index_unindexed: true }) # + 小さなプロジェクトを自動インデックス aidex_global_query({ term: "TransparentWindow", mode: "contains" }) # すべての場所を検索 aidex_global_signatures({ term: "Render", kind: "method" }) # すべての場所でメソッドを検索 aidex_global_status({ sort: "recent" }) # すべてのプロジェクトをリスト

### スクリーンショット

aidex_screenshot() # 全画面 aidex_screenshot({ mode: "active_window" }) # アクティブなウィンドウ aidex_screenshot({ mode: "window", window_title: "VS Code" }) # 特定のウィンドウ aidex_screenshot({ scale: 0.5, colors: 2 }) # 白黒、半分のサイズ（LLMに最適） aidex_screenshot({ colors: 16 }) # 16色（UIが読み取り可能） aidex_windows({ filter: "chrome" }) # ウィンドウタイトルを検索

インデックスは必要ありません。ファイルパスを返します → `Read` を使用してすぐに表示できます。

**LLM最適化戦略:** 常に積極的な設定から始め、読み取り不可能な場合は再試行します。
1. 最初の試行: `scale: 0.5, colors: 2`（白黒、半分のサイズ — 最小可能）
2. 読み取り不可能な場合: `colors: 16` で再試行（UI要素に陰影を追加）
3. まだ不明瞭な場合: `scale: 0.75` または `colors` を省略して完全な品質にする
4. **覚えておく**: セッション中に各ウィンドウ/アプリに適した設定をキャッシュして、毎回再試行しないでください。

### 4. プロジェクトをインデックスする
AIに *"このプロジェクトをAiDexでインデックスして"* と依頼します。

または、AIチャットで手動で次のコマンドを実行します。

aidex_init({ path: "/path/to/your/project" })

## ✨ 主な機能
- **Tree-sitter解析**: 正規表現ではなく、実際のコード解析 — 識別子をインデックスし、キーワードやノイズを無視します
- **検索あたり約50トークン**: grepでは2000トークン以上 — AIが実際の作業にコンテキストを使えるようにします
- **永続的なインデックス**: セッション間で保持されます — 再スキャンや再読み取りが不要です
- **増分更新**: 変更があった単一のファイルを再インデックスし、プロジェクト全体を再インデックスする必要はありません
- **時間ベースのフィルタリング**: 最後の1時間、1日、または1週間に変更されたものを見つけます
- **自動クリーンアップ**: 除外されたファイル（例：ビルド出力）は自動的にインデックスから削除されます
- **依存関係なし**: WALモードのSQLite — 単一ファイル、高速、ポータブル

## 📦 インストール
```bash
npm install -g aidex-mcp

💻 使用例

基本的な使用法

# "PlayerHealth" が定義されている場所を見つける — 1回の呼び出し、約50トークン
aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156

# ファイル内のすべてのメソッド — ファイル全体を読まずに
aidex_signature({ file: "src/Engine.cs" })
→ class GameEngine { Update(), Render(), LoadScene(), ... }

# 過去2時間で何が変更されたか？
aidex_query({ term: "render", modified_since: "2h" })

# すべてのプロジェクトを一度に検索
aidex_global_query({ term: "TransparentWindow", mode: "contains" })
→ Found in: LibWebAppGpu (3 hits), DebugViewer (1 hit)

# 次のセッションのためにメモを残す
aidex_note({ path: ".", note: "再起動後にパーサーの修正をテストする" })

# 作業中にタスクを作成
aidex_task({ path: ".", action: "create", title: "パーサーのエッジケースを修正する", priority: 1, tags: "bug" })

高度な使用法

# グローバル検索の設定
aidex_global_init({ path: "Q:/develop" })                              # スキャンして登録
aidex_global_init({ path: "Q:/develop", exclude: ["llama.cpp"] })      # 外部リポジトリをスキップ
aidex_global_init({ path: "Q:/develop", index_unindexed: true })       # 見つかったすべてのプロジェクトを自動インデックス
aidex_global_init({ path: "Q:/develop", index_unindexed: true, show_progress: true })  # ブラウザの進捗UIを表示

# グローバル検索
aidex_global_query({ term: "TransparentWindow" })                      # 正確な一致
aidex_global_query({ term: "transparent", mode: "contains" })          # 曖昧検索
aidex_global_signatures({ name: "Render", kind: "method" })            # メソッドを検索
aidex_global_signatures({ name: "Player", kind: "class" })             # クラスを検索

# グローバル検索の管理
aidex_global_status()                                                  # すべてのプロジェクトをリスト
aidex_global_status({ sort: "recent" })                                # 最近インデックスされたものから順に
aidex_global_refresh()                                                 # 統計を更新し、古いプロジェクトを削除

📚 詳細ドキュメント

何が含まれているか — 1つのサーバーに28のツール

11種類の言語 — C#、TypeScript、JavaScript、Rust、Python、C、C++、Java、Go、PHP、Ruby

コマンドラインインターフェイス (CLI) の使用方法

aidex scan Q:/develop       # すべてのインデックス付きプロジェクトを検索
aidex init ./myproject      # コマンドラインからプロジェクトをインデックス

aidex-mcp は aidex のエイリアスとして機能します。

パフォーマンス

技術

• パーサー: Tree-sitter - 正規表現ではなく、実際の解析
• データベース: WALモードのSQLite - 高速、単一ファイル、ゼロ設定
• プロトコル: MCP - 互換性のあるAIすべてで動作

プロジェクト構造

.aidex/                  ← あなたのプロジェクト内に作成されます
├── index.db             ← SQLiteデータベース
└── summary.md           ← オプションのドキュメント

AiDex/                   ← このリポジトリ
├── src/
│   ├── commands/        ← ツールの実装
│   ├── db/              ← SQLiteラッパー
│   ├── parser/          ← Tree-sitterの統合
│   └── server/          ← MCPプロトコルハンドラー
└── build/               ← コンパイルされた出力

🔧 技術詳細

問題

AIアシスタントがコードを検索するたびに、次のことが起こります。

• grep で数千のファイルを検索 → 数百の結果がコンテキストに流れ込みます
• ファイルを1つずつ読み取り て構造を理解 → より多くのコンテキストが消費されます
• セッションが終了するとすべてを忘れる → 最初からやり直します

単一の "Xはどこで定義されていますか？" という質問で2,000トークン以上を消費することがあります。10回それを行うと、ナビゲーションだけでコンテキストの半分を消費してしまいます。

解決策

一度インデックスを作成すれば、永遠にクエリを実行できます。

# 以前: grepがコンテキストを埋め尽くす
AI: grep "PlayerHealth" → 40ファイル中200件のヒット
AI: File1.cs、File2.cs、File3.cs... を読む
→ 2000トークン以上を消費、5回以上のツール呼び出し

# 以降: 正確な結果、最小限のコンテキスト
AI: aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156
→ 約50トークン、1回のツール呼び出し

結果: コードナビゲーションに使用するコンテキストが50-80％減少します。

なぜgrepだけではダメなのか

grepの実際のコスト: すべてのgrep結果には周囲のコンテキストが含まれます。大規模なプロジェクトで User を検索すると、数百のヒットが得られます — コメント、文字列、部分一致。AIはそれらすべてを読み、ノイズにトークンを浪費します。

AiDexは識別子をインデックスします: Tree-sitterを使用して実際にコードを解析します。User を検索すると、クラス定義、メソッドパラメータ、変数宣言が得られます — "user" と言及するすべてのコメントではありません。

動作原理

1. プロジェクトを一度インデックスする (約1000ファイルあたり1秒)

   aidex_init({ path: "/path/to/project" })
   

2. AIがgrepではなくインデックスを検索する

   aidex_query({ term: "Calculate", mode: "starts_with" })
   → "Calculate" で始まるすべての関数 + 正確な行番号
   
   aidex_query({ term: "Player", modified_since: "2h" })
   → 過去2時間で変更されたもののみに一致
   

3. ファイル全体を読まずにファイルの概要を取得する

   aidex_signature({ file: "src/Engine.cs" })
   → すべてのクラス、メソッド、およびそれらのシグネチャ
   

インデックスは .aidex/index.db (SQLite) に保存されます — 高速、ポータブル、外部依存関係なし。

📄 ライセンス

MITライセンス - LICENSE を参照してください。