mdcx

Konvertieren Sie eine Dokumentsammlung in verifiziertes Markdown, verpacken Sie sie in eine einzige verschlüsselte Datei und machen Sie sie über das Model Context Protocol für Agenten abfragbar.

Das Problem

Ein Agent, der Fragen zu einer Dokumentsammlung beantwortet, hat zwei Möglichkeiten. Er kann die Dokumente in seinem Kontextfenster empfangen, was teuer und durch die Fenstergröße begrenzt ist. Oder er fragt eine Komponente ab, die bereits weiß, wo sich jedes Element befindet.

Bei einer konkreten Abfrage – wo der minimale Rohrdurchmesser für die 3D-Modellierung angegeben ist – über eine reale Sammlung von 99 Dokumenten und 180 MB, unter Verwendung des cl100k_base-Tokenizers:

Die 435 setzen sich zusammen aus 20 für die Frage, 274 für den abgerufenen Abschnitt und 141 für die Antwort.

Die erste Zeile kostet die gesamte Sammlung aus einem konkreten Grund: Eine PDF-Datei kann nicht durchsucht werden, sie ist binär, und ohne vorherige Konvertierung gibt es keine Möglichkeit zu wissen, welches der 99 Dokumente die Antwort enthält. Sie müssen alle extrahiert und gelesen werden.

Dies ist eine Messung, kein Durchschnitt: Die Ersparnis hängt davon ab, wie viel Text eine Antwort erfordert. Was sich nicht ändert, ist die Form der Veränderung. Die Arbeit verschwindet nicht, sie verlagert sich vom Kontextfenster – das abgerechnet wird und endlich ist – auf die CPU, die es nicht ist. Deshalb steigt die lokale Spalte eher, als dass sie fällt.

Related MCP server: md-mcp

Die drei Phasen

Konvertierung. Jedes Dokument wird in Markdown konvertiert und gegen den Text geprüft, den das Original tatsächlich preisgibt, gelesen mit einer Bibliothek, die unabhängig von der Engine ist, die die Konvertierung durchgeführt hat. Inhalte, die die strukturierte Engine auslässt, werden wörtlich angehängt, anstatt als verloren gemeldet zu werden.

Über die Sammlung, die während der Entwicklung verwendet wurde – 99 Dokumente, 1.144.553 Referenzwörter – wurden 594 Wörter nicht wiederhergestellt, eine globale Abdeckung von 99,948 %. Von den 184 Dokumenten, die Text preisgeben, erreichten 116 exakt 100 % und keines unter 99,5 %. Die restlichen vier sind gescannte Zeichnungen, die in der Datei überhaupt keinen Text enthalten: Sie wurden per optischer Zeichenerkennung gelesen und als nicht verifizierbar markiert, da kein Textoriginal existiert, an dem sie gemessen werden können.

Verpackung. Das Korpus, sein Suchindex und die Herkunft jedes Abschnitts passen in eine einzige .mdcx-Datei, verschlüsselt mit AES-256-GCM, deren Kopf ohne Schlüssel gelesen werden kann. Von 8,8 MB Markdown auf 3,9 MB in einer Datei.

Abruf. Eine Abfrage liefert die Abschnitte, die sie beantworten, mit ihrer genauen Quelle. Über die 20 realen Abfragen, die zur Optimierung verwendet wurden, erscheint das richtige Dokument in 19 Fällen unter den ersten fünf Ergebnissen und in allen 20 unter den ersten zehn.

Installation

Das Paket trennt Abfrage und Konvertierung, da diese sehr unterschiedliche Anforderungen haben.

Die Konvertierung ist es, die die schweren Abhängigkeiten mit sich bringt. Jemand, der eine .mdcx-Datei erhält und sie nur abfragen muss, installiert weder Docling noch PyTorch.

Konvertieren einer Sammlung

pip install "mdcx[convert]"
mdcx-convert --input ./Documents --output ./Documents_md

Die Ausgabe spiegelt die Verzeichnisstruktur der Eingabe wider, fügt einen globalen Index hinzu und zeichnet für jede Datei die erreichte Abdeckung gegenüber dem Original auf.

Verpacken und Abfragen

mdcx pack --output ./Documents_md --target corpus.mdcx --key "..."
mdcx info corpus.mdcx
mdcx search corpus.mdcx "where is the minimum diameter stated" --key "..."
mdcx export corpus.mdcx --target ./restored --key "..."

info liest den Kopf ohne Schlüssel, sodass der Aussteller und die Integrität einer Datei überprüft werden können, bevor sie geöffnet wird. export baut den ursprünglichen Ordner wieder auf: Ein Format, das nicht verlassen werden kann, ist eine Falle, so gut gemeint es auch sein mag.

Verwendung als MCP-Server

Der Server erfordert Python und dieses Paket. Er benötigt nicht den Konvertierungsstapel, sodass der Fußabdruck etwa 50 MB beträgt.

{
  "mcpServers": {
    "mdcx": {
      "command": "python",
      "args": ["-m", "mdcx.mcp_server"],
      "env": {
        "MDCX_FILE": "/path/to/corpus.mdcx",
        "MDCX_KEY": "package-key"
      }
    }
  }
}

Alternativ, mit uv, läuft der Server ohne vorherige Installation, was die übliche Anordnung für Python-MCP-Server ist:

{
  "mcpServers": {
    "mdcx": {
      "command": "uvx",
      "args": ["--from", "mdcx[mcp]", "python", "-m", "mdcx.mcp_server"],
      "env": {
        "MDCX_FILE": "/path/to/corpus.mdcx",
        "MDCX_KEY": "package-key"
      }
    }
  }
}

Drei Werkzeuge werden bereitgestellt. search gibt die Abschnitte zurück, die eine Frage beantworten, jeweils mit Quelldokument und portablem Pfad. info beschreibt das Korpus und die Genauigkeit seiner Konvertierung. document gibt ein vollständiges Dokument zurück, wenn Abschnitte nicht ausreichen.

Der Server überprüft das Paket, bevor er mit dem Zuhören beginnt, sodass ein falscher Pfad oder Schlüssel sofort gemeldet wird, anstatt bei der ersten Abfrage.

Tests

pip install pytest
python -m pytest tests/ -v

Die Suite deckt feindliche Eingaben ab: leere und beschädigte Dateien, Namen in anderen Alphabeten, fehlerhafte Abfragen einschließlich SQL-Injection-Versuchen, abgeschnittene und manipulierte Pakete sowie Kompaktierung gegen Inhaltsverlust.

Pfade

Keine Ausgabe enthält absolute Pfade. Jedes Dokument wird durch einen Pseudopfad identifiziert, der mit @/ beginnt und gegen den Ordner oder das Paket aufgelöst wird, das es enthält, sodass ein Korpus gültig bleibt, wo immer es gespeichert ist: lokale Festplatte, Netzwerkfreigabe oder Cloud.

Signierung

Ein Paket kann signiert werden, sodass sein Aussteller nachgewiesen werden kann, anstatt nur behauptet zu werden. Die Signatur deckt den Digest des verschlüsselten Körpers ab, sodass sie sowohl Herkunft als auch Inhalt bezeugt und ohne den Verschlüsselungsschlüssel verifiziert wird.

mdcx keygen
mdcx pack --output ./Documents_md --target corpus.mdcx --key "..." \
          --issuer "Acme Ltd" --signing-key <private-key>
mdcx verify corpus.mdcx --public-key <public-key>

Die Verifizierung erfordert auch, dass der Körper intakt ist: Eine Signatur, die nur den aufgezeichneten Digest abdeckt, würde sonst ein Paket akzeptieren, dessen Inhalt ersetzt wurde, während sein Kopf unberührt blieb.

Das Ausstellerfeld allein ist freier Text und beweist nichts. Nur eine Signatur tut das.

Verschlüsselung

Das Paket verschlüsselt im Ruhezustand und entschlüsselt im Speicher, wenn es geöffnet wird; nichts wird im Klartext auf die Festplatte geschrieben. Dies schützt eine Datei während der Übertragung. Es ist nicht dasselbe wie die Suche über verschlüsselte Daten, ohne sie jemals zu entschlüsseln, was ein separates Feld mit dokumentierten Leckage-Angriffen und pro Abfrage gemessenen Kosten in Sekunden ist.

Der Schlüssel wird mit scrypt abgeleitet, was das Erraten verlangsamt: etwa 8 Versuche pro Sekunde, jeder benötigt 32 MB Speicher, was eine Parallelisierung auf einer GPU verhindert. Dennoch ist die eigentliche Stärke die Passphrase: Ein Wörterbuchpasswort fällt an einem Tag.

Autorenschaft

Konzipiert und geleitet von Jorge Ellena G., programmiert mit Unterstützung von Claude (Anthropic).

Jede Entscheidung in diesem Paket wurde anhand von Messungen getroffen, nicht anhand von Konventionen: welche Konvertierungs-Engine verwendet wird, welche Lizenz welche erlaubt, wie eine Suche zu ranken ist, welche Optimierungen akzeptiert und welche verworfen werden. Einige wurden genau deshalb verworfen, weil sie gemessen wurden – die Reduzierung des Suchkandidatenpools schien zehnmal schneller zu sein und senkte tatsächlich die Genauigkeit von 19 auf 17 von 20 – und diese Messungen sind zusammen mit den Entscheidungen, die sie rechtfertigen, aufgezeichnet.

Zitierung

Auf Zenodo mit einer dauerhaften Kennung archiviert. Die Konzept-DOI löst immer auf die neueste Version auf:

https://doi.org/10.5281/zenodo.22015991

Lizenz

Apache 2.0. Die Software darf verwendet, modifiziert und verkauft werden, sofern der Urheberrechtshinweis erhalten bleibt.

PyMuPDF wurde bewusst vermieden: Seine AGPL-Lizenz würde jeden, der diese Software verwendet, dazu verpflichten, seine eigene unter AGPL zu veröffentlichen, einschließlich derjenigen, die sie nur als Netzwerkdienst anbieten.