Local Document MCP Server with Marker and ChromaDB

Dieses Projekt implementiert einen Python-MCP-Server für OpenCode. Er liest PDF-, Word- (.docx), PowerPoint- (.pptx) und EPUB-Dateien, die unter DOCS/ liegen, und schließt dabei stets DOCS/mdDB/ aus. Er konvertiert die Dokumente mit Marker nach Markdown, bewahrt Tabellen und Gleichungen als LaTeX, speichert die vollständigen Markdown-Dateien unter DOCS/mdDB/ und erstellt einen persistenten semantischen Index in ChromaDB.

Das Retrieval ist strukturbewusst. ChromaDB lokalisiert die für eine Abfrage relevantesten Chunks, aber der MCP-Server gibt keinen isolierten Chunk zurück. Er nutzt die Ergebnis-Metadaten, um die ursprüngliche Markdown-Datei zu öffnen und den vollständigen, durch Überschriften abgegrenzten Abschnitt zu rekonstruieren. Die Antwort enthält den umgebenden Text, Tabellen und Gleichungen sowie Dateipfade und Zeilenbereiche.

Datenfluss

flowchart TD
    A["DOCS: PDF, DOCX, PPTX, EPUB"] --> B["Marker 2"]
    B --> C["Complete Markdown + images"]
    C --> D["DOCS/mdDB"]
    C --> E["Structural chunks"]
    E --> F["Local ChromaDB"]
    G["OpenCode query"] --> F
    F --> H["Chunk metadata"]
    H --> D
    D --> I["Complete Markdown section"]
    I --> G

Jeder Chunk speichert mindestens source_path, markdown_path, section_title, section_path, section_start_line, section_end_line, chunk_start_line und chunk_end_line. Außerdem speichert er SHA-256-Hashes des Quelldokuments und der Markdown-Datei, um Änderungen zu erkennen.

Related MCP server: Personal Semantic Search MCP

Projektstruktur

current-project/
├── DOCS/
│   ├── article.pdf
│   ├── manual.docx
│   └── mdDB/
│       ├── article.md
│       ├── manual.md
│       └── .chroma/
├── .opencode/
│   └── MCP/
│       └── opencode-document-rag-mcp/
│           ├── src/doc_rag_mcp/
│           ├── tests/
│           ├── README.md
│           └── pyproject.toml
└── opencode.jsonc

Quelldokumente können direkt unter DOCS/ oder in einem beliebigen Unterverzeichnis außer DOCS/mdDB/ abgelegt werden. Ihre relative Verzeichnisstruktur bleibt in der Ausgabe erhalten. Beispielsweise erzeugt DOCS/manuals/instrument.pdf die Datei DOCS/mdDB/manuals/instrument.md. Extrahierte Bilder werden neben der Markdown-Datei unter instrument_assets/ gespeichert, und ihre Links werden als relative Pfade umgeschrieben. Der gesamte Verzeichnisbaum DOCS/mdDB/ ist von der Erkennung ausgeschlossen, damit der MCP-Server nicht seine eigene Ausgabe verarbeiten kann.

Voraussetzungen

Python 3.10–3.13 und uv sind erforderlich. Marker 2 benötigt ein Inferenz-Backend für OCR und Gleichungen. llama.cpp wird auf macOS oder reinen CPU-Systemen empfohlen. Systeme mit NVIDIA-GPUs können das über Surya konfigurierte VLLM-Backend verwenden.

Unter macOS:

brew install uv llama.cpp

Unter Linux installieren Sie uv und ein aktuelles llama-server-Binary von llama.cpp. Für NVIDIA-Systeme installieren Sie Docker und das NVIDIA Container Toolkit entsprechend den Anforderungen von Marker.

Installation

Entpacken Sie das Release-Archiv direkt in das Stammverzeichnis des aktuellen Projekts. Das Archiv enthält bereits die Verzeichnisstruktur .opencode/MCP/opencode-document-rag-mcp/:

cd /path/to/current-project
unzip opencode-document-rag-mcp-v1.1.2.zip -d .
uv sync --project .opencode/MCP/opencode-document-rag-mcp

Nach dem Entpacken ist der MCP-Server genau hier installiert:

.opencode/MCP/opencode-document-rag-mcp

Die erste Konvertierung und die erste Vektorisierung laden die erforderlichen Modelle herunter. Das ONNX-Embedding-Modell wird unter DOCS/mdDB/.chroma/.embedding_models/ gespeichert. Marker-Modelle verwenden den von Marker und Surya konfigurierten Cache. Der erste Vorgang kann einige Zeit dauern und mehrere Gigabyte verbrauchen. DOCX-, PPTX- und EPUB-Dokumente erfordern die Variante marker-pdf[full], die bereits in pyproject.toml enthalten ist.

OpenCode-Konfiguration

Kopieren Sie die Konfiguration aus opencode.example.jsonc in die Datei opencode.json oder opencode.jsonc im Projektstamm. Wenn der MCP-Server an anderer Stelle gespeichert ist, ändern Sie nur den Pfad, der auf --project folgt.

Mindestkonfiguration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "document-rag": {
      "type": "local",
      "command": [
        "uv",
        "run",
        "--project",
        ".opencode/MCP/opencode-document-rag-mcp",
        "doc-rag-mcp"
      ],
      "cwd": ".",
      "enabled": true,
      "timeout": 30000,
      "environment": {
        "DOC_RAG_PROJECT_ROOT": ".",
        "SURYA_INFERENCE_BACKEND": "llamacpp",
        "SURYA_INFERENCE_KEEP_ALIVE": "true"
      }
    }
  }
}

Die Einstellung cwd: "." löst alle Pfade relativ zum Stamm des in OpenCode geöffneten Projekts auf. Überprüfen Sie die Verbindung mit:

opencode mcp list

Die Datei AGENTS.example.md enthält eine optionale Richtlinie, die OpenCode anweist, diesen MCP-Server abzufragen, bevor Fragen zu den Dokumenten beantwortet werden. Sie können deren Inhalt in die Datei AGENTS.md des Projekts übernehmen.

MCP-Tools

Verwenden des MCP-Servers in OpenCode

Legen Sie Quelldokumente unter DOCS/ ab, aber niemals unter DOCS/mdDB/. Sie können dann beispielsweise folgende Anfragen verwenden:

Use document-rag to list the available documents.

Use ingest_all_documents to convert and index every source document under DOCS, excluding mdDB.

Search the documents for the definition of wave energy flux, preserving the related LaTeX equations and tables.

Search only manual_tecnico.pdf for the instrument's operating limits and cite the Markdown section and line range.

Read the Methods > Statistical analysis section from article.docx.

Erweitertes Retrieval

search_documents akzeptiert query, einen top_k-Wert von 1 bis 20 und einen optionalen document_name. Intern fordert es zusätzliche Ergebnisse von ChromaDB an, damit nicht mehrere Chunks aus demselben Abschnitt jede Ergebnisposition belegen. Anschließend entfernt es doppelte Abschnitte und gibt bis zu top_k verschiedene Abschnitte zurück.

Jedes Ergebnis enthält context, den vollständigen Abschnitt, der zum Zeitpunkt der Abfrage von der Festplatte gelesen wird. index_is_current gibt an, ob die Markdown-Datei noch denselben Hash hat wie zum Zeitpunkt der Indexierung. Wenn dieser Wert false ist, führen Sie ingest_document oder ingest_all_documents aus. Wenn sich das Quelldokument nicht geändert hat, indexiert das System das vorhandene Markdown neu, ohne Marker erneut auszuführen.

Konvertierung und Gleichungen

Marker erzeugt formatierte Tabellen und LaTeX-Gleichungen, die durch $$ begrenzt werden. Der Standardmodus ist balanced; er eignet sich, wenn die Wiedergabetreue von Tabellen, OCR und Mathematik Priorität hat. Auf CPU- oder Apple-Silicon-Systemen reduzieren Sie den Verarbeitungsaufwand mit:

"DOC_RAG_MARKER_MODE": "fast"

Für gescannte Dokumente oder unlesbaren Text:

"DOC_RAG_FORCE_OCR": "true"

Für Markers optionale hybride Korrektur über einen kompatiblen LLM-Dienst:

"DOC_RAG_USE_LLM": "true"

Die letzte Option erfordert Zugangsdaten und einen von Marker unterstützten Dienst. Für den normalen Betrieb des MCP-Servers ist sie nicht erforderlich.

Umgebungsvariablen

Sicherheit und Konsistenz

Der Server lehnt nicht unterstützte Dateiendungen, ..-Pfad-Traversierung, Quellen außerhalb von DOCS/, jede Quelle innerhalb von DOCS/mdDB/ und Markdown-Pfade außerhalb von DOCS/mdDB/ ab. Ein in ChromaDB gespeicherter Pfad wird nie verwendet, ohne erneut validiert zu werden. Markdown-Schreibvorgänge sind atomar, und der Index-Austausch ist auf das jeweilige Dokument beschränkt.

Wenn zwei Dateien im selben Verzeichnis denselben Basisnamen haben, etwa manual.pdf und manual.docx, würden beide manual.md erzeugen. Der Server erkennt diese Kollision und verlangt, dass eine der Quelldateien umbenannt wird, bevor geschrieben oder indexiert wird.

Tests

Die Unit-Tests laden weder Marker noch ChromaDB. Sie validieren die hierarchische Segmentierung, die Erhaltung von Tabellen und Gleichungen, die Abschnittserweiterung und den Pfadschutz:

PYTHONPATH=src python -m unittest discover -s tests -v

Sie können die Syntax des gesamten Quellbaums auch überprüfen mit:

python -m compileall -q src tests

Lizenzen

Dieses Projekt wird unter der MIT-Lizenz vertrieben. Marker verwendet für seinen Code die Apache-2.0-Lizenz und für seine Modellgewichte eine separate Lizenz. Prüfen Sie Markers Bedingungen, bevor Sie Marker in großem Umfang kommerziell einsetzen.