# PPTX MCP

**AI-Powered PowerPoint Generation**

[![PyPI version](https://img.shields.io/pypi/v/pptx-mcp)](https://pypi.org/project/pptx-mcp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)
[![PyPI Downloads](https://img.shields.io/pypi/dm/pptx-mcp)](https://pypistats.org/packages/pptx-mcp)

Made by [swak](https://github.com/swak)

---

## What This Does

PPTX MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI assistants create, edit, and review real PowerPoint files. It produces native `.pptx` files with 32 slide types (including org charts, Gantt charts, and 8 diagram types), 12 chart types, 12 brand presets, 27 deck archetypes, and a 26-rule review engine that scores your decks across 8 categories (accessibility, brand compliance, typography, color, layout, content, narrative, whitespace) and auto-fixes design issues. The output opens in PowerPoint, Keynote, or Google Slides -- fully editable, no lock-in.

## Why Use This

- **Real editable files** -- not images, not PDFs. Native `.pptx` you can open, edit, and present.
- **32 slide types** -- title, content, charts, tables, timelines, dashboards, SWOT, funnels, card grids, org charts, Gantt charts, and more.
- **12 chart types** -- bar, line, pie, column, area, scatter, bubble, radar, doughnut, stacked bar, stacked column, combo.
- **8 diagram types** -- org chart, matrix, pyramid, Venn, waterfall, hub-spoke, cycle, Gantt.
- **Review engine** -- 26 rules across 8 categories (accessibility, brand, typography, color, layout, content, narrative, whitespace), scores decks 0-10, and auto-fixes 7 issue types.
- **Brand consistency** -- 12 built-in presets (including industry verticals) or bring your own brand config.
- **Brand extraction** -- analyze an existing `.pptx` to extract colors, fonts, and spacing as a reusable brand config.
- **Round-trip editing** -- read existing decks, modify individual slides, re-render with new branding.
- **Designer features** -- shadow presets, edge accent bars, dividers, text auto-fit, logo placement, line dash styles.
- **Deck archetypes** -- 27 templates (pitch deck, board update, consulting assessments, product launch, etc.) for intelligent slide selection.
- **Brand guide** -- generate a 13-slide PPTX with visual specimens showcasing your brand's colors, typography, spacing, and shape styles.
- **Plan cache** -- server-side caching of planned decks avoids token-limit issues. Plans return compact summaries (~1-2KB) regardless of deck size.

---

## Quick Start

### Option 1: uvx (recommended)

Zero-install for any MCP client. Requires [uv](https://docs.astral.sh/uv/).

```bash
uvx pptx-mcp serve
```

### Option 2: pip install

```bash
pip install pptx-mcp
pptx-mcp serve
```

### Option 3: From source

```bash
git clone https://github.com/swak/pptx-mcp.git
cd pptx-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
pptx-mcp serve
```

---

## Connecting to AI Tools

### Claude Code

```bash
claude mcp add pptx-mcp -- uvx pptx-mcp serve
```

Or add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "pptx-mcp": {
      "command": "uvx",
      "args": ["pptx-mcp", "serve"]
    }
  }
}
```

<details>
<summary>Using a local install instead of uvx?</summary>

```json
{
  "mcpServers": {
    "pptx-mcp": {
      "command": "/absolute/path/to/pptx-mcp/.venv/bin/python",
      "args": ["-m", "pptx_mcp.server"]
    }
  }
}
```
</details>

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "pptx-mcp": {
      "command": "uvx",
      "args": ["pptx-mcp", "serve"]
    }
  }
}
```

<details>
<summary>Using a local install instead of uvx?</summary>

```json
{
  "mcpServers": {
    "pptx-mcp": {
      "command": "/absolute/path/to/pptx-mcp/.venv/bin/python",
      "args": ["-m", "pptx_mcp.server"]
    }
  }
}
```
</details>

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "pptx-mcp": {
      "command": "uvx",
      "args": ["pptx-mcp", "serve"]
    }
  }
}
```

### Windsurf

Add to your Windsurf MCP config:

```json
{
  "mcpServers": {
    "pptx-mcp": {
      "command": "uvx",
      "args": ["pptx-mcp", "serve"]
    }
  }
}
```

---

## What You Can Do

Once connected, your AI assistant has access to 41 tools:

**Generation**

| Tool | What to ask |
|------|-------------|
| `generate_presentation` | "Create a 6-slide deck on cloud migration" |
| `plan_presentation` | "Plan a 12-slide deck on AI adoption for the board" |
| `create_from_plan` | "Render the plan I just created" |
| `create_presentation` | "Render this slide definition as a PowerPoint file" |
| `parse_spec` | "Parse this markdown spec into slides" |

**Editing**

| Tool | What to ask |
|------|-------------|
| `add_slide` | "Add a pros/cons slide after slide 3" |
| `update_slide` | "Replace slide 5 with a chart showing Q1-Q4 revenue" |
| `delete_slide` | "Remove slide 8" |
| `move_slide` | "Move slide 2 to the end" |
| `duplicate_slide` | "Duplicate slide 4" |
| `add_speaker_notes` | "Add speaker notes to slide 2" |

**Analysis**

| Tool | What to ask |
|------|-------------|
| `read_presentation` | "Read my existing deck at ~/deck.pptx" |
| `get_plan_slide` | "Show me slide 3 from the plan" |
| `analyze_presentation` | "Describe what's in this deck" |
| `review_presentation` | "Review my deck and tell me what to fix" |

**Improvement**

| Tool | What to ask |
|------|-------------|
| `improve_presentation` | "Auto-improve my deck and save a new version" |
| `apply_brand_guidelines` | "Re-style my deck using the minimal preset" |
| `restyle_presentation` | "Restyle this deck with the consulting brand" |
| `optimize_design` | "Optimize the layout of this slide plan" |

**Element Editing**

| Tool | What to ask |
|------|-------------|
| `list_slide_elements` | "Show me all shapes on slide 3" |
| `modify_element` | "Move the title up and make it bold" |
| `add_element` | "Add a text box at the bottom" |
| `align_elements` | "Align these three boxes to the left" |
| `group_elements` | "Group these shapes together" |
| `delete_element` | "Remove that text box from slide 3" |
| `copy_element` | "Copy this shape to slide 5" |
| `ungroup_elements` | "Ungroup the shapes on slide 4" |
| `validate_slide_layout` | "Check slide 2 for layout issues" |

**Bulk Editing**

| Tool | What to ask |
|------|-------------|
| `find_and_replace` | "Replace all occurrences of 'Acme' with 'Globex'" |
| `batch_modify_elements` | "Make all titles bold and blue" |
| `reorder_slides` | "Rearrange slides to: 1, 3, 2, 5, 4" |
| `update_plan_slide` | "Change slide 3 in the plan before rendering" |
| `create_checkpoint` | "Save a checkpoint before I make changes" |
| `restore_checkpoint` | "Revert to the last checkpoint" |

**Discovery**

| Tool | What to ask |
|------|-------------|
| `get_slide_templates` | "Show me what slide types are available" |
| `get_brand_presets` | "What brand styles can I use?" |
| `get_deck_types` | "What deck archetypes are available?" |
| `generate_brand_guide` | "Create a brand guide for the consulting preset" |

**Brand Tools**

| Tool | What to ask |
|------|-------------|
| `parse_brand_guide` | "Parse this markdown brand guide into a brand config" |
| `extract_brand` | "Extract the brand from my existing deck" |

**Workflows by deck size:**

| Deck size | Workflow | Why |
|-----------|----------|-----|
| Small (3-6 slides) | `generate_presentation` | Single step, fast |
| Medium (7-15 slides) | `plan_presentation` -> `create_from_plan` | Compact summary avoids token limits |
| Large (15+ slides) | `plan_presentation` -> `create_from_plan` -> `update_slide`/`add_slide` | Plan + targeted edits |
| Edit existing | `read_presentation` -> `add_slide`/`update_slide`/`delete_slide` | Modify individual slides |
| Fine-tune | `list_slide_elements` -> `modify_element` -> `validate_slide_layout` | Adjust individual shapes |
| Review loop | `review_presentation` -> `improve_presentation` | Auto-fix design issues |
| Markdown spec | `parse_spec` | Parse structured markdown into slides |

---

## Example Conversation

**You:** Create an executive presentation about migrating our payment system to Stripe. 8 slides. Save to ~/Desktop/stripe_migration.pptx

**Claude will:**
1. Call `plan_presentation` to get a compact summary with `plan_id`
2. Call `create_from_plan` with the `plan_id` to render the `.pptx` file
3. Summarize what's in each slide

**You:** Read it back and review it

**Claude will:**
1. Call `read_presentation` to parse the file
2. Call `review_presentation` to score it (e.g., 8.5/10) and list issues

**You:** Fix the issues and save as v2

**Claude will:**
1. Call `improve_presentation` to auto-fix issues and re-render
2. Report the before/after scores and changes made

---

## Slide Types

32 slide types are available. Here are the JSON definitions for each.

### Title

```json
{ "slide_type": "title", "title": "Quarterly Review", "subtitle": "Q4 2025" }
```

### Section

```json
{ "slide_type": "section", "title": "Market Analysis", "subtitle": "Deep dive into trends" }
```

Section slides serve as visual dividers. They also support optional body text and bullets for context:

```json
{
  "slide_type": "section",
  "title": "Key Findings",
  "subtitle": "Phase 1 Results",
  "body": "Our analysis revealed three critical areas for improvement.",
  "bullets": ["Process efficiency gaps", "Technology debt", "Staffing constraints"]
}
```

### Content

```json
{
  "slide_type": "content",
  "title": "Key Findings",
  "bullets": ["Revenue grew 15%", "Retention at 92%", "NPS improved to 67"]
}
```

Body text variant:

```json
{
  "slide_type": "content",
  "title": "Executive Summary",
  "body": "The migration program is on track to deliver $2.1M in annual savings by Year 3."
}
```

### Two Column

```json
{
  "slide_type": "two_column",
  "title": "Before vs After",
  "columns": [
    { "title": "Before", "bullets": ["Manual process", "5-day turnaround", "Error-prone"] },
    { "title": "After", "bullets": ["Automated", "Same-day", "99.9% accuracy"] }
  ]
}
```

### Pros and Cons

```json
{
  "slide_type": "pros_cons",
  "title": "Build vs Buy",
  "pros": ["Full control", "Custom fit", "No vendor lock-in"],
  "cons": ["Higher cost", "Longer timeline", "Maintenance burden"]
}
```

### Comparison

```json
{
  "slide_type": "comparison",
  "title": "Platform Options",
  "columns": [
    { "title": "AWS", "bullets": ["Broadest services", "Mature ecosystem"] },
    { "title": "Azure", "bullets": ["AD integration", "Enterprise focus"] },
    { "title": "GCP", "bullets": ["ML/AI strength", "Competitive pricing"] }
  ]
}
```

### Chart

```json
{
  "slide_type": "chart",
  "title": "Revenue Trend",
  "elements": [{
    "type": "chart",
    "chart_type": "bar",
    "title": "Revenue by Quarter ($M)",
    "data": {
      "categories": ["Q1", "Q2", "Q3", "Q4"],
      "series": [
        { "name": "2024", "values": [10, 12, 11, 14] },
        { "name": "2025", "values": [13, 15, 16, 18] }
      ]
    }
  }]
}
```

Chart types: `bar`, `line`, `pie`, `column`, `area`, `scatter`, `bubble`, `radar`, `doughnut`, `stacked_bar`, `stacked_column`, `combo`

### Table

```json
{
  "slide_type": "table",
  "title": "Team Allocation",
  "elements": [{
    "type": "table",
    "header_row": true,
    "rows": [
      [{ "text": "Team" }, { "text": "Headcount" }, { "text": "Budget" }],
      [{ "text": "Engineering" }, { "text": "24" }, { "text": "$3.2M" }],
      [{ "text": "Product" }, { "text": "8" }, { "text": "$1.1M" }]
    ]
  }]
}
```

### Diagram

```json
{
  "slide_type": "diagram",
  "title": "System Architecture",
  "elements": [
    { "type": "shape", "shape_type": "rounded_rectangle", "text": "API Gateway",
      "position": { "left": 1, "top": 2, "width": 2, "height": 1 } },
    { "type": "shape", "shape_type": "rounded_rectangle", "text": "Service",
      "position": { "left": 5, "top": 2, "width": 2, "height": 1 } }
  ]
}
```

### Blank

```json
{ "slide_type": "blank" }
```

### Quote

```json
{
  "slide_type": "quote",
  "body": "The best way to predict the future is to create it.",
  "quote_attribution": "Peter Drucker",
  "quote_attribution_role": "Management Consultant"
}
```

### Big Number

```json
{
  "slide_type": "big_number",
  "body": "47%",
  "title": "Customer Satisfaction Score",
  "subtitle": "Q4 2025 Results",
  "bullets": ["Up from 32% last quarter"]
}
```

### Process

```json
{
  "slide_type": "process",
  "title": "Implementation Plan",
  "active_step": 1,
  "steps": [
    { "title": "Discovery", "description": "Gather requirements", "status": "completed" },
    { "title": "Design", "description": "Create architecture", "status": "active" },
    { "title": "Build", "description": "Implement solution", "status": "future" }
  ]
}
```

### Timeline

```json
{
  "slide_type": "timeline",
  "title": "Project Milestones",
  "steps": [
    { "title": "Kickoff", "date": "Jan 2025", "status": "completed" },
    { "title": "Beta", "date": "Mar 2025", "status": "active" },
    { "title": "GA Release", "date": "Jun 2025", "status": "future" }
  ]
}
```

### Step Cards

```json
{
  "slide_type": "step_cards",
  "title": "How It Works",
  "steps": [
    { "title": "Sign Up", "description": "Create your account in minutes" },
    { "title": "Configure", "description": "Set your preferences" },
    { "title": "Launch", "description": "Go live with one click" }
  ]
}
```

### Dashboard

```json
{
  "slide_type": "dashboard",
  "title": "Key Metrics",
  "kpis": [
    { "value": "$1.2M", "label": "Revenue", "change": "+15%", "trend": "up" },
    { "value": "92%", "label": "Retention", "change": "+3%", "trend": "up" },
    { "value": "67", "label": "NPS Score", "change": "-2", "trend": "down" },
    { "value": "4.2s", "label": "Avg Response", "trend": "neutral" }
  ]
}
```

### Image + Text

```json
{
  "slide_type": "image_text",
  "title": "Our Product",
  "image_path": "/path/to/product.png",
  "image_position": "left",
  "body": "Next-generation platform for enterprise teams.",
  "bullets": ["Fast deployment", "Built-in analytics", "24/7 support"]
}
```

### Icon Grid

```json
{
  "slide_type": "icon_grid",
  "title": "Our Values",
  "icons": [
    { "icon": "star", "title": "Speed", "description": "Ship fast, iterate often" },
    { "icon": "shield", "title": "Trust", "description": "Transparent by default" },
    { "icon": "bulb", "title": "Innovation", "description": "Question everything" }
  ]
}
```

### Team

```json
{
  "slide_type": "team",
  "title": "Leadership Team",
  "team_members": [
    { "name": "Jane Smith", "role": "CEO", "bio": "20 years in enterprise SaaS" },
    { "name": "John Doe", "role": "CTO", "bio": "Former VP Engineering at Acme" }
  ]
}
```

### Closing

```json
{
  "slide_type": "closing",
  "title": "Thank You",
  "subtitle": "Questions? Let's connect.",
  "cta_text": "Schedule a Demo",
  "contact_info": ["hello@company.com", "+1 (555) 123-4567"]
}
```

### SWOT

```json
{
  "slide_type": "swot",
  "title": "SWOT Analysis",
  "swot": {
    "strengths": ["Strong brand", "Loyal customers"],
    "weaknesses": ["High costs", "Limited reach"],
    "opportunities": ["New markets", "Partnerships"],
    "threats": ["Competition", "Regulation"]
  }
}
```

### Funnel

```json
{
  "slide_type": "funnel",
  "title": "Sales Pipeline",
  "funnel_stages": [
    { "label": "Prospects", "value": "10,000", "description": "Website visitors" },
    { "label": "Leads", "value": "2,500", "description": "Form submissions" },
    { "label": "Qualified", "value": "800", "description": "Sales-qualified leads" },
    { "label": "Closed", "value": "120", "description": "Won deals" }
  ]
}
```

### Agenda

```json
{
  "slide_type": "agenda",
  "title": "Today's Agenda",
  "active_agenda_item": 1,
  "agenda_items": [
    { "title": "Opening Remarks", "status": "completed" },
    { "title": "Q4 Financial Review", "description": "Revenue, margins, forecast", "status": "active" },
    { "title": "2026 Strategic Priorities", "status": "upcoming" },
    { "title": "Q&A", "status": "upcoming" }
  ]
}
```

### Card Grid

```json
{
  "slide_type": "card_grid",
  "title": "Our Services",
  "cards": [
    {
      "title": "Strategy",
      "icon": "target",
      "body": "End-to-end strategic advisory",
      "bullets": ["Market analysis", "Growth planning"],
      "badge": { "text": "NEW" }
    },
    {
      "title": "Implementation",
      "icon": "wrench",
      "body": "Hands-on delivery and execution",
      "bullets": ["Agile delivery", "Change management"]
    },
    {
      "title": "Analytics",
      "icon": "chart",
      "body": "Data-driven insights and reporting",
      "bullets": ["Dashboards", "Predictive models"]
    }
  ]
}
```

Each card supports `title`, `icon`, `body`, `bullets`, and an optional `badge` with `text` and `color`. Supports 2-12 cards in an auto-grid layout.

### Org Chart

```json
{
  "slide_type": "org_chart",
  "title": "Organization Structure",
  "org_nodes": {
    "name": "CEO",
    "title": "Jane Smith",
    "children": [
      { "name": "VP Engineering", "title": "John Doe", "children": [
        { "name": "Team Lead", "title": "Alice" },
        { "name": "Team Lead", "title": "Bob" }
      ]},
      { "name": "VP Product", "title": "Carol White" }
    ]
  }
}
```

Uses Buchheim tree layout for automatic node positioning.

### Matrix

```json
{
  "slide_type": "matrix",
  "title": "Priority Matrix",
  "matrix_data": {
    "x_axis_label": "Effort",
    "y_axis_label": "Impact",
    "quadrant_labels": ["Quick Wins", "Major Projects", "Fill-Ins", "Thankless Tasks"],
    "items": [
      { "label": "Feature A", "x": 0.2, "y": 0.8 },
      { "label": "Feature B", "x": 0.7, "y": 0.9 }
    ]
  }
}
```

### Pyramid

```json
{
  "slide_type": "pyramid",
  "title": "Strategic Priorities",
  "pyramid_layers": [
    { "label": "Vision", "description": "Long-term direction" },
    { "label": "Strategy", "description": "How we get there" },
    { "label": "Execution", "description": "Day-to-day operations" }
  ]
}
```

### Venn

```json
{
  "slide_type": "venn",
  "title": "Market Overlap",
  "venn_data": {
    "circles": [
      { "label": "Enterprise", "description": "Large orgs" },
      { "label": "Mid-Market", "description": "Growth companies" },
      { "label": "SMB", "description": "Small teams" }
    ],
    "intersection_label": "Our ICP"
  }
}
```

### Waterfall

```json
{
  "slide_type": "waterfall",
  "title": "Revenue Bridge",
  "waterfall_bars": [
    { "label": "Starting", "value": 100, "bar_type": "total" },
    { "label": "New Sales", "value": 40, "bar_type": "increase" },
    { "label": "Churn", "value": -15, "bar_type": "decrease" },
    { "label": "Ending", "value": 125, "bar_type": "total" }
  ]
}
```

### Hub & Spoke

```json
{
  "slide_type": "hub_spoke",
  "title": "Platform Ecosystem",
  "hub_label": "Core Platform",
  "spoke_items": [
    { "label": "API", "description": "Developer access" },
    { "label": "Analytics", "description": "Insights engine" },
    { "label": "Auth", "description": "Identity management" },
    { "label": "Storage", "description": "Data layer" }
  ]
}
```

### Cycle

```json
{
  "slide_type": "cycle",
  "title": "Development Lifecycle",
  "cycle_steps": [
    { "label": "Plan", "description": "Define requirements" },
    { "label": "Build", "description": "Implement features" },
    { "label": "Test", "description": "Validate quality" },
    { "label": "Deploy", "description": "Release to production" },
    { "label": "Monitor", "description": "Track performance" }
  ]
}
```

### Gantt

```json
{
  "slide_type": "gantt",
  "title": "Project Timeline",
  "gantt_tasks": [
    { "label": "Research", "start": 0, "duration": 3, "progress": 1.0 },
    { "label": "Design", "start": 2, "duration": 4, "progress": 0.5 },
    { "label": "Development", "start": 5, "duration": 6, "progress": 0.0 },
    { "label": "Testing", "start": 10, "duration": 2, "progress": 0.0 }
  ],
  "gantt_unit": "weeks"
}
```

### Speaker Notes

Any slide type supports speaker notes:

```json
{
  "slide_type": "content",
  "title": "Key Metrics",
  "bullets": ["Revenue: $14M", "Margin: 42%"],
  "speaker_notes": "Emphasize the margin improvement -- strongest signal for the board."
}
```

---

## Brand Configuration

### Built-in Presets

| Preset | Style | Primary | Accent | Font |
|--------|-------|---------|--------|------|
| `executive` | Clean, navy/white | `#1B2A4A` | `#E8913A` | Aptos |
| `technical` | Dark, teal accents | `#263238` | `#00BCD4` | Segoe UI |
| `minimal` | High-contrast B&W | `#111111` | `#FF4444` | Arial |
| `creative` | Bold, colorful | `#6B21A8` | `#F59E0B` | Georgia / Aptos |
| `corporate` | Conservative, formal | `#1E3A5F` | `#C9A84C` | Garamond / Aptos |
| `consulting` | Professional, structured | `#1A3C6E` | `#D4A843` | Aptos |
| `healthcare` | Clean, trustworthy | `#0D6EAE` | `#27AE60` | Aptos |
| `startup` | Bold, modern | `#6C5CE7` | `#00D2D3` | Aptos Display |
| `academic` | Scholarly, structured | `#800020` | `#DAA520` | Garamond / Aptos |
| `government` | Formal, accessible | `#003366` | `#CC0000` | Aptos |
| `finance` | Sophisticated, precise | `#1A3C34` | `#B8860B` | Aptos Display |
| `nonprofit` | Warm, approachable | `#E07C3E` | `#2E86AB` | Aptos Display |

The `consulting` and `finance` presets include confidential markings. The `consulting`, `government`, `healthcare`, and `finance` presets include slide numbers and date footers. The `startup` preset features a left edge bar; `consulting` uses medium shadow presets; `minimal` enables dividers and text auto-fit.

Generate a brand guide PPTX for any preset with `generate_brand_guide`. Extract a brand config from an existing deck with `extract_brand`.

Use presets via CLI (`--preset executive`) or in tool calls (`brand_preset="executive"`).

### Custom Brand Config

Create a YAML file:

```yaml
name: "Your Company"

colors:
  primary: "#002B5C"
  secondary: "#0066CC"
  accent: "#FF6B00"
  background: "#FFFFFF"
  text_primary: "#1A1A1A"
  text_secondary: "#666666"
  surface: "#F8F9FA"
  border: "#E0E0E0"
  chart_colors: ["#002B5C", "#0066CC", "#FF6B00", "#28A745"]

fonts:
  heading_font: "Arial"
  body_font: "Arial"
  display_font: "Impact"
  title_size: 36
  heading_size: 28
  body_size: 16
  display_size: 44
  font_weight_heading: "Bold"
  font_weight_body: "Regular"
  paragraph_spacing: 6.0

spacing:
  margin_left: 0.75
  margin_right: 0.75
  content_top: 1.6
  column_gap: 0.5
  base_unit_pt: 8

shape_style:
  card_corner_radius: 0.08
  shadow_preset: "subtle"        # none | subtle | medium | elevated
  edge_bar: "left"               # none | left | top
  edge_bar_width: 0.15
  divider_style: "thin_line"     # none | thin_line | dotted
  line_dash_style: "solid"       # solid | dash | dot | dash_dot | long_dash
  text_auto_fit: true

logo:
  path: "/path/to/logo.png"
  placement: "top_left"          # top_left | top_right | bottom_left | bottom_right
  max_height: 0.5
  skip_on: ["title", "closing"]

layout_rules:
  max_bullets_per_slide: 5
  max_words_per_bullet: 12
  max_words_per_slide: 60

tone: "executive"
footer_text: "Confidential -- Your Company"
```

Use via CLI:

```bash
pptx-mcp generate plan.json output.pptx --brand my_brand.yaml
```

### Brand from Markdown

Use the `parse_brand_guide` tool with markdown:

```markdown
# My Brand

## Colors
- primary: #002B5C
- secondary: #0066CC
- accent: #FF6B00

## Typography
- heading_font: Arial
- body_font: Arial
- title_size: 36

## Shape Style
- shadow_preset: medium
- edge_bar: left
```

### Brand from Existing Deck

Use the `extract_brand` tool to analyze a `.pptx` and extract its colors, fonts, and spacing as a reusable brand config:

```
"Extract the brand from my_deck.pptx and save it to my_brand.json"
```

---

## Deck Archetypes

27 built-in archetypes define recommended slide structures for common presentation types. Pass the archetype name as `deck_type` to `plan_presentation` or `generate_presentation`.

**General**

| Archetype | Description |
|-----------|-------------|
| `pitch_deck` | Investor/stakeholder pitch with problem, solution, traction, team, and ask |
| `board_deck` | Quarterly board update with financials, strategy, and operational review |
| `sales_deck` | Customer-facing presentation with value proposition and social proof |
| `all_hands` | Company-wide update with achievements, metrics, and team recognition |
| `project_update` | Status update with progress, timeline, and risk assessment |
| `training` | Educational presentation with structured lessons and exercises |
| `product_launch` | Product launch with features, competitive edge, and rollout schedule |
| `case_study` | Customer success story with challenge, approach, results, and testimonial |
| `quarterly_earnings` | Quarterly financial report with highlights, trends, and guidance |
| `onboarding` | New hire/client onboarding with values, timeline, and key contacts |
| `annual_report` | Year-in-review with KPIs, milestones, leadership, and year-ahead outlook |
| `conference_talk` | Keynote/conference presentation with big ideas and takeaways |

**Consulting**

| Archetype | Description |
|-----------|-------------|
| `strategy_deck` | Strategic planning with market analysis, competitive landscape, and recommendations |
| `due_diligence` | Investment analysis with financials, risks, and deal assessment |
| `market_analysis` | Market sizing, segmentation, trends, and competitive positioning |
| `org_design` | Organizational restructuring with current/future state and implementation plan |
| `competitive_assessment` | Competitor landscape, SWOT analysis, and strategic positioning |
| `transformation_roadmap` | Change management with phased implementation and success metrics |
| `assessment` | General assessment/audit with findings, matrix, and remediation plan |
| `opportunity_assessment` | Opportunity sizing with pipeline, scenarios, and investment recommendation |
| `strategy_training` | Consulting methodology training with frameworks and case application |
| `template_guide` | How-to-use guide for templates, systems, or workflows |
| `executive_overview` | High-level executive briefing with key metrics and strategic focus |
| `analysis_deck` | Data-driven analytical deep-dive with trends and scenario modeling |
| `cost_breakdown` | Cost/revenue breakdown with line items, benchmarks, and optimization |
| `architecture_review` | IT/systems architecture review with components and migration roadmap |
| `analytics_dashboard` | Data analytics presentation with KPIs, charts, and key insights |

---

## Review Engine

The review engine scores decks 0-10 with 26 rules across 8 categories. It auto-fixes deterministic issues (title casing, minimum font sizes, off-brand colors) and flags the rest for manual review.

**Content & Layout** (definition-level)

| Rule | What it checks |
|------|----------------|
| Word count | Slides exceeding max words per slide |
| Bullet count | Too many bullets on a single slide |
| Bullet length | Individual bullets that are too wordy |
| Title presence | Missing titles on non-blank slides |
| Empty slides | Slides with no content |
| Column balance | Uneven content across columns |
| Card count | Too many cards (>6) or KPIs (>8) |
| Shadow + border conflict | Thick borders combined with shadow presets |

**Narrative & Consistency** (deck-level)

| Rule | What it checks |
|------|----------------|
| Narrative flow | Missing title slide, monotonous slide types, deck length |
| Consistency | Mixed title casing across slides |
| Visual rhythm | 3+ consecutive slides of the same type |

**Spatial Validation** (PPTX-level)

| Rule | What it checks |
|------|----------------|
| Element overlap | Shapes overlapping by more than 0.05" |
| Element bounds | Shapes extending beyond slide edges |
| Element spacing | Shapes closer than 0.1" apart |
| Text overflow | Text likely overflowing its container |
| Whitespace ratio | Slide >85% covered (crowded) or <15% (sparse) |

**Accessibility**

| Rule | What it checks |
|------|----------------|
| Image alt text | Images missing alt text descriptions |
| Min font size | Text runs below brand minimum font size |
| Contrast ratio | WCAG text-to-background contrast (4.5:1 body, 3.0:1 large text) |

**Brand Compliance**

| Rule | What it checks |
|------|----------------|
| Font compliance | Fonts not in the brand font set |
| Color compliance | Colors far from the brand palette (distance >50) |
| Logo presence | Brand logo configured but missing from title slide |
| Chart brand colors | Charts present but no `chart_colors` defined |

**Typography & Color**

| Rule | What it checks |
|------|----------------|
| Font hierarchy | Title > heading > body > caption sizes not strictly decreasing |
| Font family count | More than 3 distinct font families per slide |
| Accent overuse | More than 2 elements using the accent color |
| Distinct color count | More than 5 non-neutral colors per slide |

**Auto-fix patterns** (applied by `improve_presentation`):

| Fix | Trigger |
|-----|---------|
| Split bullets to columns | >6 bullets on a content slide |
| Promote first bullet | Missing title on content slide |
| Rebalance columns | Significantly unbalanced column content |
| Remove empty slides | Slides with no content |
| Normalize title casing | Inconsistent title casing across deck |
| Bump minimum font size | Text below brand minimum |
| Snap off-brand colors | Fill colors far from brand palette |

Scoring: errors deduct 3 points, warnings 1.5, info 0.5, suggestions 0.25.

Example review output:

```
Score: 7.2/10.0
Issues: 8

  ERROR [slide 4] Slide has 95 words (max 60). Consider reducing text.
  WARN  [slide 6] Slide has 7 bullets (max 5).
  WARN  [slide 2] 3 text run(s) below minimum font size (12pt).
  WARN  [slide 5] Low contrast (2.1:1) on 'Content Box' (threshold 4.5:1).
  INFO  [slide 3] Off-brand font(s): Comic Sans MS.
  INFO  [slide 7] Accent color used on 4 elements; sparingly is preferred.
  HINT  [deck] Slides 3-5 are all content; vary layout for visual rhythm.
  HINT  [slide 1] Image missing alt text description for accessibility.
```

---

## Token Limit Guidance

Large presentation plans (10+ slides) can produce 13-16KB of JSON, which may exceed LLM output token limits. PPTX MCP solves this with **server-side plan caching**:

1. `plan_presentation` caches the full definition server-side and returns a **compact summary** (~1-2KB) with a `plan_id`
2. `create_from_plan` renders the cached plan to `.pptx` without transferring the full definition
3. `get_plan_slide` retrieves individual slides (~0.5-1.5KB each) for inspection

Plans are cached for 1 hour (max 50 concurrent plans). For backward compatibility, pass `return_full_json=True` to `plan_presentation` to get the full definition.

---

## Markdown Spec Format

The `parse_spec` tool accepts structured markdown that describes slide content. This lets you write presentations in markdown and convert them to `.pptx`.

```markdown
# Presentation Title
subtitle: Q4 2025 Review
author: Jane Smith

---

## Market Analysis
- Revenue grew 15% YoY
- Customer retention at 92%
- NPS improved from 54 to 67

---

## Financial Dashboard
| Metric | Value | Change |
|--------|-------|--------|
| Revenue | $14M | +15% |
| Margin | 42% | +3pp |
| Headcount | 124 | +18 |

---

## Key Quote
> "The best way to predict the future is to create it."
> — Peter Drucker
```

**Supported elements:** headers (`##`), bullet lists (`-`), tables (`|`), blockquotes (`>`), code blocks, and color tokens (`color: #FF6B00`). Slide types are auto-detected from content structure.

---

## CLI Reference

```bash
# Start MCP server
pptx-mcp serve

# Generate from JSON definition
pptx-mcp generate plan.json output.pptx
pptx-mcp generate plan.json output.pptx --preset executive
pptx-mcp generate plan.json output.pptx --brand my_brand.yaml

# Plan a deck (outputs JSON)
pptx-mcp plan "Q4 Business Review" -n 10
pptx-mcp plan "Cloud Migration" -n 12 --audience executive \
  --points "Current state,Business case,Timeline,Risks" -o plan.json

# Read an existing deck
pptx-mcp read deck.pptx
pptx-mcp read deck.pptx -o parsed.json

# Review a deck
pptx-mcp review deck.pptx --preset executive

# Auto-improve a deck
pptx-mcp improve deck.pptx
pptx-mcp improve deck.pptx -o improved.pptx --preset executive
```

Run `pptx-mcp --help` for full options.

---

## Python Library

```python
from pptx_mcp.engine.generator import DeckGenerator
from pptx_mcp.engine.parser import parse_presentation
from pptx_mcp.brand.config import resolve_brand_config
from pptx_mcp.review.engine import ReviewEngine
from pptx_mcp.agents.planner import PlannerInput, SlidePlannerAgent
from pptx_mcp.models.slides import *

# Generate from a definition
brand = resolve_brand_config(preset="executive")
generator = DeckGenerator(brand=brand)
generator.generate(definition, "output.pptx")

# Plan -> Generate
planner = SlidePlannerAgent()
plan = planner.run(PlannerInput(
    topic="AI Adoption Strategy",
    audience="executive",
    num_slides=10,
    key_points=["Market opportunity", "Current capabilities", "Investment ask"],
))
generator.generate(plan, "ai_strategy.pptx")

# Read -> Review -> Improve
definition = parse_presentation("existing.pptx")
engine = ReviewEngine(brand=resolve_brand_config(preset="executive"))
review = engine.review_definition(definition)
print(f"Score: {review.overall_score}/10 -- {review.total_issues} issues")
```

---

## Project Structure

```
pptx_mcp/
  server.py               # MCP server -- 41 tools, 10 prompts, 2 resources
  cli.py                  # CLI -- serve, generate, read, review, plan, improve
  models/
    slides.py             # 32 slide types, 12 chart types, elements, definitions
    brand.py              # BrandConfig, LogoConfig, ColorPalette, FontConfig, ShapeStyleConfig
    diagrams.py           # OrgNode, MatrixData, PyramidLayer, VennData, and more
    review.py             # ReviewResult, ReviewIssue, SlideReview
    editor.py             # ElementLocator, ElementModification, ElementInfo
  engine/
    generator.py          # DeckGenerator -- renders definitions to .pptx
    parser.py             # Reads .pptx -> PresentationDefinition
    spec_parser.py        # Markdown spec -> PresentationDefinition + parse_brand_guide
    describer.py          # Natural-language slide/deck descriptions
    charts.py             # 12 chart types (bar, scatter, bubble, radar, combo, etc.)
    shapes.py             # 15+ shape types, connectors, shadow/dash/color helpers
    layouts.py            # Layout renderers for all slide types + edge bars, dividers
    composition.py        # LayoutGrid responsive positioning system
    editor.py             # Element-level editing (list, modify, add, align, group, delete, copy, find/replace, batch, reorder)
    brand_guide.py        # 13-slide brand guide with visual specimens
    brand_extractor.py    # Extract BrandConfig from existing .pptx
    diagrams/             # 8 diagram renderers (org chart, matrix, pyramid, etc.)
  brand/
    config.py             # Loads YAML/JSON brand configs
    defaults.py           # 12 built-in presets
  agents/
    base.py               # BaseAgent[Input, Output] abstract class
    planner.py            # SlidePlannerAgent -- topic -> slide plan
    designer.py           # DesignAgent -- layout optimization
    reviewer.py           # ReviewAgent -- structured critique
    iterator.py           # IterationAgent -- applies review fixes (7 auto-fix patterns)
    archetypes.py         # 27 deck archetypes
    content_mapper.py     # Keyword -> SlideType suggestions
  review/
    engine.py             # ReviewEngine -- scoring and summary
    rules.py              # 15 design rules (content, layout, narrative, accessibility, brand, color, typography)
    spatial.py            # 11 spatial rules (overlap, bounds, spacing, text overflow, contrast, font/color compliance, whitespace)
  utils/
    logging.py            # Structured logging
    errors.py             # Typed exceptions
    paths.py              # Path validation and security
```

---

## Security

This server operates on local filesystem paths provided in tool arguments. See [SECURITY.md](SECURITY.md) for details on path validation and input handling.

---

## Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

```bash
git clone https://github.com/swak/pptx-mcp.git
cd pptx-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -v
```

---

## License

MIT
