🔌 MCP Docs Assistant

Produktionsreife Retrieval-Augmented-Generation-Pipeline (RAG) über der offiziellen Model Context Protocol-Dokumentation — bereitgestellt über REST, MCP-Tools und Docker.

Stellen Sie natürlichsprachliche Fragen zu MCP (Architektur, Aufbau von Servern/Clients, Tools/Ressourcen/Prompts, Sicherheit) und erhalten Sie Antworten, die in der echten Dokumentation verankert sind — mit Guardrails, PII-Maskierung, Reranking, semantischem Cache und eingebauter Halluzinationsprüfung.

✨ Features

Related MCP server: FusionPact MCP Server

🏗️ Architektur

flowchart TD
    A[User Question] --> B[Guard Input<br/>NeMo Guardrails]
    B -->|blocked| Z[Refusal message]
    B -->|allowed| C[Mask Input PII<br/>Presidio]
    C --> D[Condense Follow-up<br/>into standalone question]
    D --> E{Semantic<br/>Cache Hit?}
    E -->|yes| F[Return cached answer]
    E -->|no| G[Retrieve Top-15<br/>Qdrant Vector Store]
    G --> H[Rerank Top-5<br/>Cross-Encoder]
    H --> I[Fit to Token Budget]
    I --> J[Generate Answer<br/>Portkey: Gemini / Groq]
    J --> K[Guard Output<br/>leak / PII pattern check]
    K --> L[Hallucination Check<br/>LLM-as-judge]
    L --> M[Mask Output PII]
    M --> N[Cache + Store History]
    N --> O[Return Answer]

Jeder obige Knoten ist ein Modul in rag_pipeline/, die zu einem LangGraph-StateGraph in rag_pipeline/graph.py verdrahtet sind. rag_core.py erstellt alle Abhängigkeiten genau einmal (als Singleton) und bietet eine kleine stabile API — chat(), search(), get_history(), cache_stats() — die von der REST-Ebene (main.py) und der MCP-Ebene (mcp_server.py) identisch genutzt wird. So werden ein gemeinsamer Vektor-Speicher / Cache / ein gemeinsamer Unterhaltungsverlauf geteilt, egal über welche Schnittstelle eine Anfrage eingeht.

📁 Projektstruktur

mcp-docs-rag-assistant/
├── main.py                    # FastAPI app — REST endpoints + mounts MCP at /mcp
├── mcp_server.py               # MCP tools (stdio standalone, or mounted in main.py)
├── rag_core.py                 # Singleton facade wiring the whole pipeline together
├── rag_pipeline/
│   ├── config.py                 # Env vars / secrets (single source of truth)
│   ├── logging_setup.py          # Logging + Logfire
│   ├── gateway.py                 # Portkey multi-key LLM gateway
│   ├── errors.py                   # Retry + safe-node error handling
│   ├── ingestion.py                 # MCP docs loader + splitter
│   ├── vectorstore.py                # Embeddings + persistent Qdrant store
│   ├── reranker.py                    # Cross-encoder reranking
│   ├── pii_masking.py                  # Presidio PII masking
│   ├── guardrails.py                    # NeMo Guardrails (Colang 2.x)
│   ├── token_management.py               # Context window budgeting
│   ├── semantic_cache.py                  # Embedding-similarity cache
│   ├── query_condensation.py               # Follow-up question rewriting
│   ├── hallucination.py                     # Runtime hallucination judge
│   └── graph.py                              # LangGraph StateGraph — full pipeline
├── scripts/
│   └── evaluate_ragas.py        # Offline RAGAS evaluation (25 reference Q&A)
├── tests/
│   └── test_pipeline.py         # Fast smoke tests (no API keys needed)
├── configs/guardrails/           # Colang rail files (generated at first run)
├── data/                          # Persisted Qdrant vector store (gitignored)
├── notebooks/                      # Original development notebook
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── .env.example

🚀 Einrichtung

Voraussetzungen

• Python 3.11+

• API-Schlüssel: Google AI Studio (Gemini, ×2), Groq (×2), Portkey (Gateway + Config-ID)

1. Repository klonen und virtuelle Umgebung einrichten

git clone https://github.com/<your-username>/mcp-docs-rag-assistant.git
cd mcp-docs-rag-assistant
python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate     # macOS/Linux

2. Abhängigkeiten installieren

pip install -r requirements.txt
python -m spacy download en_core_web_sm   # required by Presidio for PII detection

3. Umgebungsvariablen konfigurieren

cp .env.example .env

Öffnen Sie .env und tragen Sie die echten Schlüssel ein (GEMINI_API_KEY_1/2, GROQ_API_KEY_1/2, PORTKEY_API_KEY, PORTKEY_CONFIG_ID).

4. Server starten

uvicorn main:app --reload

⏳ Nur erster Lauf: Der Vektor-Speicher existiert noch nicht, also werden die MCP-Dokumentation eingelesen und in limitierten Batches eingebettet — das kann 5–10 Minuten dauern. Bei jedem weiteren Start wird der persistierte Speicher aus data/qdrant_mcp_db/ sofort geladen.

Sobald Sie Startup: RAG-Pipeline bereit. oder Startup: RAG pipeline ready. sehen, öffnen Sie:

• http://localhost:8000/docs — interaktive Swagger-BrowseruI, POST /chat ausprobieren

• http://localhost:8000/health — Health-Check

📡 REST-API

🔌 Verwendung als MCP-Server

Standalone (stdio) — für Claude Desktop

Direkt ausführen:

python mcp_server.py

Oder einen lokalen MCP-Host auf den Server zeigen, z. . in der Konfigurationsdatei von Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-docs-assistant": {
      "command": "python",
      "args": ["E:\\mcp-docs-rag-assistant\\mcp_server.py"]
    }
  }
}

Remote (streamable-http) — über FastAPI

Wenn main.py läuft, sind dieselben MCP-Tools erreichbar unter:

http://localhost:8000/mcp

Verfügbare Tools: ask_mcp_docs, search_mcp_docs, get_conversation_history, cache_stats.

🐳 Docker

Die einzige Voraussetzung ist Docker Desktop (das Docker Compose mitbringt) — Sie müssen Python, die pip-Abhängigkeiten oder das spacy-Modell nicht separat auf dem Rechner installieren. All das geschieht automatisch innerhalb des Images beim Build (siehe Dockerfile ohne Komma — es führt pip install -r requirements.txt und python -m spacy download en_core_web_sm als Build-Schritte aus).

# 1. Make sure .env exists (same as the local setup, step 3 above)
cp .env.example .env   # then fill in real keys

# 2. Build and run
docker compose up --build

Der eine Befehl baut das Image, installiert alle Abhängigkeiten darin und startet den Container. Der Ordner data/ ist als Volume eingebunden (siehe docker-compose.yml), so bleibt der Vektor-Speicher über Container-Neustarts erhalten — der langsae einzige Erstlauf-Aufwand entsteht auch mit Docker nur einmal.

Der Server ist genauso erreichbar wie beim lokalen Lauf: http://localhost:8000/docs.

Zum Stoppen:

docker compose down

Nach dem Ändern von Code oder Abhängigkeiten neu erstellen:

docker compose up --build

🧪 Tests

Schnelle Smoke-Tests — keine API-Schlüssel oder Netzwerkaufrufe nötig (nutzen Fake-Embeddings):

pip install pytest
pytest tests/ -v

📊 Offline-Evaluierung (RAGAS)

Qualifiziert die Pipeline gegen 25 handgeschriebene MCP-Fragen mit Referenzantworten, unter Verwendung von RAGAS:

python scripts/evaluate_ragas.py

Dieses Skript benötigt keinen laufenden Server — es baut die Pipeline selbst auf (derselbe Singleton wie main.py/mcp_server.py) und gibt eine Metriktabelle aus:

• Faithfulness — ist die Antwort im abgerufenen Kontext begründet?

• Response Relevancy — geht die Antwort wirklich auf die Frage ein?

• Context Precision — ist der abgerufene Kontext relevant?

• Context Recall — deckt der abgerufene Kontext ab, was die Referenzantwort braucht?

⏱️ Dauert einige Minuten: Jede der 25 Fragen durchläuft eine echte Retrieval- und Generierrungsrunde, danach wird jede Metrik selbst per LLM-as-Judge bewertet.

⚙️ Konfigurationsreferenz

Die gesamte Konfiguration findet sich in .env (siehe .env.example). Die wichtigsten Variablen:

🛠️ Technologie-Stack

FastAPI · LangChain · LangGraph · Qdrant · Portkey · Sentence-Transformers · Presidio · NeMo Guardrails · RAGAS · MCP Python SDK · Docker

📄 Lizenz

MIT — siehe LICENSE.