[english version]

AntiquarIO

Herramienta y servidor MCP de extracción de texto de documentos e imágenes (según el engine que se elija) con privacidad como prioridad (100% local).

Qué hace

Convierte documentos (PDF e imágenes) a Markdown estructurada usando múltiples motores de parsing seleccionables. Soporta también chunking jerárquico optimizado para bases de datos vectoriales (RAG).

Capacidades:

• Análisis PDF → Markdown con calidad adaptativa
• OCR en imágenes (JPG, PNG, WebP, BMP, TIFF) mediante motores VLM
• Detección automática de anexos y saltos de páginas no relevantes
• Chunking jerárquico para embeddings y RAG
• Soporte de documento como ruta de archivo o bytes base64
• Interfaz CLI (MCP server), HTTP y GUI (Streamlit)

Prerrequisitos del sistema

Requisito	Detalles
macOS	Solo Apple Silicon (M1/M2/M3)
Python	>= 3.10
uv	Gestor de paquetes — guía de instalación
Espacio en disco	~5 GB libres para modelos ML (se descargan al primer uso desde HuggingFace)
RAM	16 GB recomendados (los engines VLM son intensivos en memoria)

Instalar uv

# macOS vía Homebrew
brew install uv

# o instalador standalone
curl -LsSf https://astral.sh/uv/install.sh | sh

Instalación

# Clonar y entrar al repositorio
git clone <repo-url> && cd antiquario

# Instalar dependencias
uv sync

Uso

1. Interfaz gráfica (Streamlit)

Modo por defecto — drag & drop de PDFs o imágenes, visualización en vivo del Markdown resultante y descarga.

antiquario

O equivalentemente:

antiquario-gui

2. Como servidor MCP (stdio)

Conectar desde clientes compatibles con MCP (Claude Desktop, Cursor, etc.).

antiquario-mcp

Herramientas expuestas:

Tool	Descripción
parse_document	Parsea un PDF o imagen y retorna su contenido en Markdown
parse_document_chunks	Igual que arriba, más chunks jerárquicos

Parámetros comunes:

Parámetro	Tipo	Default	Descripción
file_path	str	—	Ruta absoluta al PDF o imagen
file_bytes_b64	str	—	Contenido del documento codificado en base64
language	str	"es"	Idioma para OCR
skip_annexes	bool	true	Detectar y saltar anexos (PDF)
end_page	int	—	Límite de páginas a procesar (PDF)
engine	str	—	Motor forzado: qwen3_vl_4b, docling, pymupdf, marker

Ejemplo de llamada desde un cliente MCP (también funciona con imágenes):

{
  "name": "parse_document",
  "arguments": {
    "file_path": "/ruta/a/documento.pdf",
    "language": "es",
    "skip_annexes": true
  }
}

3. Como servidor HTTP

antiquario-mcp --transport http --host 127.0.0.1 --port 8000

Exponde las herramientas MCP vía protocolo Streamable HTTP en http://127.0.0.1:8000/mcp.

Motores de parsing

El usuario selecciona el motor de parsing. Los motores marcados con ✦ aceptan imágenes como input.

#	Motor	Tecnología	Velocidad	Calidad	Imágenes
1	qwen3_vl_4b ✦	Qwen-VL vía mlx-vlm (Apple Silicon)	Media	Alta (OCR con VLM)	Sí
2	docling	Docling nativo con OCR	Lenta	Alta	No
3	pymupdf	Extracción directa de texto	Muy rápida	Media	No
4	marker	Marker-PDF (Surya + layout)	Muy lenta	Alta	No

Nota: Solo los motores VLM (Qwen-VL) soportan imágenes. Al pasar una imagen con un motor incompatible, el pipeline devuelve un error claro indicando que el engine no acepta ese formato.

Arquitectura

El proyecto sigue un patrón pipeline configurable: cada motor es una clase independiente (BaseEngine) y los pasos del flujo son funciones puras componibles orquestadas por ParsePipeline. Ver ARCHITECTURE.md para el diagrama completo, contratos entre módulos y decisiones de diseño.

Referencia detallada por módulo: docs/modules.md.

Configuración

Variables de entorno:

Variable	Default	Descripción
ANTIQUARIO_DEBUG	"0"	"1" o "true" para logs en debug

Licencia

MIT