Deck Builder MCP

Crear y manipular presentaciones de PowerPoint programáticamente usando JSON o Markdown.

Documentación

[!IMPORTANT]
Deckbuilder está actualmente en desarrollo activo y NO debe considerarse listo para producción.

🎯 Deckbuilder

Crea presentaciones profesionales de PowerPoint desde Markdown o JSON

Deckbuilder es una biblioteca de Python, una herramienta de línea de comandos y un servidor MCP que genera presentaciones de PowerPoint a partir de contenido estructurado. Concéntrate en tu contenido: Deckbuilder se encarga del formato y el diseño.

✨ Características principales

🚀 Generación de presentaciones en un solo paso

Crea presentaciones completas de PowerPoint desde JSON o Markdown con frontmatter YAML en un solo comando.

🎨 Soporte de contenido enriquecido

Formato avanzado: **bold**, *italic*, ___underline___, ***bold italic***
Actualización de idioma y fuentes: La capacidad de actualizar las fuentes y el idioma de todos los objetos de las diapositivas mediante las herramientas de línea de comandos usando la CLI.
Tablas profesionales: Estilo personalizado con temas, colores y controles precisos de dimensiones (anchos de columna, alturas de fila, tamaño de tabla).
Diseños compatibles: Biblioteca progresiva de plantillas que se va añadiendo.

🧠 Sistema de plantillas inteligente

Selección inteligente de diseño: Recomendaciones automáticas de diseño según el tipo de contenido
Arquitectura basada en patrones: Personaliza cualquier diseño con tus propias plantillas
Soporte de contenido enriquecido: Tablas, imágenes, diseños de varias columnas con estilo profesional

🖼️ Procesamiento inteligente de imágenes

Reemplazos automáticos de imágenes: ¿Faltan imágenes? Deckbuilder genera marcadores de posición profesionales automáticamente
Recorte inteligente: Detección de rostros y composición inteligente para un dimensionamiento perfecto de imágenes
Filtros profesionales: Estilo apropiado para negocios con escala de grises y otros efectos

⚡ Experiencia CLI mejorada

Interfaz jerárquica profesional: Estructura de comandos limpia (deckbuilder <command> <subcommand>)
Configuración con un comando: deckbuilder init crea plantillas y configuración
Rutas sensibles al contexto: precedencia de argumentos CLI > variables de entorno > directorio actual
Salida siempre local: la CLI genera en el directorio actual para un desarrollo local predecible
Argumentos globales: -t/--template-folder, -l/--language, -f/--font para una personalización completa
Estructura de comandos completa:
- deckbuilder template → analyze, validate, document, enhance, list
- deckbuilder config → show, languages, completion
- deckbuilder image → generate, crop
- deckbuilder remap → actualizar archivos PowerPoint existentes con cambios de idioma/fuentes
Gestión de plantillas: Analiza, valida y mejora plantillas de PowerPoint con validación detallada

🚀 Inicio rápido

Instalación

pip install deckbuilder

Uso de CLI (independiente)

# Initialize templates (one-time setup) This will create the default template and mapping JSON.
deckbuilder init

# Create presentation from markdown (outputs to current directory)
deckbuilder create presentation.md

# Use custom template folder (CLI arg overrides env vars)
deckbuilder --template-folder /custom/templates create presentation.md

# Create with custom language and font (supports both formats)
deckbuilder create presentation.md --language "es-ES" --font "Arial"
deckbuilder create presentation.md --language "Spanish (Spain)" --font "Times New Roman"

# View supported languages
deckbuilder config languages

# Template management & intelligence
deckbuilder template analyze default --verbose
deckbuilder template validate default
deckbuilder template list

# Smart template recommendations available through MCP tools

# Image generation with crop-first approach
deckbuilder image generate 800 600 --filter grayscale
deckbuilder image crop image.jpg 800 600

# Language and font remapping for existing PowerPoint files
deckbuilder remap existing.pptx --language en-US --font Arial

# View current configuration (shows path sources)
deckbuilder config show

# Get help
deckbuilder --help

Servidor MCP (Claude Desktop)

Añade a tu configuración de Claude Desktop:

Opción 1: Instalación directa (recomendada)

{
  "mcpServers": {
    "deckbuilder": {
      "command": "deckbuilder-server",
      "env": {
        "DECK_TEMPLATE_FOLDER": "/Users/username/Documents/Deckbuilder/Templates",
        "DECK_TEMPLATE_NAME": "default",
        "DECK_OUTPUT_FOLDER": "/Users/username/Documents/Deckbuilder",
        "DECK_PROOFING_LANGUAGE": "en-AU",
        "DECK_DEFAULT_FONT": "Calibri"
      }
    }
  }
}

Nuevas variables de entorno:

DECK_PROOFING_LANGUAGE: Establece el idioma de revisión para corrección ortográfica y gramatical (acepta formatos "en-AU" y "English (Australia)")
DECK_DEFAULT_FONT: Establece la familia de fuentes predeterminada para todas las presentaciones
Idioma predeterminado: Inglés australiano (en-AU) si no se especifica

📝 Ejemplos de uso

Markdown con Frontmatter (Recomendado)

---
layout: Title Slide
---
# **Deckbuilder** Presentation
## Creating presentations with *content-first* intelligence

---
layout: Four Columns
title: Feature Comparison
columns:
  - title: Performance
    content: "**Fast** processing with optimized algorithms"
  - title: Security
    content: "***Enterprise-grade*** encryption and compliance"
  - title: Usability
    content: "*Intuitive* interface with minimal learning curve"
  - title: Cost
    content: "___Transparent___ pricing with proven ROI"
---

---
layout: Picture with Caption
title: Market Analysis
media:
  image_path: "charts/revenue_growth.png"  # Auto-fallback to PlaceKitten if missing
  alt_text: "Revenue growth chart"
  caption: "**Q4 Revenue Growth** - 23% increase"
---

---
layout: Title and Content
title: "**Table Dimensions:** Custom Column Widths"
style: dark_blue_white_text
row_style: alternating_light_gray
border_style: thin_gray
column_widths: [8, 6, 4, 5]
row_height: 0.9
content: |
  Sales Performance Report with individual column width control:

  | **Product Category** | **Q1 Sales** | **Q2** | **Growth %** |
  | Enterprise Software | $125,000 | $142,000 | +13.6% |
  | SaaS Solutions | $89,500 | $98,200 | +9.7% |
  | Cloud Services | $156,000 | $178,000 | +14.1% |
  | Mobile Apps | $67,300 | $73,800 | +9.7% |
---

---
layout: Title and Content
title: "**Table Dimensions:** Equal Column Distribution"
style: light_blue_dark_text
row_style: alternating_light_gray
border_style: thin_gray
table_width: 22
row_height: 0.9
content: |
  Team Performance Dashboard with equal column distribution:

  | **Team Member** | **Projects** | **Completed** | **Success Rate** |
  | Alice Johnson | 25 | 24 | 96% |
  | Bob Smith | 18 | 17 | 94% |
  | Carol Davis | 32 | 31 | 97% |
  | David Wilson | 21 | 20 | 95% |

Formato JSON (Programático)

{
  "presentation": {
    "slides": [
      {
        "type": "Title Slide",
        "title": "**Deckbuilder** Presentation",
        "subtitle": "Content-first presentation generation"
      },
      {
        "type": "Title and Content",
        "title": "Key Benefits",
        "content": [
          "**Intelligent** content analysis",
          "*Semantic* layout recommendations",
          "***Professional*** template system"
        ]
      },
      {
        "type": "Title and Content",
        "title": "Team Performance Dashboard",
        "table": {
          "column_widths": [6, 4, 5, 3],
          "row_height": 1.8,
          "data": [
            ["**Team Member**", "**Projects**", "**Completed**", "**Rate**"],
            ["Alice Johnson", "25", "24", "96%"],
            ["Bob Smith", "18", "17", "94%"],
            ["Carol Davis", "32", "31", "97%"]
          ],
          "header_style": "dark_blue_white_text",
          "row_style": "alternating_light_gray",
          "border_style": "thin_gray"
        }
      }
    ]
  }
}

API de Python

from deckbuilder import Deckbuilder

# Initialize engine
db = Deckbuilder()

# Create from markdown
result = db.create_presentation_from_markdown(
    markdown_content=open("presentation.md").read(),
    fileName="My_Presentation"
)

# Create from JSON
result = db.create_presentation(
    json_data={"presentation": {"slides": [...]}},
    fileName="JSON_Presentation"
)

print(f"✅ Created: {result}")

🌍 Soporte de idiomas y fuentes

Idiomas compatibles (20)

Deckbuilder admite 20 idiomas de revisión para corrección ortográfica y gramatical. Puedes usar códigos de configuración regional (en-AU) o nombres completos (English (Australia)):

# View all supported languages (shows both formats)
deckbuilder config languages

Idiomas disponibles:

Inglés (Estados Unidos, Reino Unido, Canadá, Australia)
Español (España, México, Latinoamérica)
Francés (Francia, Canadá)
Alemán (Alemania, Austria, Suiza)
Italiano, Portugués (Brasil, Portugal)
Chino (Simplificado, Tradicional), Japonés, Coreano
Neerlandés, Ruso, Árabe

Personalización de fuentes

# Set language and font globally (supports both formats)
export DECK_PROOFING_LANGUAGE="en-AU"           # Locale code format
export DECK_PROOFING_LANGUAGE="English (Australia)"  # Full name format
export DECK_DEFAULT_FONT="Arial"

# Or use CLI arguments (both formats work)
deckbuilder create presentation.md --language "fr-CA" --font "Times New Roman"
deckbuilder create presentation.md --language "French (Canada)" --font "Arial"

# Check current settings (shows locale codes and descriptions)
deckbuilder config show

🖼️ Procesamiento de imágenes PlaceKitten

Sistema inteligente de reemplazo de imágenes - Cuando faltan imágenes o no son válidas, PlaceKitten genera automáticamente marcadores de posición profesionales:

from placekitten import PlaceKitten

pk = PlaceKitten()
placeholder = (pk.generate(1920, 1080, image_id=1)
                .smart_crop(1920, 1080)
                .apply_filter("grayscale")
                .save("professional_placeholder.jpg"))

Características:

✅ Validación de archivos: Comprueba la existencia, el formato y la accesibilidad de las imágenes
✅ Estilo profesional: Filtrado automático en escala de grises para contexto empresarial
✅ Recorte inteligente: Recorte basado en visión por computadora con detección de rostros
✅ Optimización de rendimiento: El almacenamiento en caché inteligente evita el procesamiento duplicado
✅ Integración perfecta: No se requiere intervención del usuario

🚀 Novedades en v1.2.0

Recomendaciones inteligentes de plantillas

Análisis de contenido: Analiza automáticamente tu contenido para sugerir los mejores diseños
Integración MCP: Disponible a través de Claude Desktop con recomendaciones inteligentes

Procesamiento de imágenes mejorado

Mejor dimensionamiento de imágenes: El recorte inteligente garantiza que las imágenes encajen perfectamente sin distorsión
Reemplazos automáticos: Imágenes de marcador de posición profesionales cuando faltan tus imágenes

Sistema de patrones mejorado

Personalización del usuario: Crea patrones de diseño personalizados en {template_folder}/patterns/
Carga dinámica: Todos los diseños ahora usan archivos de patrones flexibles en lugar de plantillas codificadas

🏗️ Arquitectura

    Your Content (Markdown/JSON)
              ↓
    ┌─────────────────────┐
    │   Content Analysis  │  ← Analyzes your content type and audience
    └─────────┬───────────┘
              ↓
    ┌─────────────────────┐
    │ Template Selection  │  ← Recommends best layouts for your content
    └─────────┬───────────┘
              ↓
    ┌─────────────────────┐
    │  PowerPoint Engine  │  ← Generates professional presentations
    └─────────┬───────────┘
              ↓
    Your Professional Presentation

🎨 Diseños Markdown compatibles

✅ Implementados actualmente

Diapositiva de título - Diapositiva de apertura con título y subtítulo
Título y contenido - Texto enriquecido con encabezados, párrafos y viñetas
Cuatro columnas - Cuatro áreas de contenido con frontmatter estructurado
Dos contenidos - Áreas de contenido lado a lado
Comparación - Diseño de comparación izquierda vs derecha
Tabla - Tablas de datos con estilo profesional
Encabezado de sección - Diapositivas divisorias entre temas
Imagen con título - Diapositivas centradas en imágenes con reemplazos inteligentes

🚧 Implementación progresiva (más de 50 planificados)

Visualizaciones de números grandes, análisis FODA, matriz de características
Cronología, flujo de procesos, organigrama
Panel de control, métricas, diseños financieros
Y más de 40 diseños de presentaciones empresariales

Consulta la Documentación de características para especificaciones detalladas.

🛠️ Desarrollo

Requisitos previos

Python 3.11+
Se recomiendan entornos virtuales.

Instalación de desarrollo

git clone https://github.com/teknologika/deckbuilder.git
cd deckbuilder
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .[dev]

Estándares de calidad de código

# Format code (required before commits)
black --line-length 100 src/

# Check linting (required)
flake8 src/ tests/ --max-line-length=100 --ignore=E203,W503,E501

# Run tests (required)
pytest tests/

Contribuciones

Haz un fork del repositorio
Crea una rama de características: git checkout -b feature-name
Sigue los estándares de calidad de código
Añade pruebas exhaustivas
Envía una solicitud de extracción con una descripción clara

📚 Documentación

Documentación completa - Índice completo de documentación
Plantillas compatibles - Biblioteca completa de diseños (más de 26 patrones)
Biblioteca Deckbuilder - Referencia de API de Python y clases
Interfaz de línea de comandos - Comandos CLI y ejemplos de uso
Servidor MCP - Recomendaciones inteligentes de plantillas y herramientas MCP
Biblioteca PlaceKitten - Procesamiento de imágenes con enfoque de recorte primero
Código fuente de PlaceKitten - Detalles técnicos de implementación

🔧 Pila tecnológica

Python 3.11+ con sugerencias de tipo modernas y manejo integral de errores
FastMCP para la implementación del servidor del Protocolo de Contexto de Modelo
python-pptx para la generación de PowerPoint y manipulación de plantillas
PyYAML para el procesamiento estructurado de frontmatter
OpenCV + Pillow para visión por computadora y procesamiento de imágenes
pytest para pruebas unitarias
Anthropic Claude - para la mayor parte del trabajo pesado de desarrollo :-)

📋 Solución de problemas

Plantilla no encontrada:

# Create templates folder
deckbuilder init

# Check configuration
deckbuilder config

Permiso denegado al guardar:

Verifica que la carpeta de salida tenga permisos de escritura
Asegúrate de que los archivos no estén abiertos en PowerPoint

Fallos de conexión MCP:

Verifica que el entorno virtual esté activado
Comprueba la ruta de Python en la configuración de Claude Desktop
Asegúrate de que todas las dependencias estén instaladas

📄 Licencia

Licencia Apache 2.0 - Consulta el archivo LICENSE para más detalles.

Construido con ❤️ para la generación inteligente de presentaciones - Copyright Bruce McLeod

🚀 Comenzar • 📖 Documentación • 🐛 Reportar problemas