CorpusGate

Ein LLM-fähiges privates Dokument-Gateway auf Basis von MarkItDown und MCP.

Konvertieren, indexieren und abrufen Sie private Dokumente für KI-Tools – ohne den Inhalt der Dokumente an Drittanbieter zu senden.

Ein **CorpusGate ist ein allgemein nutzbarer, selbst gehosteter Dokument-MCP-Server für Einzelpersonen und Teams, die einen kontrollierten Zugriff von KI-Werkzeugen auf Dokumente in ihrer eigenen Infrastruktur benötigen. MarkItDown konvertiert unterstützte Dateien in wiederverwendbares Markdown. Das Gateway zerlegt dieses Markdown in Chunks und indexiert sie; die MCP-Schnittstelle gibt daraufhin nur die relevanten, mit Quellenangabe versehenen Chunks zurück – innerhalb serverseitig erzwungener Budgets.

Beim Selbsthosting bleiben Quelldokumente, generiertes Markdown, Abfragen, Metadaten und Indizes unter der Kontrolle des Betreibers. Die Token-Reduktion ergibt sich aus begrenztem Retrieval und der Chunk-Auswahl – nicht allein durch MarkItDown. Dieses Projekt ist kein Chatbot, kein LLM-Antwortgenerator, kein Produkt zur Vertragsanalyse, keine SaaS-Plattform und kein benutzerorientiertes Dokument-Panel.

Funktionen

• Konvertierung von PDF, DOCX, PPTX, XLSX, TXT, Markdown und HTML über Microsoft MarkItDown.

• Dauerhafter Markdown-Cache, tokenbewusste, überschriftenbewahrende Chunks und SHA-256-Deduplizierung.

• SQLite-FTS5/BM25-Suche in der schlanken Standardinstallation.

• Optionale, rein CPU-basierte multilinguale semantische Suche und RRF-Hybrid-Retrieval mit lokalen Embeddings.

• Begrenzte MCP-Antworten mit Quellen-/Positionsmetadaten, Cursoren, Deduplikation und Nachbar-Limits.

• REST-API-Key- und MCP-Bearer-Authentifizierung, sichere UUID-Speicherung, Pfad-/Symlink-Schutz, Rate-Limits und strukturierte, inhaltsichere Protokolle.

• Gehärtetes Docker-Compose-Deployment für AMD64/ARM64, Oracle Cloud, Tailscale oder Caddy-HTTPS.

• Setup-Helfer, operative doctor/scan/reindex/backup-Befehle, versioniertes SQLite-Schema und CI.

Related MCP server: rag-retriever-mcp

Funktionsweise

REST upload or read-only inbox scan
        │
        ├─ type, signature, size, path, and free-space validation
        ├─ UUID storage + SHA-256 ── unchanged? ── reuse cached/indexed record
        │
        └─ MarkItDown ──> persistent Markdown ──> token-aware chunks
                                                   │
                              ┌────────────────────┴────────────────────┐
                              │                                         │
                    SQLite FTS5 / BM25                      optional local embeddings
                              │                                  + private Qdrant
                              └────────────────────┬────────────────────┘
                                                   │
                               ranking → dedup → token/char budget → MCP

Der Code hält die Verträge für Parser, Speicherung, Repository, Chunking, Embedding, Vektor-Store und Retrieval hinter Schnittstellen, ohne das Einzel-Server-Produkt in ein verteiltes System zu verwandeln. Dokumente bleiben die primäre Datenquelle; Markdown- und Vektorindizes können neu aufgebaut werden.

Unterstützte Formate

Verschlüsselte, beschädigte, nur-zu-Bilddateien gezählt werden gescannt, oder Umkommittel? Besser: Verschlüsselte, beschädigte, nur gescannte Bilddateien oder vom Konverter nicht unterstützte Dateien werden sicher abgewiesen, ohne andere Dokumente zupeilen.

To be precise: "Verschlüsselte, beschädigte, ausschließlich gescannte-oder, Konverter nicht unterstützte Dateien werden sicher abgewiesen, ohne andere Dokumente zu stoppen."

Schnellstart

Voraussetzungen: Docker Engine mit Compose v2 und OpenSSL. Python auf dem Host ist nicht erforderlich.

git clone https://github.com/mustafa0zdemir/corpusgate.git
cd corpusgate
./corpusgate init
./corpusgate up
curl --fail http://127.0.0.1:8000/health
./corpusgate doctor

./corpusgate init erstellt die persistent/inbox-Ordner, kopiert .env.example nur dann, Wenn .env noch nicht existiert, generiert separate zufällige REST-/MCP-Zugangsdaten, ohne sie auszugeben, prüft Docker/Compose und den ausgewählten Port und validiert Compose. Eine bereits vorhandene .env wird niemals überschrieben.

Der äquivalente manuelle Ablauf: .env.example nach .env kopieren, beide Platzhalter für Zugangsdaten durch unterschiedliche openssl rand -hex 32-Werte ersetzen, documents/ anlegen und docker compose up -d aufrufen. Commiten Sie niemals die .env.

Auch das optionale lokale semantische/Hybrid-Retrieval ist nach der Initialisierung nur noch ein einziger Vorgang:

./corpusgate init --semantic
./corpusgate up --semantic

Der erste semantische Start lädt das Modell in einem persistenten Cache herunter und startet das Gateway anschließend offline mit Qdrant im internen Docker-Netzwerk. Spätere Starts nutzen sowohl das Modell- als auch die Vektor-Volumes erneut. Die rein lexikalische Installation installiert und startet keine der semantischen Komponenten.

Dokumente hinzufügen

Der einfachste Operator-Workflow mit dem schreibgeschützten Host-Inbox-Ordner:

cp examples/documents/* documents/
./corpusgate scan
./corpusgate list-documents

Der Scan überspringt versteckte-, System- und Tempor„dateien, nicht unterstützte Typen, Verzeichnisse und Symlinks. Eingabedateien verbleiben in documents/; private UUID-Kopien werden im persistenten Quell-Volume gespeichert. Einen vollständigen Durchlauf von lexikalisch über semantisch/Hybrid bis zur MCP bietet die synthetische Demo.

Für einen Workflow mit einer Datei, den KI-Tools aufrufen können, ohne Dateibytes in den Modellkontext zu legen, Streamen Sie die lokale Datei direkt an die laufende REST-API (erfordert curl):

./corpusgate upload /absolute/path/to/document.pdf

Der Befehl liest den REST-Schlüssel aus CORPUSGATE_CLIENT_API_KEY, CORPUSGATE_API_KEY oder der benachbarten .env, gibt ihn nie aus, lehnt Weiterleitungen und unsicheres Remote-HTTP ab und liefert ausschließlich die Upload-Metadaten der API. Für einen entfernten privaten Server übergeben Sie --url https://YOUR-NODE.YOUR-TAILNET.ts.net.

REST-Uploads für Anwendungen:

export CORPUSGATE_CLIENT_API_KEY='value-from-your-env'
curl --fail -X POST http://127.0.0.1:8000/api/v1/documents \
  -H "X-API-Key: ${CORPUSGATE_CLIENT_API_KEY}" \
  -F 'file=@examples/documents/private-network-guide.md'

REST stellt unter /api/v1/documents außerdem paginierte Metadaten, Markdown, Chunks, lexikalische Suche und Löschvorgänge bereit. Die interaktive OpenAPI-Dokumentation liebt unter /docs; geschützte Operationen erfordern weiterhin X-API-Key.

Verbindung eines MCP-Clients

Die Remote- Endpunkt ist https://YOUR_PRIVATE_OR_PUBLIC_HOST/mcp, und jede MCP-Anfrage benötigt:

Authorization: Bearer YOUR_MCP_TOKEN

Verwenden Sie Tailscale Serve als empfohlene private Route. Caddy HTTPS ist die öffentliche Alternative; Gateway-Port bleibt in beiden Fällen an den Host-Loopback gebunden. Die verifizierte Feldzuordnung, den Inspector-Befehl, Tailscale/HTTPS-Beispiele und die Fehlerbehebung finden Sie in der MCP-Verbindungsanleitung. Übernehmen Sie keinen ungeprüften Client-spezifischen JSON-Wrapper und speichern Sie kein Token in diesel-Quellcodeverwaltung.

MCP-Werkzeuge

Retrieval-Elemente enthalten durchgängig document_id, document_name, chunk_id, heading, position, Relevanz-/Ranking-Felder, begrenzte content, content_length sowie Metadaten zum RetrievalModus. Leere Suchen liefert eine leere items-Liste mit den angewandten Budgetsn zurück, Metriken und keinen Cursor. Nicht unterstützte Modi, ungültige Filter, Dokument-IDs oder überhöhte Werte erzeugen kontrollierte Tool-Fehler. Upload und Löschen bleiben REST-only.

Empfohlener Ablauf:

AI tool → search_document(query, top_k=3, max_tokens=600)
        → ranked chunks + source positions + actual retrieval mode
        → optional bounded get_document_section

Lexikalische, semantische und Hybrid-Suche

• lexical ist der Standardmodus für den Produktivbetrieb: die in SQLite integrierte FTS5 mit überschriftgewichteter BM25 erhaelt indentifyders exakte Bezeichner scaffold – ohne oder einem weiteren Dienst.

• semantic bettet Abfragen und Chunks lokal mithilfe des konfigurierbaren multilingualen CPU-Modells ein; In Dez.

• hybrid führt die unabhängigen lexikalischen semantischen Rankings rüber eine Reciprocal Rank Fusion zusammen; Duplikate werden nur einmal zurückgegebenpunkt, exakte lexikalische Treffer bleiben erhalten.

• lexical_fallback wird gemeldet, wenn semantisch oder Hybrid angefordert wurde, aber das optionale lokale Modell, der Vektor-Store oder Index nicht verfügbar ist und der Fallback-Aktivierung.

Das Standardmodell ist die Apache-2.0-lizenzierte Sprachrepräsentation sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2, ein 384-dimensionales multilinguales Modell, das über FastEmbed/ONNX auf der CPU pupet. Modellaustausch, Offline-Übertrag, Reindex-Regeln, Messungen Beimessungen und Speichereinstellungen für Oracle finden Sie im Dokument Semantische Suche.

Token-Optimierung

MarkItDown macht unterschiedlichste Dateien einheitlich parsebar, garantiert für sich genommen aber nicht geringere Tokenmengen. Das Gateway reduziert den zurückgegebenen Kontext, indem es die Konvertierung nur einmal cachet, Chunks rankt, Duplikate ausgrenzt, top_k, max_chars und ein geschätztes max_tokens durchsetzt, Nachbarchunks begrenzt und lange Ergebnislisten paginiert. Es bietet kein Standard-MCP-Werkzeug, das ein ganzes Dokument oder die Rohdatei zurückgibt.

Tokenzahlen sind eine lokale deterministische Schätzung, kein anbieter- oder abrechnugsspezifischer Tokenizer. Die reproduzierbare synthetische Messung und ihren exakten Umfang finden Sie im Retrieval-Report; es wird kein universelier Sparprozentsatz behauptet.

Sicherheit und Privatsphäre

• Keine Telemetrie, keine Dokumenttexte, keine Abfragetexte, keine Cloud-Embedding-API und kein benötigter LLM-Anbieter.

• Quelldateien erhalten UUID-Pfade; Dateinamen-Traversal, absolute Pfade, Symlink-Ausbrüche, versteckte / -temporäre Dateien, MIME-/Signatur-Abweichungen, Archiv-Entpacken, Upload-Größe und wenig befüllt Speicher werden geprüft.

• REST nutzt API-Schlüssel; entfernetes MCP verwendet Floating-time Bearer-Tokens aus der Umgebung oder einem Docker-Secret. Mehrere aktuelle/alte Tokens ermöglichen Rotation.

• Die strukturierten Logs enthalten überwachtete operationsmetadaten und niemals den Dokumentinhalt, Zugangsdaten, vollständige Abfragen oder dem Client sichtbare Stacks.

• Portal zur und Router: Der Gateway-Container läuft als non-root, ohne Capabilities, mit no-new-privileges, read-only Root, explizit schreibbaren Volumes/tmpfs sowie Ressourcen-/Loglimits.

• Das Basis-Compose veröffentlicht nur 127.0.0.1:8000; Qdrant ist ausschließlich intern erreichbar. Für besteht ein öffentstellen: bepikation wird angeboten.

Gespeicherte Daten bestehen aus privaten UUID-Quellkopien, generiertem Markdown, SQLite-Metadaten/Chunks/FTS, optionalen lokalen Vektor-/Modell- und Vektor-Volumes, Backups und Betreiberkonfiguration. Zum Löschen von Daten entfernen Sie Dokumente über REST zuerst; entfernen Sie persistente Volumes erst nach einem expliziten Backup und Herunterfahren. Private Schwachstellenmeldungen unter Sicherheit.md.

Oracle-Cloud-Deployment

Das empfohlene Oracle Ubuntu-Deployment bindet die Anwendung an den Loopback und verwendet Tailscale Serve, um HTTPS nur im Tailnet zu ermöglichen. Ein Caddy-Profil public ist für Fälle dokumentiert, die eine Domäne benötigen. Oracle Security Listen/NSGs dürfen TCP 8000 oder Qdrant 6333 niemals öffnen.

VM-Vorbereitung, Hinweise zu AMD64/Ampere ARM64, Docker-Installation, Dateisystem-Eigentümer, Secrets, Firewalls, Tailscale/Caddy, Protokollierung, Updates, Backup, Wiederherstellung und Fehlerbehebung sind im Handbuch Oracle-Deployment enthalten.

Konfiguration

Alle Umgebungsvariablen der Anwendung, Standardwerte, Anforderungen, Bereiche, Beispiele und sicherheitsrelevante Auswirkungen sind aufgeführt in der Konfiguration und in .env.example enthalten. Der Start verwirft fehlendes/zu kurze Credentials, ungültige Ports/Pfade, unmögliche Chunk-/Budget-Beziehungen, nicht unterstützte Retrieval-Modi und ungültige Semantik-Settings für den Vektor-Store, ohne Schlüsselwerte auszugeben.

Operative Befehle:

./corpusgate version
./corpusgate status
./corpusgate doctor
./corpusgate mcp-smoke
./corpusgate upload /absolute/path/to/document.pdf
./corpusgate scan
./corpusgate reindex
./corpusgate reindex --semantic
./corpusgate list-documents --limit 20 --offset 0

Sicherung und Wiederherstellung

./corpusgate backup
./corpusgate restore /backups/corpusgate-backup-TIMESTAMP.tar.gz --confirm-restore

Eine Wiederherstellung ersetzt die aktuellen persistenten Daten und erfordert daher in der Produktion ein explizites Bestätigungsflag und einen gestoppten Writer. Backups enthalten den privaten Quellspeicher, den Markdown-Cache, eine transaktional kopierte SQLite-Datenbank, ein Manifest und eine geheimnisfreie Beispielkonfiguration. .env- und Token-Dateien befinden sich in einem separaten, verschlüsselten Secret-Backup. Vektordaten können aus Chunks neu aufgebaut werden.

Update und Rollback

Ermitteln Sie die aktuelle Version, erstellen Sie ein Backup, wählen Sie das geprüfte Tag/Image, führen Sie die versionierte idempotente Migration aus, starten Sie neu, prüfen Sie Bereitschaft/MCP und behalten Sie das Backup, bis die Validierung abgeschlossen ist. Eine Datenbank, die von einer neueren, inkompatiblen Anwendung erstellt wurde, wird abgelehnt, statt stillschweigend verändert zu werden.

Die genauen Befehle und der sichere Rollback-/Wiederherstellungspfad sind in Update und Rollback beschrieben. Führen Sie während eines normalen Updates niemals docker compose down -v aus.

Das Repository enthält außerdem einen manuellen, freigabepflichtigen GHCR-Workflow. Das Verhalten von Stable-Tag, Moving-Minor und latest ist in der Container-Publishing-Richtlinie definiert; in diesem Sprint wurde noch kein Image veröffentlicht.

Fehlerbehebung

• ./corpusgate doctor: validiert die Konfiguration, Speicherberechtigungen, SQLite/Schema, Speicherplatz, den optionalen Modell/Vektor-Status, die Service-Bereitschaft und die Version, ohne Geheimnisse auszugeben.

• 401: Verwenden Sie den REST-X-API-Key oder die MCP-Authorization: Bearer – nicht den jeweils anderen Berechtigungstyp.

• Host-Ablehnung: Fügen Sie exakt den Tailscale-/Domain-Host zu CORPUSGATE_ALLOWED_HOSTS hinzu und erstellen Sie das Gateway neu.

• 403: 507: Speicherplatz freigeben oder den reservierten Speicherschwellenwert anpassen, bevor Sie die Aufnahme erneut versuchen.

• lexical_fallback: Prüfen Sie den Modell-Cache und die Qdrant-Gesundheit; das lexikalische Retrieval bleibt verfügbar.

• Konvertierungsfehler: Prüfen Sie die unterstützte Dateierweiterung, MIME/Signatur, UTF-8/Office-Archivintegrität, Größe, Verschlüsselung und ob das PDF Text enthält.

• Protokolle: ./corpusgate logs --tail=100; bereinigen Sie die Ausgabe vor dem Teilen.

Siehe SUPPORT.md und den bereitstellungsspezifischen Troubleshooting-Leitfaden, bevor Sie ein Issue öffnen.

Kompatibilität

Nicht getestete Plattformen werden nicht als unterstützt dargestellt. Lesen Sie die Release-Checkliste, bevor Sie Artefakte veröffentlichen.

Einschränkungen

• SQLite auf einem einzelnen Knoten ist keine hochverfügbare oder Multi-Writer-Datenbank.

• Der Upload-Konvertierung ist in 0.1.0 synchron; bei großen Dokumenten sind möglicherweise längere Client-/Proxy-Zeitüberschreitungen erforderlich.

• Keine OCR, kein Cloud-Speicher-Adapter, keine Benutzerkonten, keine UI, keine Antwortgenerierung, kein Reranking, kein Fine-Tuning.

• Die angenäherte Token-Budgets können von einem bestimmten LLM-Tokenizer abweichen.

• Der Download semantischer Modelle erfordert temporären ausgehendenden Netzwerkzugriff, es sei denn, der Cache wird offline übertragen.

Roadmap

• Hintergrund-Konvertierungsaufträge ohne Redis für Einzelknoten-Benutzer.

• Optionale PostgreSQL/pgvector- und Objektspeicher-Adapter hinter vorhandenen Schnittstellen.

• Mehr Metadatenextraktion durch Konverter und ein von Betreibern steuerbares OCR-Adapter.

• Signierte Release-Images, SBOM/Provenienz, erweiterte Cross-Architektur- und Upgrade-Fixtures.

Mitwirken

Lesen Sie CONTRIBUTING.md, folgen Sie CODE_OF_CONDUCT.md, ergänzen Sie Tests und verwenden Sie ausschließlich synthetische, nicht sensible Fixtures. Sicherheitsmeldungen müssen den privaten Kanal in SECURITY.md nutzen, niemals ein öffentliches Issue.

Lizenz

CorpusGate steht unter der MIT License. Drittanbieterbibliotheken und das optionale Einbettungsmodell behalten ihre eigenen Lizenzen.