# true-deck-mcp

An MCP server that turns Markdown into True Corporation branded PowerPoint decks.
Same renderer as the `true-deck` skill — one template, two front doors.

See [DESIGN.md](DESIGN.md) for the architecture and the interactive-app plan.

## Install

```bash
pip install -e .            # or: pip install mcp>=2.0.0 python-pptx pillow
```

Preview rendering additionally needs LibreOffice and poppler:

```bash
apt-get install -y libreoffice-impress poppler-utils
```

Without them everything except `deck_preview` still works, and
`deck_capabilities` reports `preview_available: false`.

## Run

```bash
# local, for Claude Code / Claude Desktop / Gemini CLI
python -m true_deck_mcp --output-dir ~/Decks

# remote, for a Claude custom connector
python -m true_deck_mcp --transport http --port 3333 \
  --public-url https://decks.example.com
```

| Env var | Meaning |
| --- | --- |
| `TRUE_DECK_PUBLIC_URL` | Base URL. Enables `download_url`; **disables** writing to caller-supplied paths. |
| `TRUE_DECK_OUTPUT_DIR` | stdio mode: always also save decks here. |
| `TRUE_DECK_ARTIFACT_DIR` | Artifact cache (default `~/.cache/true-deck-mcp`). |

## Connect

**Claude Code / Claude Desktop** — `claude_desktop_config.json` or `.mcp.json`:

```json
{
  "mcpServers": {
    "true-deck": {
      "command": "python",
      "args": ["-m", "true_deck_mcp", "--output-dir", "/Users/you/Decks"],
      "env": { "PYTHONPATH": "/path/to/true-deck-mcp/src" }
    }
  }
}
```

**Claude web / Cowork** — run with `--transport http`, expose it
(`npx cloudflared tunnel --url http://localhost:3333` for a quick test), then
Settings → Connectors → Add custom connector → `https://.../mcp`.

**Gemini Spark** — Settings & help → Connected Apps → add the server URL.
Tools work; interactive UI is not documented there, so the server's text results
are what you get.

## Tools

| Tool | What it does |
| --- | --- |
| `deck_capabilities` | Slide kinds, block types, capacity limits, palette. |
| `deck_validate` | Outline + layout warnings, without rendering. Fast. |
| `deck_generate` | Markdown → `.pptx`; returns an `artifact_id`. |
| `deck_preview` | Renders the deck to PNGs so the agent can see it. |
| `deck_fetch` | Returns the `.pptx` as an embedded base64 blob. |

Resources: `deck://format`, `deck://design-spec`, `deck://example`.
Prompt: `build_true_deck(topic)`.

## Typical agent loop

```
deck_capabilities()                     → learn the format (once)
deck_validate(markdown)                 → fix warnings
deck_generate(markdown, "board.pptx")   → artifact_id
deck_preview(artifact_id)               → LOOK AT IT
   ...edit the Markdown, regenerate...
deck_fetch(artifact_id) / download_url  → hand it over
```

## Test

```bash
python3 tests/test_e2e.py
```

Spawns the server over real stdio and exercises every tool, writing the
resulting deck and contact sheet to `/tmp/true-deck-e2e`.