Pandoc

Incluido oficialmente en el proyecto de código abierto servidores del Model Context Protocol. 🎉

Resumen

Un servidor del Model Context Protocol para la conversión de formatos de documentos utilizando pandoc. Este servidor proporciona herramientas para transformar contenido entre diferentes formatos de documentos preservando el formato y la estructura.

Tenga en cuenta que mcp-pandoc se encuentra actualmente en desarrollo temprano. El soporte para PDF está en desarrollo, y la funcionalidad y las herramientas disponibles están sujetas a cambios y expansión a medida que continuamos mejorando el servidor.

Crédito: Este proyecto utiliza el paquete Python de Pandoc para la conversión de documentos, formando la base de este proyecto.

📋 Referencia Rápida

¿Nuevo en mcp-pandoc? Consulte 📖 CHEATSHEET.md para

• ⚡ Ejemplos de copiar y pegar para todos los formatos
• 🔄 Matriz de conversión bidireccional
• 🎯 Flujos de trabajo comunes y consejos profesionales
• 🌟 Guía de estilo de documentos de referencia

¡Perfecto para consultas rápidas y comenzar rápidamente!

Demostración

🎥 Ver en YouTube

Capturas de pantalla

Más por venir...

Herramientas

1. convert-contents

   • Transforma contenido entre formatos compatibles

   • Entradas:

     • contents (cadena): Contenido fuente a convertir (requerido si no se proporciona input_file)
     • input_file (cadena): Ruta completa al archivo de entrada (requerido si no se proporciona contents)
     • input_format (cadena): Formato fuente del contenido (por defecto markdown)
     • output_format (cadena): Formato destino (por defecto markdown)
     • output_file (cadena): Ruta completa para el archivo de salida (requerido para formatos pdf, docx, rst, latex, epub, odt, pptx)
     • reference_doc (cadena): Ruta a un documento de referencia para usar como estilo (compatible con salida docx, odt y pptx; el archivo debe coincidir con el formato de salida)
     • defaults_file (cadena): Ruta a un archivo de valores predeterminados de Pandoc (YAML) que contiene opciones de conversión
     • filters (matriz): Lista de rutas de filtros de Pandoc para aplicar durante la conversión

   • Formatos compatibles, por dirección:

     Formato	Leer	Escribir
     markdown	✅	✅
     html	✅	✅
     docx	✅	✅
     odt	✅	✅
     rst	✅	✅
     latex	✅	✅
     epub	✅	✅
     ipynb	✅	✅
     txt	✅	✅
     pdf	❌	✅
     pptx	❌	✅

   • Nota: Para formatos avanzados (pdf, docx, rst, latex, epub, odt, pptx), se requiere una ruta de archivo de salida

🔧 Funciones Avanzadas

Archivos de Valores Predeterminados (Configuración YAML)

Use archivos de valores predeterminados para crear plantillas de conversión reutilizables con formato consistente:

# academic-paper.yaml
from: markdown
to: pdf
number-sections: true
toc: true
metadata:
  title: "Academic Paper"
  author: "Research Team"

Ejemplo de uso: "Convert paper.md to PDF using defaults academic-paper.yaml and save as paper.pdf"

Filtros de Pandoc

Aplique filtros personalizados para un procesamiento mejorado:

Ejemplo de uso: "Convert docs.md to HTML with filters ['/path/to/mermaid-filter.py'] and save as docs.html"

💡 Para ejemplos completos y flujos de trabajo, consulte CHEATSHEET.md

📊 Formatos y Conversiones Compatibles

Matriz de Conversión Bidireccional

Las filas son formatos fuente, las columnas son destinos. PDF y PPTX no tienen filas porque pandoc no puede leerlos.

Nota sobre Formatos de Solo Escritura

PDF y PPTX se pueden producir pero no leer.

Pandoc nunca ha incluido un lector de PDF. Pandoc obtuvo un lector de PowerPoint en 3.8.3 (lanzado el 2025-12-01), pero este proyecto no declara una versión mínima de pandoc, y Ubuntu 24.04 aún incluye pandoc 3.1.3, por lo que la entrada pptx no se ofrece. Se rastrea en #54 y #49.

La salida PPTX no requiere una versión específica de pandoc. El escritor de PowerPoint existe desde pandoc 2.0.5.

Categorías de Formatos

Requisitos por Formato

• PDF (.pdf) - requiere instalación de TeX Live
• DOCX (.docx), ODT (.odt), PPTX (.pptx) - admiten estilo personalizado mediante documentos de referencia, y la referencia debe ser del mismo formato que la salida
• Todos los demás - sin requisitos adicionales

Nota: Para formatos avanzados:

1. Se requieren rutas de archivo completas con nombre de archivo y extensión
2. La conversión a PDF requiere instalación de TeX Live (consulte la sección Requisitos Críticos -> Para macOS: brew install texlive)
3. Cuando no se especifica una ruta de salida:
   • Formatos básicos: Muestra el contenido convertido en el chat
   • Formatos avanzados: Puede guardar en el directorio temporal del sistema (/tmp/ en sistemas Unix)

Uso y configuración

NOTA: Asegúrese de completar la instalación de los paquetes requeridos mencionados a continuación en "Requisitos Críticos".

Para usar la versión publicada

{
  "mcpServers": {
    "mcp-pandoc": {
      "command": "uvx",
      "args": ["mcp-pandoc"]
    }
  }
}

💡 Inicio Rápido: Consulte CHEATSHEET.md para ejemplos de copiar y pegar y flujos de trabajo comunes.

⚠️ Notas Importantes

Requisitos Críticos

1. Instalación de Pandoc

• Requerido: Instale pandoc - el motor central de conversión de documentos

• Instalación:

  # macOS
  brew install pandoc
  
  # Ubuntu/Debian
  sudo apt-get install pandoc
  
  # Windows
  # Download installer from: https://pandoc.org/installing.html
  

• Verificar: pandoc --version

2. Instalación del paquete UV

• Requerido: Instale el paquete uv (incluye el comando uvx)

• Instalación:

  # macOS
  brew install uv
  
  # Windows/Linux
  pip install uv
  

• Verificar: uvx --version

3. Requisitos previos para conversión a PDF: Solo necesarios si necesita convertir y guardar PDF

• TeX Live debe estar instalado antes de intentar la conversión a PDF

• Comandos de instalación:

  # Ubuntu/Debian
  sudo apt-get install texlive-xetex
  
  # macOS
  brew install texlive
  
  # Windows
  # Install MiKTeX or TeX Live from:
  # https://miktex.org/ or https://tug.org/texlive/
  

4. Requisitos de Ruta de Archivo

• Al guardar o convertir archivos, DEBE proporcionar rutas de archivo completas incluyendo nombre de archivo y extensión
• La herramienta no genera automáticamente nombres de archivo o extensiones

Ejemplos

✅ Uso Correcto:

# Converting content to PDF
"Convert this text to PDF and save as /path/to/document.pdf"

# Converting between file formats
"Convert /path/to/input.md to PDF and save as /path/to/output.pdf"

# Converting to DOCX with a reference document template
"Convert input.md to DOCX using template.docx as reference and save as output.docx"

# Converting to ODT with a reference document template
"Convert input.md to ODT using template.odt as reference and save as output.odt"

# Converting to a branded PowerPoint deck
"Convert slides.md to PPTX using template.pptx as reference and save as deck.pptx"

# Step-by-step reference document workflow
"First create a reference document: pandoc -o custom-reference.docx --print-default-data-file reference.docx" or if you already have one, use that
"Then convert with custom styling: Convert this text to DOCX using /path/to/custom-reference.docx as reference and save as /path/to/styled-output.docx"

❌ Uso Incorrecto:

# Missing filename and extension
"Save this as PDF in /documents/"

# Missing complete path
"Convert this to PDF"

# Missing extension
"Save as /documents/story"

Problemas Comunes y Soluciones

1. La Conversión a PDF Falla

   • Error: "xelatex no encontrado"
   • Solución: Instale TeX Live primero (consulte los comandos de instalación anteriores)

2. La Conversión de Archivos Falla

   • Error: "Ruta de archivo no válida"
   • Solución: Proporcione la ruta completa incluyendo nombre de archivo y extensión
   • Ejemplo: /path/to/document.pdf en lugar de solo /path/to/

3. La Conversión de Formato Falla

   • Error: "Formato no compatible"
   • Solución: Use solo formatos compatibles:
     • Básicos: txt, html, markdown
     • Avanzados: pdf, docx, rst, latex, epub

4. Problemas con Documentos de Referencia

   • Error: "Documento de referencia no encontrado"
   • Solución: Asegúrese de que la ruta del documento de referencia exista y sea accesible
   • Error: "reference_doc debe ser un archivo '.odt' cuando output_format es 'odt'"
   • Solución: El documento de referencia debe ser del mismo formato que la salida. Pandoc no lo verifica por sí mismo: una referencia no coincidente se ignora silenciosamente para la salida DOCX y produce un archivo ODT que no se puede abrir
   • Nota: Los documentos de referencia funcionan con formatos de salida DOCX, ODT y PPTX
   • Cómo crear: pandoc -o reference.docx --print-default-data-file reference.docx, y de manera similar con reference.odt o reference.pptx

Inicio Rápido

Instalación manual mediante el archivo de configuración claude_desktop_config.json

• En MacOS: open ~/Library/Application\ Support/Claude/claude_desktop_config.json
• En Windows: %APPDATA%/Claude/claude_desktop_config.json

a) Solo para desarrollo local y contribución a este repositorio

"mcpServers": {
  "mcp-pandoc": {
    "command": "uv",
    "args": [
      "--directory",
      "<DIRECTORY>/mcp-pandoc",
      "run",
      "mcp-pandoc"
    ]
  }
}

b) Configuración de Servidores Publicados - Los consumidores deben usar esta configuración

"mcpServers": {
  "mcp-pandoc": {
    "command": "uvx",
    "args": [
      "mcp-pandoc"
    ]
  }
}

• Si tiene algún problema, use la "Configuración de Servidores Publicados" anterior directamente en lugar de esta cli.

Nota: Para usar mcp-pandoc configurado localmente, siga el paso "Configuración de Servidores de Desarrollo/No Publicados" anterior.

Desarrollo

Pruebas

Para ejecutar la suite de pruebas completa y validar todas las conversiones bidireccionales compatibles, use el siguiente comando:

uv run pytest tests/test_conversions.py

Esto garantiza la compatibilidad hacia atrás y verifica la funcionalidad principal de la herramienta.

Compilación y Publicación

Para preparar el paquete para distribución:

1. Sincronice las dependencias y actualice el archivo de bloqueo:

uv sync

2. Compile las distribuciones del paquete:

uv build

Esto creará distribuciones de fuente y rueda en el directorio dist/.

3. Publique en PyPI:

uv publish

Nota: Necesitará configurar las credenciales de PyPI mediante variables de entorno o banderas de comando:

• Token: --token o UV_PUBLISH_TOKEN
• O nombre de usuario/contraseña: --username/UV_PUBLISH_USERNAME y --password/UV_PUBLISH_PASSWORD

Depuración

Dado que los servidores MCP se ejecutan sobre stdio, la depuración puede ser desafiante. Para la mejor experiencia de depuración, recomendamos encarecidamente usar el Inspector MCP.

Puede lanzar el Inspector MCP mediante npm con este comando:

npx @modelcontextprotocol/inspector uv --directory /Users/vivekvells/Desktop/code/ai/mcp-pandoc run mcp-pandoc

Al lanzarlo, el Inspector mostrará una URL que puede acceder en su navegador para comenzar la depuración.

Contribuciones

¡Damos la bienvenida a contribuciones para mejorar mcp-pandoc! Así es como puede participar:

1. Reportar Problemas: ¿Encontró un error o tiene una solicitud de función? Abra un problema en nuestra página de Problemas de GitHub.
2. Enviar Solicitudes de Extracción: Mejore el código base o agregue funciones creando una solicitud de extracción.