MCP MD2PDF Server

Un sistema completo per convertire documenti Markdown in PDF con supporto per diagrammi Mermaid, utilizzabile sia come script standalone che come server MCP (Model Context Protocol).

🚀 Panoramica

Questo progetto offre due modalità d'uso:

🔧 Modalità Script Standalone

Utilizza direttamente lo scri## 🏗️ Struttura del Progetto

md2pdf/
├── mcp_md2pdf_server.py    # 🌐 Server MCP principale
├── convert.sh              # 🔧 Script conversione standalone
├── pandoc-wrapper.sh       # 🔄 Wrapper per Pandoc
├── requirements.txt        # 📦 Dipendenze Python
├── Dockerfile              # 🐳 Immagine Docker per conversione
├── install.sh              # ⚙️ Script di installazione automatica
├── test_both_modes.sh      # 🧪 Test completo entrambe modalità
├── start_server.sh         # 🚀 Script di avvio MCP (generato)
├── test_document.md        # 📄 Documento di test (generato)
└── README.md              # 📖 Questa documentazione

# Directory generate durante test/uso:
test_results/               # 📂 Risultati test automatici
├── test_document.md        # 📄 Documento test complesso
├── script_output.pdf       # 📑 Output modalità script  
├── mcp_content_output.pdf  # 📑 Output modalità MCP (contenuto)
├── mcp_file_output.pdf     # 📑 Output modalità MCP (file)
└── test_mcp.py            # 🐍 Script test MCP generato

📋 Descrizione File Principali

• mcp_md2pdf_server.py: Server MCP con API completa

• convert.sh: Script bash per conversioni dirette

• install.sh: Setup automatico di tutto il sistema

• test_both_modes.sh: Test completo che verifica entrambe le modalità

• Dockerfile: Ambiente Docker con Pandoc + Mermaid + LaTeX` per conversioni rapide:

• Conversione diretta da command line

• Nessuna configurazione MCP richiesta

• Perfetto per script automatizzati e CI/CD

• Utilizzo immediato senza server

🌐 Modalità Server MCP

Espone un server MCP con strumenti avanzati per:

• Integrazione con client MCP

• API programmatica per conversioni

• Gestione avanzata di contenuti e metadati

• Controllo granulare delle opzioni di conversione

✨ Funzionalità Comuni

Entrambe le modalità supportano:

• Conversione Markdown → PDF di alta qualità

• Supporto completo per diagrammi Mermaid

• Personalizzazione dell'output (formato carta, stili, indice)

• Gestione degli stili di syntax highlighting

• Rendering professionale con LaTeX

📋 Prerequisiti

• Python 3.7+ con pip

• Docker (per l'ambiente di conversione)

• Sistema operativo: Linux, macOS, Windows (con WSL)

🔧 Installazione

Installazione Automatica

Esegui lo script di installazione che configura tutto automaticamente:

./install.sh

Lo script:

1. ✅ Verifica Python e pip

2. 📦 Installa le dipendenze Python

3. � Verifica Docker

4. 🏗️ Costruisce l'immagine Docker per Pandoc/Mermaid

5. 🧪 Esegue test di funzionalità

6. 🚀 Crea script di avvio

7. 📝 Crea file di test

Installazione Manuale

Se preferisci installare manualmente:

1. Installa dipendenze Python:

   pip3 install -r requirements.txt

2. Costruisci l'immagine Docker:

   docker build -t pandoc-mermaid .

3. Rendi eseguibili gli script:

   chmod +x convert.sh start_server.sh

🏃 Utilizzo

🔧 Modalità Script Standalone

Utilizzare direttamente lo script di conversione:

# Conversione semplice
./convert.sh input.md output.pdf

# Conversione con file di esempio
./convert.sh test_document.md test_document.pdf

Vantaggi:

• ⚡ Veloce e immediato

• 🚀 Nessuna configurazione server

• 📝 Perfetto per script automatizzati

• 🔄 Ideale per CI/CD pipeline

🌐 Modalità Server MCP

Avvio del Server MCP

./start_server.sh

Oppure direttamente:

python3 mcp_md2pdf_server.py

Configurazione Client MCP

Il server si connette tramite stdio. Esempio di configurazione:

{
  "mcpServers": {
    "md2pdf": {
      "command": "python3",
      "args": ["/path/to/mcp_md2pdf_server.py"],
      "cwd": "/workspace/db-ready/md2pdf/"
    }
  }
}

Vantaggi:

• 🔌 Integrazione con client MCP

• 📊 API strutturata con response JSON

• 🎯 Controllo granulare dei parametri

• 📦 Gestione avanzata di contenuti e metadati

🎯 Quando Usare Quale Modalità

🔧 Usa la Modalità Script quando:

• ⚡ Hai bisogno di conversioni rapide e immediate

• 🔄 Stai automatizzando processi in script bash/shell

• 🏗️ Integri in pipeline CI/CD

• � Converti documenti occasionalmente

• 🖥️ Lavori principalmente da command line

• ⚙️ Vuoi il minimo overhead di setup

Esempio tipico:

# Nel tuo script di build
./convert.sh documentation.md docs/manual.pdf

🌐 Usa la Modalità MCP quando:

• 🔌 Ti integri con client MCP esistenti

• 📊 Hai bisogno di response strutturate JSON

• 🎛️ Vuoi controllo granulare sui parametri

• 📦 Gestisci metadati complessi (title, author, etc.)

• 🔄 Converti contenuti dinamici da applicazioni

• 🖥️ Sviluppi applicazioni che richiedono API

Esempio tipico:

# Nel tuo client MCP
result = await mcp_client.call_tool("convert_md_to_pdf", {
    "markdown_content": dynamic_content,
    "title": "Report Generato",
    "author": "Sistema Automatico"
})

📊 Confronto Modalità

🛠️ Strumenti Disponibili (Modalità MCP)

Il server MCP espone i seguenti strumenti:

1. convert_md_to_pdf

Converte contenuto Markdown in PDF.

Parametri:

• markdown_content (required): Il contenuto Markdown da convertire

• output_filename (optional): Nome del file PDF di output (default: "output.pdf")

• title (optional): Titolo del documento

• author (optional): Autore del documento

• papersize (optional): Formato carta (a4, letter, a3, legal, etc.) (default: "a4")

• toc (optional): Includere l'indice (default: true)

• highlight_style (optional): Stile di syntax highlighting (default: "pygments")

Esempio risposta:

{
  "success": true,
  "filename": "output.pdf",
  "size_bytes": 123456,
  "size_human": "120.6 KB",
  "pdf_base64": "JVBERi0xLjQK...",
  "message": "✅ PDF generato con successo"
}

2. convert_md_file_to_pdf

Converte un file Markdown esistente in PDF.

Parametri:

• input_path (required): Percorso del file Markdown di input

• output_path (optional): Percorso del file PDF di output

• title, author, papersize, toc, highlight_style: Come sopra

Esempio risposta:

{
  "success": true,
  "output_path": "/path/to/output.pdf",
  "filename": "output.pdf",
  "size_bytes": 123456,
  "size_human": "120.6 KB",
  "message": "✅ PDF salvato in: /path/to/output.pdf"
}

3. list_highlight_styles

Elenca gli stili di syntax highlighting disponibili.

Esempio risposta:

{
  "success": true,
  "styles": ["pygments", "kate", "monochrome", "breezeDark", ...],
  "count": 25
}

4. get_pandoc_info

Ottiene informazioni sulla versione di Pandoc e funzionalità disponibili.

Esempio risposta:

{
  "success": true,
  "pandoc_version": "pandoc 3.1.11",
  "pdf_engines": ["pdflatex", "xelatex", "lualatex"],
  "mermaid_filter_available": true
}

� Esempi Pratici

🔧 Script Mode - Esempi Command Line

# Conversione base
./convert.sh document.md document.pdf

# Conversione con file di documentazione
./convert.sh README.md manual.pdf

# Batch conversion (esempio script)
for file in *.md; do
    ./convert.sh "$file" "${file%.md}.pdf"
done

# Integrazione in Makefile
docs: 
	./convert.sh docs/api.md dist/api-manual.pdf
	./convert.sh docs/guide.md dist/user-guide.pdf

🌐 MCP Mode - Esempi Programmatici

Conversione contenuto dinamico:

import asyncio
from mcp_md2pdf_server import convert_md_to_pdf

async def generate_report():
    content = f"""
# Report Giornaliero
Data: {datetime.now().strftime('%Y-%m-%d')}

## Statistiche
- Utenti attivi: {get_active_users()}
- Vendite: {get_sales_data()}
"""
    
    result = await convert_md_to_pdf(
        markdown_content=content,
        output_filename="daily_report.pdf",
        title="Report Giornaliero",
        author="Sistema Automatico"
    )
    
    return result

Integrazione con client MCP:

{
  "tool": "convert_md_file_to_pdf",
  "arguments": {
    "input_path": "/docs/specification.md",
    "output_path": "/output/spec_v2.pdf",
    "title": "API Specification v2.0",
    "author": "Development Team",
    "papersize": "a4",
    "toc": true
  }
}

📊 Supporto Mermaid

Il server supporta completamente i diagrammi Mermaid. Esempi di diagrammi supportati:

Flowchart

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Sequence Diagram

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob, how are you?
    B-->>A: Great!

Gantt Chart

gantt
    title A Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2014-01-01, 30d
    Another task     :after a1  , 20d

�️ Struttura del Progetto

md2pdf/
├── mcp_md2pdf_server.py    # Server MCP principale
├── requirements.txt        # Dipendenze Python
├── Dockerfile             # Immagine Docker per conversione
├── convert.sh             # Script di conversione
├── pandoc-wrapper.sh      # Wrapper per Pandoc
├── install.sh             # Script di installazione
├── start_server.sh        # Script di avvio (generato)
├── test_document.md       # Documento di test (generato)
└── README.md             # Questa documentazione

🐳 Ambiente Docker

L'ambiente Docker include:

• Ubuntu 22.04 come base

• Pandoc 3.1.11 per la conversione

• Node.js 18.x per mermaid-filter

• TeX Live per la generazione PDF

• Google Chrome per il rendering Mermaid

• mermaid-filter e @mermaid-js/mermaid-cli

⚙️ Configurazione

Variabili d'Ambiente Docker

Il container utilizza:

• PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true

• PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome-stable

• PUPPETEER_ARGS="--no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage --disable-gpu"

Opzioni di Conversione

Il sistema supporta:

• Formati carta: a4, letter, a3, legal, etc.

• Stili highlighting: pygments, kate, monochrome, breezeDark, etc.

• Engines PDF: pdflatex, xelatex, lualatex

• Opzioni layout: margini personalizzabili, indice, numerazione pagine

🔍 Troubleshooting

Errori Comuni

1. Docker non in esecuzione

   Errore: Docker daemon non in esecuzione
   Soluzione: Avvia Docker Desktop o il daemon Docker

2. Immagine Docker non trovata

   Errore: Unable to find image 'pandoc-mermaid:latest'
   Soluzione: Ricostruisci l'immagine con: docker build -t pandoc-mermaid .

3. Errori di conversione Mermaid

   Errore: mermaid-filter non trovato
   Soluzione: Ricostruisci l'immagine Docker per installare mermaid-filter

4. Problemi di permessi

   Errore: Permission denied
   Soluzione: Verifica i permessi dei file e directory

Debug

Per debug dettagliato, modifica convert.sh aggiungendo:

set -x  # Abilita debug verbose

Log

Il server MCP scrive su stdout/stderr. Per salvare i log:

python3 mcp_md2pdf_server.py 2>&1 | tee server.log

🧪 Testing

Test Script Standalone

1. Test conversione diretta con script:

   # Test con documento di esempio
   ./convert.sh test_document.md test_output.pdf
   
   # Test con contenuto personalizzato
   echo "# Test Document" > my_test.md
   ./convert.sh my_test.md my_test.pdf

2. Test con diagrammi Mermaid:

   cat > mermaid_test.md << 'EOF'
   # Test Mermaid
   
   ```mermaid
   graph TD
       A[Start] --> B[End]

   EOF

   ./convert.sh mermaid_test.md mermaid_test.pdf

Test Server MCP

1. Test server MCP programmatico:

   python3 -c "
   from mcp_md2pdf_server import convert_md_to_pdf
   import asyncio
   result = asyncio.run(convert_md_to_pdf('# Test MCP'))
   print(result)
   "

2. Test avvio server:

   # Avvia server in background per test
   python3 mcp_md2pdf_server.py &
   SERVER_PID=$!
   
   # Attendi avvio e poi chiudi
   sleep 2
   kill $SERVER_PID

Test Completo Sistema

1. Verifica Docker:

   # Verifica che l'immagine sia stata costruita
   docker images | grep pandoc-mermaid
   
   # Test dell'immagine
   docker run --rm pandoc-mermaid pandoc --version

2. Test integrazione completa:

   # Crea documento di test complesso
   cat > full_test.md << 'EOF'
   # Test Completo
   
   ## Sezione Code
   ```python
   print("Hello World")

   Sezione Mermaid

   sequenceDiagram
       Alice->>Bob: Hello
       Bob-->>Alice: Hi!

   EOF

   Test script

   ./convert.sh full_test.md full_test_script.pdf

   Test MCP (se server è in esecuzione)

   Confronta i risultati

3. Test automatico completo (Entrambe le modalità):

   # Esegue test completo di entrambe le modalità
   ./test_both_modes.sh

   Questo script:

   • ✅ Testa conversione con script convert.sh

   • ✅ Testa conversione con server MCP

   • 📊 Confronta i risultati di entrambe le modalità

   • 🔍 Verifica l'integrazione Docker

   • 📈 Genera report dettagliato dei test

   • 📂 Salva tutti i file di test in test_results/

🤝 Contribuire

1. Fork del repository

2. Crea un branch per la feature (git checkout -b feature/AmazingFeature)

3. Commit delle modifiche (git commit -m 'Add some AmazingFeature')

4. Push al branch (git push origin feature/AmazingFeature)

5. Apri una Pull Request

📄 Licenza

Questo progetto è distribuito sotto licenza MIT. Vedi il file LICENSE per i dettagli.

🆘 Supporto

Per problemi o domande:

1. Controlla la sezione Troubleshooting

2. Verifica che tutti i prerequisiti siano installati

3. Esegui il test di installazione con ./install.sh

4. Apri un issue su GitHub con i dettagli dell'errore

🔄 Aggiornamenti

Per aggiornare il sistema:

1. Ferma il server MCP

2. Fai il pull delle modifiche

3. Ricostruisci l'immagine Docker: docker build -t pandoc-mermaid .

4. Riavvia il server

Versione: 1.0.0
Ultimo aggiornamento: $(date +%Y-%m-%d)