# PPT Generator

An MCP (Model Context Protocol) server that automatically generates presentations from a given topic.

**LLM generation is offloaded to the client.** The server owns the prompts, the output
JSON schemas, and all deterministic post-processing (validation, layout, lint, HTML/PPTX
render); it never calls a model itself. Each generation step is a `prepare_*` /
`ingest_*` pair — `prepare_*` hands the client the prompt + schema, the client generates
the JSON, and `ingest_*` validates and post-processes it. This means **no AWS/Anthropic
credentials and no per-call model cost on the server side** — the client's own model does
the generating. See the ADR index under [`docs/adr/`](docs/adr/) for the design rationale.

## Prerequisites

1. Python 3.13+
2. [uv](https://docs.astral.sh/uv/) package manager
3. [Claude Code](https://claude.com/claude-code) (recommended — the plugin bundles the MCP server + workflow skills). Any MCP client that can generate JSON also works — no model API keys needed on the server.

## 1. Install as a Claude Code plugin (recommended)

The repo ships as a Claude Code plugin (manifest at `.claude-plugin/plugin.json`) that
registers the MCP server and the `ppt-outline` / `ppt-design` / `ppt-speaker-script` / `ppt-modify` /
`ppt-visual-qa` skills which drive the prepare→generate→ingest workflow.

Add the marketplace and install the plugin from within Claude Code:

```
/plugin marketplace add haandol/ppt-generator
/plugin install ppt-generator@ppt-generator
```

The plugin runs the MCP server via `uv run` against the plugin's own checkout
(`${CLAUDE_PLUGIN_ROOT}`), so `uv` must be on your `PATH` and the plugin's dependencies
must be synced. If the server fails to start, sync deps once from the plugin directory:

```bash
uv sync   # run inside the installed plugin's directory
```

> No model API keys are required — the client supplies the generation.

### Alternative — clone and register the MCP server directly

If you are not using the Claude Code plugin system (e.g. Kiro / Claude Desktop, or you
prefer a local clone), clone the repo and register just the MCP server:

```bash
git clone https://github.com/haandol/ppt-generator.git
cd ppt-generator
uv sync
```

```json
{
  "mcpServers": {
    "ppt-generator": {
      "command": "uv",
      "args": ["--directory", "/path/to/ppt-generator", "run", "ppt-generator"]
    }
  }
}
```

> Replace `/path/to/ppt-generator` with the actual project path. This registers the MCP
> server only; the workflow skills are Claude Code plugin skills.

### Use it as a skill in Kiro / Codex

The workflow is just the MCP server plus the `prepare_*`/`ingest_*` handshake, so any
MCP client that can generate JSON can drive it — including **Kiro** and **Codex**. The
repo ships the entry points each harness loads automatically (Kiro steering at
`.kiro/steering/ppt-generator.md`, Codex guidance in `AGENTS.md`), so you get the same
skill-level guidance without duplicating the prompts.

First clone and sync once (no model API keys needed):

```bash
git clone https://github.com/haandol/ppt-generator.git
cd ppt-generator
uv sync
```

**Kiro** — copy the bundled example and fix the path, then Kiro auto-loads the steering:

```bash
cp .kiro/settings/mcp.json.example .kiro/settings/mcp.json
# edit .kiro/settings/mcp.json → replace /path/to/ppt-generator with your clone path
```

```json
{
  "mcpServers": {
    "ppt-generator": {
      "command": "uv",
      "args": ["--directory", "/path/to/ppt-generator", "run", "ppt-generator"],
      "disabled": false,
      "autoApprove": ["export_html", "load_project_status", "list_projects"]
    }
  }
}
```

Use `~/.kiro/settings/mcp.json` instead for a global (all-workspace) registration.

**Codex** — register the MCP server via CLI or `~/.codex/config.toml`:

```bash
codex mcp add ppt-generator -- uv --directory /path/to/ppt-generator run ppt-generator
```

```toml
# ~/.codex/config.toml
[mcp_servers.ppt-generator]
command = "uv"
args = ["--directory", "/path/to/ppt-generator", "run", "ppt-generator"]
```

Codex reads the repo's `AGENTS.md` for the prepare/ingest workflow guidance. See
[docs/harness/kiro-codex.md](docs/harness/kiro-codex.md) for the full walkthrough
(Visual QA setup, custom Codex prompt, per-harness entry-point table).

> For the full list of environment variables and detailed client / plugin configurations, see [docs/harness/environment.md](docs/harness/environment.md).

## 2. Usage

You interact in natural language; the client drives the prepare→generate→ingest handshake
behind the scenes (guided by the bundled skills). You don't call the `prepare_*`/`ingest_*`
tools by hand — just describe what you want.

### Tool-client update for 0.8.1

Visual QA clients must pass the `prepared_context` returned by
`prepare_visual_qa_analysis` to `ingest_visual_qa_analysis`. The bundled skill
does this automatically. Restart in-flight analysis from prepare after upgrading;
results without that context, or with changed slide/intent/screenshot inputs, are
rejected before they can authorize a visual fix.

### Step 1 — Generate or Import PPT

**Create new** — Prepare your content in a file like `context.md`, then request via your MCP client:

```
Read @context.md and generate a PPT using ppt-generator.
```

The client generates the outline JSON, then the per-slide design specs, following the
prompts and schemas the server hands back — no model credentials on the server side.
The `ppt-speaker-script` skill then writes the spoken script from the actual deck.
Its writing guide covers read-aloud wording, grounded claims, slide transitions,
and timing without tying the workflow to a particular customer or language.

**Import existing PPTX** — You can also import an existing PPTX file for editing:

```
Import @presentation.pptx using import_pptx.
```

Importing automatically generates an HTML preview. You can skip Step 2 and directly use per-slide editing, Visual QA, and export features. Parsing is deterministic with no LLM calls.

### Step 2 — Provide Project Information

Before outline generation, you will be asked for the following:

- **Presentation purpose** — e.g., "internal tech sharing", "client proposal", "conference talk"
- **Presentation duration** — 3–60 minutes (default: 15 minutes)
- **Audience type** — `general` / `technical` / `executive`
- **Presenter info** — name / title / organization

The flow proceeds Outline → DESIGN.md (design intent) → per-slide Design Spec →
Speaker Script → deck review → Visual QA → final export. A complete-deck request
can proceed through these stages without a separate outline approval. You can
request an outline-only result, omit script generation, or edit at each stage.

### Speaker scripts and notes

Ask for a script or revise notes without regenerating the visual slides:

```text
Write an English speaker script for this deck for a 15-minute online introduction.
Revise only slide 3's notes and keep the rest of the script unchanged.
```

The skill uses `prepare_speaker_script` / `ingest_speaker_script` to validate and
save only the notes. Generated and imported decks both work. Preparation includes
the actual slides and existing notes; stale submissions are rejected if the deck
changes. The completion checkpoint exports `speaker-script.md`, HTML, and PPTX
from the same saved notes. Re-export the script with `export_speaker_script` after
slide moves or edits so its order and headings match the current deck. Calculated
timing is an estimate; a read-through still verifies the presenter's actual pace.

### Step 3 — Edit Individual Slides (Optional)

After design spec generation (or PPTX import), you can modify individual slides. Instead of regenerating everything, you can add, update, delete, move, or make narrow single-component edits:

```
Add a bar chart comparing performance data below the diagram on slide 3.
Slide 5 has too much text — reduce it to key bullet points with icon layout.
Add a Q&A slide after slide 7.
Make the "LLM" box on slide 4 red.
Move slide 6 to position 2.
```

Add/update/component edits use the prepare/ingest handshake; move and delete are pure file
operations with no generation.

### Step 4 — Visual QA

Detects and fixes visual defects (line breaks, overlaps, margin misalignment, etc.). The
server captures screenshots (Playwright); the client analyzes them and generates fixes via
the prepare/ingest handshake. **Does not run automatically — must be explicitly requested.**

**Prerequisites:**

```bash
uv sync --group visual-qa
uv run --group visual-qa playwright install chromium
```

```
Run visual QA.
```

> End-to-end deck requests include read-only Visual QA and issue-scoped low-risk
> patches. If Playwright is unavailable, provide a client-captured PNG through
> `screenshot_path`. Content, data, element-count, and slide-count changes still
> require user confirmation.

### Step 5 — Export Files

After the design spec is finalized, request an HTML preview:

```
Export as HTML and open it.
```

To export in PPTX format:

```
Export as PPT and open it.
```

## Debug Logging

The MCP server uses stdio communication, so stdout logs cannot be viewed directly. Enable file logging to write debug-level logs to a file.

### Configuration

When registering the MCP server directly, add `PPT_LOG_DIR` to the `env` section:

```json
{
  "mcpServers": {
    "ppt-generator": {
      "command": "uv",
      "args": ["--directory", "/path/to/ppt-generator", "run", "ppt-generator"],
      "env": {
        "PPT_LOG_DIR": "/tmp/ppt-generator"
      }
    }
  }
}
```

> When installed as a Claude Code plugin, set `PPT_LOG_DIR` in your Claude Code MCP
> environment for the `ppt-generator` server. See [docs/harness/environment.md](docs/harness/environment.md).

### Environment Variables

| Variable | Description |
| --- | --- |
| `VISUAL_QA_PARALLEL` | Number of parallel screenshot-capture workers for Visual QA (Playwright, server-side; default: 8). Analysis/fix generation runs on the client |
| `VISUAL_QA_MAX_ITERATIONS` | Maximum fix iterations for Visual QA (default: 2) |
| `SCREENSHOT_TIMEOUT` | Per-slide screenshot capture timeout in seconds (default: 60) |
| `PPT_LOG_DIR` | Directory for per-project log files (recommended). e.g., `/tmp/ppt-generator` |
| `PPT_LOG_FILE` | Single log file path (legacy). Ignored when `PPT_LOG_DIR` is set |

- Log files rotate at 10MB with 2 backups retained.
- When `PPT_LOG_DIR` is set, a `<project_id>.log` file is created for each project.

### Viewing Logs

```bash
# View logs for a specific project
tail -f /tmp/ppt-generator/<project_id>.log

# View all logs
tail -f /tmp/ppt-generator/*.log
```

## Development

```bash
uv run ppt-generator          # Run MCP server (stdio mode)
python3 scripts/verify.py      # Locked checks, tests, build, and wheel smoke
uv run --locked pytest        # Run tests directly while debugging
```

## Documentation

- Design and contracts: [Architecture](docs/harness/architecture.md), [Schemas](docs/harness/schemas.md)
- Setup: [Environment & Config](docs/harness/environment.md), [Kiro / Codex](docs/harness/kiro-codex.md)
- Verification and delivery: [Testing](docs/harness/testing.md), [Release](docs/harness/release.md)
- Development decisions: [ADR](docs/adr/), [Contributing Guide](CONTRIBUTING.md)