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:

✅ Verifica Python e pip
📦 Installa le dipendenze Python
� Verifica Docker
🏗️ Costruisce l'immagine Docker per Pandoc/Mermaid
🧪 Esegue test di funzionalità
🚀 Crea script di avvio
📝 Crea file di test

Installazione Manuale

Se preferisci installare manualmente:

Installa dipendenze Python:
```
pip3 install -r requirements.txt
```
Costruisci l'immagine Docker:
```
docker build -t pandoc-mermaid .
```
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à

Aspetto	🔧 Script	🌐 MCP
Setup	Immediato	Configurazione client
Velocità	⚡ Velocissimo	🔧 Configurabile
Output	File PDF	JSON + PDF base64
Integrazione	Shell/Bash	Programmatica
Metadati	Limitati	Completi
Error Handling	Exit codes	JSON structured
Uso Tipico	Batch/Automation	Applications/Services

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

Docker non in esecuzione

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

Immagine Docker non trovata

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

Errori di conversione Mermaid

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

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

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

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

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

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

Verifica Docker:

# Verifica che l'immagine sia stata costruita
docker images | grep pandoc-mermaid

# Test dell'immagine
docker run --rm pandoc-mermaid pandoc --version

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

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

Fork del repository
Crea un branch per la feature (git checkout -b feature/AmazingFeature)
Commit delle modifiche (git commit -m 'Add some AmazingFeature')
Push al branch (git push origin feature/AmazingFeature)
Apri una Pull Request

📄 Licenza

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

🆘 Supporto

Per problemi o domande:

Controlla la sezione Troubleshooting
Verifica che tutti i prerequisiti siano installati
Esegui il test di installazione con ./install.sh
Apri un issue su GitHub con i dettagli dell'errore

🔄 Aggiornamenti

Per aggiornare il sistema:

Ferma il server MCP
Fai il pull delle modifiche
Ricostruisci l'immagine Docker: docker build -t pandoc-mermaid .
Riavvia il server

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

MCP MD2PDF Server

MCP MD2PDF Server

🚀 Panoramica

🔧 Modalità Script Standalone

📋 Descrizione File Principali

🌐 Modalità Server MCP

✨ Funzionalità Comuni

📋 Prerequisiti

🔧 Installazione

Installazione Automatica

Installazione Manuale

🏃 Utilizzo

🔧 Modalità Script Standalone

🌐 Modalità Server MCP

Avvio del Server MCP

Configurazione Client MCP

🎯 Quando Usare Quale Modalità

🔧 Usa la Modalità Script quando:

🌐 Usa la Modalità MCP quando:

📊 Confronto Modalità

🛠️ Strumenti Disponibili (Modalità MCP)

1. convert_md_to_pdf

2. convert_md_file_to_pdf

3. list_highlight_styles

4. get_pandoc_info

� Esempi Pratici

🔧 Script Mode - Esempi Command Line

🌐 MCP Mode - Esempi Programmatici

📊 Supporto Mermaid

Flowchart

Sequence Diagram

Gantt Chart

�️ Struttura del Progetto

🐳 Ambiente Docker

⚙️ Configurazione

Variabili d'Ambiente Docker

Opzioni di Conversione

🔍 Troubleshooting

Errori Comuni

Debug

Log

🧪 Testing

Test Script Standalone

Test Server MCP

Test Completo Sistema

Sezione Mermaid

Test script

Test MCP (se server è in esecuzione)

Confronta i risultati

🤝 Contribuire

📄 Licenza

🆘 Supporto

🔄 Aggiornamenti

Reviews

1. `convert_md_to_pdf`

2. `convert_md_file_to_pdf`

3. `list_highlight_styles`

4. `get_pandoc_info`