mdcx

Convierte una colección de documentos a Markdown verificado, empaquétalo en un único archivo cifrado y haz que los agentes puedan consultarlo mediante el Model Context Protocol.

El problema

Un agente que responde preguntas sobre una colección de documentos tiene dos opciones. Puede recibir los documentos en su ventana de contexto, lo cual es costoso y está limitado por el tamaño de la ventana. O puede consultar un componente que ya sabe dónde está cada elemento.

Midiendo una consulta específica — dónde se indica el diámetro mínimo de tubería a modelar en 3D — sobre una colección real de 99 documentos y 180 MB, usando el tokenizador cl100k_base:

Los 435 se componen de 20 para la pregunta, 274 para el pasaje recuperado y 141 para la respuesta.

La primera fila cuesta toda la colección por una razón concreta: un PDF no se puede buscar, es un binario, y sin conversión previa no hay forma de saber cuál de los 99 documentos contiene la respuesta. Todos deben extraerse y leerse.

Esta es una medición, no un promedio: el ahorro depende de cuánto texto requiera una respuesta. Lo que no varía es la forma del cambio. El trabajo no desaparece, se traslada de la ventana de contexto — que se factura y es finita — a la CPU, que no lo es. Por eso la columna local sube en lugar de bajar.

Related MCP server: md-mcp

Las tres etapas

Conversión. Cada documento se convierte a Markdown y se verifica contra el texto que el original realmente expone, leído con una biblioteca independiente del motor que realizó la conversión. El contenido que el motor estructurado omite se añade textualmente en lugar de informarse como perdido.

Sobre la colección utilizada durante el desarrollo — 99 documentos, 1,144,553 palabras de referencia — no se recuperaron 594 palabras, una cobertura global del 99.948%. De los 184 documentos que exponen texto, 116 salieron exactamente al 100% y ninguno por debajo del 99.5%. Los cuatro restantes son dibujos escaneados que no contienen texto alguno en el archivo: se leyeron mediante reconocimiento óptico de caracteres y se marcan como no verificables, porque no existe un texto original con el que medirlos.

Empaquetado. El corpus, su índice de búsqueda y la procedencia de cada pasaje caben en un único archivo .mdcx, cifrado con AES-256-GCM, cuyo encabezado se puede leer sin la clave. De 8.8 MB de Markdown a 3.9 MB en un solo archivo.

Recuperación. Una consulta devuelve los pasajes que la responden con su fuente exacta. Sobre las 20 consultas reales utilizadas para el ajuste, el documento correcto aparece entre los cinco primeros resultados en 19 casos y entre los diez primeros en los 20.

Instalación

El paquete separa la consulta de la conversión, porque tienen requisitos muy diferentes.

La conversión es lo que arrastra las dependencias pesadas. Alguien que recibe un archivo .mdcx y solo necesita consultarlo no instala ni Docling ni PyTorch.

Conversión de una colección

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

La salida refleja la estructura de directorios de entrada, añade un índice global y registra para cada archivo la cobertura lograda frente a su original.

Empaquetado y consulta

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 lee el encabezado sin la clave, por lo que el emisor y la integridad de un archivo se pueden comprobar antes de abrirlo. export reconstruye la carpeta original: un formato del que no se puede salir es una trampa, por bien intencionado que sea.

Uso como servidor MCP

El servidor requiere Python y este paquete. No requiere la pila de conversión, por lo que la huella es de unos 50 MB.

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

Alternativamente, con uv el servidor se ejecuta sin instalación previa, que es la disposición habitual para servidores MCP de Python:

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

Se exponen tres herramientas. search devuelve los pasajes que responden a una pregunta, cada uno con su documento fuente y ruta portátil. info describe el corpus y la fidelidad de su conversión. document devuelve un documento completo cuando los pasajes no son suficientes.

El servidor verifica el paquete antes de empezar a escuchar, por lo que una ruta o clave incorrecta se informa de inmediato en lugar de en la primera consulta.

Pruebas

pip install pytest
python -m pytest tests/ -v

La suite cubre entradas hostiles: archivos vacíos y corruptos, nombres en otros alfabetos, consultas malformadas incluyendo intentos de inyección SQL, paquetes truncados y manipulados, y compactación contra pérdida de contenido.

Rutas

Ninguna salida contiene rutas absolutas. Cada documento se identifica mediante una pseudoruta que comienza con @/, resuelta contra la carpeta o paquete que lo contiene, de modo que un corpus sigue siendo válido dondequiera que se almacene: disco local, recurso compartido de red o nube.

Firma

Un paquete puede firmarse para que su emisor pueda demostrarse en lugar de simplemente declararse. La firma cubre el resumen del cuerpo cifrado, por lo que atestigua tanto el origen como el contenido, y se verifica sin la clave de cifrado.

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>

La verificación también requiere que el cuerpo esté intacto: una firma que cubra solo el resumen registrado aceptaría de otro modo un paquete cuyo contenido hubiera sido reemplazado mientras su encabezado se dejaba intacto.

El campo de emisor por sí solo es texto libre y no prueba nada. Solo una firma lo hace.

Cifrado

El paquete cifra en reposo y descifra en memoria al abrirlo; nada se escribe en disco en claro. Esto protege un archivo en tránsito. No es lo mismo que buscar sobre datos cifrados sin descifrarlos nunca, que es un campo separado con ataques de fuga documentados y costes por consulta medidos en segundos.

La clave se deriva con scrypt, lo que hace lento el adivinarla: unas 8 intentos por segundo, cada uno requiriendo 32 MB de memoria, lo que impide la paralelización en una GPU. Aun así, la fortaleza real es la contraseña: una contraseña de diccionario cae en un día.

Autoría

Concebido y dirigido por Jorge Ellena G., programado con la asistencia de Claude (Anthropic).

Cada decisión en este paquete se tomó contra mediciones en lugar de convenciones: qué motor de conversión usar, qué licencia permite cuál, cómo clasificar una búsqueda, qué optimizaciones aceptar y cuáles descartar. Varias se descartaron precisamente porque se midieron — reducir el grupo de candidatos de búsqueda parecía ser diez veces más rápido y de hecho bajó la precisión de 19 a 17 de 20 — y esas mediciones se registran junto con las decisiones que justifican.

Cita

Archivado en Zenodo con un identificador permanente. El DOI de concepto siempre resuelve a la última versión:

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

Licencia

Apache 2.0. El software puede usarse, modificarse y venderse, siempre que se conserve el aviso de copyright.

Se evitó deliberadamente PyMuPDF: su licencia AGPL obligaría a cualquiera que use este software a publicar el suyo bajo AGPL, incluidos aquellos que lo ofrecen solo como servicio de red.