local-rag-mcp

ローカルドキュメントコーパスに対するセマンティック検索のための読み取り専用MCPサーバー — オンデバイス埋め込み（Ollama）、ローカルChromaストア、ホストから何も出ません。 コーパスコンテンツをクラウドAPIに送れない環境向けに構築され、すべてのMCPクライアント（Claude Code、Codex、プロトコルを話すものすべて）に同じように提供されます。

これはclaude-code-session-memoryのMCPサーバー版の兄弟プロジェクトです：同じ埋め込みモデル、同じ命令プレフィックス方式、同じ測定方法論 — 1つの検索基盤、2つの消費者。セッションメモリのREADMEには完全な評価ストーリー（事前コミットされた基準、敵対的クエリセット、回帰の帰属）が記載されています。このリポジトリは同じ規律をフックではなくサーバーに適用します。

Tools

両方とも読み取り専用として注釈されています。失敗は構造化された{"error": ...}ペイロードを返します — 依存関係のダウンはツールを劣化させますが、セッションは決して劣化させません。

Quickstart

git clone https://github.com/wesglockzin/local-rag-mcp
cd local-rag-mcp
python3 -m venv .venv && ./.venv/bin/pip install -r requirements.txt
ollama pull embeddinggemma

# Index the included sample corpus (or point RAG_CORPUS_DIR at your own)
./.venv/bin/python ingest.py

# Register with Claude Code — ABSOLUTE paths on both sides: the MCP client
# launches the server from its own working directory, so relative paths are
# the #1 install failure.
claude mcp add local-rag -- "$PWD/.venv/bin/python" "$PWD/server.py"

次に、コーパスが知っていることをClaude Codeに尋ねてください — 「sev-1のときに誰がページングされるか？」 — そしてsearch_corpusを呼び出すのを見てください。

設定は3つの環境変数です：RAG_CORPUS_DIR（デフォルト：./sample-corpus）、RAG_STORE_DIR（デフォルト：~/.local-rag-mcp/store）、OLLAMA_HOST。

Design decisions that earn their keep

• サーバーは読み取り専用で、ストアを作成することはありません。 作成はインジェストが所有します。静かに空のストアを初期化する読み取り専用サーバーは、「インジェストを忘れた」を「検索が何も返さない」に変えます — それは答えのように見えるため、より悪い失敗です。

• 埋め込み後に交換するインジェスト。 ファイルの古いチャンクは、すべての新しいチャンクが正常に埋め込まれた後にのみ削除されます。ファイル途中でのOllamaの失敗は、そのファイルがインデックスから欠落したままになることはありません。

• 退役したドキュメントは後フィルターではなく事前フィルターされます。 frontmatterにlifecycle: supersededを持つドキュメントは、ベクトル検索の前にwhere句によって除外されるため、結果スロットを占有することはありません。インジェストはすべてのチャンクにlifecycleキーを明示的に書き込みます — ストアの一部のバージョンでは、キーが欠落していると$neをすり抜けるため、欠落は安全なデフォルトではありません。（このルールの元は、再インジェストが一度マーカーを静かに消去し、退役したドキュメントが結果に再浮上したためです。回帰テストがそれを固定しています。）

• get_fileはシンボリックリンクに対して強化されています。 インデックスされたパスのみが読み取り可能で、インジェスト時とは異なる場所に解決されるパスは拒否されます — そうでなければ、コーパスファイルをシンボリックリンクに交換できる人は誰でもサーバーを通じてコーパス外を読み取ることができます。ファイルがディスク上に存在しない場合（コーパスの移動、別のマシン）、インデックスされたチャンクテキストがチャンク順に代わりに提供されます。

• ストアは常にマシンローカルです。 それはライブのSQLiteバックアップデータベースです。クラウド同期はトランザクション認識なしでファイル全体の置換を行い、失敗モードは書き込まなかったマシン上の静かに破損したインデックスです。コーパスとこのレシピを同期してください。各マシンが独自のストアを構築します。

• すべてのインジェストはコーパスのgitコミットを出力にスタンプします。これにより、インデックスビルドをそれを生成した正確なコーパス状態に固定できます（「未コミットの変更あり」自体が警告ラベルです）。

• 非対称埋め込みプレフィックス（EmbeddingGemmaの文書化されたクエリ/ドキュメント命令プレフィックス）を検索の両側で使用し、コンパニオンプロジェクトの測定された方式に一致させます — そこではプレフィックス付きが生の検索を2桁上回り、混合プレフィックス/生ベクトルは未較正の帯域でスコアリングされます。

Corpus conventions

*.mdファイルの任意のディレクトリで動作します。3つのオプションのfrontmatterキー：

rag: false            # exclude this file from the index entirely
rag_chunk: headings   # heading-split a long document (default: whole-file)
lifecycle: superseded # keep the file, hide it from search

コミットされたsample-corpus/は、3つすべてとプレーンファイルを実行します — 6つの架空のプラットフォームチームドキュメントで、tools/gen_sample_corpus.pyによって生成されます（CIはコミットされたコーパスがジェネレーターと一致することを検証します）。

Tests

pip install pytest && python -m pytest -q

Ollamaもストアもありません：エンベッダーはスタブされ、コレクションは呼び出しを記録するフェイクです。テスト対象は契約です — 引数検証、ライフサイクル事前フィルターがwhere句としてストアに到達すること、読み取り専用の作成なし保証、シンボリックリンク拒否、埋め込み後に交換する順序（エンベッダーダウンパスを含む）、mtime許容スキップ、チャンカーのマージと過大サイズ分割動作。

Known limitations

• 信頼モデル： サーバーは指定されたコーパスを読み取り、クライアントは取得したテキストをモデルコンテキストに注入します。信頼するコンテンツのみをインデックスしてください — 敵対的なドキュメントはプロンプトインジェクションベクターです。サーバーは取得するだけで、サニタイズしません。Stdio MCPには認証層がありません。起動したプロセスの信頼を継承します。

• スコアは1つの埋め込み方式内でのみ比較可能です。較正された「弱い一致」の下限はコーパス固有です（コンパニオンリポジトリが較正方法を文書化しています）。

• 1つのストア、1つのコレクション — マルチコーパスルーティングはここでは範囲外です。

• ハイブリッドキーワード+ベクトルステージはありません。パラフレーズの余裕はコンパニオンリポジトリで測定され文書化されています。

License

MIT — LICENSEを参照してください。

Author

Wes Glockzin