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