mcp-local-rag

MCP Local RAG

🍴 shinpr/mcp-local-rag からフォーク — 元の作者：Shinsuke Kagawa

AI コーディングアシスタント向けのローカルコードインテリジェンスエンジンです。AST レベルのセマンティック分割とキーワードブーストにより、関数、クラス、API をピンポイントで特定します。完全にプライベートで、セットアップは不要です。

📖 中国語ドキュメント

---

目次

1. 機能
2. クイックスタート
   • 2.1 AI コーディングツールの設定
   • 2.2 CLI クイックスタート
   • 2.3 初回のプロジェクトインデックス作成
3. 基本概念
   • 3.1 二重方式の分割
   • 3.2 ハイブリッド検索
   • 3.3 セキュリティ境界
4. MCP ツールリファレンス
   • 4.1 取り込みツール
   • 4.2 検索ツール
   • 4.3 管理ツール
   • 4.4 コードインテリジェンス
   • 4.5 システムツール
5. CLI
   • 5.1 基本コマンド
   • 5.2 CLI の設定
6. ネットワークとモデル
   • 6.1 ミラーの自動検出
   • 6.2 モデルの選択
   • 6.3 ファイル監視
7. 検索の調整
8. パフォーマンスの調整
   • 8.1 量子化精度
   • 8.2 実行デバイス
   • 8.3 チャンクの最小長
   • 8.4 推奨設定
9. 設定リファレンス
10. トラブルシューティング
11. 開発

---

1. 機能

• スマートな二重方式の分割 — tree-sitter による AST レベルのコード分割です（関数／クラス／メソッドの境界で分割し、スコープチェーンとインポートを挿入します）。ドキュメントにはセマンティック分割を使用し、文字数ではなく意味に基づいて分割します。
• セマンティック検索＋キーワードブースト — まずベクトル検索を行い、その後キーワード照合で完全一致する語句の順位を上げます。useEffect、エラーコード、クラス名などは、意味上の推測だけに頼らず、より上位に表示されます。
• 15 個の MCP ツール — 取り込み、検索、管理、コードインテリジェンス、システム操作を 1 つのサーバーで利用できます。
• AST コードインテリジェンス — 取り込み時に取得した tree-sitter のメタデータを活用し、IDE レベルのコードナビゲーションを実現する find_definition と find_references を提供します。
• 3 段階のミラー自動フォールバック — huggingface.co → hf-mirror.com → modelscope.cn。中国本土のユーザーは設定不要で利用できます。
• すべてローカルで実行 — API キーもクラウドも不要で、データがマシンの外部に送信されることはありません。初回のモデルダウンロード後はオフラインで動作します。
• 手間のかからないセットアップ — npx コマンド 1 つで利用できます。Docker、Python、サーバーの管理は不要です。

---

2. クイックスタート

検索するフォルダーを BASE_DIR に設定します（複数のルートを指定する場合は BASE_DIRS を使用してください。設定を参照してください）。

2.1 AI コーディングツールを設定する

Cursor — ~/.cursor/mcp.json:

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": ["-y", "@damoqiongqiu/mcp-local-rag"],
      "env": { "BASE_DIR": "/path/to/your/project" }
    }
  }
}

Claude Code:

claude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/project -- npx -y @damoqiongqiu/mcp-local-rag

Codex — ~/.codex/config.toml:

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "@damoqiongqiu/mcp-local-rag"]

[mcp_servers.local-rag.env]
BASE_DIR = "/path/to/your/project"

WorkBuddy — Settings → Custom Connectors → Add:

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": ["-y", "@damoqiongqiu/mcp-local-rag"],
      "env": { "BASE_DIR": "/path/to/your/project" }
    }
  }
}

⚠️ WorkBuddy：追加後、Custom Connectors リストで必ず「Trust」をクリックしてください。クリックしないと、サーバーは通知なくブロックされます。

2.2 CLI クイックスタート

MCP は不要です。ターミナルから直接実行できます。

npx @damoqiongqiu/mcp-local-rag ingest ./src/
npx @damoqiongqiu/mcp-local-rag query "auth middleware"
npx @damoqiongqiu/mcp-local-rag status

以上です。Docker、Python、サーバーのセットアップは不要です。

2.3 初回のプロジェクトインデックス作成

You: "Index the src directory of this project"
Assistant: Successfully ingested 156 files (2,847 chunks created)

You: "Where's the middleware that handles API rate limiting?"
Assistant: src/middleware/rateLimiter.ts — useRateLimiter(), lines 42–89

You: "How is the database connection pool configured?"
Assistant: src/config/database.ts — createPool() default max: 20, idle: 5

---

3. 基本概念

3.1 2つの方式によるチャンク分割

チャンク分割方式はファイル形式ごとに選択されます。

• コードファイル（50以上の言語） — CodeChunker は tree-sitter AST を使ってソースを解析し、関数、クラス、メソッドなどの構造上の境界で分割します。各チャンクの contextualizedText にはスコープの階層とインポートのコンテキストが含まれるため、正確なセマンティック検索が可能です。
• ドキュメント（PDF/DOCX/TXT/MD/HTML） — SemanticChunker は文に分割し、埋め込みの類似度に基づいてグループ化して、自然なトピックの境界を見つけます。Markdown のコードブロックはそのまま保持され、ブロックの途中で分割されることはありません。

3.2 ハイブリッド検索

検索 ＝ セマンティック類似度 ＋ キーワードによるブースト（RAG_HYBRID_WEIGHT、デフォルトは 0.6）：

1. クエリをベクトル化 → セマンティック検索で最も関連性の高いチャンクを特定
2. 品質フィルターを適用（距離しきい値、グループ化）
3. キーワードマッチングで完全一致する語句の順位をブースト

useEffect などの識別子が、セマンティック検索の近似結果に埋もれることはありません。

3.3 セキュリティ境界

BASE_DIR / BASE_DIRS の配下にあるファイルのみ、取り込み、一覧表示、削除、近隣チャンクの読み取り操作の対象になります。ルート外を指すよう解決されたシンボリックリンクは拒否されます。兄弟プレフィックスのパス（ルートが /foo/bar の場合の /foo/barista など）もブロックされ、パストラバーサル攻撃を防止します。

---

4. MCP ツールリファレンス

5つのカテゴリに整理された15個のツールがあります。

4.1 取り込みツール

#	ツール	目的	例
1	ingest_file	単一ファイル（PDF/DOCX/TXT/MD/コード）	"./docs/api-spec.pdf を取り込む"
2	ingest_data	メモリ上のテキスト/HTML	"このページを取得して HTML を取り込む"
3	ingest_directory	ディレクトリの一括取り込み	"./src 配下のすべてを取り込む"

ingest_file は50以上のコード言語に対応しています。PDF ではオプションのビジュアルモードを利用できます。ローカル VLM が図のあるページのキャプションを生成し、視覚的なコンテンツを検索可能にします。次の2つのプロファイルを利用できます。

プロファイル	モデル	キャッシュ	用途
fast（デフォルト）	SmolVLM-256M	約250 MB	軽量なビジュアルインデックス作成
quality	Qwen2.5-VL-3B-ONNX	約2.9 GB	画像内にテキストがある図

# CLI
npx @damoqiongqiu/mcp-local-rag ingest ./spec.pdf --visual --visual-quality quality
# MCP
"Ingest ./spec.pdf with visual: true, visualQuality: 'quality'"

ingest_data は Readability → Markdown → インデックス作成の順に処理します。AI アシスタントが取得したウェブコンテンツに最適です。再取り込みすると、古いバージョンは自動的に置き換えられます。

ingest_directory は再帰的にスキャンし、.gitignore に従い、MCP 通知を通じてリアルタイムの進捗を表示します。

4.2 検索ツール

#	ツール	目的	主なパラメーター
4	query_documents	ハイブリッド検索（セマンティック＋キーワード）	query、limit、scope、highlightContext、fromTimestamp
5	read_chunk_neighbors	検索結果の前後のコンテキストを展開	filePath、chunkIndex、before、after

query_documents — scope には単一のパスプレフィックスまたはリストを指定でき、結果をそのサブツリーに制限します。highlightContext は、マッチした語句の前後のスニペットを返します。fromTimestamp / untilTimestamp を使って時間範囲を絞り込めます。

read_chunk_neighbors — デフォルトでは前後2チャンクを返します（grep -C 2 のような動作）。それぞれ最大50チャンクを指定できます。レスポンスでは対象チャンクに isTarget: true のマークが付きます。

4.3 管理ツール

#	ツール	用途
6	list_files	ファイルと取り込み状態（ingested: true/false）を一覧表示します
7	delete_file	ファイルパスまたはソース URL を指定して削除します
8	status	インデックスの統計情報：ドキュメント、チャンク、メモリ、検索モード

list_files は、検索と同じ前方一致のセマンティクスで scope によるフィルタリングをサポートします。大規模なディレクトリでは、スコープ外のサブツリーをスキップすることで、スキャンを高速化できます。

4.4 コードインテリジェンス

#	ツール	用途	入力
9	find_definition	シンボルの定義位置を特定します（ファイル、行範囲、スコープ）	正確なシンボル名
10	find_references	すべての参照を検索します（インポート＋テキスト内の言及）	シンボル名

どちらのツールも、取り込み時に tree-sitter が抽出する AST メタデータ（インポート、エンティティ、スコープチェーン）に依存します。CodeChunker で取り込まれたコードファイルでのみ動作します。v0.18.7 より前に取り込まれたファイルにはこのメタデータがないため、再構築には reindex_all が必要です。

find_references は、2 段階の方法を使用します：（1）codeMeta.imports で完全一致を検索 →（2）シンボル名を FTS 全文検索します。結果は（filePath、chunkIndex）で重複排除され、インポートへの参照が先に表示されます。

4.5 システムツール

#	ツール	用途
11	config	実行時に設定を読み書きします。再起動は不要です
12	dedup_check	SHA256＋Jaccard 類似度でファイルの重複を検出します
13	export_index	インデックス全体を JSON としてエクスポートします（バックアップまたは移行用）
14	reindex_all	全件を再チャンク化し、再埋め込みします（モデル変更後）
15	reindex_stale	ディスク上で変更されたファイルのみを再取り込みします（増分同期）

config は hybridWeight、modelName、cacheDir、baseDir／baseDirs などをホットスワップします。モデルを切り替えると、古い Embedder を自動的に破棄して新しいものを初期化します。注意：モデルを変更すると埋め込み空間が変わるため、reindex_all が必要です。

dedup_check はモノレポで特に便利です。spot ↔ futures のミラーコードは通常、類似度 1.0 として検出されます。

---

5. CLI

5.1 基本コマンド

# Ingest
npx @damoqiongqiu/mcp-local-rag ingest ./src/

# Search (with scope)
npx @damoqiongqiu/mcp-local-rag query "auth middleware"
npx @damoqiongqiu/mcp-local-rag query "auth" --scope /docs/api

# Context expansion
npx @damoqiongqiu/mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5

# Management
npx @damoqiongqiu/mcp-local-rag list --scope /docs/api
npx @damoqiongqiu/mcp-local-rag status
npx @damoqiongqiu/mcp-local-rag delete ./docs/old.pdf
npx @damoqiongqiu/mcp-local-rag delete --source "https://..."

query、read-neighbors、list、status、delete は JSON を標準出力に出力します（jq にパイプで渡せます）。ingest は進行状況を標準エラー出力に出力します。

グローバルオプション（--db-path、--cache-dir、--model-name）はサブコマンドの前に指定します：

npx @damoqiongqiu/mcp-local-rag --help

⚠️ CLI は MCP クライアントの設定（mcp.json など）を読み込みません。フラグまたは環境変数で設定してください。

5.2 CLI の設定

フラグ — グローバルオプションは前に、サブコマンドのオプションは後に指定します：

npx @damoqiongqiu/mcp-local-rag --db-path ./my-db query "auth" --base-dir ./docs

--base-dir は ingest と list で繰り返し指定できます：

npx @damoqiongqiu/mcp-local-rag ingest --base-dir ./docs --base-dir ./specs ./docs/readme.md

環境変数：

export DB_PATH=./my-db
export BASE_DIR=./docs
npx @damoqiongqiu/mcp-local-rag query "auth"

複数のルートを指定するには、BASE_DIRS（JSON 配列）を使用します：

export BASE_DIRS='["/Users/me/work","/Users/me/specs"]'

優先順位：CLI フラグ > 環境変数 > デフォルト値。

---

6. ネットワークとモデル

6.1 ミラーの自動検出

huggingface.co は中国本土からアクセスできません。自動フォールバック機能を備えた、3 段階のミラーチェーンが組み込まれています：

huggingface.co → hf-mirror.com → modelscope.cn

起動時に各ミラーへ HEAD リクエストを送り、到達可能かどうかを確認します（タイムアウトは 3 秒）。API が完全に利用可能なミラーのうち、最初に到達したものが選択されます：

• プロキシあり（HTTPS_PROXY）→ huggingface.co に直接接続します
• プロキシなし → hf-mirror.com に自動的に切り替えます
• hf-mirror API が利用できない場合 → modelscope.cn にフォールバックします

手動で HF_ENDPOINT を設定する必要はありません。 手動で制御するには：

環境変数	効果
HF_AUTO_MIRROR=false	自動検出を無効にし、huggingface.co のみを使用します
HF_ENDPOINT=<url>	特定のミラーを強制的に使用し、自動検出をスキップします

v0.18.5 以降では setGlobalDispatcher(ProxyAgent) を使用します。Node.js 22 のすべてのネットワークリクエストがプロキシを経由します。

6.2 モデルの選択

model-registry によるエイリアス解決に対応した、6 種類の埋め込みモデルです。

モデル	エイリアス	サイズ	次元数
Xenova/all-MiniLM-L6-v2（デフォルト）	mini	約 90 MB	384
Xenova/all-MiniLM-L12-v2	—	約 120 MB	384
Xenova/bge-small-en-v1.5	bge-small	約 130 MB	384
Xenova/all-mpnet-base-v2	mpnet	約 420 MB	768
Xenova/bge-base-en-v1.5	—	約 420 MB	768
Xenova/multi-qa-mpnet-base-dot-v1	multi-qa	約 420 MB	768

ガイダンス：コードリポジトリではデフォルトモデルと高いキーワードブーストを使用します。多言語対応では embeddinggemma-300m、科学論文では allenai-specter の利用を検討してください。

RAG_DTYPE は ONNX の精度（fp32／fp16／q8）を制御します。デフォルトは fp32 です。メモリに制約がある場合は q8 を使用してください。⚠️ モデルや dtype を変更する場合は、DB_PATH を削除して再インデックスする必要があります。

6.3 ファイルの監視

RAG_WATCH=true を設定すると、サーバーは baseDirs を再帰的に fs.watch で監視します（デバウンスは 500ms です）。

• ファイルの作成／変更 → ingest_file を自動実行
• ファイルの削除 → delete_file を自動実行

頻繁に変更されるプロジェクトに最適です。

---

7. 検索の調整

変数	デフォルト	説明
RAG_HYBRID_WEIGHT	0.6	キーワードブースト：0 = セマンティック検索のみ、1 = キーワード検索のみ
RAG_GROUPING	未設定	similar = 上位グループのみ、related = 上位 2 グループ
RAG_MAX_DISTANCE	未設定	関連性の低い結果を除外します（例：0.5）
RAG_MAX_FILES	未設定	結果を上位 N 件のファイルに制限します

コードに重点を置いた調整（推奨デフォルト）：

{ "RAG_HYBRID_WEIGHT": "0.7", "RAG_GROUPING": "similar" }

ドキュメントに重点を置いた調整：

{ "RAG_HYBRID_WEIGHT": "0.4", "RAG_GROUPING": "related" }

キーワードブーストはセマンティックフィルタリングの後に適用されるため、ノイズを増やさずに適合率を向上できます。

---

8. パフォーマンスの調整

検索精度だけでなく、推論パフォーマンスも設定できます。すべて環境変数で最適化でき、コードの変更は不要です。

8.1 量子化の精度（RAG_DTYPE）

ONNX モデルの推論精度を制御します。all-MiniLM-L6-v2 では、次の 3 段階を利用できます。

値	モデルサイズ	速度	メモリ	精度の損失	最適な用途
fp32（デフォルト）	約 90 MB	基準	約 80 MB	なし	初回利用、最大限の精度
fp16	約 45 MB	20～30% 高速	約 45 MB	ごくわずか	日常利用に推奨
q8	約 45 MB	30～50% 高速	約 45 MB	軽微	メモリが少ない環境、大規模プロジェクト

"env": { "RAG_DTYPE": "fp16", "BASE_DIR": "..." }

⚠️ dtype を変更すると、インデックスの再構築が必要です。埋め込み空間に互換性がないためです。

動作の確認： 再起動後、MCP 経由で status を呼び出し、dtype フィールドを確認してください。設定値（例："fp16"）と一致している必要があります。

失敗した場合： 起動時に、サポートされている dtype の一覧とともに EmbeddingError が発生します。よくある原因は、モデルに q8 バリアントが用意されていないことです。その場合は fp16 に切り替えてください。

8.2 実行デバイス（RAG_DEVICE）

使用する ONNX Runtime バックエンドを制御します。

値	バックエンド	備考
cpu（デフォルト）	CPU	最も安定し、追加の依存関係は不要です
webgpu	GPU（WebGPU）	⚠️ 試験的です。M1／M2 Mac では Metal、NVIDIA では Vulkan を使用します

"env": { "RAG_DEVICE": "webgpu", "RAG_DTYPE": "fp16", "BASE_DIR": "..." }

⚠️ デバイスを変更すると埋め込み空間が変わるため、インデックスの再構築が必要です。RAG_DTYPE と併用できます。fp16 + webgpu を設定すると、モデルサイズの縮小と GPU による高速化の両方が得られます。

動作の確認： MCP の起動ログに Loading model on device "webgpu" と表示されることを確認してください。status には device: "webgpu" と表示されます。

失敗した場合：

• 起動時に Unsupported device が表示される → 環境で WebGPU を利用できません。"cpu" に戻してください。
• 起動は成功するが推論がクラッシュする → ONNX WebGPU バックエンドの不具合の可能性があります。"cpu" に戻してください。
• RAG_DEVICE の行を削除するだけで、ほかの設定を変更せずに CPU に戻せます。

8.3 最小チャンク長（CHUNK_MIN_LENGTH）

取り込み時に、この値より短いチャンクを除外します。デフォルトの 50 ではほぼすべてを保持し、200 ではノイズとなる断片の30～40％を除外します。

"env": { "CHUNK_MIN_LENGTH": "200", "BASE_DIR": "..." }

⚠️ 大まかな手段です。短くても重要なコード（設定定数など）も破棄される場合があります。インデックスの再構築が必要です。最適な範囲は 100-200 です。

8.4 推奨設定

シナリオ	設定
日常の開発	RAG_DTYPE=fp16
大規模プロジェクト＋M1/M2 Mac	RAG_DTYPE=fp16, RAG_DEVICE=webgpu
メモリに制約がある場合	RAG_DTYPE=q8

変更を適用するには、reindex_all（MCP）を実行するか、ingest（CLI）を再実行する必要があります。問題が発生した場合は、該当する環境変数の行を削除してデフォルトに戻してください。

---

9. 設定リファレンス

MCP サーバー：環境変数のみ（MCP クライアントの env ブロックで設定）。 CLI：環境変数と同等のフラグ（フラグが優先されます）。

環境変数	CLI フラグ	デフォルト	説明
BASE_DIR	--base-dir（繰り返し指定可能）	cwd	ドキュメントのルート（セキュリティ境界）
BASE_DIRS	—	未設定	ルートの JSON 配列。BASE_DIR を上書きします
DB_PATH	--db-path	./lancedb/	ベクトルデータベースのパス
CACHE_DIR	--cache-dir	./models/	モデルキャッシュ。絶対パスを推奨します
MODEL_NAME	--model-name	all-MiniLM-L6-v2	HuggingFace モデル ID
MAX_FILE_SIZE	--max-file-size	100 MB	最大ファイルサイズ（バイト）
CHUNK_MIN_LENGTH	--chunk-min-length	50	最小チャンク長（1～10000文字）
RAG_DEVICE	—	cpu	ONNX の実行デバイス
RAG_DTYPE	—	fp32	量子化（fp32/fp16/q8）
HTTPS_PROXY	—	未設定	モデルダウンロード用プロキシ。v0.18.5+ ではグローバルに有効です
HF_ENDPOINT	—	huggingface.co	ミラーの手動指定
HF_AUTO_MIRROR	—	true	自動検出の切り替え
RAG_WATCH	—	未設定	ファイル監視（true/1）

ルートの解決順序：CLI の --base-dir > BASE_DIRS > BASE_DIR > cwd。BASE_DIRS と BASE_DIR は結合されません。BASE_DIRS でサポートされるのは JSON 配列形式のみです。区切り文字による形式は意図的に拒否されます。

---

10. トラブルシューティング

モデルのダウンロードに失敗する

症状：fetch failed が発生する、または status に hybrid ではなく searchMode: fts と表示される。

解決策：

1. ネットワークの制限（中国本土など）— プロキシを使用します：

   "env": { "HTTPS_PROXY": "http://127.0.0.1:7890" }
   

   ターミナルではなく、MCP クライアントの設定で指定してください。v0.18.5+ では setGlobalDispatcher によってグローバルに有効です。

2. 自動ミラーへのフォールバック（v0.18.2+、デフォルト）— 3段階のプローブを実行します。通常、設定なしで動作します。

3. 手動での上書き — HF_ENDPOINT=https://modelscope.cn を設定するか、モデルを手動でダウンロードして CACHE_DIR に保存します。

4. npx に古いバージョンがキャッシュされている — キャッシュをクリアして再起動します：

   rm -rf ~/.npm/_npx/
   

MCP クライアントにツールが表示されない

1. 設定ファイルの構文を確認します
2. WorkBuddy ユーザーの場合は、「Trust」ボタンをクリックしたことを確認します
3. クライアントを完全に再起動します（macOS では Cmd+Q）
4. 直接テストします：npx @damoqiongqiu/mcp-local-rag を実行し、エラーが発生しないことを確認します

インデックスの再構築

モデルを切り替えた後、またはデータベースが破損した場合：

1. MCP サービスを停止します
2. DB_PATH ディレクトリ（デフォルトは ./lancedb/）を削除します。元ファイルには影響しないため、安全です
3. MCP を再起動します → 新しいデータベースが自動的に作成されます
4. 一括で再取り込みします：

   npx @damoqiongqiu/mcp-local-rag ingest ./src/
   

よくある質問

• プライバシーは保護されますか？ はい。モデルのダウンロード後、データがマシンの外部に送信されることはありません。
• オフラインで使えますか？ はい。モデルがキャッシュされていれば使用できます。
• 対応形式は？ 50種類以上のプログラミング言語に加え、PDF/DOCX/TXT/MD/HTML に対応しています。Excel、PPT、画像には対応していません。
• GPU アクセラレーションに対応していますか？ RAG_DEVICE でオプトインできます。対応状況はシステム、Node.js のバージョン、ONNX バックエンドによって異なります。
• バックアップ方法は？ DB_PATH ディレクトリをコピーしてください。

---

11. 開発

git clone https://github.com/damoqiongqiu/mcp-local-rag.git
cd mcp-local-rag
pnpm install

pnpm test              # All tests
pnpm run type-check    # TypeScript check
pnpm run check:fix     # Lint + format
pnpm run check:all     # Full CI pipeline

src/
  index.ts      # Entry point
  server/       # MCP tool handlers
  cli/          # CLI subcommands
  parser/       # PDF/DOCX/TXT/MD/code parsing
  chunker/      # SemanticChunker + CodeChunker
  embedder/     # Transformers.js embeddings
  vectordb/     # LanceDB operations
  utils/        # Shared utilities (security, scan, scope)
  __tests__/    # Test suites

---

ライセンス

MIT License。個人利用および商用利用は無料です。

謝辞

Model Context Protocol（Anthropic）、[LanceDB](https://lancedb.com/）、および Transformers.js を使用して構築されています。