# 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 — TOKEN-EFFICIENT workflows by deck size

**CRITICAL**: Choose the right workflow to avoid hitting output token limits.

- **Small (3-8 slides)**: `generate_presentation` — one-shot, ~200 tokens output
- **Medium/Large (9+ slides)**: `plan_presentation` → `create_from_plan` — ~600-800 tokens total

`generate_presentation` is HARD-CAPPED at 8 slides. For 9+ slides, always use the plan workflow.

### Plan workflow (9+ slides) — RECOMMENDED
1. `plan_presentation` — returns compact summary (~500 tokens) with `plan_id`
2. Optionally `get_plan_slide` — inspect individual slides (~200 tokens each)
3. Optionally `update_plan_slide` — modify slides before rendering
4. Optionally `optimize_plan` — run DesignAgent server-side (~100 tokens)
5. `create_from_plan` — render cached plan to .pptx (~80 tokens)

### Token traps to AVOID
- **`create_presentation`**: Accepts full PresentationDefinition as INPUT (4-25K tokens). Only use with output from `parse_spec` or `read_presentation`. Never manually construct definitions.
- **`optimize_design`**: Accepts AND returns full definition (8-50K tokens round-trip). Use `optimize_plan` instead for cached plans.
- **`return_full_json=True`** on `plan_presentation`: Returns 8-20K tokens. Avoid unless debugging.

### 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` / `ungroup_elements` — group or dissolve shape groups
6. `delete_element` — remove a shape from a slide
7. `copy_element` — copy shapes within or across slides
8. `validate_slide_layout` — check for overlaps, bounds, spacing issues

### Bulk editing
- `find_and_replace` — search/replace text across all or specific slides
- `batch_modify_elements` — apply multiple modifications in one call
- `reorder_slides` — rearrange slide order
- `create_checkpoint` / `restore_checkpoint` — undo via backup

### Plan editing
- `update_plan_slide` — modify individual slides in a cached plan before rendering

### Discovery tools
- `get_slide_templates` — all 32 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     — 41 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
```
