BDC Doc RAG

Das Dokumentations-RAG-MCP von bdc-assist

bdc_doc_mcp/config.py      env-driven embeddings/LLM/Chroma (replaces utils/__init__.set_emb_llm)
bdc_doc_mcp/ingest.py      .pkl/.md/.mdx/.txt/.pdf → embeddings → Chroma (replaces utils/chroma/utils.py)
bdc_doc_mcp/api.py         FastAPI: /health /search
bdc_doc_mcp/mcp_server.py  search_docs MCP tool for AI agents — self-contained, same search as the API
bdc_doc_mcp/preproc/       source-specific preprocessing pipeline
tests/                     self-checks + API / agent notebooks
data/                      preproc output (*.pkl), ingest input

Einrichtung

uv sync
cp .env.example .env    # then fill in keys/URLs

Quell-Repos

Nur für die Vorverarbeitung (--sources all) benötigt; der API/MCP-Server und das Aufnehmen vorhandener .pkl-Dateien funktionieren auch ohne sie. Klonen Sie neben dieses Repo (oder setzen Sie die Umgebungsvariablen darauf):

git clone https://github.com/stagecc/interim-bdc-website ../interim-bdc-website   # BDC_WEBSITE_DIR
git clone https://github.com/stagecc/bdc-gitbook ../bdc-gitbook                   # BDC_GITBOOK_DIR

Modelle

Für die Vervollständigung verwenden Sie die OpenAI-API auf Azure (standardmäßig gpt-4o-mini)

Für Einbettungen verwenden Sie Ollama auf Sterling (Verbindung über RENCI-VPN)

kubectl -n ner port-forward svc/ollama 11434:11434

Oder mit lokalem Ollama und dem Modell groonga/bge-m3-Q4_K_M-GGUF.

Related MCP server: okfy

Aufnahme

Vollständiger Neuaufbau aus jeder Quelle (benötigt die beiden geklonten Quell-Repos – siehe Einrichtung; schreibt data/*.pkl und lädt sie dann):

uv run python -m bdc_doc_mcp.preproc.pipeline --sources all --ingest --reset

Einzelne Dateien oder Verzeichnisse:

uv run python -m bdc_doc_mcp.ingest ./data/docs.pkl --doc-type docs   # BDC_Chatbot preproc .pkl
uv run python -m bdc_doc_mcp.ingest ../interim-bdc-website/src/pages --doc-type page --reset

Einbettungsmodelle sind innerhalb einer Sammlung nicht austauschbar – bge-m3 hat 1024 Dimensionen, text-embedding-3-small 1536. Ein Modellwechsel bedeutet --reset und eine vollständige Neuaufnahme.

API

uv run uvicorn bdc_doc_mcp.api:app --port 8000     # docs at /docs

mode ist embedding (Standard; semantische Ähnlichkeit, Punktzahl = Distanz, niedriger ist besser) oder keyword (unscharfer wörtlicher Wortabgleich – ignoriert Groß-/Kleinschreibung und Satzzeichen und toleriert kleine Tippfehler, sodass picsure "PIC-SURE" findet; Punktzahl = Anzahl der Vorkommen, höher ist besser – für exakte Namen/Akronyme verwenden). doc_type ist eine CSV der zu durchsuchenden Typen (z. B. page,faq). Wenn nicht angegeben, werden nur docs, page, faq und video durchsucht – nennen Sie fellow, update oder event explizit, um sie zu durchsuchen. date_from/date_to (YYYY-MM-DD, inklusive) filtern nach Datum; nur Ereignis- und Update-Dokumente haben ein Datum, daher schränkt ein Datumsfilter implizit auf diese Typen ein.

Der Dienst ist von Natur aus nur für die Suche gedacht; die Aufnahme erfolgt offline über die CLI (siehe Aufnahme) und das Beantworten ist Aufgabe des Aufrufers – ein Agent bringt sein eigenes LLM mit.

MCP

uv run python -m bdc_doc_mcp.mcp_server           # stdio
uv run python -m bdc_doc_mcp.mcp_server --http    # streamable HTTP, port MCP_PORT (default 8001)

Stellt ein Tool bereit, search_docs – dieselbe Suche wie die API, fragt aber Chroma direkt ab, sodass der API-Dienst nicht laufen muss. Benötigt eine aufgenommene .chroma_db + Einbettungen.

Stdio-Clients (Claude Desktop/Code, Cursor) starten den Server selbst – registrieren Sie ihn:

{"mcpServers": {"bdc-doc-mcp": {
  "command": "uv",
  "args": ["--directory", "/path/to/bdc-doc-mcp", "run", "python", "-m", "bdc_doc_mcp.mcp_server"]
}}}

Netzwerk-Clients: Führen Sie --http aus und richten Sie sie stattdessen auf http://host:8001/mcp.

Smoke-Test: uv run python tests/test_mcp.py

Vorverarbeitung

bdc_doc_mcp/preproc/ ist die portierte BDC_Chatbot-Pipeline:

--no-contextualize überspringt den LLM-Aufruf pro Chunk (viel schneller, schwächere Abfrage). Quellpfade stammen aus BDC_WEBSITE_DIR / BDC_GITBOOK_DIR.

Tests

uv run python tests/test_ingest.py                             # batching + chunk-id logic, no network
uv run python tests/test_keyword.py                            # keyword ranking, pure function, no DB or API
uv run python tests/test_mcp.py                                # starts the server over stdio and exercises its tools; needs .chroma_db + embeddings

Notebooks (jedes startet die API auf einem freien Port und fährt sie am Ende herunter; beide benötigen eine aufgenommene .chroma_db):

• tests/api_test.ipynb — einfacher API-Durchlauf: /health, /search, doc_type-Filter. Benötigt nur die lokalen Einbettungen.

• tests/agent_test.ipynb — ein Tool-aufrufender Agent (deepagents): das konfigurierte LLM erhält search_docs als LangChain-Tool und entscheidet, wann es aufgerufen wird. Benötigt außerdem den erreichbaren Vervollständigungsanbieter.