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 for the architecture and the interactive-app plan.

Install

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

Preview rendering additionally needs LibreOffice and poppler:

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

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

Run

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

{
  "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

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.