FAQ RAG MCP Server

Eine bewusst kleine Anwendung für Retrieval-Augmented Generation (RAG) für die technische Übung von Glean Solutions Engineering. Sie indexiert die mitgelieferten FAQ-Markdown-Dateien, ruft relevante Passagen per Kosinus-Ähnlichkeit ab, erzeugt eine fundierte Antwort über ein LLM und stellt das Ergebnis als ein lokales MCP-Tool bereit: ask_faq.

Das Projekt ist vollständig plattformübergreifend: Alle Setup- und Ausführungsbefehle verwenden uv und sind unter Windows, macOS und Linux identisch. Das an einen Windows-Benutzer mit Claude Code weitergeben? Beginnen Sie mit START_HERE_WINDOWS.md. Das Repository enthält ein CLAUDE.md-Setup-Runbook, das Claude Code automatisch liest, sowie eine portable projektspezifische .mcp.json-Definition für den faq-rag-Server.

Erklärung in dreißig Sekunden

Beim Prozessstart liest Python die FAQ-Dateien, teilt sie in Chunks von etwa 200 Zeichen, erstellt Embeddings, normalisiert sie und speichert den Index im Speicher zwischen. Für jede Frage wird die Frage eingebettet, Chunks anhand der Kosinus-Ähnlichkeit bewertet, die besten vier Text-Chunks an das konfigurierte LLM gesendet und nur eine fertige Antwort sowie Quelldateinamen zurückgegeben.

flowchart LR
  A[FAQ Markdown files] --> B[~200-character chunks]
  B --> C[Document embeddings cached in RAM]
  Q[Question] --> D[Query embedding]
  C --> E[Cosine similarity]
  D --> E
  E --> F[Top 4 text chunks]
  F --> G[Grounded LLM generation]
  G --> H[answer + sources]
  H --> I[MCP client]

Die Embeddings dienen nur zum Auffinden von Passagen. Das LLM erhält die ursprüngliche Frage und den abgerufenen Text, nicht die rohen Embedding-Vektoren.

Related MCP server: Inkdex

Exakter MCP-Vertrag

Tool: ask_faq

Eingabe:

{
  "question": "How do I reset my password?",
  "top_k": 4
}

Ausgabe—keine zusätzlichen Schlüssel:

{
  "answer": "Use the reset link on the login page [faq_auth.md].",
  "sources": ["faq_auth.md", "faq_sso.md"]
}

top_k akzeptiert ganze Zahlen von 1 bis 10 und hat den Standardwert 4.

Warum MCP statt der vorgegebenen HTTP-Option?

Der RAG-Kern wäre hinter beiden Wrappern identisch. MCP wurde gewählt, weil ein KI-Client das Tool-Schema entdecken, selbst über den Aufrufzeitpunkt entscheiden, den lokalen Python-Prozess starten und strukturierte Ergebnisse empfangen kann – ohne einen eigenen HTTP-Client, Port, URL oder Health-Endpunkt. MCP verbessert die Interoperabilität; es verbessert nicht von sich aus die Retrieval-Qualität.

Diese Implementierung verwendet den von der Aufgabe geforderten stdio-Transport. Der MCP-Client startet mcp_server.py als lokalen Kindprozess und tauscht MCP-Nachrichten über die Standardeingabe und -ausgabe des Prozesses aus. Der Server schreibt keine normalen Logs nach stdout, da dieser Kanal für den Protokollverkehr reserviert ist.

Einrichtung (alle Betriebssysteme: Windows, macOS, Linux)

Voraussetzungen:

• Git

• uv — es lädt automatisch ein kompatibles Python herunter, daher ist keine separate Python-Installation erforderlich. Windows: winget install -e --id astral-sh.uv; macOS: brew install uv.

• Ein OpenAI-API-Schlüssel mit verfügbarem API-Guthaben

• Ein MCP-Client wie Claude Code oder Cursor

Die Befehle sind in PowerShell, zsh und bash identisch:

git clone https://github.com/cq2wgwtzb5-lgtm/glean-faq-rag-mcp.git
cd glean-faq-rag-mcp
uv sync

Erstellen Sie .env.local, indem Sie .env.example kopieren, und fügen Sie dann den API-Schlüssel in Ihrem Editor hinzu:

OPENAI_API_KEY=your_key_here

.env.local wird von Git ignoriert. Committen Sie sie niemals und geben Sie sie niemals weiter.

Führen Sie die deterministischen Tests aus (keine API-Aufrufe):

uv run pytest -q

Führen Sie vor dem Hinzufügen von MCP einen direkten End-to-End-Smoke-Test aus:

uv run rag_core.py

Claude Code erkennt die eingecheckte .mcp.json automatisch, wenn eine Sitzung in diesem Ordner startet. Befolgen Sie docs/WINDOWS_MCP_SETUP.md, um sie zu genehmigen, zu überprüfen und aufzurufen (die Schritte gelten für jedes Betriebssystem). Windows-Benutzer können alternativ setup_windows.ps1 ausführen, das dieselben uv-Befehle kapselt.

Nutzung aus jedem Chat-Thread auf einem Rechner

Die projektspezifische .mcp.json wird nur in Sitzungen geladen, die innerhalb dieses Ordners gestartet werden. Um ask_faq in jeder Claude-Code-Sitzung auf einem Rechner verfügbar zu machen, registrieren Sie den Server einmal im Benutzerbereich mit dem absoluten Pfad zum Klon (auf jedem Betriebssystem derselbe Befehl):

claude mcp add --scope user faq-rag -- uv run --directory "<absolute path to this repo>" mcp_server.py

Sitzungen innerhalb des Repositorys verwenden weiterhin den projektspezifischen Eintrag; alle anderen Sitzungen verwenden den benutzerspezifischen. Entfernen Sie ihn mit claude mcp remove --scope user faq-rag.

Evaluierung

Unit-Tests verwenden deterministische Fake-Embeddings und tätigen keine Modellaufrufe:

uv run pytest -q

Der Live-Evaluator führt fünf repräsentative Fragen gegen die tatsächlichen Modell-APIs aus und prüft erwartete Quellen, erforderliche Fakten und das Enthaltungsverhalten:

uv run evaluate.py --output eval-results.json

eval-results.json wird absichtlich ignoriert, da Modellausgabe und Kontokonfiguration variieren. Erfassen Sie den Bericht während des Interviews oder teilen Sie ihn per Bildschirmfreigabe.

Wichtige Designentscheidungen

In-Memory-NumPy-Index

Der mitgelieferte Korpus erzeugt nur wenige Chunks. Eine Vektordatenbank würde Bereitstellungs- und Review-Komplexität hinzufügen, ohne dieses Ergebnis zu verbessern. Normalisierte NumPy-Vektoren machen die Kosinus-Ähnlichkeit zu einem einfachen Matrizen-Vektor-Produkt.

Grenzbewusstes Chunking

Das Ziel bleibt wie gefordert bei etwa 200 Zeichen. Die Implementierung bevorzugt Absatz-, Zeilen-, Satz- und Wortgrenzen, sodass Text nicht nur zum Erreichen einer exakten Zahl an einer beliebigen Stelle abgeschnitten wird.

Einmaliger Embedding-Durchlauf beim Start

Dokument-Embeddings werden einmalig beim Prozessstart erzeugt und im RAM zwischengespeichert. Jede Frage erhält ein neues Query-Embedding. Der Cache besteht aus gemeinsamen Korpusdaten—nicht aus Gesprächs- oder Benutzersitzungsspeicher. Wenn der Prozess endet, verschwindet der Cache und wird beim nächsten Start neu aufgebaut.

Fundierte Generierung und Quellenangaben

Der Generierungs-Prompt beschränkt das Modell auf den abgerufenen FAQ-Kontext, verlangt exakte Dateinamen-Zitate und weist es an zu sagen, wenn die FAQs eine Frage nicht beantworten. Die sources-Liste der Antwort bewahrt die Reihenfolge des Abrufs und enthält nur Dateinamen aus abgerufenen Chunks.

Explizites Fehlerverhalten

Die Anwendung bricht sofort ab, wenn OPENAI_API_KEY fehlt, lehnt leere Fragen und ungültige top_k-Werte ab, verwendet ein 30-Sekunden-Modell-Timeout und erlaubt zwei SDK-Wiederholungsversuche. Fehler bleiben MCP-Fehler statt erfundener FAQ-Antworten.

Bekannte Einschränkungen und Weiterentwicklung für die Produktion

Diese Übung lässt absichtlich einen persistenten Index, inkrementelle Erfassung, Zugriffskontrollen, hybrides lexikalisches Retrieval, Re-Ranking, Aktualitäts- und Autoritätssignale, Audit-Logs und eine Personalisierung pro Benutzer aus.

In einem Unternehmenssystem müssen Berechtigungen vor dem Retrieval durchgesetzt werden, damit unbefugter Text niemals in den Modellkontext gelangt. Die Suchqualität würde außerdem lexikalische, semantische, Aktualitäts-, Autoritäts- und Graphsignale nutzen statt allein der Kosinus-Ähnlichkeit. Das sind zentrale Produktionsanliegen, aber ihre Implementierung für drei lokale Dateien würde die Anforderung der Übung nach einer leichtgewichtigen Lösung verletzen.

Repository-Übersicht

• rag_core.py — Erfassung, Chunking, Embeddings, Retrieval und Generierung

• mcp_server.py — ein ask_faq-MCP-Tool über stdio

• faqs/ — mitgelieferter FAQ-Korpus

• tests/ — deterministische Unit- und Konfigurationstests

• evals/cases.json — fünf Live-Evaluierungsfälle

• evaluate.py — Live-Evaluierungs-Runner

• pyproject.toml / uv.lock — gepinnte plattformübergreifende Umgebung (uv sync)

• setup_windows.ps1 — Windows-Komfortwrapper um dieselben uv-Schritte

• CLAUDE.md — automatische Setup- und Lehrhinweise für Claude Code

• .mcp.json — portable projektspezifische Claude-Code-MCP-Konfiguration

• START_HERE_WINDOWS.md — Übergabe mit einem einzigen Prompt an den Windows-Benutzer

• docs/WINDOWS_MCP_SETUP.md — Schritte zur Verbindung mit Claude Code

• docs/TALK_TRACK.md — Interview-Präsentation und voraussichtliche Fragen

• docs/REQUIREMENTS_TRACEABILITY.md — Zuordnungskarte von Aufgabe zu Code

• docs/VALIDATION.md — bestandene Prüfungen und die verbleibende Live-Test-Grenze

Sicherheit

Committen Sie keine API-Schlüssel. Überprüfen Sie MCP-Server, bevor Sie sie aktivieren; ein lokaler stdio-Server läuft mit den Berechtigungen des Benutzers, der den Client gestartet hat. Dieser Server liest nur sein konfiguriertes FAQ-Verzeichnis und ruft die konfigurierten OpenAI-Modelle auf.

Vorbereitung auf das Interview

Verwenden Sie docs/TALK_TRACK.md. Dieses Dokument erklärt die Architektur, warum jede Entscheidung getroffen wurde, wie sich MCP von HTTP unterscheidet und wie diese kleine Übung auf Gleans Unternehmenssuche und das Problem fundierter Antworten abbildet.