# 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:
```bash
./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:**
```bash
pip3 install -r requirements.txt
```
2. **Costruisci l'immagine Docker:**
```bash
docker build -t pandoc-mermaid .
```
3. **Rendi eseguibili gli script:**
```bash
chmod +x convert.sh start_server.sh
```
## 🏃 Utilizzo
### 🔧 Modalità Script Standalone
Utilizzare direttamente lo script di conversione:
```bash
# 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
```bash
./start_server.sh
```
Oppure direttamente:
```bash
python3 mcp_md2pdf_server.py
```
#### Configurazione Client MCP
Il server si connette tramite stdio. Esempio di configurazione:
```json
{
"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:**
```bash
# 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:**
```python
# 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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"success": true,
"styles": ["pygments", "kate", "monochrome", "breezeDark", ...],
"count": 25
}
```
### 4. `get_pandoc_info`
Ottiene informazioni sulla versione di Pandoc e funzionalità disponibili.
**Esempio risposta:**
```json
{
"success": true,
"pandoc_version": "pandoc 3.1.11",
"pdf_engines": ["pdflatex", "xelatex", "lualatex"],
"mermaid_filter_available": true
}
```
## � Esempi Pratici
### 🔧 Script Mode - Esempi Command Line
```bash
# 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:**
```python
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:**
```json
{
"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
```mermaid
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
C --> E[End]
D --> E
```
### Sequence Diagram
```mermaid
sequenceDiagram
participant A as Alice
participant B as Bob
A->>B: Hello Bob, how are you?
B-->>A: Great!
```
### Gantt Chart
```mermaid
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:
```bash
set -x # Abilita debug verbose
```
### Log
Il server MCP scrive su stdout/stderr. Per salvare i log:
```bash
python3 mcp_md2pdf_server.py 2>&1 | tee server.log
```
## 🧪 Testing
### Test Script Standalone
1. **Test conversione diretta con script:**
```bash
# 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:**
```bash
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:**
```bash
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:**
```bash
# 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:**
```bash
# 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:**
```bash
# Crea documento di test complesso
cat > full_test.md << 'EOF'
# Test Completo
## Sezione Code
```python
print("Hello World")
```
## Sezione Mermaid
```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à):**
```bash
# 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](#-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)
