de en es ja ko ru zh

code-search-mcp

Name: code-search-mcp
Author: genautkin

by genautkin

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

🔍 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: smart-coding-mcp

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

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

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

仕組み：意味の地図

数字に変える: AI モデルがテキスト（またはコード）を読み取り、**エンベディング（ベクトル）**と呼ばれる数字のリストに変換します。
地図上の座標: その数字は、あたかも人間の概念が集まった巨大な地図上の GPS 座標だと考えてください。
- "discount" と "promotional deduction" は地図上で隣り合う。
- "espresso shot" と "latte" も同じ場所に並ぶ。
- "database migration" は地図の反対側、遠く離れた場所にあります。
最近傍を探す: あなたが自然英語で質問すると、検索エンジンはその質問を座標に変換し、地図上で最も近くにあるコードを見つけます。

                  [ 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/                     │
└─────────────────────────────────────────────────────────────┘

⚙️ 技術の中身

コンポーネント	技術	選んだ理由
ランタイム	Node.js + TypeScript	追加ランタイム依存がなくクロスプラットフォーム（macOS と Windows と Linux）。
ローカル AI エンベディング	`@huggingface/transformers` (ONNX)	プロセス内で `Xenova/all-MiniLM-L6-v2` を使って密な 384 次元ベクトルを生成。 100% プライベート、ネットワークリクエストはゼロ。
ベクトルストレージ	LanceDB	Apache Arrow 上に構築された組み込み型・サーバーレスのベクターデータベース。外部サーバープロセス不要。
ライブファイル監視	`chokidar`	ファイルをリアルタイムで監視し、保存すると約 ~200ms でインクリメンタルにベクトルを更新。
プロトコル	`@modelcontextprotocol/sdk`	Claude Code、Gemini CLI、Cursor、Windsurf がサポートする標準 MCP プロトコル。

🔍 内側の仕組み

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 を実行すると:

ライブウォッチャーが検知: Git がファイルを更新すると、組み込みの chokidar ファイルウォッチャーが、追加・変更・削除されたファイルをリアルタイムで検出します。
高速差分再スキャン: 2つのブラン間で変更された特定のファイルだけをインデックスし直す（数分のではなく 1〜2 秒）。
自動プルーニング（削除）: 以前のブランチで削除されたファイルや古いコードのチャンクは、LanceDB から自動的に削除されます。
手動同期: 大きなマージの後に全体をきちんと再構築したい場合は、アシスタントにこう伝えます。"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 ツール

ツール名	引数	説明	呼び出しのタイミング
`code_search`	`query` (必須)`limit` (任意、デフォルト10)`pathFilter` (任意の文字列)`language` (任意の文字列)`codeOnly` (任意のブール値)	インデックス化されたリポジトリファイルを横断して、セマンティック＋語彙のハイブリッド検索を実行します。類似度スコア付きの行番号付きコードチャンクを返します。	最初の呼び出しです。概念、ビジネスロジック、ワークフロー、UIコンポーネント、機能などを自然言語で探すときに使います（例：「ユーザー認証のリフレッシュはどこ？」「ショッピングカートの税額計算機」）。
`code_search_status`	(なし)	現在のインデックス処理状況（`READY`、`INDEXING`）、進捗率、総ファイル数、LanceDB内のチャンク数を返します。	インデックスがまだ進行中かもしれない場合は、大規模な検索の前に確認してください。
`code_search_reindex`	`forceFull` (任意のブール値)	バックグラウンドでの再インデックス、またはデータベース全体の再構築をトリガーします。	ユーザーがデータベース再構築を明示的に要求した場合、または大規模なブランチマージ後に呼び出します。
`code_search_guide`	(なし)	エージェント利用時のベストプラクティスとヒントをインラインで返します。	ツールを呼び出す場面でベストプラクティスを自己発見するために呼び出します。

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

                       ┌───────────────────────────────────────────────┐
                       │ 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エージェント向けプロヒント

純粋な実装ロジックには codeOnly: true を使う: TypeScript/JavaScriptの計算式だけを探して、マークダウン文書やスキルガイドを除外したい場合は、常に codeOnly: true を渡します。
サブシステムに絞り込むには pathFilter を使う: ユーザーが「billingモジュールのチェックアウトはどう動くの？」と尋ねたら、pathFilter: "src/billing" を渡します。
直接コード編集には行番号を使う: コードスニペットは1始まりの行番号（14: export function calculateTotal()）付きで返されます。この .行リストを replace_file_content や view_file に、行数を勘で見つけることなく直接渡せます。
タイポ耐性: 自然な言葉をそのまま渡してください。エンジンが複数形（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)  │
                   └─────────────────────────────────────────────────────────┘

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

ツール	主な役割	最も得意なこと	苦手なところ
`code-search` (semantic vector)	概念・意図の発見	平易な言葉で書かれたビジネスロジック、機能、コンポーネント、アーキテクチャ文書を見つけること	動的な呼び出し階層や、注釈のないレガシーファイルの横断
`codegraph` (ASTシンボルグラフ)	構造ナビゲーションと爆発範囲	シンボル定義、呼び出し元、呼び出し先、関連単体テストを1ジャンプで追跡すること	シンボル名を事前に知らずに、自然言語で語用概念を探すこと

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

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

モダンエンジン（subscription-billing.engine.ts）には明示的なシンボル名（calculateSubscriptionDiscount）と充実したJSDoc解説があります。code_search はこれを <ミリ秒で対応率55%以上のマッチとして見つけます。
レガシーコア（LegacyOrderProcessor.js）は古い用語（getDiscountedTotal、applyOldDeduction）やタイポが交じる2,000行のファイルです。セマンティック検索だけではスコアが低くなる場合があります。
相乗効果：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: ライブでのファイル監視

プロジェクト内（例 src/drinks/secret-recipe.ts）で、特徴的なコメント付きの新テストファイルを1つ作ります：
```
// Caramel macchiato secret syrup blend formula
export const caramelBlend = 42;
```
ファイルを保存します。
すぐにAIアシスタントに尋ねます：
「シークレットシロップの配合式を code_search で探して」
新しいファイルは 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! 🚀

Available Tools

4 tools

code_searchA

Search the codebase semantically using natural language queries (e.g. "how is payment verified", "calculate discount rate"). Returns relevant code snippets with file paths and line numbers. Supports filtering by directory path, programming language, or codeOnly (to exclude markdown docs).

Name	Required	Description
`limit`	No	Maximum number of results to return (default: 10)
`query`	Yes	The natural language or identifier search query
`codeOnly`	No	If true, excludes markdown documentation files (.md) to prioritize actual code formulas and logic
`language`	No	Optional programming language filter (e.g. "typescript", "javascript", "vue")
`pathFilter`	No	Optional directory or file path substring to restrict search (e.g. "src/auth", "src/billing")

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that the tool returns 'relevant code snippets with file paths and line numbers' and describes supported filters, which conveys a read-only, non-destructive behavior. It does not mention any side effects or limitations, but for a search tool this level of detail is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and efficient, consisting of two sentences that front-load the primary action with examples, then cover the return format and filters. There is zero filler, and every sentence contributes to the agent's ability to invoke the tool correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Since there is no output schema, the description appropriately explains the return value ('relevant code snippets with file paths and line numbers'). It also covers all parameters implicitly through the filtering descriptions and the query example, making the tool fully usable without needing to inspect the schema or other sources.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter. The description adds minimal extra meaning beyond what the schema provides—it merely echoes the filtering options (directory path, language, codeOnly) without introducing new syntax or details. This is the baseline score for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('search'), a resource ('the codebase'), and a method ('semantically'), with concrete examples of natural language queries. It also differentiates from sibling tools by implying this is the actual search operation, while siblings are status, reindex, and guide tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool (searching the codebase semantically) and mentions filtering options that shape usage. It does not explicitly name alternatives or state when not to use it, but the sibling tools are so distinct (status, reindex, guide) that exclusion guidance is not strictly necessary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_search_guideA

Get best practices and usage instructions for AI agents on how and when to use code_search.

Name	Required	Description	Default
No parameters

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the behavioral burden. It clearly implies a read-only retrieval of guidance, but does not disclose output format, size, or any side effects. For a simple guide tool, the lack of explicit behavioral detail is acceptable but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the action and the target resource with zero redundancy. Every word contributes to clarity, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless guide with no output schema, the description sufficiently conveys the tool's purpose and content. It could explicitly state that the returned instructions should be followed before using code_search, but the sibling context and the description's phrasing make this largely self-evident, so the gap is minimal.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, and schema coverage is 100% (vacuously). Since the tool takes no inputs, the description need not add parameter-specific meaning; the baseline of 4 for no-parameter tools applies without deduction.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('get') and a clear resource ('best practices and usage instructions for AI agents on code_search'). It distinguishes itself from sibling tools like code_search (which performs the search), code_search_status, and code_search_reindex, making its purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states it provides guidance on how and when to use code_search, which implicitly tells an agent to use this tool when needing to decide on code_search usage. However, it does not explicitly contrast with sibling tools or state 'use this before calling code_search', leaving that inference to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_search_reindexA

Trigger a background re-index of the repository. Can be used to force a full reindex.

Name	Required	Description	Default
`forceFull`	No	If true, clears existing vector database and rebuilds index from scratch

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of disclosing behavior. It mentions 'background' indicating asynchronicity and 'force a full reindex' implying destructive potential, but it omits details like whether an incremental reindex is available, idempotency, or cancellation behavior. It provides some useful context but is not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short, focused sentences with no filler. It front-loads the core action ('Trigger a background re-index') and adds the optional force behavior succinctly. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with a single optional parameter and no output schema, the description covers the essentials but leaves gaps: it does not clarify what happens when forceFull is false (e.g., incremental indexing) nor mention the sibling code_search_status for checking reindex progress. These are minor gaps given the simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the forceFull parameter is fully documented in the schema ('clears existing vector database and rebuilds index from scratch'). The description's mention of 'force a full reindex' adds minimal value beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Trigger a background re-index of the repository') with a specific verb and resource. It also hints at the forceFull parameter. This distinguishes it from siblings like code_search, code_search_status, and code_search_guide, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives. It implies usage through the tool's purpose but lacks explicit context such as 'use after schema changes' or 'when index is stale'. No exclusions or alternative routing are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_search_statusA

Get the current indexing status, progress percentage, total files, and indexed chunk count.

Name	Required	Description	Default
No parameters

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It correctly implies a read-only operation via 'Get' and enumerates the output fields. It does not mention side effects, authentication, or rate limits, but for a simple status check these are not critical. It does not contradict any annotations (there are none) and gives sufficient behavioral context for expectation setting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that lists the key outputs without any fluff. It is front-loaded with the verb and resource, making it instantly scannable. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters, no annotations, and no output schema, the description is fully sufficient. It states exactly what information will be retrieved. An agent can call it without needing additional context or clarification.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema coverage is trivially 100%. Baseline for 0 parameters is 4. The description adds no parameter-specific details (none needed), and it correctly explains what the tool returns, which is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and the resource ('current indexing status'), and lists specific fields (progress percentage, total files, indexed chunk count). The verb and resource differentiate it from siblings like code_search, code_search_reindex, and code_search_guide. It unambiguously describes what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies its use for checking indexing status but provides no explicit guidance on when to choose this over the sibling tools (e.g., 'use this to check, not to trigger reindexing'). No exclusions or alternative references are given. While the purpose is clear, the tool lacks explicit routing compared to the high-standard examples.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv0.1.0Aug 24, 2026
- First observedcode_search
- First observedcode_search_guide
- First observedcode_search_reindex
- First observedcode_search_status

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-08-24 00:35 across 4 tools

Disambiguation5/5

Each tool has a unique, clearly defined purpose: search, status, reindex, and guide. There is no overlap or ambiguity between them, and the descriptions make it obvious which tool to use for each task.

Naming Consistency5/5

All tool names follow the same convention: 'code_search_' followed by a simple action verb (search, status, reindex, guide). This is perfectly consistent and makes the tool set easy to predict and use.

Tool Count5/5

With 4 tools, the set is tightly scoped and every tool serves a necessary function for a code search server. This is an ideal count—not too thin or over-bloated—for the domain.

Completeness5/5

The tool surface covers the full lifecycle of a code search server: performing searches, checking index status, triggering reindexes, and providing usage guidance. There are no obvious gaps in functionality.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Related MCP Connectors

TeamShared C
io.github.xhad
Shared memory for coding agents. Stop re-explaining your codebase every session.
Knowledge & Memory Developer Tools
1981
https://teamshared.com/mcp
Maguyva
ai.maguyva
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code Analysis Coding Agents
23
https://maguyva.tools/mcp
searchcode A
com.searchcode
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Search Code Analysis Version Control
72
https://api.searchcode.com/v1/mcp
SirroOAuth
io.github.Jonathanmberg
Shared memory for AI coding agents. Save once, reuse from Cursor, Claude Code, Codex.
Knowledge & Memory Developer Tools
1
https://www.sirro.dev/beta/mcp/sirro-public-beta

Related MCP Servers

claude-context-local
RAG Systems Developer Tools Code Analysis
tazhate
A
license
Not graded
quality
C
maintenance
Provides Claude Code with local semantic search and indexing of your codebase using AST-aware chunking and hybrid search, enabling deep code understanding without sending data to the cloud.
Updated 7 months ago (2026-03-18 19:42 UTC)
61 PyPI
MIT
smart-coding-mcp
Code Analysis Developer Tools
amalikn
A
license
A
quality
D
maintenance
Enables AI assistants to perform intelligent semantic code search across codebases using local AI embeddings for meaning-based retrieval.
Updated 7 months ago (2026-03-29 01:00 UTC)
6
79 npm
MIT
CodeBrain MCP Server
RAG Systems Search Code Analysis
candrle20
F
license
Not graded
quality
D
maintenance
Enables semantic code search across codebases using AI embeddings and vector similarity, integrated with Claude Desktop and Cursor.
Updated a year ago (2025-11-02 05:55 UTC)
-
ContextTree MCP
Code Analysis RAG Systems Search
chelslava
A
license
A
quality
A
maintenance
Enables AI coding assistants to perform local semantic code search using AST parsing and embeddings, finding code by meaning with exact file and line locations, plus AST-based usage lookup.
Updated 2 months ago (2026-09-03 06:01 UTC)
4
MIT

🔍 code-search-mcp

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

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

仕組み：意味の地図

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

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

⚙️ 技術の中身

🔍 内側の仕組み

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. Claude Code

2. Antigravity CLI (agy)

3. Gemini CLI

4. Cursor / Claude Desktop:

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

🛠️ 利用可能な MCP ツール

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

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

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

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

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

推奨するデュアル構成

आकां Recommendations

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

🧪 動作確認の仕方

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

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

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

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

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

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

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

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

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

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

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

💡 まとめ

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

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

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

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

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

2. Antigravity CLI (`agy`)

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

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