dbv-pdf2md (v0.1.0)

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

---

<a name="sobre-el-proyecto"></a>

📌 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

---

<a name="requisitos"></a>

🧰 Requisitos

• Python 3.10+
• uv (recomendado) o pip

---

<a name="instalacion"></a>

⚙️ 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

---

<a name="uso"></a>

▶️ Cómo ejecutar

<a name="uso-cli"></a>

📝 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"

---

<a name="uso-mcp"></a>

🤖 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"]
    }
  }
}

---

<a name="uso-skills"></a>

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

---

<a name="parar"></a>

⏹ Cómo parar

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

Windows:

stop.cmd

macOS / Linux:

./stop.sh

---

<a name="estructura"></a>

📂 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
├── skills/                  # Carpeta de Habilidad para distribución
│   └── dbv-pdf2md/
│        ├── SKILL.md        # Manifiesto de la Habilidad y reglas para la IA
│        ├── dbv-pdf2md.zip  # Habilidad comprimida para distribución manual
│        └── scripts/
│             └── pdf_converter.py
├── CHANGELOG.md             # Historial de cambios del proyecto
├── LICENSE                  # Licencia MIT del proyecto
└── README.md                # Este archivo

---

<a name="changelog"></a>

📋 Changelog

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

---

<a name="licencia"></a>

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