CorpusGate

Una pasarela privada de documentos preparada para LLM, impulsada por MarkItDown y MCP.

Convierte, indexa y recupera documentos privados para herramientas de IA sin enviar contenido de documentos a servicios de terceros.

CorpusGate es un servidor Document MCP Server autohospedado y de propósito general para particulares y equipos que necesitan un acceso controlado de las herramientas de IA a documentos de su propia infraestructura. MarkItDown convierte los archivos compatibles en Markdown reutilizable. A continuación, la pasarela fragmenta e indexa ese Markdown, y MCP devuelve únicamente los fragmentos relevantes con atribución de fuente dentro de los presupuestos impuestos por el servidor.

El autoalojamiento mantiene los documentos fuente, el Markdown generado, las consultas, los metadatos y los índices bajo el control del operador. La reducción de tokens proviene de una recuperación y fragmentación acotadas—no de MarkItDown en exclusiva. Este proyecto no es un mismo un chatbot, un generador de respuestas con LLM, un producto de análisis de contratos, una plataforma SaaS ni un panel de documentos orientado al usuario.

Características

• Conversión de PDF, DOCX, PPTX, XLSX, TXT, Markdown y HTML mediante Microsoft MarkItDown.

• Caché persistente de Markdown, fragmentos que conservan los encabezados y que se ajustan al recuento de tokens, y deduplicación SHA-256.

• Búsqueda léxica SQLite FTS5/BM25 en la instalación ligera por defecto.

• Búsqueda semántica multilingüe opcional solo para CPU y recuperación híbrida RRF con embeddings locales.

• Respuestas MCP acotadas con metadatos de fuente/posición, cursores, deduplicación y límites de vecinos.

• Autenticación REST con clave de API y Bearer para MCP, almacenamiento seguro de UUID, protecciones de rutas y enlaces simbólicos, límites de tasa y registros estructurados seguros frente al contenido.

• Despliegue endurecido con Docker Compose para AMD64/ARM64, Oracle Cloud, Tailscale o Caddy HTTPS.

• Asistente de configuración, comandos operativos doctor/scan/reindex/backup, esquema SQLite versionado y CI.

Related MCP server: rag-retriever-mcp

Cómo funciona

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

El código mantiene los contratos de parser, almacenamiento, repositorio, fragmentación, embeddings, almacén de vectores y recuperación tras interfaces sin convertir el producto de servidor único en un sistema distribuido. Los documentos siguen siendo la fuente principal de datos; el Markdown y los índices vectoriales pueden reconstruirse.

Formatos compatibles

Los archivos cifrados, corruptos, de solo imagen escaneada o no compatibles el convertidor fallan de forma segura sin detener el resto de los documentos.

Inicio rápido

Requisitos: Docker Engine con Compose v2 y OpenSSL. No se requiere Python en el host.

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 crea las carpetas persistentes/inbox, copia .env.example únicamente cuando no exista .env, genera credenciales REST/MCP aleatorias separadas sin imprimirlas, comprueba Docker/Compose y el puerto seleccionado, y valida Compose. No sobrescribe nunca un .env existente.

El flujo manual equivalente consiste en copiar .env.example a .env, sustituir los dos comodines de credenciales por valores distintos de openssl rand -hex 32, crear documents/ y ejecutar docker compose up -d. Nunca hagas commit de un .env.

La recuperación semántica/híbrida local opcional es también una sola operación tras la inicialización:

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

El primer inicio semántico descarga el modelo en una caché persistente y, a continuación, inicia la pasarela fuera de línea con Qdrant en la red interna de Docker. Los inicios posteriores reutilizan tanto los volúmenes de modelo como de vectores. La instalación léxica no instala ni ejecuta ninguno de los dos componentes semánticos.

Añadir documentos

El flujo de trabajo de operador más sencillo usa la bandeja de entrada del host de solo lectura:

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

El escaneado omite los archivos ocultos, del sistema o temporales, los tipos no compatibles, los directorios y los symlinks. Los archivos de entrada permanecen en documents/; las copias privadas UUID se guardan en el volumen persistente de fuente. Para una guía completa con un paseo léxico → semántico/híbrido → MCP, use la demo sintética.

Para un flujo de un solo archivo que las herramientas de IA puedan invocar sin incluir el valor del archivo en context del modelo, envía el archivo local directamente a la API REST en ejecución (requiere curl):

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

El comando lee la clave REST de CORPUSGATE_CLIENT_API_KEY, CORPUSGATE_API_KEY o el .env local, nunca la imprime, rechaza redirecciones y HTTP remoto no seguro, y devuelve únicamente los metadatos de subida de la API. Para un servidor privado remoto, es pass --url https://YOUR-NODE.YOUR-TAILNET.ts.net.

La subida REST está disponible para las aplicaciones:

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 también ofrece metadatos paginados, Markdown, fragmentos, búsqueda léxica y borrado antes de /api/v1/documents. La documentación interactiva de OpenAPI está en /docs; las operaciones protegidas siguen requiriendo X-API-Key.

Conectar un cliente MCP

El endpoint remoto es https://YOUR_PRIVATE_OR_PUBLIC_HOST/mcp y cada solicitud MCP necesita:

Authorization: Bearer YOUR_MCP_TOKEN

Usa Tailscale Serve como la ruta privada recomendada. Caddy HTTPS es la alternativa pública; el puerto de la pasarela permanece vinculado al loopback del host en ambos casos. Consulta el mapeo de campos verificado, el comando de Inspector, los ejemplos Tailscale/HTTPS y el troubleshooting en la guía de conexión MCP. No copies un envoltorio JSON específico de un cliente no verificado ni guardes un token en el control de código.

Herramientas MCP

Los elementos de recuperación incluyen de forma sistemática document_id, document_name, chunk_id, heading, position, campos de relevancia/rango, content acotado, content_length y metadatos de modo. Las búsquedas vacías devuelven una lista items vacía, presupuestos aplicados, métricas y no cursor. Modos o cursores no válidos, filtros de búsqueda, identificadores de documento o valores por encima de los límites producen errores controlados de herramientas. La carga y la borrado siguen siendo exclusivos de REST.

Flujo recomendado:

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

Búsqueda léxica, semántica e híbrida

• lexical es el valor por defecto de producción: SQLite FTS5 con BM25 ponderada por encabezados preserva los identificadores exactos y las frases sin otro servicio.

• semantic computa los embeddings de las consultas/fragmentos de forma local con el modelo multilingüe configurable para CPU y guarda los vectores en Qdrant privado.

• hybrid fusiona los rankings léxico y semántico independientes con Reciprocal Rank Fusion; los fragmentos duplicados se devuelven una sola vez y no se descartan coincidencias léxicas exactas.

• lexical_fallback se informa cuando solicitas semantic/hybrid, pero el modelo local opcional, el vector store o el índice no están disponibles y la función fallback está habilitada.

El modelo predeterminado es el de licencia Apache-2.0 sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2, un modelo multilingüe de 384 dimensiones que se usa a través de FastEmbed/ONNX en CPU. Consulta la sustitución del modelo, la transferencia fuera de línea, las reglas de reintento, las mediciones y la guía de memoria de Oracle en búsqueda semántica.

Optimización de tokens

MarkItDown consigue que archivos diversos se puedan parsear de forma consistente; no garantiza por sí mismo menos tokens. . La pasarela reduce la cantidad de contexto devuelto cacheando la conversión una vez, ordenando la recuperación por fragmentos, omitiendo duplicados, aplicando top_k, max_chars y max_tokens estimado, con vecinos limitados y resultados largos paginados. Nunca expone una herramienta MCP por defecto que devuelva un documento completo o un archivo sin procesar.

Los recuentos de tokens son una estimación determinista local, no un tokenizador de facturación de proveedor. La medición sintética repetible y su alcance exacto están en el informe de voluntad de recuperación; no se reclama ningún porcentaje universal de ahorro.

Seguridad y privacidad

• Sin telemetría, sin texto de documento, sin texto de consulta, sin API de embeddings en la nube y sin moderación de LLM obligatorio obligatorio.

• Los archivos fuente usan rutas UUID; se verifican las vías de traversal de nombres, las rutas absolutas, los escapes por symlink, los archivos ocultos/temporales, las discordancias de MIME/firma, el descompresión de archivos, y se verifican el tamaño de descarga y el espacio de disco.

• La REST usa claves de API; MCP remoto usa Bearer tokens comparados en constante Replace from entorno or Docker. El token antiguo/actual permitellamado rotación.

• Los registros estructurados contienen metadatos de operación en una lista de permitidos, pero nunca el contenido del documento, credenciales, consultas completas o trazas de pila visibles al cliente.

• El contenedor de la gateway es no-root, sin capabilities, no-new-privileges, root de solo lectura y volúms/tmpfs explícitos, con límites de recursos y de logs.

• El Compose base publica únicamente 127.0.0.1:8000; Qdrant es sólo interno. El despliegue público requiere Caddy TLS y mantiene la autenticación Bearer y los límites de tasa/respuesta.

Los datos almacenados comprenden copias UUID privadas de la fuente, el Markdown generado, los metadatos/fragmentos/FTS SQLite, los vectores locales opcionales/caché del modelo, las copias de seguridad y configuraciones de operación. Para borrar los datos, considera eliminar los documentos a través de REST primero; retira los volúmenes persistentes solo después de una copia de seguridad explícita y del apagado. Ver SECURITY.md haber identificado reporting private de vulnerabilidades.

Despliegue en Oracle Cloud

El despliegue de Oracle Ubuntu recomendado un unir la app al loopback y utilizar Tailscale Serve para HTTPS exclusivo de tailnet. Para los casos que requieren un nombre de dominio se documenta un perfil Caddy public. Las Security Lists/NSG de Oracle nunca deben exponerexponer TCP 8000 ni Qdrant 6333.

La preparación de VMs, las notas para AMD64/Ampere ARM64, la instalación de Docker, la prestación de archivos del sistema de archivos, secretos, firewalls, Tailscale/Caddy, uso de logs, actualización, backup/restore y troubleshooting están todas en la guía de despliegue en Oracle.

Configuration

Todas las variables de entorno de aplicación, sus valores por defecto, requisitos, rangos, ejemplos y efectos de seguridad los muestra el contrato de configuración y .env.example. El arranque rechaza credenciales inexistentes/demasiado cortas, puertos/rutas no válidos, condiciones de fragmentos/inorte imposibles, modos de recuperación no soportados y configuración no válida del vector, sin mostrar los valores de los secretos.

Comandos operativos:

./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

Copia de seguridad y restauración

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

La restauración reemplaza los datos persistentes actuales y, por lo tanto, requiere un indicador explícito de confirmación y un escritor detenido en producción. Las copias de seguridad incluyen el almacenamiento privado de origen, la memoria caché de Markdown, una base de datos SQLite copiada transaccionalmente, el manifiesto y un ejemplo de configuración sin secretos. Conserva .env y los archivos de tokens en una copia de seguridad de secretos cifrada y separada. Los datos vectoriales se pueden reconstruir a partir de los fragmentos.

Actualización y reversión

Comprueba la versión actual, realiza una copia de seguridad, selecciona la etiqueta/imagen revisada, ejecuta la migración idempotente versionada, reinicia, comprueba la disponibilidad/MCP y conserva la copia de seguridad hasta que se complete la validación. Una base de datos creada por una aplicación más reciente e incompatible se rechaza en lugar de modificarse en silencio.

Los comandos exactos y la ruta segura de reversión/restauración están en actualización y reversión. Nunca ejecutes docker compose down -v durante una actualización normal.

El repositorio también contiene un flujo de trabajo manual de GHCR con aprobación. Las etiquetas estables, la versión menor móvil y el comportamiento de latest se definen en la política de publicación de contenedores; ninguna imagen ha sido publicada en este sprint.

Solución de problemas

• ./corpusgate doctor: valida la configuración, los permisos de almacenamiento, SQLite/el esquema, el disco, el estado opcional del modelo/vector, la preparación del servicio y la versión, sin exponer secretos.

• 401: usa la X-API-Key REST o Authorization: Bearer de MCP, no el otro tipo de credencial.

• Rechazo de host: añade el host exacto de Tailscale/dominio a CORPUSGATE_ALLOWED_HOSTS y vuelve a crear la puerta de enlace.

• 507 : libera espacio en disco o revisa el umbral reservado de disco antes de reintentar la ingesta.

• lexical_fallback: inspecciona la caché del modelo y el estado de Qdrant; la recuperación léxica sigue disponible.

• Fallo de conversión: confirma la extensión compatible, MIME/firma, la integridad del archivo UTF-8/Office, el tamaño, el cifrado y si el PDF contiene texto.

• Registros: ./corpusgate logs --tail=100; sanea la salida antes de compartirla.

Consulta SUPPORT.md y la guía de solución de problemas específica del despliegue antes de abrir una incidencia.

Compatibilidad

Las plataformas no probadas no se presentan como compatibles. Revisa la lista de verificación de publicación antes de publicar artefactos.

Limitaciones

• SQLite de un solo nodo no es una base de datos de alta disponibilidad ni de múltiples escritores.

• La conversión de la subida es síncrona en 0.1.0; los documentos grandes pueden necesitar tiempos de espera de cliente/proxy más grandes.

• No hay OCR, adaptador de almacenamiento en la nube, cuentas de usuario, interfaz de usuario, generación de respuestas, reranker, fine-tuning ni plano de control SaaS.

• Los presupuestos aproximados de tokens pueden diferir de un tokenizador LLM específico.

• La descarga del modelo semántico necesita acceso saliente temporal a menos que la caché se transfiera sin conexión.

Hoja de ruta

• Trabajos de conversión en segundo plano sin que Redis sea obligatorio para los usuarios de un solo nodo.

• Adaptadores opcionales de PostgreSQL/pgvector y almacenamiento de objetos detrás de las interfaces existentes.

• Más extracción de metadatos del convertidor y adaptador de OCR controlado por el operador.

• Publicaciones firmadas, SBOM/procedencia y dados de prueba ampliados con arquitecturas cruzadas y actualizaciones.

Contribuciones

Lee CONTRIBUTING.md, sigue CODE_OF_CONDUCT.md, añade pruebas y usa solo datos de prueba sintéticos no sensibles. Los informes de seguridad deben usar la ruta privada en SECURITY.md, nunca una incidencia pública.

Licencia

CorpusGate está disponible bajo the existing Licencia MIT. Las bibliotecas de terceros y el modelo de incrustación opcional conservan sus propias licencia.