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

📋 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:

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:

Vantaggi:

• ⚡ Veloce e immediato

• 🚀 Nessuna configurazione server

• 📝 Perfetto per script automatizzati

• 🔄 Ideale per CI/CD pipeline

🌐 Modalità Server MCP

Avvio del Server MCP

Oppure direttamente:

Configurazione Client MCP

Il server si connette tramite stdio. Esempio di configurazione:

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:

🌐 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:

📊 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:

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:

3. list_highlight_styles

Elenca gli stili di syntax highlighting disponibili.

Esempio risposta:

4. get_pandoc_info

Ottiene informazioni sulla versione di Pandoc e funzionalità disponibili.

Esempio risposta:

� Esempi Pratici

🔧 Script Mode - Esempi Command Line

🌐 MCP Mode - Esempi Programmatici

Conversione contenuto dinamico:

Integrazione con client MCP:

📊 Supporto Mermaid

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

Flowchart

Sequence Diagram

Gantt Chart

�️ Struttura del Progetto

🐳 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:

Log

Il server MCP scrive su stdout/stderr. Per salvare i 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)