# Instrucciones para el agente: Markdownify MCP: convierte archivos en texto para tu agente

Pega este texto a tu agente (Claude Code, Codex, OpenCode, Hermes o el que uses) y dile «ayúdame a montarlo». Son los pasos para ponerlo en marcha; el porqué de cada pieza está en la guía completa.

- Dificultad: principiante
- Proyecto: https://github.com/zcaceres/markdownify-mcp (licencia MIT)
- Guía completa: https://lab.wisd.ai/hub/markdownify-mcp

---

## Para el agente: cómo acompañar al usuario

1. Pregunta primero para qué lo quiere. Si su objetivo no necesita algún paso, sáltalo.
2. Antes de instalar, comprueba lo que ya tiene (versiones, claves, sistema operativo).
3. Avanza un paso cada vez: explica en una frase qué vas a hacer y deja que el usuario lo ejecute o lo apruebe.
4. Tras cada paso, comprueba que funcionó antes de seguir. Si falla, para y explica el error.
5. No inventes comandos ni opciones: si la documentación del proyecto contradice estos pasos, manda la documentación.
6. Al terminar, haz una prueba real con el objetivo del usuario y dile dónde profundizar.

---

## Pasos de configuración

Comprueba que Git, Bun, Node.js ≥22 (requisito de Repomix) y Python 3.11–3.14 con el módulo venv y pip están disponibles; el script `preinstall` usa Node para preparar MarkItDown. El [manifiesto Python](https://github.com/zcaceres/markdownify-mcp/blob/main/pyproject.toml) exige ≥3.11, aunque MarkItDown acepta ≥3.10. El instalador usa `python3 -m venv` y `.venv/bin/pip`: comprueba que `python3` es ese intérprete. El manifiesto principal no fija mínimos de Bun o Node, pero [Repomix](https://github.com/yamadashy/repomix/blob/main/package.json) exige Node ≥22.

```bash
git clone https://github.com/zcaceres/markdownify-mcp.git
cd markdownify-mcp
```

Desde su directorio raíz, el README indica:

```bash
bun install
bun run build
```

El resultado es `dist/index.js` y el entorno `.venv` con MarkItDown. Añade esta configuración al cliente MCP, sustituyendo ambas rutas por las de tu máquina:

```json
{
  "mcpServers": {
    "markdownify": {
      "command": "node",
      "args": ["/ruta/markdownify-mcp/dist/index.js"],
      "env": {"MD_ALLOWED_PATHS": "/ruta/documentos-de-prueba"}
    }
  }
}
```

Reinicia el cliente; este arranca el proceso por entrada/salida estándar. No hace falta dejar otro `bun start` abierto. Coloca un PDF no sensible en el directorio permitido y pide al agente que lo convierta con `pdf-to-markdown`, indicando su ruta absoluta. Acepta esa llamada y revisa el Markdown devuelto.

## Comprobación

Convierte un documento de prueba y revisa títulos, tablas y texto omitido.

## Si algo falla

Comprueba el entorno Python creado por preinstall y la ruta al conversor que usa el servidor.