dbv-pdf2md (v0.2.1)

Conversor avanzado e inteligente de PDF a Markdown diseñado especialmente para trabajar con agentes de Inteligencia Artificial (como Claude, Gemini, etc.). Además de extraer texto e imágenes físicas a un directorio relativo, soluciona un problema común en otros conversores: reconstruye los enlaces de hipertexto ocultos (como textos que dicen "pincha aquí" o "+ INFO" que apuntan a una URL) intersectando las cajas de los enlaces del PDF con las palabras en la página.

📑 Índice

• Sobre el proyecto

• Requisitos

• Instalación

• Cómo ejecutar

  • Línea de Comandos (CLI)

  • Servidor MCP (Model Context Protocol)

  • Habilidades de Agente (Agentic Skills)

• Cómo parar

• Estructura del proyecto

• Changelog

• Licencia

Related MCP server: PDF2MD MCP Server

📌 Sobre el proyecto

dbv-pdf2md es un conversor de PDF a Markdown desarrollado bajo el estándar SDD de dbv-specs-ops. Su valor diferencial reside en:

• Reconstrucción geométrica de hipervínculos: Mapea las coordenadas físicas del PDF y asocia los enlaces URI con las palabras reales de la página, recomponiendo enlaces como [pincha aquí](URL) o [+ INFO](URL) que de otro modo se perderían.

• Extracción física de imágenes secuencial: Extrae y guarda imágenes físicas de forma ordenada basándose en su flujo de lectura Y-X original, evitando duplicar recursos mediante una caché de xref.

• Mapeo de navegación interna: Convierte enlaces de páginas físicas del PDF en marcadores de anclaje de tipo [Texto](#página-X).

• Firma e Integridad: Inyecta automáticamente una firma de autoría al pie de cada archivo de Markdown generado para mantener el origen de los datos claro para las IAs.

Tecnologías principales:

• Python 3.10+

• PyMuPDF (fitz) para procesamiento del PDF y mapeo geométrico

• Python MCP SDK para exposición stdio vía FastMCP

• Patrón Result (Ok/Err) para control estricto de excepciones

• pytest para suite de pruebas unitarias

• uv como gestor rápido de paquetes y dependencias

🧰 Requisitos

• Python 3.10+

• uv (recomendado) o pip

⚙️ Instalación

Instalación Local (Desarrollo)

# 1. Crear y activar entorno virtual usando uv (o python -m venv .venv)
uv venv
.venv\Scripts\activate     # Windows (CMD/PowerShell)
source .venv/bin/activate  # macOS / Linux

# 2. Instalar dependencias y registrar los comandos globales en modo editable
uv pip install -e .[dev]

Instalación desde Repositorio (Git / GitHub)

Cualquier usuario puede instalar la aplicación y registrar los ejecutables globales directamente desde el repositorio remoto con un único comando:

pip install git+https://github.com/davidbuenov/dbv-pdf2md.git

▶️ Cómo ejecutar

📝 Línea de Comandos (CLI)

Opción A (Comando Global de Pip / Instalado): Si instalaste el proyecto localmente mediante pip install -e . o vía Git, puedes llamar al comando global directamente desde cualquier ubicación de tu terminal:

# Procesar un PDF individual
dbv-pdf2md "ruta/al/documento.pdf" -o "ruta/carpeta_salida"

# Procesar recursivamente todos los PDFs en una carpeta
dbv-pdf2md "ruta/carpeta_con_pdfs" -o "ruta/carpeta_salida" --recursive

# Ver versión y autoría
dbv-pdf2md --version

Opción B (Ejecución Tradicional de Python):

# Activar entorno virtual e invocar el módulo directamente
python pdf_converter.py "ruta/al/documento.pdf"

🤖 Servidor MCP (Model Context Protocol)

El proyecto incluye un servidor MCP (mcp_server.py) que expone la herramienta convert_pdf a entornos de agentes LLM como Cursor, Windsurf o Claude Desktop.

Si instalaste el paquete vía pip, puedes configurar tu cliente MCP para que apunte directamente al ejecutable registrado dbv-pdf2md-mcp. Para configurarlo en Claude Desktop, añade esto a tu archivo claude_desktop_config.json:

{
  "mcpServers": {
    "dbv-pdf2md": {
      "command": "dbv-pdf2md-mcp"
    }
  }
}

O si deseas ejecutarlo llamando al intérprete de Python del entorno virtual:

{
  "mcpServers": {
    "dbv-pdf2md": {
      "command": "C:\\Ruta\\A\\Tu\\Proyecto\\.venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_server"]
    }
  }
}

🧠 Habilidades de Agente (Agentic Skills)

El convertidor está empaquetado como un Agentic Skill bajo el estándar de herramientas locales de IA. Esto permite que asistentes autónomos (como Antigravity) o agentes web (como Claude Projects y Custom GPTs) reconozcan y ejecuten la conversión de archivos de forma directa en su terminal sandbox.

Para ver las guías de integración detalladas de la habilidad, cómo usarla en tus propios proyectos de Claude y ChatGPT, o instalarla manualmente usando el archivo comprimido dbv-pdf2md.zip, consulta la Guía de Habilidades de Agente.

⏹ Cómo parar

Para detener el servidor MCP o cualquier proceso en ejecución rápida:

Windows:

stop.cmd

macOS / Linux:

./stop.sh

📂 Estructura del proyecto

dbv-pdf2md/
├── pdf_converter.py         # Lógica principal del conversor, reemplazos y CLI
├── mcp_server.py            # Servidor MCP para integraciones con IAs
├── pyproject.toml           # Configuración del paquete y comandos CLI (PEP 621)
├── start.cmd / start.sh     # Scripts de inicio rápido (Windows / macOS / Linux)
├── stop.cmd / stop.sh       # Scripts de parada rápida (Windows / macOS / Linux)
├── tests/                   # Pruebas unitarias y de integración
│   ├── test_cli.py
│   └── test_converter.py
├── dbv-specs-ops/           # Framework SDD para desarrollo asistido por IA
│   └── docs/
│       ├── AGENTIC_SKILLS.md # Guía detallada de integración de habilidades
│       └── AGENT_PLUGINS.md # Guía técnica de Agent Plugins 1.0.0
├── agent-plugin/            # Carpeta del Plugin bajo estándar Agent Plugins 1.0.0
│   ├── plugin.json          # Manifiesto principal del plugin
│   ├── mcp.json             # Descriptor de servidor MCP asociado
│   └── skills/              # Habilidades portadas para distribución
│       └── dbv-pdf2md/
│            ├── SKILL.md    # Manifiesto de la Habilidad y reglas para la IA
│            ├── dbv-pdf2md.zip # Habilidad comprimida para distribución
│            └── scripts/
│                 └── pdf_converter.py
├── CHANGELOG.md             # Historial de cambios del proyecto
├── LICENSE                  # Licencia MIT del proyecto
└── README.md                # Este archivo

📋 Changelog

Consulta el archivo CHANGELOG.md para ver el historial detallado de cambios.

📄 Licencia

Este proyecto está bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.

Copyright (c) 2026 David Bueno (davidbuenov)

🛠️ Construido con dbv-specs-ops — el framework SDD para el desarrollo asistido por IA.
Creado por David Bueno Vallejo — libre y gratuito.