Servidor MCP de documentos local con Marker y ChromaDB

Este proyecto implementa un servidor MCP de Python para OpenCode. Lee archivos PDF, Word (.docx), PowerPoint (.pptx) y EPUB ubicados en DOCS/, excluyendo siempre DOCS/mdDB/. Convierte los documentos a Markdown con Marker, conserva las tablas y ecuaciones como LaTeX, almacena los archivos Markdown completos en DOCS/mdDB/ y crea un índice semántico persistente en ChromaDB.

La recuperación tiene en cuenta la estructura. ChromaDB localiza los fragmentos más relevantes para una consulta, pero el servidor MCP no devuelve un fragmento aislado. Utiliza los metadatos del resultado para abrir el archivo Markdown original y reconstruir la sección completa delimitada por los encabezados. La respuesta incluye el texto circundante, las tablas y las ecuaciones, junto con las rutas de archivo y los rangos de líneas.

Flujo de datos

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

Como mínimo, cada fragmento almacena source_path, markdown_path, section_title, section_path, section_start_line, section_end_line, chunk_start_line y chunk_end_line. También almacena hashes SHA-256 del documento de origen y del archivo Markdown para detectar cambios.

Related MCP server: Personal Semantic Search MCP

Estructura del proyecto

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

Los documentos de origen pueden colocarse directamente en DOCS/ o en cualquiera de sus subdirectorios, excepto DOCS/mdDB/. Su estructura de directorios relativa se conserva en la salida. Por ejemplo, DOCS/manuals/instrument.pdf produce DOCS/mdDB/manuals/instrument.md. Las imágenes extraídas se almacenan junto al archivo Markdown en instrument_assets/, y sus enlaces se reescriben como rutas relativas. Todo el árbol de DOCS/mdDB/ queda excluido de la detección para que el servidor MCP no pueda procesar su propia salida.

Requisitos

Se requieren Python 3.10–3.13 y uv. Marker 2 requiere un backend de inferencia para OCR y ecuaciones. llama.cpp se recomienda en macOS o en sistemas solo con CPU. Los sistemas con GPU NVIDIA pueden usar el backend VLLM configurado mediante Surya.

En macOS:

brew install uv llama.cpp

En Linux, instala uv y un binario reciente de llama-server proporcionado por llama.cpp. Para sistemas NVIDIA, instala Docker y el NVIDIA Container Toolkit según los requisitos de Marker.

Instalación

Extrae el archivo de la versión directamente en la raíz del proyecto actual. El archivo ya contiene la estructura de directorios .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

Tras la extracción, el servidor MCP queda instalado exactamente en:

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

La primera conversión y la primera vectorización descargan los modelos necesarios. El modelo de embeddings ONNX se almacena en DOCS/mdDB/.chroma/.embedding_models/. Los modelos de Marker usan la caché configurada por Marker y Surya. El proceso inicial puede llevar tiempo y consumir varios gigabytes. Los documentos DOCX, PPTX y EPUB requieren la variante marker-pdf[full], que ya está incluida en pyproject.toml.

Configuración de OpenCode

Copia la configuración de opencode.example.jsonc al archivo opencode.json o opencode.jsonc en la raíz del proyecto. Si el servidor MCP se encuentra en otro lugar, cambia únicamente la ruta que sigue a --project.

Configuración mínima:

{
  "$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"
      }
    }
  }
}

El ajuste cwd: "." resuelve todas las rutas en relación con la raíz del proyecto abierto en OpenCode. Verifica la conexión con:

opencode mcp list

El archivo AGENTS.example.md contiene una política opcional que indica a OpenCode que consulte a este servidor MCP antes de responder preguntas sobre los documentos. Puedes incorporar su contenido al archivo AGENTS.md del proyecto.

Herramientas MCP

Uso del servidor MCP en OpenCode

Coloca los documentos de origen en DOCS/, pero nunca en DOCS/mdDB/. Después puedes usar solicitudes como:

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.

Recuperación ampliada

search_documents acepta query, un valor top_k de 1 a 20 y un document_name opcional. Internamente, solicita resultados adicionales a ChromaDB para que varios fragmentos de la misma sección no ocupen todas las posiciones del resultado. Después elimina las secciones duplicadas y devuelve hasta top_k secciones distintas.

Cada resultado contiene context, que es la sección completa leída del disco en el momento de la consulta. index_is_current indica si el archivo Markdown sigue teniendo el mismo hash que tenía cuando se indexó. Si este valor es false, ejecuta ingest_document o ingest_all_documents. Cuando el documento de origen no ha cambiado, el sistema reindexa el Markdown existente sin volver a ejecutar Marker.

Conversión y ecuaciones

Marker genera tablas formateadas y ecuaciones LaTeX delimitadas por $$. El modo predeterminado es balanced, que es adecuado cuando la prioridad es la fidelidad de tablas, OCR y matemáticas. En sistemas con CPU o Apple Silicon, reduce el coste de procesamiento con:

"DOC_RAG_MARKER_MODE": "fast"

Para documentos escaneados o texto ilegible:

"DOC_RAG_FORCE_OCR": "true"

Para la corrección híbrida opcional de Marker mediante un servicio LLM compatible:

"DOC_RAG_USE_LLM": "true"

La última opción requiere credenciales y un servicio compatible con Marker. No es necesaria para el funcionamiento normal del servidor MCP.

Variables de entorno

Seguridad y consistencia

El servidor rechaza extensiones no compatibles, el path traversal con .., los archivos de origen fuera de DOCS/, cualquier archivo de origen dentro de DOCS/mdDB/ y las rutas Markdown fuera de DOCS/mdDB/. Una ruta almacenada en ChromaDB nunca se utiliza sin volver a validarse. Las escrituras de Markdown son atómicas y el reemplazo del índice se limita al documento correspondiente.

Si dos archivos del mismo directorio tienen el mismo nombre base, como manual.pdf y manual.docx, ambos producirían manual.md. El servidor detecta esta colisión y exige que uno de los archivos de origen se renombre antes de escribir o indexar.

Pruebas

Las pruebas unitarias no cargan Marker ni ChromaDB. Validan la segmentación jerárquica, la conservación de tablas y ecuaciones, la expansión de secciones y la protección de rutas:

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

También puedes comprobar la sintaxis de todo el árbol de código fuente con:

python -m compileall -q src tests

Licencias

Este proyecto se distribuye bajo la licencia MIT. Marker utiliza la licencia Apache-2.0 para su código y una licencia independiente para los pesos de sus modelos. Revisa los términos de Marker antes de un uso comercial a gran escala.