# 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

### Quick generation (single step)
Use `generate_presentation` — plans, optimizes, and renders in one call.

### Controlled workflow (multi-step)
1. `plan_presentation` — get a PresentationDefinition
2. `optimize_design` — improve layout
3. `create_presentation` — render to .pptx

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

### Discovery tools
- `get_slide_templates` — all 23 slide types with examples
- `get_brand_presets` — available brand configurations
- `get_deck_types` — deck archetypes (pitch, board, sales, all-hands)

## Important Constraints

- `output_path` must end in `.pptx`
- `slide_index` is 0-based
- `plan_presentation` returns JSON, not a file
- Brand presets: executive, technical, minimal, creative, corporate
- All file paths should be absolute
- Hyperlinks only support http://, https://, mailto: schemes

## Project Architecture

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