Agentischer RAG-Assistent mit FastAPI + MCP

Ein Assistent für interne Dokumente, der vier Dinge kombiniert, nach denen Recruiter derzeit suchen:

• Agentische KI — eine Tool-Use-Schleife, in der das LLM entscheidet, ob es die Wissensdatenbank durchsucht, eine Berechnung durchführt oder direkt antwortet.

• FastAPI — ein sauberes REST-Backend (/ingest, /query, /agent/chat) mit automatisch generierter Swagger-Dokumentation.

• RAG — Dokumente werden in Chunks aufgeteilt, indiziert und anhand semantischer Relevanz abgerufen, bevor das LLM antwortet.

• MCP (Model Context Protocol) — dieselben Tools (RAG-Suche + Geschäftslogik) werden als MCP-Server bereitgestellt, sodass jeder MCP-kompatible Client (Claude Desktop, Claude Code, usw.) sie direkt nutzen kann, nicht nur diese API.

Architektur

                     ┌────────────────────┐
                     │   FastAPI Service   │
                     │  (app/main.py)      │
                     └─────────┬───────────┘
                               │
                     ┌─────────▼───────────┐
                     │   Agent Loop         │◄──── Groq API (tool use)
                     │  (app/agent.py)      │
                     └─────────┬───────────┘
                               │ calls
                 ┌─────────────┼──────────────┐
                 ▼                             ▼
        ┌────────────────┐           ┌──────────────────┐
        │  RAG Engine      │           │  Business Tools    │
        │  (app/rag.py)    │           │  (app/tools.py)     │
        └────────────────┘           └──────────────────┘
                 ▲                             ▲
                 └─────────────┬───────────────┘
                                │  same tools, exposed via
                     ┌──────────▼───────────┐
                     │   MCP Server           │
                     │  (app/mcp_server.py)   │
                     └────────────────────────┘

Einrichtung

python -m venv venv
source venv/bin/activate       # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env           # add your GROQ_API_KEY

Die API starten

uvicorn app.main:app --reload --port 8000

Öffne http://localhost:8000/docs für die interaktive Swagger-Dokumentation.

Probier es aus

# Pure retrieval, no LLM call
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "how many days of leave do I get?"}'

# Full agentic chat — LLM decides which tool(s) to call
curl -X POST http://localhost:8000/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "I joined in March and have taken 4 days off. How much leave do I have left, and what is the WFH policy?"}'

Der zweite Aufruf demonstriert Multi-Tool-Reasoning: Das Modell ruft rag_search für die Homeoffice-Richtlinie UND calculate_leave_balance für die Berechnung in einem einzigen Gespräch auf.

Als MCP-Server starten

python -m app.mcp_server

Richte einen beliebigen MCP-Host per stdio auf dieses Skript aus (z. B. füge es in Claude Desktops claude_desktop_config.json als benutzerdefinierten MCP-Server hinzu) und es wird rag_search, get_current_datetime und calculate_leave_balance als aufrufbare Tools bereitstellen.

Was du in einem Vorstellungsgespräch über dieses Projekt sagen kannst

• Warum standardmäßig TF-IDF statt Embeddings: Es sorgt dafür, dass die Demo ohne API-Keys und ohne externe Downloads läuft; die VectorStore-Klasse ist so geschrieben, dass das Austauschen gegen FAISS/Chroma + echte Embeddings eine Drop-in-Änderung ist, keine Neuimplementierung.

• Warum die Tools in einer Datei (tools.py) liegen und zweimal bereitgestellt werden (agent.py und mcp_server.py): eine einzige Quelle der Wahrheit, keine doppelte Logik zwischen HTTP-Pfad und MCP-Pfad.

• Die Agent-Schleife ist eine manuelle Implementierung des Tool-Use-Musters (kein Black-Box-Framework), sodass du jeden Schritt erklären kannst: Das Modell fordert ein Tool an → der Server führt es aus → das Ergebnis wird zurückgegeben → das Modell fährt fort oder antwortet.

Mögliche Erweiterungen (gute Antworten auf „Was würdest du verbessern?“)

• TF-IDF gegen echte Embeddings austauschen (OpenAI/Voyage/lokale sentence-transformers) + eine persistente Vektor-DB.

• Gesprächsspeicher über mehrere Turns hinweg hinzufügen (aktuell ist jeder /agent/chat-Aufruf zustandslos).

• Streaming-Antworten per Server-Sent Events hinzufügen.

• Authentifizierung hinzufügen (API-Key oder JWT), bevor du öffentlich bereitstellst.

• Mit Docker + docker-compose containerisieren für den Start mit einem einzigen Befehl.