DocFiller

Sistema modular para rellenar plantillas DOCX/ODT y generar PDFs usando Model Context Protocol (MCP) 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

# 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

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.

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:

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

cd mcp-adaptado

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

Ejecución

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:

   ollama serve
   

   (En otra terminal)

Ejecución

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:

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

# 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

# Verificar que está corriendo
ollama serve

# Descargar modelo si falta
ollama pull mistral

Port 8501 ya en uso (Streamlit)

streamlit run app.py --server.port 8502

---

📚 API Reference

Herramientas MCP

listar_variables_plantilla(template_path="")

Analiza una plantilla y devuelve sus variables.

Respuesta:

{
  "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:

{
  "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:

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

---

📄 Recursos

• Model Context Protocol
• Streamlit Documentation
• OpenAI API
• Ollama

---

📝 Licencia

MIT - Libre para uso personal y comercial.

---

🤝 Soporte

Para issues o consultas, contactar al equipo de desarrollo.