# 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](#sobre-el-proyecto)
- [Requisitos](#requisitos)
- [Instalación](#instalacion)
- [Cómo ejecutar](#uso)
  - [Línea de Comandos (CLI)](#uso-cli)
  - [Servidor MCP (Model Context Protocol)](#uso-mcp)
  - [Habilidades de Agente (Agentic Skills)](#uso-skills)
- [Cómo parar](#parar)
- [Estructura del proyecto](#estructura)
- [Changelog](#changelog)
- [Licencia](#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)
```bash
# 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:
```bash
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:
```bash
# 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):**
```bash
# 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`:

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

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

```json
{
  "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](./dbv-specs-ops/docs/AGENTIC_SKILLS.md)**.

---

<a name="parar"></a>
## ⏹ Cómo parar

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

**Windows:**
```cmd
stop.cmd
```

**macOS / Linux:**
```bash
./stop.sh
```

---

<a name="estructura"></a>
## 📂 Estructura del proyecto

```text
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
```


---

<a name="changelog"></a>
## 📋 Changelog

Consulta el archivo [CHANGELOG.md](./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](./LICENSE) para más detalles.

Copyright (c) 2026 David Bueno (davidbuenov)

---

> 🛠️ Construido con **[dbv-specs-ops](https://github.com/davidbuenov/dbv-specs-ops)** — el framework SDD para el desarrollo asistido por IA.  
> Creado por **[David Bueno Vallejo](https://github.com/davidbuenov)** — libre y gratuito.