Modular RAG MCP Server

Lokal priorisierter, plugbarer und beobachtbarer RAG-Infrastruktur für Wissensabfragen und Observability im Bewerbungsprozess – für interne Berater des DIY-Studienberatungsteams

Der Modular RAG MCP Server ist ein lokal priorisierter, plugbarer und beobachtbarer Retrieval-Augmented-Generation-Dienst (RAG). Das System stellt KI-Clients über das Model Context Protocol (MCP) Wissensabfragen bereit und verwaltet über ein Streamlit-Dashboard Dokumente, Ingestionsaufgaben, Abfrageketten und Bewertungsergebnisse.

Dieses Projekt entstand aus einem realen Kollaborationsszenario während des Studiums: Das DIY-Studienberatungsteam der Fakultät unterstützte Kommilitonen bei Bewerbungen an ausländischen Hochschulen. Das System löst das Problem, dass Berater wiederholt zwischen Hochschulanforderungen, Bewerbungsunterlagen, Prozessstandards und historischen Erfahrungen suchen mussten, ohne die Quellen nachvollziehen zu können. Das System ist derzeit intern im Team bereitgestellt; das öffentliche Repository enthält nur anonymisierte synthetische Beispieldaten, keine echten Studierendendaten, internen Dokumente oder Betriebsdaten.

Die Beispieldaten im Repository sollten ausschließlich anonymisierte synthetische Daten verwenden; die Systemausgabe dient als von Beratern zu prüfende Retrieval-Grundlage, ersetzt nicht die Beraterentscheidung und stellt keine Hochschul-, Visum- oder Rechtsberatung dar.

Inhaltsverzeichnis

• Geschäftlicher Hintergrund

• Systemgrenzen

• Kernfunktionen

• Systemarchitektur

• Daten- und Speicherkonsistenz

• MCP-Tools

• Dashboard

• Schnellstart

• Qualitätssicherung

• Sicherheits- und Betriebsbeschränkungen

• Aktueller Stand und Entwicklungsplan

Related MCP server: mcp-rag-assistant

Geschäftlicher Hintergrund

DIY-Studienberater müssen bei der Bearbeitung von Bewerbungen gleichzeitig auf offizielle Hochschulwebseiten, Projektbroschüren, Materialvorlagen, interne Arbeitslisten und historische Fallbeispiele zugreifen. Die Rohmaterialien sind in der Regel als PDFs verstreut gespeichert und weisen folgende Probleme auf:

• Dieselbe Anforderung kann in mehreren Dokumenten mit unterschiedlichen Formulierungen auftreten; reine Stichwortsuche führt leicht zu unvollständigem Retrieval.

• Fachbegriffe wie Hochschule, Studiengang, Abschluss und Bewerbungssemester müssen exakt übereinstimmen; reine Vektor-Retrieval führt leicht zu falschen Treffern.

• Tabellen, Flussdiagramme und Screenshots in PDFs enthalten wichtige Informationen; reine Textanalyse verliert Kontext.

• Berater müssen wissen, aus welchem Dokument und welchem Abschnitt eine Antwort stammt, und beurteilen können, ob das Dokument noch gültig ist.

• Nach Dokumentaktualisierungen müssen Vektor-Datenbank, BM25-Index, Bildindex und Ingestionsprotokolle konsistent bleiben.

• Die Retrieval-Qualität muss durch stabile Test-Sets regressiv überprüft werden, nicht durch subjektive Erfahrung.

Das System richtet sich an interne Berater des Teams. Typische Arbeitsabläufe umfassen:

1. Hochschulprojektmaterialien, interne Checklisten und anonymisierte Fallbeispiele in eine bestimmte Collection aufnehmen.

2. Über einen MCP-Client oder die Befehlszeile natürliche Sprachfragen stellen.

3. Das System führt Dense + BM25 Dual-Retrieval, RRF-Fusion und optionales Reranking durch.

4. Rückgabe von Textabschnitten mit Quellenangaben sowie multimodalen Inhaltsblöcken bei Bildtreffern.

5. Über das Dashboard Ingestionsprozess, Retrieval-Ergebnisse, Latenz und Bewertungsmetriken prüfen.

Systemgrenzen

Dieses Projekt ist für Wissensaufnahme, Retrieval, Zitierung, Bewertung und Beobachtung der Ablaufkette verantwortlich, nicht für:

• Ersetzen der Beraterentscheidung bei Hochschulwahl, Zulassungswahrscheinlichkeit oder Visumfragen.

• Automatisches Einreichen von Bewerbungen, Senden von E-Mails oder Ändern von Studierendenmaterialien.

• Bereitstellung von Studierendenkonten, CRM, Zahlungs- oder Bewerbungsfortschrittsverwaltung.

• Automatisches Abrufen und Behaupten aktueller Hochschulpolitik.

• Generierung deterministischer Geschäftsschlussfolgerungen ohne Quellenbasis.

Kernfunktionen

Systemarchitektur

flowchart LR
    A["PDF 业务资料"] --> B["Ingestion Pipeline"]
    B --> C["Chroma 向量库"]
    B --> D["BM25 索引"]
    B --> E["SQLite 摄取历史"]
    B --> F["图片文件与索引"]
    G["顾问 / MCP Client"] --> H["MCP Server"]
    H --> I["Query Processor"]
    I --> J["Dense Retrieval"]
    I --> K["Sparse Retrieval"]
    J --> L["RRF Fusion"]
    K --> L
    L --> M["Optional Rerank"]
    M --> N["Response + Citations + Images"]
    B --> O["Ingestion Trace"]
    I --> P["Query Trace"]
    O --> Q["Streamlit Dashboard"]
    P --> Q

Kernverzeichnisse:

src/
├── core/            # 数据契约、查询编排、响应构建、Trace、配置
├── ingestion/       # Chunk、Transform、Embedding、Storage 与 Pipeline
├── libs/            # LLM/Embedding/Loader/Reranker/Splitter/VectorStore 抽象
├── mcp_server/      # MCP 协议处理、Server 与 Tools
└── observability/   # Dashboard、评估与结构化日志

scripts/             # ingest、query、evaluate、Dashboard 启动入口
config/              # Provider、检索、重排、评估与摄取配置
tests/               # Unit、Integration、E2E 测试与固定样例

Detaillierte Schnittstellen, Datenflüsse und Modulbeschränkungen finden Sie in DEV_SPEC.md.

Daten- und Speicherkonsistenz

Eine Ingestion koordiniert mehrere Speicher-Backends:

Die Dateiintegritätsprüfung verwendet SHA256, um bereits erfolgreich verarbeitete und unveränderte Dateien zu überspringen. Chunk-IDs werden stabil aus Quelle, Position und Inhalt generiert; wiederholte Ingestion verwendet idempotentes Upsert. Der DocumentManager koordiniert das Löschen über Chroma, BM25, Ingestionshistorie und Bildindex und gibt Informationen zu Teilfehlern zurück.

MCP-Tools

Der aktuelle Server stellt vier Tools bereit. Die ersten drei allgemeinen Tools bleiben unverändert; das vierte ist eine Anpassungsschicht für das Studienberatungsgeschäft:

MCP verwendet den Stdio-Transport. stdout ist ausschließlich für JSON-RPC reserviert; Laufzeitprotokolle werden nach stderr geschrieben, um Protokollrahmen nicht zu beschädigen.

search_admissions_knowledge fragt standardmäßig admissions_knowledge ab und begrenzt immer auf business_domain=study_abroad_admissions. Es unterstützt präzise Filterung nach Land, Hochschule, Programm, Abschlussniveau, Bewerbungssemester, Bewerbungsrunde und Quellentyp; standardmäßig werden Dokumente ausgeschlossen, deren valid_until vor dem Geschäftsdatum der Abfrage liegt. Dokumente ohne oder mit nicht parsebarem Gültigkeitsdatum werden als needs_review markiert und nicht stillschweigend als aktuelle Regeln behandelt. Das Geschäftstool ist nur eine Parameter- und Antwortanpassungsschicht; die zugrunde liegende Ausführung umfasst weiterhin Dense + BM25, RRF, Cross-Encoder/LLM-Rerank, Zitierung und multimodale Rückgabe.

Dashboard

Das Dashboard behält die Struktur mit sechs Seiten bei:

1. Overview: Komponentenkonfiguration, Datenbestand, Betriebsstatus sowie Statistiken zu aktuellen, zu überprüfenden und abgelaufenen Studienmaterialien.

2. Data Browser: Dokumente, Chunks, Metadaten und zugehörige Bilder; unterstützt kombinierte Filterung nach Land, Hochschule, Programm, Abschluss, Bewerbungssemester, Bewerbungsrunde, Quellentyp und Gültigkeitsstatus.

3. Ingestion Manager: Ingestion auslösen, Fortschritt anzeigen und Dokumente koordiniert löschen.

4. Ingestion Traces: Ingestionsphasen, Verarbeitungsmethoden, Latenz und Ausnahmen.

5. Query Traces: Dense/Sparse-Retrieval, Fusion, Reranking und Endergebnisse.

6. Evaluation Panel: Bewertungen ausführen und Metriken sowie historische Ergebnisse anzeigen.

Schnellstart

1. Umgebungsvorbereitung

Erfordert Python 3.10–3.12.

git clone https://github.com/xiaoxinbuxingyeyuan/MODULAR-RAG-MCP-SERVER.git
cd MODULAR-RAG-MCP-SERVER
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

macOS / Linux:

source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

pyproject.toml hat die direkt verwendeten Abhängigkeitsversionen für die aktuelle Verifizierung dieses Projekts festgelegt. Beim Upgrade von MCP, Ragas, LangChain oder Speicherkomponenten sollte separat aktualisiert und die Offline- und Online-Regression erneut ausgeführt werden.

2. Provider konfigurieren

Bearbeiten Sie config/settings.yaml, um LLM, Embedding, Vision-LLM, VectorStore, Reranker und Bewertungs-Backend zu konfigurieren. API-Schlüssel sollten über sichere Konfigurationsinjektion bereitgestellt und nicht in das Repository committet werden.

Wenn kein lokaler Modellservice verfügbar ist, können nicht notwendige LLM-Erweiterungen und Reranking deaktiviert werden, um die Basiskette ohne externe Dienste zu verifizieren.

3. Dokumente aufnehmen

python scripts/ingest.py \
  --path tests/fixtures/sample_documents/simple.pdf \
  --collection admissions_knowledge

Verzeichnisaufnahme:

python scripts/ingest.py \
  --path tests/fixtures/sample_documents/ \
  --collection admissions_knowledge

Aufnahme mit Studien-Manifest:

python scripts/ingest.py \
  --path examples/documents/synthetic/ \
  --collection admissions_knowledge \
  --manifest examples/admissions_manifest.example.jsonl

Das Manifest verwendet UTF-8-JSONL, jede Zeile entspricht einem PDF. Relative document_path werden relativ zum Manifest-Verzeichnis aufgelöst; Pflichtfelder sind document_path, title, country und source_type. Optionale Felder umfassen institution, program, degree_level, intake, application_round, published_at, valid_until, language, tags und access_scope. Ein vollständiges Beispiel finden Sie in examples/admissions_manifest.example.jsonl.

Nach Übergabe eines Manifests muss jedes aufzunehmende PDF eine eindeutige Übereinstimmung haben. Unbekannte Felder, doppelte Pfade, ungültige Enumerationen und invertierte Daten führen vor dem Schreiben in den Speicher zu einem Fehler. Manifest-Metadaten werden vom Dokument auf Chunk- und Chroma-Einträge übertragen; LLM-Titel und -Tags auf Chunk-Ebene überschreiben nicht document_title und business_tags.

Die Inkrementelle Prüfung vergleicht sowohl den PDF-SHA256 als auch den SHA256 der normalisierten Geschäftsmetadaten: Nur wenn beide unverändert sind, wird übersprungen; eine reine Manifest-Änderung löst automatisch eine erneute Aufnahme aus und überschreibt die Metadaten der stabilen Chunk-IDs. Bei PDF-Inhaltsänderungen schreibt das System zuerst die neue Version und bereinigt dann Chroma-Chunks, Bilder und alte Ingestionsprotokolle anhand der alten doc_hash; BM25 ersetzt Postings über das stabile Quellenpfad-Präfix. Alte SQLite-Ingestionshistorien erhalten automatisch das Feld metadata_hash, ohne manuelle Migration. --force kann weiterhin für expliziten Wiederaufbau verwendet werden, ist aber nicht mehr erforderlich, um Manifest-Updates anzuwenden.

Das Repository enthält drei vollständig fiktive, personenbezogene Datenfreie Geschäftsbeispiele, die aktuelle Materialien, fehlende Gültigkeitsdaten und abgelaufene Materialien abdecken; der Kursleitfaden enthält ein Flussdiagramm zur Verifizierung der multimodalen Kette. Zum Neugenerieren der Beispiel-PDFs führen Sie aus:

python examples/generate_synthetic_admissions_pdfs.py

4. Befehlszeilenabfrage

python scripts/query.py \
  --query "申请材料需要包含哪些证明？" \
  --collection admissions_knowledge \
  --verbose

5. Dashboard starten

python scripts/start_dashboard.py

Standardadresse ist http://localhost:8501.

6. MCP-Server starten

python -m src.mcp_server.server

Die Konfigurationsformate verschiedener MCP-Clients unterscheiden sich geringfügig; die Kernprozesskonfiguration lautet:

{
  "command": "<project>/.venv/Scripts/python.exe",
  "args": ["-m", "src.mcp_server.server"],
  "cwd": "<project>"
}

Unter macOS / Linux ersetzen Sie den Python-Pfad durch <project>/.venv/bin/python.

7. Bewertung ausführen

python scripts/evaluate.py \
  --test-set examples/admissions_golden_test_set.json \
  --collection admissions_knowledge

Ohne externe Retrieval-Umgebung können Sie ausführen:

python scripts/evaluate.py --no-search

Qualitätssicherung

Das Projekt verwendet eine dreistufige Teststruktur:

• Unit: Datenverträge, Algorithmen, Factory, Tool-Handler und Speicheradapter.

• Integration: Kombinationsverhalten von Ingestion, Hybrid-Retrieval, MCP, Provider und Trace.

• E2E: CLI-Ingestion, MCP-Client, Dashboard-Smoke und Recall-Regression.

python -m pytest tests/unit
python -m pytest tests/integration
python -m pytest tests/e2e
python -m pytest

Die obigen Befehle überspringen standardmäßig alle als online markierten Testfälle und rufen keine echten Provider auf. Wenn echte Azure-, OpenAI- oder Ollama-Dienste benötigt werden, führen Sie in einer Umgebung mit entsprechenden Anmeldeinformationen und Diensten explizit aus:

python -m pytest --run-online -m online

OpenAI-kompatible Gateways können über OPENAI_API_KEY, OPENAI_BASE_URL und OPENAI_MODEL injiziert werden, ohne die Repository-Konfiguration zu ändern oder Anmeldeinformationen zu committen. Nicht konfigurierte Provider-Testfälle sollten übersprungen bleiben.

Um nur zu prüfen, ob Online-Testfälle korrekt klassifiziert sind, ohne Aufrufe auszulösen, führen Sie python -m pytest --collect-only -m online aus. Offline- und Online-Ergebnisse sollten getrennt aufgezeichnet werden; --run-online hebt nur die Überspringungseinschränkung auf und ersetzt nicht die Provider-Konfiguration.

Die Bewertungsebene unterstützt weiterhin Custom Evaluator und Ragas. Das geschäftliche Golden Test Set erfasst zusätzlich kombinierte Filter, Geschäftsdaten, Ablaufrichtlinien, erwartete Quellen und Referenzantworten; die Offline-Geschäftsabnahme prüft sowohl diese Felder als auch das Zeitverhalten des MCP-Geschäftsadapters. Die allgemeine Bewertungsschnittstelle und das ursprüngliche Golden Test Set wurden nicht geändert.

Sicherheits- und Betriebsbeschränkungen

• Standardmäßig werden lokaler Stdio und lokaler Speicher verwendet; keine Netzwerkports werden geöffnet.

• API-Schlüssel und persönliche Studierendendaten werden nicht in Protokollen, Traces, Test-Fixtures oder Git-Verlauf gespeichert.

• Geschäftsmaterialien müssen vor der Aufnahme in die Wissensdatenbank autorisiert und datenschutzrechtlich anonymisiert werden.

• Retrieval-Ergebnisse müssen Quellenangaben enthalten; wenn keine zuverlässige Grundlage gefunden wird, sollten leere Ergebnisse oder Hinweise auf manuelle Prüfung zurückgegeben werden.

• Hochschulanforderungen sind zeitabhängig; das Geschäftstool schließt standardmäßig Dokumente aus, deren valid_until überschritten ist, und weist explizit auf fehlende Gültigkeitsdaten hin, aber Berater müssen dennoch offizielle Quellen überprüfen.

• Die aktuelle Architektur ist ein Einzelbenutzer-Lokaldienst ohne Authentifizierung, Berechtigungsisolierung oder Mandantenfähigkeit.

Aktueller Stand und Entwicklungsplan

Der bestehende main-Zweig verfügt bereits über ein vollständiges allgemeines RAG-, MCP-, Dashboard-, Trace- und Bewertungsgerüst. Die Studienbereichsanpassung wird inkrementell vorangetrieben und darf bestehende technische Fähigkeiten nicht entfernen oder vereinfachen.

Jede Phase muss die vollständige PDF-Ingestion-Kette, Dense + BM25, RRF, Rerank, Multimodal, Mehrfachspeicher-Koordination, Inkrementelle und Löschung, die ursprünglichen drei MCP-Tools, das Sechs-Seiten-Dashboard, Dual-Ketten-Traces, Custom + Ragas, dreistufige Tests und alle plugbaren Schnittstellen beibehalten.