# PPTX MCP — Claude Code Instructions

## Running the Server

- Use `.venv/bin/python` — system Python does not have dependencies installed
- Start: `.venv/bin/python -m pptx_mcp.server`
- CLI: `.venv/bin/python -m pptx_mcp serve`
- Tests: `.venv/bin/python -m pytest tests/ -q`

## Tool Usage Patterns

### Creating presentations (RECOMMENDED workflows by deck size)
- **Small (3-6 slides)**: `generate_presentation` — single step, plans + renders in one call
- **Medium (7-15 slides)**: `plan_presentation` → `create_from_plan` — plan returns a compact summary with `plan_id`, render with `create_from_plan`
- **Large (15+ slides)**: same as medium, then `update_slide` / `add_slide` for targeted edits

### Two-step workflow (plan → render)
1. `plan_presentation` — returns compact summary (~1-2KB) with a `plan_id` (full definition cached server-side)
2. Optionally `get_plan_slide` — inspect individual slides without pulling the full plan
3. `create_from_plan` — render the cached plan to .pptx
4. Use `return_full_json=True` on `plan_presentation` for backward compatibility (returns full JSON)

### Editing existing decks
1. `read_presentation` — parse .pptx to JSON
2. `add_slide` / `update_slide` / `delete_slide` / `move_slide` / `duplicate_slide`
3. `review_presentation` — get design feedback
4. `improve_presentation` — auto-fix issues

### Fine-grained element editing
1. `list_slide_elements` — see all shapes with positions, sizes, text
2. `modify_element` — change any property of a single shape
3. `add_element` — add textbox, shape, or image to existing slide
4. `align_elements` — align or distribute elements
5. `group_elements` — group shapes together
6. `validate_slide_layout` — check for overlaps, bounds, spacing issues

### Discovery tools
- `get_slide_templates` — all 23 slide types with examples
- `get_brand_presets` — available brand configurations
- `get_deck_types` — 27 deck archetypes (pitch, board, sales, consulting, etc.)
- `generate_brand_guide` — create a brand guide PPTX showcasing colors, fonts, layouts

## Important Constraints

- `output_path` must end in `.pptx`
- `slide_index` is 0-based
- `plan_presentation` returns compact summary with `plan_id` by default (not the full JSON)
- Brand presets: executive, technical, minimal, creative, corporate, consulting, healthcare, startup, academic, government, finance, nonprofit
- All file paths should be absolute
- Hyperlinks only support http://, https://, mailto: schemes

## Project Architecture

```
pptx_mcp/
  server.py     — 29 MCP tools, 10 prompts, 2 resources
  cli.py        — CLI: serve, generate, read, review, plan, improve
  models/       — Pydantic models (slides, brand, review, editor)
  engine/       — Generator, parser, layouts, charts, shapes, editor
  brand/        — Brand config loading + 12 presets
  agents/       — Planner, designer, reviewer, iterator
  review/       — Review engine + design rules + spatial validation
  utils/        — Errors, logging, path validation
```
