Qdrant RAG Build

Der Qdrant-MCP-Server, der eine vollständige RAG-Pipeline im Gespräch aufbaut.

Inoffiziell, von der Community gebaut — nicht mit Qdrant verbunden und nicht von Qdrant unterstützt.

Der offizielle Qdrant-MCP-Server stellt 2 Tools bereit (qdrant-store, qdrant-find). Qdrant RAG Build stellt 33 Tools in 6 Namespaces bereit – ein produktionsreifes RAG-System, das vollständig über eine MCP-Konversation verwaltet wird – plus einen gesprächsbasierten Einrichtungsassistenten, der einen Benutzer in einem einzigen Chat von null auf eine funktionierende, gut konfigurierte RAG-Collection bringt, ganz ohne Dokumentation.

Elevator Pitch: „Verbinde deine KI mit Qdrant und lass ein produktionsreifes RAG in einem einzigen Gespräch laufen." Nicht etwa ein weiterer Qdrant-Wrapper — RAG-in-a-Box per MCP.

Paket: qdrant-rag-build-mcp · Lizenz: Apache-2.0 · Status: Planung abgeschlossen, Implementierung nicht begonnen.

Inhaltsverzeichnis

1. Vision und Marktlücke

2. Festzuschreibene Entscheidungen

3. Architektur

4. Tool-Katalog

5. Der gesprächsbasierte Einrichtungsassistent

6. Ingestion-Pipeline

7. Elite-Retrieval

8. Qualität und Evaluierung

9. GitHub-Autorität

10. Entwicklungsphasen

11. Übernommene Lehren und Risiken

12. Name, Lizenz und erster Schritt

Related MCP server: RAG Knowledge Base MCP Server

1. Vision und Marktlücke

These: Heute bekommst du, wenn du eine LLM per MCP mit Qdrant Freunde verbindest, ein semantisches Spielzeuggedächtnis. Keine Collection-Verwaltung, keine Datei-Erfassung, keine hybride Suche, kein Reranking, keine Zitate, keine geführte Konfiguration. All das existiert in maßgeschneiderten Enterprise-RAG-Systemen — aber niemand hat es als MCP-Server Map verpackt, den man in einem einzigen Befehl installiert.

2. Festgeschreibene Entscheidungen

Umfang. Vollständiges Retrieval + Qdrant-Engine Management + hochwertige Verarbeitung gängiger Formate (PDF, DOCX, Excel, PPTX, MD, HTML, CSV, URL). Sauberer, RAG-optimaler Inhalt ist das Markenzeichen des Projekts.

Ziel-Clients. V1 ist die gesamte Claude-Familie: Claude Code, Claude Desktop und claude.ai (Web). Code und Desktop sind stdio, lokal und nahezu eine One-Click-Installation (§3). claude.ai benötigt aus Protokollaussicherheitsgründen Remote-HTTP (ein Browser kann keinen lokalen Prozess starten) – das ist jedoch eine überschaubare Ergänzung, keine neue Kategorie: Das offizielle SDK spricht bereits streamable HTTP, und v1 benötigt nur ein Bearer-Token, kein vollständiges OAuth 2.1 (§3), plus einen Deployment-Guide, um eine öffentliche HTTPS-URL zu erreichen. ChatGPT bleibt außerhalb von v1. Im Gegensatz zu claude.ai erfordert es Developer Mode (eine zwingende Risikoanzeige, die zu akzeptieren ist) und einen Premium-Plan ganz ohne click-free Stufe – Reibung, die dem Ziel „ClCentrate" nicht dient, daher auf v2 verschoben.

Ziel. Ein herausragendes Open-Source-Werkzeug: Portfolio-Herzstück und GitHub-Autoritätsmaschine. Der Qualität von Dokumentation, CI und Entwicklererfahrung sind nicht optional – sie sind das Produkt.

Nicht im Umfang (v1). PST/E-Mail-Ingestion, schwerer OCR, NER/Entity-Extraction, server-seitige LLM-Generierung (der Client ist das LLM), eine eigene UI. Jeder Aus8 ist in §11 begründet.

3. Architektur

Ein Python-Paket, drei saubere Schichten. Der MCP-Server ist eine dünne Fassade; die gesamte Logik lebt in einem testbaren Kern ohne MCP-Abhängigkeit (was ohne jede Anpassung eine spätere CLI oder ein SDK ermöglicht).

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

Technische Entscheidungen

MCP verbindet einen Server nicht abstrakt „mit der KI“ – es verbindet ihn mit der Client-Anwendung, die das Modell beherbergt (Claude Desktop, Claude Code, claude.ai). Dieser Client hält die Verbindung aufrecht, übergibt dem Modell die Liste der verfügbaren Tools, fängt die Tool-Aufruf-Entscheidungen des Modells ab und führt sie gegen den Server aus. Für Nutzer liest sich das als „Ich spreche mit Claude und es verwaltet mein Qdrant“ – eine berechtigte Vereinfachung –, aber tatsächlich ist der Client mit dem Server verbunden, nicht das Modell.

Im Umfang von v1 gibt es keinen gemeinschaftlichen/Multi-Tenant-Server. Jeder Benutzer betreibt seinen eigenen Server, und derselbe lokale Prozess bedient alle drei v1-Clients:

• Claude Code / Claude Desktop: Der Server läuft als lokaler Stdio-Kindprozess auf dem eigenen Rechner des Benutzers und wird vom Client aus dessen Konfiguration heraus startet. Echter Dateisystemzugriff, beschränkt auf per Allowlist freigegebene Verzeichnisse – Standard-MCP-stdio-Verhalten, nichts, was dieses Projekt erst noch bauen müsste.

• claude.ai: Derselbe lokale Prozess, über HTTPS durch einen Tunnel (cloudflared) oder über einen kleinen, permanent laufenden Host (ein $5 (VPS, Fly.io, Railway) erreichbar, der dasselbe Docker-Image ausführt – keine separate Cloud-Deployment und kein gemeinsamer Server. Der Dateisystemzugriff ist mit dem lokalen Fall identisch, wenn es sich um den eigenen getunnelten Rechner handelt; allein der Transport dorthin unterscheidet sich. Verfügbar in jedem claude.ai-Tarif, einschließlich Free (ein Connector).

• Konsequenz: ingest_directory / ingest_file right verhalten sich bei allen drei Clients gleich, solange der eigene Server des Benutzers (und bei claude.ai der Tunnel) läuft. Keinerlei Datei-Upload-Mechanismus nötig – der Server hat durch Konstruktionsweise immer direkten Dateisystemzugriff.

• Installation, einmalig:

  • Claude Desktop: eine .mcpb-Datei in Einstellungen → Erweiterungen ziehen. Kein Terminal nötig.

  • Claude Code: claude mcp add qdrant-rag-build -- uvx qdrant-rag-build-mcp. Eine Zeile.

  • claude.ai: Einstellungen → Connectors → Hinzufügen, die HTTPS-URL des Servers und das Bearer-Token einfügen. Der Server (und ggfs. Tunnel, wenn du das Laptop-Rezept nutzt) muss dabei zuerst laufen – das ist genauso bei jedem Remote-MCP-Connector protokollbedingt und keine aus freien Stücken getroffene Entscheidung dieses Projekts.

  • Von da an macht der Assistent das Konfigurieren des RAG vollständig gesprächsbasiert – Collections anlegen, Embeddings wählen, Dokumente erfassen, Suchen –, ganz ohne weitere technische Schritte, und zwar auf allen drei Clients.

v2: ChatGPT (absichtlich noch nicht)

ChatGPT benötigt dieselbe Remote-HTTP-Struktur wie claude.ai – technisch ist daran nichts Neues. Was es bewusst aus v1 heraushält, ist eine ChatGPT-spezifische Hürde: Developer Mode muss explizit aktiviert werden (mit einer Warnung über die Ausführung von Drittanbieter-Code), und benutzerdefinierte Connectors erfordern einen bezahlten Plan (Plus/Pro/Business/Enterprise/Edu) – es gibt keinerlei kostenfreien ChatGPT-Pfad, anders als bei den kostenlos inkludierten conncatoren von claude.ai. Nichts davon unterstützt das Ziel „Claude priorisieren“. v2 ergänzt einen ChatGPT-spezifischen Connector-Leitfaden und geprüft, falls relevant, erneut die volle OAuth-2.1-Unterstützung (ChatGPT lean more strongly than claude.ai) mehr darauf than.

4. Tool-Katalog

Das Herzstück of the Projekts. Sechs Namespaces, vorhersehbare Namen, Beschreibungen, die für das LLM geschrieben sind (wann ein Tool verwendet werden soll, nicht nur was es tut). Jedes destruktive Tool verlangt eine ausdrückliche Bestätigung, außerdem existiert ein globaler Modus read-only.

Collections

Ingestion

Suche

RAG-Kontext

Wizard

Verwaltung

5. Der gesprächsbasierte Assistent

Das Unterscheidungsmerkmal. Auf dem Server läuft eine Zustandsmaschine: Jede Tool-Call liefert die nächste Frage samt Optionen und einer abgewogenen Empfehlung zurück; das LLM des Clients gibt sie an den Nutzer in natürlicher Sprache weiter und übermittelt die Antwort zurück. Kein weiteres Nachfragen, keine Abhängigkeit von irgendeinem bestimmten Client – die Konversation ist die Schnittstelle.

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

Frageablauf (feste Reihenfolge, Empfehlung bei jedem Schritt)

Erfolgskriterium des Assistenten. Ein Benutzer, der Qdrant noch nie gesehen hat, bekommt in einem Gespräch unter 10 Minuten: eine sauber schematisierte Collection, funktionierende Embeddings, case cooled if local? … ein gespeichertes Profil, ein Beispiel-Dokument (ingested) und eine Testsuchen, die Ergebnisse mit Zitaten liefert. Der Abschlussbericht des smoke-Tests ist der Beleg – and a recording of it is the cover of the README.

6. Ingestions-Pipeline

Qualitätsmerkmal: sauberer, RAG-optimierter Inhalt, pro Format, mit Ingestionsbericht über jeden Inschub. Nie einfach das nehmen, was der Parser higher spuckt.

Querschnittsregeln

• Struktur zuerst, Tokens zweit. Zuerst entlang der Dokumentstruktur (Abschnitt, Blatt, Folie) schneiden und nur dann nach Token-Budget (mit Überlappung) unterteilen, wenn eine Einheit es überschreitet. Jeder Chunk trägt einen Breadcrumb („Anleitung › Kapitel 3 › Installation“).

• Deduplizierung über normalisierten Inhalts-Hash auf Chunk-Ebene plus dokumentbezogene Idempotenz: Ein erneutes Einlesen einer Datei aktualisiert sie, dupliziert sie aber nie.

• Minimaler, versionierter Zitationsvertrag. Das Zitationspayload (Dokument, Seite/Abschnitt, Datum, Quelle) ist eine geschlossene Feldmenge. Inhalte der internen Pipeline erreichen nie den LLM-Kontext – dieses Projekt hat den Bug, bei dem Metadatenbloat die tatsächlichen Quellen abschnitt, an zwei bezahlt (§11).

• Ingestionsergebnisse immer melden. Erzeugte Chunks, aus Qualitätsgründen verworfene Seiten und warum, erkannte Duplikte. Transparenz ist Teil der Qualität.

• Textbereinigung (Ersatzzeichen, Steuerzeichen, defekte Kodierungen) vor dem Einbetten – auf die harte Tour aus echten PST-Dateien gelernt.

7. Elite-Retrieval

• Hybrid by default: Dense (multilinguale Embeddings) + Sparse (BM25/miniCOIL) mit nativer RR-Fusion über die Qdrant Query API (Prefetch + Fusion) – keine zusätzliche Infrastruktur.

• Optionaler Rerank mit einem Cross-Encoder von Top-50 → Top-N. Lokal via Fastembed oder API (Cohere, /v1/rerank von llama.cpp).

• MMR für Vielfalt, unter Wiederverwendung der Vektoren, die Qdrant bereits zurückgibt (with_vectors=true). Beim Retrieval niemals neu embedden – dieser Fehler verursachte beim Vorgänger dieses Projekts einen echten Produktionsabsturz.

• First-Class-Payload-Filter: Datum (sauber begrenzte Rückwertsbereiche, einschließlich Tagesende bei lte), Quelle, Typ, Autor – über Indizes, die der Wizard anlegt.

• get_context als Flaggschiff-Tool: Orchestert Hybrid → Rerank → MMR → Token-Budget → formatierten Block mit nummerierten Zitaten [1][2]. Harte Garantie: Nur was tatsächlich in den Kontext gelangt, wird zitiert – niemals Phantom-Zitate.

• Die Generierung bleibt beim Client. Der Server ruft sekundär kein Service dir.

and the current locale is zh, Vue I18n will either display the key itself (boutiqueLabel) or fall back to a configured locale — it depends on your fallbackLocale setting.

So, two possibilities:

1. The per-locale key is intentional. Maybe the message is semantically tied to a culture, product feature, or legal snippet, and you know it only belongs in the English UI. That's valid — but make sure you're not just forgetting to add the key to zh.json.

2. The key should exist everywhere, but you don't want to maintain it by hand. Then you need a single source of truth. Options:

   • Create a canonical en.json and generate zh.json from it with a tool or script.

   • Use the missing handler in Vue I18n to flag missing keys in development.

   • Add a CI validation step that checks that both files have identical key paths — this catches drift early without forcing per-locale files to start out identical.

   • Use fallbackLocale: 'en' so that, even if zh.json is missing a key, the English version shows instead of the raw key.

For the workflow you mentioned:

"Update both files upon every change"

If your convention is always update both, you can enforce it by running a small script: