Qdrant RAG Build

会話を通して完全なRAGパイプラインを構築するQdrant MCPサーバー。

非公式、コミュニティ製 — Qdrantとは提携しておらず、Qdrantによる承認も受けていません。

公式のQdrant MCPサーバーは2つのツール（qdrant-store、qdrant-find）しか公開していません。一方、Qdrant RAG Buildは6つの名前空間にわたる33個のツールを公開します — つまり、MCPの会話だけで完全に管理できる本番グレードのRAGシステムです — さらに会話形式のセットアップウィザードを備えており、ユーザーはドキュメントを一切参照しなくても、チャット1回でゼロから「動作し、適切に設定されたRAGコレクション」まで到達できます。

エレベーターピッチ：「AIをQdrantに接続し、一度の会話で本番グレードのRAGを稼働させる」。また一つのQdrantラッパーではありません — **MCP経由のRAGをそのまま一式（RAG-in-a-box）**です。

パッケージ：qdrant-rag-build-mcp · ライセンス：Apache-2.0 · ステータス：計画完了、実装は未開始

目次

1. ビジョンと市場のギャップ

2. 確定した決定事項

3. アーキテクチャ

4. ツールカタログ

5. 会話型ウィザード

6. 取り込みパイプライン

7. エリート検索

8. 品質と評価

9. GitHubでの権威

10. 開発フェーズ

11. 引き継いだ教訓とリスク

12. 名称、ライセンス、最初の一歩

Related MCP server: RAG Knowledge Base MCP Server

1. ビジョンと市場のギャップ

主張する。 今日、MCPを経由してLLMをQdrantに接続しても、得られるのはおもちゃレベルのベクトル記憶だけです。コレクション管理も、ファイル取り込みも、ハイブリッド検索も、リランクも、引用も、設定のナビゲーションもありません。これらはすべてオーダーメイドのエンタープライズRAGシステムには存在しますが、それを「3つのコマンドでインストールできるMCPサーバー」としてパッケージ化した人はいません。

2. 確定したの決定事項

スコープ。 完全な検索 + Qdrant管理 + 一般的な形式（PDF、DOCX、Excel、PPTX、MD、HTML、CSV、URL）の非常に高品質な取り込み。クリーンでRAGに最適なコンテンツがこのプロジェクトの顔です。

ターゲットクライアント。 あなたv1はClaudeファミリー全体を対象 Claude Code、Claude Desktop、claude.ai（Web） です。CodeとDesktopはstdio・ローカル・ワンクリックインストールに近い（§3）。claude.aiはプロトコルの必然性としてリモートHTTPが必要です（ブラウザはローカルプロセスを起動できない）— しかしこれは控えめな拡張であって、新しい作業区分ではありません。公式SDKがすでにストリーミングHTTPに対応しており、v1で必要なのは完全なOAuth 2.1ではなく、ベアラートークン（§3）と、公開HTTPS URLに到達するためのデプロイガイド1つだけです。ChatGPTはv1では扱わない。 claude.aiと違い、ChatGPTは開発者モード（明示的なリスク警告を受けること）と有料プランが必須で、無料枠はありません — これは「Claudeを優先する」という方針にそぐわない抵抗なので、v2に延期します。

プロジェクトゴール。 優れたオープンソースツール：ポートフォリオの目玉であり、GitHubでの権威を生むエンジン。ドキュメント、CI、DXの品質はオプションではありません — それ自体が製品です。

範囲外（v1）。 PST／Cメール取り込み、高負荷OCR、あらゆる、NER/固有表現抽出、サーバーサイドLLM生成（クライアント自身がLLMだから）、特注UI。それぞれの除外理由は§11で説明します。

3. アーキテクチャ

単一のPythonバイナリ、3層のクリーンな構成。MCPサーバーは薄いファサードで、すべてのロジックはMCP非依存のテスト可能なコアに置かれています（これにより、将来のCLIやSDKも既存の何も触らずに実現できます）。

flowchart LR
    subgraph Clients
      CC[Claude Code / Desktop<br/>stdio]
      WEB[claude.ai<br/>HTTPS + bearer token]
    end
    subgraph QRB["Qdrant RAG Build"]
      T[Transport<br/>stdio · streamable HTTP]
      F[MCP facade<br/>33 tools · validation]
      CORE[RAG core<br/>ingestion · retrieval · wizard]
      EMB[Embeddings<br/>local fastembed · external APIs]
    end
    Q[(Qdrant<br/>local · cloud)]
    CC --> T
    WEB --> T
    T --> F --> CORE
    CORE --> EMB
    CORE --> Q

技術決定事項

ウィザードがMCPの「elicitation」ではなくステートマシンである理由。 elicitationのサポートはMCPクライアント/SDKバージョンさまざまで、Claudeファミリーの中でも異なります。シンプルなステートマシンは普通のツールで動き、がどこでも同じ動作を保証し、特殊な機能を要求しません。また、vi復新しいV2時に別のelicitation対応クライアントが追加されても、そのまま維持できます。トランスポートの範囲に関係なく確定済みです。

v1の認証決定。 MCP向けの完全なOAuth 2.1（認可サーバー、PKCE、管理外クライアント登録/Client ID Metadata Documents、実行者検証、リフレッシュトークン含む）は実用的なマルチウィークのエンジニアリングであり、v1の予算には入りません。しかもclaude.ai自身のコネクタ設定ではOAuthは任意の高度フィールドとされ、必須ではない。v1はHTTPパスで静的でプロファイルごとのBearerトークンを使います。ウィザードが生成し、プロファイルYAMLに保存し、Authorization: Bearer <token> で送信します。stdio（Code、Desktop）は認証不要 — ローカルでネットワーク公開がないプロセスなので。完全なOAuth 2.1はドキュメント化されたv2アップグレードとし、ChatGPT（そのエコシステムは他よりOAuthに重きを置く）が対象になったときに再検討します。lities.

デプロイメントモデル： ごユーザー、 1サーバー

MCPは、抽象的な意味でサーバーを「AI」に接続するわけではありません。モデルをホストするクライアントアプリケーション（Claude Desktop、Claude Code、claude.ai）に接続します。接続を維持し、モデルに利用可能なツールの一覧を渡し、モデルのツール呼び出しの決定を受け取り、それをサーバーに対して実行するのは、そのクライアントです。エンドユーザーには「自分はClaudeと話していて、Claudeが自分のQdrantを管理している」と読めます。これは妥当な単純化ですが、実際にサーバーと接続されているのはモデルではなくクライアントです。

v1のスコープには、共有/マルチテナントのサーバーはありません。各ユーザーが自分専用のサーバーを実行します。同じローカルプロセスが、v1の3つすべてのクライアントにサービスを提供します。

• Claude Code / Claude Desktop: サーバーはユーザーのマシン上でローカルのstdio子プロセスとして実行され、クライアントがその設定から起動します。許可リストに登録されたディレクトリに限定された実ファイルシステムアクセスができます。これは標準的なMCP stdioの動作であり、このプロジェクトが新たに構築するものは何もありません。

• claude.ai: 同じローカルプロセスを、トンネル（cloudflared）または同じDockerイメージを実行する小さな常時稼働ホスト（5ドルのVPS、Fly.io、Railway）を介してHTTPS公開します。これは別クラウドデプロイや共有サーバーではありません。ユーザー自身のトンネル経由マシンであれば、ファイルシステムへのアクセスはローカルの場合と同一です。到達するためのトランスポートだけが異なります。claude.aiの全プラン（無料プランを含む、コネクタは1つ）で利用できます。

• 結果: ingest_directory / ingest_file は、ユーザー自身のサーバー（claude.aiの場合はトンネルも）が稼働していれば、3クライアントすべてで同じ動作をします。どこにもファイルアップロードの仕組みは必要ありません。サーバーは構造上、常にディスクへ直接アクセスできるからです。

• 蒸気は一度だけ:

  • Claude Desktop: .mcpbファイルを1つ、Settings → Extensionsにドラッグするだけ。ターミナルは不要です。

  • Claude Code: claude mcp add qdrant-rag-build -- uvx qdrant-rag-build-mcp の1行。

  • claude.ai: Settings → Connectors → Addで、サーバーのHTTPS URLとベアラートークンを貼り付けます。先にサーバー（ラップトップ方式ならトンネル）が起動している必要があります。これはあらゆるリモートMCPコネクタと同じ、プロトコルの必然であり、このプロジェクトが選んだ話ではありません。

  • その先は、ウィザードがRAGの設定を完全に会話型にします。コレクションの作成、エンベディングの選定、ドキュメントの取り込み、検索を、3つのクライアントのどれでも、それ以上技術的な手順なしで行えます。

v2: ChatGPT（意図的に対象外のまま）

ChatGPTも、claude.aiと同じリモートHTTPの形が必要です。技術的に新しいことは何もありません。v1で対象外にするのは、ChatGPT固有の摩擦です。Developer Modeを明示的に有効にする必要があり（第三者のコードの実行についての警告付き）、カスタムコネクタは**有料プラン（Plus/Pro/Business/Enterprise/Edu）**が必須です。claude.aiの無料プラン込みのコネクタとは異なり、ChatGPTには無料で使えるルートがまったくありません。そのどれも「Claudeを優先する」には必要ないのです。v2ではChatGPT専用のコネクタガイドを追加し、もし重要になれば完全なOAuth 2.1を再検討します（ChatGPTのエコシステムそのものがclaude.aiよりもそれを強く求めています）。

4. ツールカタログ

このプロジェクトの中核です。6つの名前空間、予測しやすい名前、LLM向けに書かれた説明があります（ツールが何をするかではなく、いつ使うのか）。破壊的なツールはすべて明示的な確認を必要とし、グローバルな read-only モードも存在します。

Collections

Ingestion

Search

RAG context

Wizard

Admin

5. 会話型ウィザード

起動要因はこれです。サーバ上の状態機械です。各ツール呼び出しは、次の質問を選択肢と根拠ある推奨付きでで返します。クライアントのLLMは、それを自然な言葉でユーザーに伝え、答えを返します。話で確認するようなことは何もなく、特別なクライントに依存するわけでもありません。会話それ自体がインターフェースです。

stateDiagram-v2
    direction LR
    [*] --> Discover
    Discover --> Validate : setup_answer
    Validate --> Discover : next question
    Validate --> Summary : all answered
    Summary --> Apply : user confirms
    Apply --> SmokeTest
    SmokeTest --> [*] : report + saved profile

質問スクリプト（固定順、すべてのステップに推奨付き）

ウィザードの成功定義。 Qdrantを見たことがないユーザーが、10分以内の会話で、うまくスキーマ定義されたコレクション、誰かのエンベディング、保存済みプロファイル、サンプルドキュメント1件の取り込み、引用付き結果を返すテスト検索を手に入れることです。スモークテストの最終レポートがその証拠です。その会話の録画が、READMEの表紙になります。

6. 取り込みパイプライン

品質のシグニチャは、クリーンでRAGに最適化されたコンテンツえ、フォーマットごとに生成し、すべての取り込みで品質レポートを出力することです。「パーサが出したものをそのまま放り込む」ことはありません。

横断的なルール

• 構造優先、トークンは後回し。 まずドキュメントの構造（セクション、シート、スライド）に沿って分割し、ユニットがその上限を超えた場合のみ、トークン予算（オーバーラップ付き）に従って細分化する。すべてのチャンクにはパンくずリストが付く（「マニュアル › 第3章 › インストール」）。

• 正規化された内容ハッシュによる重複排除 をチャンクレベルで行い、ドキュメントごとの冪等性も維持する。ファイルを再取り込みしたら更新ににり、重複はしません。

• 最小限でバージョン管理された引用契約。 引用ペイロード（document、page/section、date、source）はクローズドなフィールドセットである。内部パイプラインメタデータが LLM の問題に届くことはありません。このプロジェクトは、メタデータの膨張が実際のソースを切り詰める事例を過去に2回修正している（§11）。

• 取り込み結果を常に報告する。 作成されたチャンク、品質上の理由で破棄されたページとその理由、検出された重複を報告する。透明性は品質の一部である。

• 事前のテキストサニタイズ（サロゲート、制御文字、壊れたエンコーディング）を埋め込み前に行う。実在する PST ファイルで痛い経験を経て得た教訓。

7. エリート検索

• デフォルトでハイブリッド：高密度（多言語埋め込み）＋スパース（BM25/miniCOIL）を、Qdrant Query API ネイティブの RRF 融合（prefetch ＋ fusion）で統合。追加インフラは不要。

• オプションのリランク：top-50 → top-N をクロスエンコーダーでリランクする。ローカルは fastembed、API は Cohere または llama.cpp の /v1/rerank を利用。

• 多様性のための MMR：Qdrant がすでに返しているベクターを再利用する（with_vectors=true）。検索時に再埋め込みをしては絶対にいけない。この失敗は、このプロジェクトの前身で実際に本番 OOM を引き起こした。

• 第一級のペイロードフィルター：日付（適切な範囲を指定し、lte では終日を含む）、source、type、author — ウィザードが作成したインデックスで使用。

• フラグシップツールの get_context：ハイブリッド → リランク → MMR → トークン予算 → 番号付き引用 [1>は[2]という形式を調整する。厳格な保証：コンテキストに実際に含まれたものだけが引用されなければならない — 幻のソースは存在しない。

• 生成はクライアント側に残す。 サーバーが LLM を直接呼ぶことはなく、ベストなコンテキストを提供するだけである。回答の生成はユーザー自身のモデル（Claude、GPT 等）の役割です。これにより、サーバーは低コスト・高速かつ免許不要（サードパーティの API キー不要）に保たれる。

8. 品質と評価

• リポジトリ内のゴールデンコーパス。 多様な15〜20 のドキュメント（表付き PDF、実在のスプレッドシート、ノイズの多い Web ページ）＋関連チャンクがアノテーションされた約50 問の質問。

• CI の検索メトリクス。 ゴールデンコーパスを対象とした recall@k、MRR、nDCG を測定し、しきい値を下回るとビルドが失敗するようにします。Dense 対 hybrid 対 hybrid+rerank の結果をドキュメントに公開します。数字がプロジェクトを販売する。

• テスト層の階層構造。 Qdrant を依存しないコア単体テスト、コンテナ内の Qdrant を対象とした統合テスト（testcontainers）、SDK のテストクライアントを使用した MCP プロトコルの e2e テスト。フォーマットごとに拷問ファイルを用意（スキャン PDF、結合セルを含む Excel、ガベージ HTML など）。

• リリース時の互換性マトリクス検証。 Claude Code、Claude Desktop、claude.ai での動作をスクリーンショット入りで記録。ChatGPT は v2 でこのマトリックンクに加わる。

9. GitHub 上での権威

ポートフォリオという目標のためには、リポジトリ自体がコードと同じくらい重要なプロダクトです。発動のためのチェックリスト：

• A README のお勧め。 実際の会話でウィザードが 1 秒で RAG を構築する映像（vhs/asciinema）、3 行の uvx クイックスタート、バッジ（CI、coverage、PyPI、license）、公式 MCP との比較表、公開済みのベンチマーク。

• ランディングページ。 README やドキュメントサイトとは別の、専用の洗練された静的ページ。ヒーロー、古式 Qdrant MCP との比較表、ウィザードデモの録画、3つの v1 クライアント向けのインストール CTA、F5 のベンチマーク計測値を含む。発効用の投稿やソーシャルリンクはここを指す。

• ドキュメント。 mkdocs-material のサイト：クライアントごとのガイド（Claude Code、Claude Desktop、claude.ai それぞれを含む — bearer-token コネクタの手順を含む）、クックブック（「自分のドキュメントを対象にした RAG」「チームの記憶」）、全33 ツールの完全なリファレンス、公開 ADR。

• 可視性の高いエンジニアリング。 ruff ＋ mypy strict ＋ pytest ＋ カバレッジの CI、自動の semver リリース（release 版）、CHANGELOG、issue/PR テンプレート、CONTRIBUTING、行動規約、GitHub Discussions の有効化。

• 配布と発動。 PyPI ＋ Claude Desktop の .mcpb バンドル ＋ Docker イメージ ＋ compose スタック（Qdrant を含む）。公式 MCP レジストリ、Smithery、Glama、PulseMCP、awesome-mcp-servers に登録。発動：技術解説記事 ＋ Show HN ＋ r/LocalLLaMA ＋ X。フックとなるのはウィザードの録画です。

10. 開発フェーズ

サイドプロジェクトのペース（平日夜・週末）。すべてのフェーズが、実演可能な形で終了します — 複数のフェーズを同時に進行させることはありません。

合計：実際のサイドプロジェクトのペースで約14.5 週間（約3.5 か月）。2 週間ごとに実証可能なマイルストクションを設けてモチベーションを維持します。

11. 受け継がれた教訓とリスク

静かな競争上の優位性があります。この計画は、テラガバイト規模のデータを扱う実績のあるエンタープライズ RAG システムですでに発生したエラーの代償を継承しています。すべての教訓は、後から修正するのではなく、初日から設計に組み込まれます。

未解決のリスク

12. 名前、ライセンス、最初の一歩

名前: Qdrant RAG Build（パッケージ: qdrant-rag-build-mcp）— 新しいブランドを作らず、このリポジトリの従来のワーキングネームに近い名前として選んだ。名前の選定は2回の試行を経ている。Quiver は無関係な「Qdrant Quantitative」の MCP 名前空間（bolshchikov/qliver-mcp、pipeworx-io/mcp-qliver、jsconiers/qlver-quant-mcp）と衝突するため却下した。Vectorsmith は衝突がないことを確認したが、リポジトリとの関連性が人名前にするという明確な方針に意があるので採用しなかった。これは当初計画で挙げたトレードオフを承知であるという意味、つまり「qdrant」という接頭語の名前が Qdrant 公式プロジェクトとして受け取られてもおかしくない。それを、README のタグラインとドキュメントサイトで「非公式、コミュニティ製」と明記することで緩和している。qdrant-rag-mcp というスラグ自体はすでに活発な別プロジェクト（ancoleman/mcp-pr...）が使用しているため意図的に避けた。qdrant-rag-build と qdrant-mcp-rag-build は PyPI と GitHub（2026年8月）で未使用であることを確認済み。

ライセンス: Apache-2.0 — Qdrant と同じライセンスであり、特許権の許諾が付属する。プロフィールをご覧になるエンタープライズ企業からも期待される選択である。

最初の具体的なステップ: サーバーコードを1行も書く前に、F0 で全33ツールの JSON スキーマの定義から着手する。§4 のカタログがこの仕様であり、まずスキーマを凍結することで実装途中での再設計を避け、初週から公開可能な設計書を手に入れる。それによって第1週の設計案への反映もできる。

参考文献: qdrant/mcp-server-qdrant（公式サーバー、2ツール） · fastembed PR #602（bge-m サポート、オープン） · MCP Bundle（.mcpb）ツールキット · リモート MCP を使用したカスタムコネクタ（claude.ai） · v2 の参考: 開発者モード（ChatGPT Developer Mode）、OpenAI の MCP とコネクタ

プラン v1.3 · 決定: 2026-08-24 · v1 は Claude の全ファミリー（Code、Desktop、claude.ai — stdio ＋ bearer-token HTTP）を対象とする。ChatGPT は claude.ai と同じ技術的制約ではなく、独自の Developer-Mode／有料プランという摩擦のため、意図的に v2 に先送りする。原案は IA_EmailsContext エンタープライズRAGプロジェクトから得た教訓を参照して作成した。