🔍 code-search-mcp

LanceDB とプロセス内 ONNX 埋め込みを利用した、デーモン不要のローカル意味的コード検索 MCP サーバー。
grep のような文字列検索はもう終わり。コードベースを「意味」で検索する力を、AI コーディングアシスタントに与えましょう。

Claude Code、Gemini CLI、Antigravity (agy)、Cursor で、macOS・Windows・Linux すべてそのまま動作します。

☕️ コーヒーショップのアプリを想像してみてください

あなたが地域の小さなコーヒーショップ向けのソフトウェアを開発しているとします。

コードベースの中に、お客さんがオーツミルクラテの追加を注文し、朝の割引が適用されたときに何が起こるかを処理するファイルがあるとします:

// Apply a 15% promotional deduction if the customer visits before 9 AM
export function calculateEarlyBirdReward(bill: OrderSummary): number {
  if (bill.orderHour < 9) {
    return bill.subtotal * 0.85;
  }
  return bill.subtotal;
}

では、AI コーディングアシスタント（Claude Code、Cursor、Gemini CLI など）を開いて、次のように聞いてみましょう。

"朝のドリンク割引はどこで計算されていますか？"

もしあなたのツールが従来のテキスト検索（grep など）だけに頼っていたら、"discount" という完全一致の単語を探すことになります。

• calculateEarlyBirdReward は見つかりましたか？ いいえ。

• なぜなら、コードは promotional deduction と EarlyBirdReward を使っていましたが、"discount" という単語は一度も使われていないからです。

ここで セマンティック検索 がすべてを変えます。

Related MCP server: claude-context-local

🧠 セマンティック検索とは（わかりやすく言うと）

従来の検索は 完全一致の文字や単語 を探します。

セマンティック検索 は、あなたが使った言葉の 背後にある“意味” を探します。

仕組み：意味の地図

1. 数字に変える: AI モデルがテキスト（またはコード）を読み取り、**エンベディング（ベクトル）**と呼ばれる数字のリストに変換します。

2. 地図上の座標: その数字は、あたかも人間の概念が集まった巨大な地図上の GPS 座標だと考えてください。

   • "discount" と "promotional deduction" は地図上で隣り合う。

   • "espresso shot" と "latte" も同じ場所に並ぶ。

   • "database migration" は地図の反対側、遠く離れた場所にあります。

3. 最近傍を探す: あなたが自然英語で質問すると、検索エンジンはその質問を座標に変換し、地図上で最も近くにあるコードを見つけます。

                  [ Map of Meaning ]

   ☕️ "morning drink discount"   📍 (Your Question)
              │ (Close match!)
              ▼
   🏷 "calculateEarlyBirdReward" 📍 (Your Code)
   
   ─────────────────────────────────────────────
   
   🗄 "sql database migration"   📍 (Far Away - Ignored)

🚀 セマンティック検索が AI コーディングを変える理由

AI コーディングアシスタントが数千ファイルの大規模リポジトリを扱うとき、ファイルを検索するたびにすべてのファイルを読むことはできません。あまりにも遅くなり、トークンも無駄になってしまうからです。

その代わりに、AI は 関連する 2〜3 個のファイルを一瞬で見つける 必要があります。

実際のプロジェクトでは、コードベースには豊富な文脈が溢れています。

• Markdown ドキュメント (.md): アーキテクチャ決定記録、API ガイド、オンボーディング資料。

• コードコメント: ビジネスルールが なぜ 存在するかを説明する（例: // Remove beans from bean hopper）。

• 関数名と変数名: ライブラリによって表記が異なる可能性がある命名パターン。

セマンティック検索は、あなたの自然言語による思考を、それらの Markdown ドキュメント、コメント、コードスニペットへ直接つなぎます。たとえ、正確な関数名を覚えていなくても。

🛠 私たちが作ったもの: code-search-mcp

既存の開発者向けセマンティック検索ツールは、どれも大掛かりなセットアップが必要です。

• Python 3 のインストール、仮想環境、pip。

• 外部のバックグラウンドデータベースサーバー（ChromaDB など）をネットワークポートで起動。

• 起動時デーモン（Mac の LaunchAgents、Windows のタスクスケジューラ）の設定。バッテリーを消耗します。

• データベースサーバーがオフラインだと作業をブロックする可能性のある複雑な Git フック（pre-commit）追加。

私たちはまったく違うものを求めました。 セットアップ不要・外部デーモン不要・どんなプロジェクトでもすぐ動く。

そこで私たちは code-search-mcp を構築しました。 Node.js 用のスタンドアロンでクロスプラットフォームな Model Context Protocol (MCP) サーバーです。

┌─────────────────────────────────────────────────────────────┐
│                       AI Client                             │
│       (Claude Code / Gemini CLI / Antigravity / Cursor)     │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP Protocol (JSON-RPC over stdio)
┌──────────────────────────────▼──────────────────────────────┐
│                      code-search-mcp                        │
│                                                             │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────┐  │
│  │   Scanner &      │  │  EmbeddingEngine │  │  Watcher  │  │
│  │ Layered Ignores  │  │  (all-MiniLM-L6) │  │(chokidar) │  │
│  └────────┬─────────┘  └────────┬─────────┘  └─────┬─────┘  │
│           │                     │                  │        │
│           └───────────┬─────────┴──────────────────┘        │
│                       ▼                                     │
│              VectorStore (LanceDB)                          │
│        node_modules/.cache/code-search/                     │
└─────────────────────────────────────────────────────────────┘

⚙️ 技術の中身

🔍 内側の仕組み

1. インデックス作成を開始するタイミング

あなたの AI アシスタントが起動するする（Claude Code、Antigravity、Gemini CLI を起動するなど）と、標準入力と出力（stdio）を介して code-search-mcp に接続します。

どMCP サーバーは 15ms 未満ですぐに接続します。

• バックグラウンドワーカーが、チャットセッションをブロックすることなくプロジェクトファイルをスキャンし始めます。

2. インデックスが完了する前に検索できますか？（インデックス途中のスーパーパワー）

できます！ プロジェクトを開いて2秒で質問しても、 code-search-mcp は ブロックもハングもしません。

これまでにインデックスされたファイルをそのまま検索し、ライブの進行状況ヘッダーを表示します:

⚠️ [Index status: INDEXING (35% complete - 2,100/6,000 files indexed)]
Results from currently indexed files:

### Match 1: src/drinks/espresso.ts (Lines 12-30) [Score: 54.2%]

3. 初回は少し待つことは待ち; というのは最初だけです！ ⏳

5,000 以上のファイルがある巨大なリポジトリでは、最初のインデックススキャンに数分かかります。ローカル AI モデルが、あなたのマシン上のすべてのコードチャンクに対して初めてベクトルエンベディングを生成するからです。

良い知らせです:

• このコストを払うのは一度だけです: 生成されたベクターデータベースは node_modules/.cache/code-search/lancedb/ に永続的に保存されます。

• 次回起動は「インスト」 ：今後セッションを開き直したり、エディタを再起動したりしても、インデックスし直すことなく <15ms で接続します。

• インクリメンタルなライブ更新: 日中にコードを書きながら、ライブウォッチャーは変更した1つのファイルだけを更新する。保存時に 約 150ms で完了します。

• ゼロ待ち： すぐに質問して検索できます。アシスタントはバックグラウンドで、すでにインデックスがあればそれを検索します。

4. インデックスはどこに保存されますか？

デフォルトでは、データベースは次の場所に保存されます。 📁 node_modules/.cache/code-search/lancedb/

なぜ node_modules/.cache なのか？

• node_modules は100%のプロジェクトで Git で無視されるようになっています。

• Git のノイズが完全にゼロ: リポジトリにトラッキングされていないフォルダや不要な差分が表示されることはありません。

• （プロジェクトに node_modules がない場合は、.code-search/ にう合理にフォールバックします）。

5. Git ブランチを切り替えたらどうなりますか？

🔀

git checkout、git switch、git pull を実行すると:

1. ライブウォッチャーが検知: Git がファイルを更新すると、組み込みの chokidar ファイルウォッチャーが、追加・変更・削除されたファイルをリアルタイムで検出します。

2. 高速差分再スキャン: 2つのブラン間で変更された特定のファイルだけをインデックスし直す（数分のではなく 1〜2 秒）。

3. 自動プルーニング（削除）: 以前のブランチで削除されたファイルや古いコードのチャンクは、LanceDB から自動的に削除されます。

4. 手動同期: 大きなマージの後に全体をきちんと再構築したい場合は、アシスタントにこう伝えます。"code_search_reindex を force: true で実行して"。

⚙️ 設定管理とさらにファイルを無視する方法

デフォルトで code-search-mcp は、バイナリファイル（.png, .mp4, .zip）、ビルド成果物（dist/, build/）、ロックファイル、500KB 以上のファイルを自動的に無視します。また、既存の .gitignore も尊重します。

プロジェクトの設定をカスタマイズしたり、さらにファイルを無視したいだけの場合、2〜3つの簡単な方法があります。

オプション1：.codesearchignore ファイルを作成する（簡単&シンプル）

プロジェクトのルートに .codesearchignore ファイルを作成し、通常の gitignore 記法を使います。

# Ignore mock data and test fixtures
tests/fixtures/**
src/mocks/**

# Ignore auto-generated files
src/models/*.generated.ts
locales/**

オプション2：.codesearchrc.json ファイルを作成する（詳細設定）

プロジェクトのルートに .codesearchrc.json ファイルを作成して、インデックス動作やチャンク、ファイルサイズ制限を制御します。

{
  "maxFileSizeKb": 300,
  "batchSize": 50,
  "customExcludes": [
    "legacy_vendor/**",
    "docs/archive/**"
  ],
  "supportedExtensions": [
    ".ts", ".tsx", ".js", ".vue", ".py", ".md", ".json"
  ]
}

📦 ツールのインストール方法

ツールは次ののいずれかの方法でインストールして実行できます。

ステップ1：インストールする方法を選択

方法 A: npx で GitHub から直接（インストール不要 — 公開なしでOK！）

どのAIクライアントでも、あなたのGitHubリポジトリから直接オンデマンドで実行できます。

npx -y github:your-username/code-search-mcp

（Node が自動的にリポジトリをダウンロードして、パッケージを`ビルドし、MCPサーバーを実行します。）

方式 B: NPM レジストリから（公開後）

パッケージを npm に公開している場合:

npx -y code-search-mcp
# or global install:
npm install -g code-search-mcp

方法 C: ローカル開発／リンク（最速のローカル起動）

ローカルのソースディレクトから直接実行する場合:

cd /path/to/code-search-mcp
npm install
npm run build
npm link

これで code-search-mcp がシステム上のグローバルコマンドとして登録されました。

ステップ2：AI クライアントに接続します

1. Claude Code

# If running via GitHub:
claude mcp add code-search -s user -- npx -y github:your-username/code-search-mcp

# If running locally (linked):
claude mcp add code-search -s user -- code-search-mcp

2. Antigravity CLI (agy)

この一行をターミナルで実行します:

mkdir -p ~/.gemini/config/plugins/code-search && cat << 'EOF' > ~/.gemini/config/plugins/code-search/plugin.json
{ "name": "code-search" }
EOF
cat << 'EOF' > ~/.gemini/config/plugins/code-search/mcp_config.json
{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "github:your-username/code-search-mcp"]
    }
  }
}
EOF

3. Gemini CLI

~/.gemini/settings.json に追加します:

{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "github:your-username/code-search-mcp"],
      "trust": true
    }
  }
}

4. Cursor / Claude Desktop:

尚 .cursor/mcp.json に追加します:

{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "github:your-username/code-search-mcp", "--path", "${workspaceFolder}"]
    }
  }
}

🤖 AI エージェント向けガイド & ツールリファレンス

このリポジトリを読んでいる AI アシスタント（Claude Code、Gemini CLI、Cursor、Antigravity、Windsurf）向けに、code-search-mcp が提供する MCP ツールのクイックスタートガイドです：

🛠️ 利用可能な MCP ツール

🧭 ツール決定マトリクス：どのツールをどの場面で使うか

                       ┌───────────────────────────────────────────────┐
                       │ What are you looking for in the codebase?     │
                       └───────────────────────┬───────────────────────┘
                                               │
           ┌───────────────────────────────────┼───────────────────────────────────┐
           ▼                                   ▼                                   ▼
┌─────────────────────────┐         ┌─────────────────────────┐         ┌─────────────────────────┐
│ Concept / Feature /     │         │ Known Symbol / Callers  │         │ Exact Literal String /  │
│ Business Logic Intent   │         │ & Blast Radius Analysis │         │ Error Code / CSS Class  │
│ (Natural Language)      │         │ (Exact identifier)      │         │ (Exact text match)      │
└──────────┬──────────────┘         └──────────┬──────────────┘         └──────────┬──────────────┘
           ▼                                   ▼                                   ▼
┌─────────────────────────┐         ┌─────────────────────────┐         ┌─────────────────────────┐
│ 🔍 USE: code_search     │         │ 🌳 USE: codegraph       │         │ 🔎 USE: grep_search     │
│ • "where is payment..." │         │ • codegraph_explore     │         │ • "ERR_INVALID_AUTH"    │
│ • "tax calculation..."  │         │ • callers / callees     │         │ • ".btn-primary-blue"   │
└─────────────────────────┘         └─────────────────────────┘         └─────────────────────────┘

💡 AIエージェント向けプロヒント

1. 純粋な実装ロジックには codeOnly: true を使う: TypeScript/JavaScriptの計算式だけを探して、マークダウン文書やスキルガイドを除外したい場合は、常に codeOnly: true を渡します。

2. サブシステムに絞り込むには pathFilter を使う: ユーザーが「billingモジュールのチェックアウトはどう動くの？」と尋ねたら、pathFilter: "src/billing" を渡します。

3. 直接コード編集には行番号を使う: コードスニペットは1始まりの行番号（14: export function calculateTotal()）付きで返されます。この .行リストを replace_file_content や view_file に、行数を勘で見つけることなく直接渡せます。

4. タイポ耐性: 自然な言葉をそのまま渡してください。エンジンが複数形（stemming）やタイポ（Levenshtein correction）を1ms未満で自動処理します。

🤝 究極のAIペア：code-search と codegraph の両方をインストールすべき理由

モダンなAIコーディングアシスタントは、セマンティック検索（code-search-mcp）と ASTコードグラフ（codegraph）という補完し合うツールを揃えると最高の性能を発揮します。

                   ┌─────────────────────────────────────────────────────────┐
                   │  User: "Where is subscription discount handled?"        │
                   └────────────────────────────┬────────────────────────────┘
                                                │
                                                ▼
                   ┌─────────────────────────────────────────────────────────┐
                   │ 1. SEMANTIC SEARCH (code_search)                        │
                   │ • Understands intent, concepts, and natural language     │
                   │ • Finds: subscription-billing.engine.ts (via JSDoc)     │
                   └────────────────────────────┬────────────────────────────┘
                                                │
                                                ▼
                   ┌─────────────────────────────────────────────────────────┐
                   │ 2. AST CODE GRAPH (codegraph_explore)                   │
                   │ • Understands syntax trees, callers, and blast radius   │
                   │ • Traces: callers into legacy LegacyOrderProcessor.js   │
                   │ • Discovers: unit tests (subscription-billing.spec.ts)  │
                   └─────────────────────────────────────────────────────────┘

片方だけでは不十分な理由

実世界のケーススタディ：モダンエンジン vs レガシーモノリス

実際のエンタープライズコードベースでは：

1. モダンエンジン（subscription-billing.engine.ts） には明示的なシンボル名（calculateSubscriptionDiscount）と充実したJSDoc解説があります。code_search はこれを <ミリ秒で対応率55%以上のマッチとして見つけます。

2. レガシーコア（LegacyOrderProcessor.js） は古い用語（getDiscountedTotal、applyOldDeduction）やタイポが交じる2,000行のファイルです。セマンティック検索だけではスコアが低くなる場合があります。

3. 相乗効果：code_search が subscription-billing.engine.ts を探り当てたら、codegraph_explore は全呼び出し元を即座に LegacyOrderProcessor.js まで直進し、余計な推測をことさら含まずにカバー可能な単体テストを横断して爆発範囲をマッピングします。

推奨するデュアル構成

両方のツールをMCP設定に追加してください：

{
  "mcpServers": {
    "code-search": {
      "command": "node",
      "args": ["/path/to/code-search-mcp/dist/bin/cli.js"]
    },
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    }
  }
}

आकां Recommendations

（目をキープして直します）

📋 推奨アシスタントルール

AIアシスタントに確実に code_search と codegraph を自動選択させるため、プロジェクトのインストラクションファイル（CLAUDE.md、GEMINI.md、.github/copilot-instructions.md、または .cursorrules）に、このルールを追加してください：

## Code Navigation & Search

1. **CodeGraph (`codegraph_explore`)**: Call FIRST when exploring known symbols, tracking call paths, finding usages, or analyzing blast radius (callers + covering tests).
2. **Semantic Search (`code_search`)**: Call FIRST when looking for features, domain behaviors, or business logic described in natural language (e.g. "where is discount calculated", "checkout suggestions formatted").

🧪 動作確認の仕方

インストール後、code-search-mcp が動作していることは、次の手早いチェックで確認できます。

Check 1: AIアシスタントにステータスを聞く

Claude Code、Cursor、Gemini CLI のチャットで次のように尋ねます。

「code_search_status を取得して」

想定される出力：

Index Status: READY (or INDEXING)
Progress: 100%
Files: 6,070 / 6,070 indexed
Chunks: 8,204 code chunks in LanceDB

Check 2: 自然言語コード検索を試す

AIアシスタントに次のように頼みます。

「code_search を使って、顧客の割引ルールや特典がどう処理されているかを検索して」

想定される出力：

### Match 1: src/rewards/early-bird.ts (Lines 1-18) [Score: 56.4%]

アシスタントは正確な行番号と類似度スコア付きの該当コードスnippetを即座に返します。

Check 3: ライブでのファイル監視

1. プロジェクト内（例 src/drinks/secret-recipe.ts）で、特徴的なコメント付きの新テストファイルを1つ作ります：

   // Caramel macchiato secret syrup blend formula
   export const caramelBlend = 42;

2. ファイルを保存します。

3. すぐにAIアシスタントに尋ねます：

   「シークレットシロップの配合式を code_search で探して」

4. 新しいファイルは 1秒未満で見つかって返ります。手動での再ビルド、再起動は不要です！

Check 4: 自動テストスイートを実行して状態を確認（任意）

ソースから開発している場合は、次のコマンドを実行します。

npm test

31件のユニットテスト／統合テストがすべて実行されて合格します。 MCPプロトコルのハンドシェイク、ONNXベクター生成、LanceDB保存、ウォッチャーライフサイクル、単語ステマー、タイポ修正まで認証されます。

🛠️ 実戦で直面した問題とそのまざな解決法（やさしく解説）

あらゆる人間とAIコーディングエージェントにシームレスに働く検索エンジンを作る過程でいくつかの実務課題が出ました。私が遭遇したことと、それぞれの直し方をを示します：

1. 🔤 複数形と語尾 の落とり穴（"marks" 対 "Marker"）

• 問題の replay： 自然な入力として ""chart icon on the chart have iq chart" のような時に "marks" を使うんです。ところがコード側のクラス名は CIQ.Marker や markersSample でした。通常のDB検索（LIKE '% marks%'）は、語末に"s" が付いただけのMarkerをズバリ逃してしまいます。

• 解決方法：軽量ステマー を用意しました。一般的末尾（-s、-ing、-ed、-tion、-ers）を自動にうまく削り、"mark" に。marks を検索すると、"axis" な語幹の値から、CIQ.Marker、markAxis、markersSample が0msで見つかるのです。

2. ✍️ タイポの罠（”calcualte mrgin shortfall”）

• 問題 replay：人類はチャットで速くタイピングするので、末書きがあります（例：marginにのにmrgin または calculate の代わりにcalcualte）。一単語にタイポがあると、従来のキーワード検索は100%失敗します。

• 解決方法：メモリ内語彙辞書と Levenshtein タイポ修正機能 を作りました。日本語と直訳注意：インデク指す際に、エンジンはリポジトリ中の実際の変数名・クラス名・用語を辞書として持ち、クエリがタイポで来たら検索前に辞書チェックで 1ms未満 ん正。

3. 🤖 AIエージェントに優しいコードブロック（行番号）

問題点：検索出力のヘッダーに行範囲（Lines 10-50）はあるけど、ブロック内のコードに区別行がなかった。AIエージェント（Claude Code、Gemini CLI、Antigravity）がその行を編集・引用する際が、行を手で数えし line offset を勝手な guess してました。

解決方法：検索結果スnippetの各行に、実際の 1-indexed 行番号（10: export class ...）を自動付加するようになりました。AIは余分なファイル読み込みなしにそのまま編集ツールへ行番号を渡せます。

4. 📚 コード検索だけのために見えない、数字エラーしやすい文書ノイズ

• 問題点： "how to format currency" のような広い概念を調べても、普通の.htsc utility よりmarkdownスキル文書やアーキテクチャ解説を多く話し言葉を含むため、上がりすぎることがありました。

• 解決方法：

  1. 検索フィルター（codeOnly: true(マークダウン/doc無視)、pathFilter: "src/..."、language）を追加。

  2. 静的なJSON-dictionaryファイルの優先度を落とし、ともかく TypeScript/JavaScriptロジックが先に出るよう調整しました。

5. 🔁 一つのファイルからの結果フラッター（大きなファイル1本からチャンクがどっと出た）

• 問題点：よく使う話題の検索では、3,000行の単一ファイルのマッチが検索結果の10件全部を占め、より小さくてきれいな helper ファイルの結果が辿れないことがありました。

• 解決方法：ファイル単位のダイバーシチを付けるした。各ファイルからは最高2チャンクだけ返し、コードベース全体の健康なバラエティが得られるようにしました。

6. ⚡ 大量保存途中で起こるデータベースロック競合

• 問題 | : ブランチ切替や連続保存すとき、LanceDBへの複数書込みが同時実行 → 競合バージョンエラーになることがありました。

• 解決方法：指数バックオフ付きの非同期書き込みキュー用意。書き込み競合が起きたら数ミリ秒待機し、サーバを落とさずに安全にリトライします。

💡 まとめ

プロセス内のONNXエンベッディング、組み込みLanceDBとインテリジェントなトークン組up、および Model Context Protocol（MCP） を組み合わせることで、ローカルセマンティック検索の摩擦をわたしたちはなくしました。

• ✅ ノートPC上で動くデーモン不要。

• ✅ Python/ChromaDB依存が不要。

• ✅ Gitのノイズが出ない（node_modules/.cache に保管）。

• ✅ タイポと“語の語形変化”を自動認識、1ms未満。

• ✅ 意味で瞬間検索: 自然言語の問いかけを、必要なコードやマークダウン文書へあいtextileリ直す。

Happy coding! 🚀