scholar-rag-mcp

Status: Vorabversion (v0.1.0). Schnittstellen und Speicherlayout können sich in zukünftigen Versionen ändern.

scholar-rag-mcp ist ein veröffentlichbares MCP-Tool für eine Wissensdatenbank akademischer Paper. Weisen Sie es auf einen Ordner mit PDFs hin, und es verarbeitet jedes Paper durch eine echte Parsing-Pipeline (MinerU), normalisiert Metadaten, annotiert die Abschnittsstruktur, chunked und embeddet den Text und speichert alles in Qdrant – danach kann ein Agent (oder Sie) semantisch nach Chunks suchen, PubMed-artige Dokumentabfragen ausführen, Volltexte Abschnitt für Abschnitt lesen, einzelne Paper hinzufügen/entfernen und Wissensdatenbanken verwalten – alles über 11 MCP-Tools über stdio. Embedding, Annotation und Re-Ranking laufen über OpenAI-kompatible Modelldienste (vLLM) mit In-Process-Fallbacks.

Funktionen

• Echte Verarbeitungspipeline: MinerU-PDF-Parsing (python/cli/api-Backends) -> Metadatenextraktion (lokale Heuristiken, CrossRef, optional GROBID) -> Bereinigung -> Abschnittsannotation -> deterministisches Chunking (konfigurierbar 300/1500/100 Zeichen) -> Embedding.

• Schnelle Abfrage bei Skalierung: Embedding-First-Pass + Cross-Encoder-Re-Rank, optionale Metadatenfilter (doc_id, section, year, journal, ...), die innerhalb des Qdrant-Index ausgewertet werden. 100k-Chunk-p95-Abfragelatenz < 1s (siehe docs/perf-report.md).

• Asynchrone Jobs: create_kb/add_document sind Hintergrundjobs, deren Fortschritt über get_job abgefragt werden kann; sicher neu startbar (unterbrochene Jobs werden wiederhergestellt und beim erneuten Ausführen übersprungen).

• Kontextsicheres Lesen: paginiertes get_document_text mit harten Größenobergrenzen; erst die Gliederung, dann Seiten bei Bedarf.

• 11 MCP-Tools über stdio: list_kbs, create_kb, delete_kb (zweiphasig), add_document, remove_document, get_document, get_document_text, list_documents, search_documents, search_chunks, get_job.

• In sich geschlossener Speicher: Wissensdatenbanken liegen unter einem einzigen Datenverzeichnis (~/.scholar-rag); Qdrant wird entweder automatisch gestartet (einzelne Binärdatei, versionsgepinnt) oder mit einer externen Instanz verbunden.

Related MCP server: Athena

Installation

Erfordert pixi. Vom Repository-Root aus:

pixi install                      # installs the default environment

Das Projekt definiert drei pixi-Umgebungen, die jeweils einem anderen Zweck dienen:

Überprüfen Sie Ihre Umgebung mit dem eingebauten Doctor:

pixi run python scripts/doctor.py

Modellbereitstellung

Die Umgebung ('chat', 'embed' und 'rerank'-Clients) erwartet OpenAI-kompatible HTTP-Endpunkte. scripts/serve_models.sh startet drei vLLM-Instanzen für den Referenzmodellsatz:

# point *_MODEL at your local model directories, then:
bash scripts/serve_models.sh

SCHOLAR_RAG_CHAT_MODEL, SCHOLAR_RAG_EMBED_MODEL und SCHOLAR_RAG_RERANK_MODEL sind erforderlich – das Skript beendet sich mit einer Meldung, die sie auflistet, wenn eine nicht gesetzt ist. Jeder Wert muss ein absoluter Pfad zu einem lokalen HuggingFace-Modellverzeichnis sein; vLLM bedient jedes Modell unter einem Kurznamen, der dem Verzeichnis-Basename entspricht, daher müssen die Client-Einstellungen diesen Kurznamen verwenden (der bediente Name entspricht nicht mehr dem vollständigen Pfad). Ersetzen Sie die /path/to/...-Platzhalter in .env.example entsprechend. Ports (CHAT_PORT/EMBED_PORT/RERANK_PORT) und GPU-IDs bleiben optional mit funktionierenden Standardwerten.

Das Skript pinnt die genauen vLLM-Flags, die für diese Modelle verifiziert wurden (das Jina-Embed-Modell benötigt --trust-remote-code für seinen benutzerdefinierten Code; der Reranker läuft mit seiner Standardaufgabe, keine zusätzlichen Flags). Das Laden der Modelle dauert mehrere Minuten; das Skript pollt die Gesundheit, bis alle drei antworten.

Minimale Umgebung

Beginnen Sie mit .env.example und setzen Sie mindestens die Modell-Endpunkte (verwenden Sie die Kurznamen, die das Serve-Skript bereitstellt, gleich dem Basename jedes Modellverzeichnisses):

SCHOLAR_RAG_DATA_DIR=~/.scholar-rag
SCHOLAR_RAG_QDRANT_STORAGE_DIR=~/.local/share/scholar-rag/qdrant

SCHOLAR_RAG_CHAT_BASE_URL=http://127.0.0.1:8101/v1
SCHOLAR_RAG_CHAT_MODEL=Qwen3.5-0.8B

SCHOLAR_RAG_EMBED_BASE_URL=http://127.0.0.1:8102/v1
SCHOLAR_RAG_EMBED_MODEL=jina-embeddings-v5-text-small

SCHOLAR_RAG_RERANK_BASE_URL=http://127.0.0.1:8103/v1
SCHOLAR_RAG_RERANK_MODEL=jina-reranker-v3.5

Die Embed-Modell-Dimension wird bei der KB-Erstellung in kb_meta.json aufgezeichnet, sodass ein späterer Wechsel des Embedding-Modells eine neue KB erfordert.

MCP-Client-Einrichtung

Starten Sie den Server-Einstiegspunkt direkt, um sicherzustellen, dass er läuft:

pixi run scholar-rag-mcp

Claude (Claude Desktop / claude CLI)

{
  "mcpServers": {
    "scholar-rag-mcp": {
      "command": "pixi",
      "args": ["run", "scholar-rag-mcp"]
    }
  }
}

opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scholar-rag-mcp": {
      "type": "local",
      "command": ["pixi", "run", "scholar-rag-mcp"]
    }
  }
}

Tools

Datenlayout

<data_dir>/                     # SCHOLAR_RAG_DATA_DIR, default ~/.scholar-rag
├── kbs/<kb_name>/
│   ├── kb_meta.json            # dimension, chunk config, schema version
│   ├── catalog.sqlite3         # documents / authors / keywords / chunks + FTS5
│   └── documents/<doc_id>/     # source.pdf, full_text.md, sections.json
├── cache/parse/                # MinerU markdown cache, keyed by content hash
├── cache/resolver/             # annotation resolver cache, keyed by content hash
├── jobs.sqlite3                # async job history
└── bin/                        # auto-downloaded Qdrant binary (v1.12.5)

Qdrant-Speicher liegt außerhalb von data_dir unter QDRANT_STORAGE_DIR (Standard ~/.local/share/scholar-rag/qdrant) – er muss auf einem lokalen Dateisystem liegen, nicht auf einem 9p/Netzwerk-Mount.

Zweiphasige KB-Löschung

delete_kb löscht beim ersten Aufruf mit falschen Argumenten nie versehentlich:

1. Rufen Sie delete_kb(kb="...") auf – gibt KB-Statistiken plus ein 10-minütiges confirm_token zurück.

2. Rufen Sie delete_kb(kb="...", confirm_token="<token>") auf, um tatsächlich die Qdrant-Sammlung, das KB-Verzeichnis und dessen Job-Verlauf zu löschen.

Entwicklung

pixi run lint          # ruff check src tests
pixi run typecheck     # mypy src
pixi run test          # pytest (unit + integration, no e2e/perf)
pixi run -e mineru pytest tests/e2e/smoke.py -v -m e2e   # real end-to-end smoke
python tests/perf/bench_query.py                          # query latency benchmark (writes docs/perf-report.md)

Versionshinweise

Für bekannte Einschränkungen und Upgrade-Anleitung siehe docs/handoffs/release-notes-v0.1.0.md.

Bekannte Einschränkungen, die es wert sind, wiederholt zu werden:

• Qdrant ist auf v1.12.5 gepinnt – es ist die höchste Version, die auf glibc 2.35 läuft; Auto-Start lädt es beim ersten Gebrauch herunter. Auf glibc >= 2.38 können Sie eine neuere Version ausführen, aber das Datenformat ist nicht vorwärtskompatibel mit älteren KBs in dieser Version.

• MinerU läuft in seiner eigenen pixi-Umgebung, weil seine transformers-Version sich gegenseitig mit der vLLM-Version ausschließt. PDF-Parsing bevorzugt daher pixi run -e mineru.

• MinerU-Gewichte (~3,2 GB) werden beim ersten Parsen in ~/.cache/modelscope/ heruntergeladen.

• Metadaten-Titel-Heuristik: Titel werden nur lokal ausgewählt, wenn das MinerU-Markdown mit einer #/##-Überschrift beginnt, sodass ein führendes ## Abstract (usw.) als Titel fehlinterpretiert werden kann. Dies betrifft nur die lokale Heuristik-Metadatenstufe; die CrossRef-Stufe (verwendet, wenn eine DOI gefunden wird) korrigiert dies normalerweise.

• Tool-Dispatch: Unbekannte zusätzliche Argumente für ein Tool werden stillschweigend ignoriert statt abgelehnt.

• 9p-Speicherlimit: Qdrant-Speicher muss auf einem lokalen Dateisystem liegen.