Deck Builder MCP

Crie e manipule apresentações do PowerPoint programaticamente usando JSON ou Markdown.

Documentação

[!IMPORTANT]
O Deckbuilder está atualmente em desenvolvimento ativo e NÃO deve ser considerado pronto para produção.

🎯 Deckbuilder

Crie apresentações profissionais em PowerPoint a partir de Markdown ou JSON

O Deckbuilder é uma biblioteca Python, ferramenta de linha de comando e servidor MCP que gera apresentações em PowerPoint a partir de conteúdo estruturado. Concentre-se no seu conteúdo - o Deckbuilder cuida da formatação e do layout.

✨ Recursos Principais

🚀 Geração de Apresentações em Uma Única Etapa

Crie apresentações completas em PowerPoint a partir de JSON ou Markdown com frontmatter YAML em um único comando.

🎨 Suporte a Conteúdo Rico

Formatação Avançada: **bold**, *italic*, ___underline___, ***bold italic***
Atualização de Idioma e Fonte: A capacidade de atualizar as fontes e o idioma de todos os objetos do slide usando as ferramentas de linha de comando via CLI.
Tabelas Profissionais: Estilização personalizada com temas, cores e controles precisos de dimensão (larguras de coluna, alturas de linha, dimensionamento de tabelas).
Layouts Suportados: Biblioteca progressiva de modelos sendo adicionada.

🧠 Sistema Inteligente de Modelos

Seleção Inteligente de Layout: Recomendações automáticas de layout com base no tipo de conteúdo
Arquitetura Baseada em Padrões: Personalize qualquer layout com seus próprios modelos
Suporte a Conteúdo Rico: Tabelas, imagens, layouts de múltiplas colunas com estilização profissional

🖼️ Processamento Inteligente de Imagens

Fallbacks Automáticos de Imagem: Imagens ausentes? O Deckbuilder gera placeholders profissionais automaticamente
Corte Inteligente: Detecção de faces e composição inteligente para dimensionamento perfeito de imagens
Filtros Profissionais: Estilização adequada para negócios com escala de cinza e outros efeitos

⚡ Experiência CLI Aprimorada

Interface Hierárquica Profissional: Estrutura de comandos limpa (deckbuilder <command> <subcommand>)
Configuração com Um Comando: deckbuilder init cria modelos e configuração
Caminhos Sensíveis ao Contexto: Precedência de argumentos CLI > variáveis de ambiente > diretório atual
Saída Sempre Local: A CLI gera saída no diretório atual para desenvolvimento local previsível
Argumentos Globais: -t/--template-folder, -l/--language, -f/--font para personalização completa
Estrutura de Comandos Abrangente:
- deckbuilder template → analyze, validate, document, enhance, list
- deckbuilder config → show, languages, completion
- deckbuilder image → generate, crop
- deckbuilder remap → atualiza arquivos PowerPoint existentes com alterações de idioma/fonte
Gerenciamento de Modelos: Analise, valide e aprimore modelos PowerPoint com validação detalhada

🚀 Início Rápido

Instalação

pip install deckbuilder

Uso da CLI (Independente)

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

Adicione à sua configuração do Claude Desktop:

Opção 1: Instalação direta (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"
      }
    }
  }
}

Novas Variáveis de Ambiente:

DECK_PROOFING_LANGUAGE: Define o idioma de revisão para verificação ortográfica e gramatical (aceita formatos "en-AU" e "English (Australia)")
DECK_DEFAULT_FONT: Define a família de fonte padrão para todas as apresentações
Idioma Padrão: Inglês Australiano (en-AU) se não for especificado

📝 Exemplos de Uso

Markdown com 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 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}")

🌍 Suporte a Idioma e Fonte

Idiomas Suportados (20)

O Deckbuilder suporta 20 idiomas de revisão para verificação ortográfica e gramatical. Você pode usar códigos de localidade (en-AU) ou nomes completos (English (Australia)):

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

Idiomas Disponíveis:

Inglês (Estados Unidos, Reino Unido, Canadá, Austrália)
Espanhol (Espanha, México, América Latina)
Francês (França, Canadá)
Alemão (Alemanha, Áustria, Suíça)
Italiano, Português (Brasil, Portugal)
Chinês (Simplificado, Tradicional), Japonês, Coreano
Holandês, Russo, Árabe

Personalização de Fontes

# 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

🖼️ Processamento de Imagens PlaceKitten

Sistema Inteligente de Fallback de Imagens - Quando as imagens estão ausentes ou inválidas, o PlaceKitten gera automaticamente placeholders profissionais:

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

Recursos:

✅ Validação de Arquivos: Verifica existência, formato e acessibilidade da imagem
✅ Estilização Profissional: Filtragem automática em escala de cinza para contexto empresarial
✅ Corte Inteligente: Corte baseado em visão computacional com detecção de faces
✅ Otimizado para Desempenho: Cache inteligente evita processamento duplicado
✅ Integração Perfeita: Nenhuma intervenção do usuário necessária

🚀 Novidades na v1.2.0

Recomendações Inteligentes de Modelos

Análise de Conteúdo: Analisa automaticamente seu conteúdo para sugerir os melhores layouts
Integração MCP: Disponível através do Claude Desktop com recomendações inteligentes

Processamento de Imagens Aprimorado

Melhor Dimensionamento de Imagens: O corte inteligente garante que as imagens se encaixem perfeitamente sem distorção
Fallbacks Automáticos: Imagens placeholder profissionais quando suas imagens estiverem ausentes

Sistema de Padrões Aprimorado

Personalização do Usuário: Crie padrões de layout personalizados em {template_folder}/patterns/
Carregamento Dinâmico: Todos os layouts agora usam arquivos de padrão flexíveis em vez de modelos codificados

🏗️ Arquitetura

    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

🎨 Layouts Markdown Suportados

✅ Atualmente Implementados

Slide de Título - Slide de abertura com título e subtítulo
Título e Conteúdo - Texto rico com títulos, parágrafos e marcadores
Quatro Colunas - Quatro áreas de conteúdo com frontmatter estruturado
Dois Conteúdos - Áreas de conteúdo lado a lado
Comparação - Layout de comparação esquerda vs direita
Tabela - Tabelas de dados com estilização profissional
Cabeçalho de Seção - Slides divisores entre tópicos
Imagem com Legenda - Slides focados em imagens com fallbacks inteligentes

🚧 Implementação Progressiva (50+ Planejados)

Exibições de Números Grandes, Análise SWOT, Matriz de Recursos
Linha do Tempo, Fluxo de Processo, Organograma
Dashboard, Métricas, Layouts Financeiros
E mais de 40 layouts de apresentações empresariais

Consulte a Documentação de Recursos para especificações detalhadas.

🛠️ Desenvolvimento

Pré-requisitos

Python 3.11+
Ambientes virtuais são recomendados.

Instalação de Desenvolvimento

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]

Padrões de Qualidade 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/

Contribuindo

Faça um fork do repositório
Crie um branch de recurso: git checkout -b feature-name
Siga os padrões de qualidade de código
Adicione testes abrangentes
Envie um pull request com descrição clara

📚 Documentação

Documentação Completa - Índice completo da documentação
Modelos Suportados - Biblioteca completa de layouts (26+ padrões)
Biblioteca Deckbuilder - Referência da API Python e classes
Interface de Linha de Comando - Comandos CLI e exemplos de uso
Servidor MCP - Recomendações inteligentes de modelos e ferramentas MCP
Biblioteca PlaceKitten - Processamento de imagens com abordagem de corte primeiro
Código-fonte do PlaceKitten - Detalhes técnicos de implementação

🔧 Stack de Tecnologia

Python 3.11+ com type hints modernos e tratamento abrangente de erros
FastMCP para implementação do servidor Model Context Protocol
python-pptx para geração de PowerPoint e manipulação de modelos
PyYAML para processamento estruturado de frontmatter
OpenCV + Pillow para visão computacional e processamento de imagens
pytest para testes unitários
Anthropic Claude - para a maior parte do trabalho pesado de desenvolvimento :-)

📋 Solução de Problemas

Modelo não encontrado:

# Create templates folder
deckbuilder init

# Check configuration
deckbuilder config

Permissão negada ao salvar:

Verifique se a pasta de saída tem permissões de escrita
Certifique-se de que os arquivos não estejam abertos no PowerPoint

Falhas de conexão MCP:

Verifique se o ambiente virtual está ativado
Verifique o caminho do Python na configuração do Claude Desktop
Certifique-se de que todas as dependências estejam instaladas

📄 Licença

Apache License 2.0 - Consulte o arquivo LICENSE para obter detalhes.

Construído com ❤️ para geração inteligente de apresentações - Copyright Bruce McLeod

🚀 Começar • 📖 Documentação • 🐛 Reportar Problemas