# DocFiller - Sistema de Generación de PDFs desde Plantillas

Sistema modular para rellenar plantillas DOCX/ODT y generar PDFs usando [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) con diferentes backends (OpenAI, Ollama local).

## 📁 Estructura del Proyecto

```
mcp-server/
├── mcp-sse/                 # Servidor MCP puro (SSE transport)
├── mcp-adaptado/            # Streamlit + OpenAI
├── mcp-adaptado-ollama/     # Streamlit + Ollama (modelos locales)
└── requirements.txt         # Dependencias compartidas
```

Cada módulo contiene:
- `server.py` - Servidor MCP
- `client.py` - Cliente MCP
- `app.py` - Interfaz Streamlit (en mcp-adaptado y mcp-adaptado-ollama)
- `templates/` - Plantillas DOCX/ODT con variables `$campo$`
- `outputs/` - PDFs generados
- `resources/` - Guías y documentación

## 🚀 Requisitos Previos

- **Python 3.9+**
- **LibreOffice** (para conversión a PDF)
  - Windows: `choco install libreoffice` o descargar desde https://www.libreoffice.org/
  - macOS: `brew install libreoffice`
  - Linux: `sudo apt install libreoffice`

### Opcional (según el módulo)
- **OpenAI API key** (para `mcp-adaptado`)
- **Ollama** (para `mcp-adaptado-ollama`) - https://ollama.ai/

## 📦 Instalación

### 1. Clonar el repositorio y crear entorno virtual

```bash
# Clonar o descargar el proyecto
cd mcp-server

# Crear entorno virtual
python -m venv venv

# Activar entorno virtual
# En Windows:
venv\Scripts\activate
# En macOS/Linux:
source venv/bin/activate
```

### 2. Instalar dependencias

```bash
pip install -r requirements.txt
```

## 🎯 Uso por Módulo

### **opción 1: mcp-sse (Servidor MCP puro)**

Servidor MCP que expone herramientas para rellenar plantillas y generar PDFs.

```bash
cd mcp-sse

# Ejecutar servidor
python server.py
```

El servidor expone las siguientes herramientas:
- `listar_variables_plantilla(template_path)` - Listar variables de una plantilla
- `validar_datos_plantilla(datos, template_path)` - Validar datos
- `generar_pdf_desde_plantilla(output_pdf_path, datos, template_path)` - Generar PDF

**Ejemplo con cliente MCP:**

```python
from client import DocFillerClient

client = DocFillerClient("http://localhost:8000")

# Listar variables
variables = client.listar_variables_plantilla()

# Generar PDF
result = client.generar_pdf_desde_plantilla(
    output_pdf_path="resultado.pdf",
    datos={"nombre": "Juan", "fecha": "2026-06-17"}
)
```

---

### **Opción 2: mcp-adaptado (Streamlit + OpenAI)**

Interfaz web completa con OpenAI como LLM.

#### Configuración

```bash
cd mcp-adaptado

# Crear archivo .env
cat > .env << EOF
OPENAI_API_KEY=sk-your-key-here
EOF
```

#### Ejecución

```bash
streamlit run app.py
```

Abre http://localhost:8501 en tu navegador.

---

### **Opción 3: mcp-adaptado-ollama (Streamlit + Ollama)**

Interfaz web con modelos locales vía Ollama (privacidad total, sin APIs externas).

#### Configuración

1. **Instalar Ollama:**
   - Descargar desde https://ollama.ai/
   - Ejecutar: `ollama pull mistral` (o tu modelo preferido)

2. **Verificar que Ollama está corriendo:**
   ```bash
   ollama serve
   ```
   (En otra terminal)

#### Ejecución

```bash
cd mcp-adaptado-ollama

# Crear archivo .env (opcional)
cat > .env << EOF
OLLAMA_API_URL=http://localhost:11434
EOF

# Ejecutar app
streamlit run app.py
```

Abre http://localhost:8501 en tu navegador.

---

## 📋 Crear Plantillas

Las plantillas usan la sintaxis `$VARIABLE$` para campos reemplazables.

### Ejemplo DOCX

```
Nombre: $nombre$
Fecha: $fecha$
Total: $total$
```

### Pasos

1. Abre Word o LibreOffice
2. Crea un documento con variables en formato `$campo_nombre$`
3. Guarda como `.docx` o `.odt` en `[modulo]/templates/`
4. La herramienta detectará automáticamente las variables

**Importante:** Los nombres de variables deben ser:
- Alfanuméricos y guiones bajos: `[A-Za-z0-9_]`
- Sin espacios ni caracteres especiales
- Máximo 200 variables por plantilla

---

## 🔧 Configuración Avanzada

### Variables de entorno

Crear `.env` en el directorio del módulo:

```bash
# Para mcp-adaptado
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini  # o tu modelo preferido

# Para mcp-adaptado-ollama
OLLAMA_API_URL=http://localhost:11434
OLLAMA_MODEL=mistral  # o tu modelo

# Global
DEBUG=true
```

### Límites configurables

En `server.py`:
- `MAX_TEMPLATE_MB` - Tamaño máximo de plantilla (default: 20 MB)
- `MAX_VARIABLES` - Máximo de variables por plantilla (default: 200)
- `LIBREOFFICE_TIMEOUT` - Timeout de conversión (default: 60s)

---

## 🐛 Solución de Problemas

### "LibreOffice no encontrado"
```bash
# Windows
choco install libreoffice

# macOS
brew install libreoffice

# Linux (Debian/Ubuntu)
sudo apt install libreoffice
```

### Error de conversión a PDF
```
LibreOffice superó el límite de 60s
```
- Aumentar `LIBREOFFICE_TIMEOUT` en `server.py`
- Verificar que LibreOffice no tiene otras instancias corriendo

### Ollama no responde
```bash
# Verificar que está corriendo
ollama serve

# Descargar modelo si falta
ollama pull mistral
```

### Port 8501 ya en uso (Streamlit)
```bash
streamlit run app.py --server.port 8502
```

---

## 📚 API Reference

### Herramientas MCP

#### `listar_variables_plantilla(template_path="")`
Analiza una plantilla y devuelve sus variables.

**Respuesta:**
```json
{
  "estado": "exito",
  "plantilla": "/ruta/a/plantilla.docx",
  "formato": ".docx",
  "variables": ["nombre", "fecha", "total"],
  "total": 3
}
```

#### `validar_datos_plantilla(datos, template_path="")`
Valida que los datos cubran todas las variables.

**Respuesta:**
```json
{
  "estado": "exito",
  "valido": true,
  "variables_requeridas": ["nombre", "fecha"],
  "faltantes": [],
  "sobrantes": ["extra"],
  "valores_vacios": []
}
```

#### `generar_pdf_desde_plantilla(output_pdf_path, datos, template_path="")`
Rellena la plantilla y genera un PDF.

**Respuesta:**
```json
{
  "estado": "exito",
  "pdf": "/ruta/a/outputs/resultado.pdf",
  "motor_conversion": "libreoffice",
  "variables_sin_reemplazar": []
}
```

---

## 📄 Recursos

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Streamlit Documentation](https://docs.streamlit.io/)
- [OpenAI API](https://platform.openai.com/docs)
- [Ollama](https://ollama.ai/)

---

## 📝 Licencia

MIT - Libre para uso personal y comercial.

---

## 🤝 Soporte

Para issues o consultas, contactar al equipo de desarrollo.