deckproof-mcp

Bring your own PowerPoint template - get spec-clean slides back. A Model Context Protocol server that creates, validates, audits, and repairs .pptx files against the real OOXML / ECMA-376 (ISO/IEC 29500) PresentationML spec.

Point it at your company deck; it adds new slides that match your existing masters, layouts, theme, and branding - and every file it hands back is validated against the same structural checklist it uses to inspect other people's files. Fully local. No API keys.

---

Why this exists

LLM-driven and library-driven PowerPoint generation quietly produces broken files. They open fine in PowerPoint (which silently self-heals on load) and then fail to import into Apple Keynote, Google Slides, or Apache POI - because those readers are strict about the spec.

This isn't hypothetical:

• Anthropic's own /pptx skill shipped files that fail to open in Keynote (anthropics/skills#1167) - root-caused to a stale sldSz attribute, a missing notesMasterIdLst, and a Windows-only embedded part.
• PptxGenJS passes invalid shape presets straight through, and its defineSlideMaster can write malformed [Content_Types].xml on multi-slide decks.
• pptx-automizer (the template-cloning engine used here) can leave dangling relationships and unregistered slide IDs.

deckproof-mcp treats the OOXML spec as the source of truth: it generates against it, checks against it, and repairs to it. Creation is self-certifying - every generated or repaired file is run back through the validator before it is returned.

Install

Run it from npm with npx (no install needed) and register it with your MCP client:

{
  "mcpServers": {
    "deckproof": {
      "command": "npx",
      "args": ["-y", "deckproof-mcp"]
    }
  }
}

Running from source (before the npm package is published, or to hack on it): clone this repo, npm install && npm run build, then point your client at "command": "node", "args": ["/absolute/path/to/deckproof-mcp/dist/index.js"].

Tools

Tool	What it does
pptx_list_layouts	List the 15 built-in layout archetypes. Pass a template to also list that file's slides (with placeholder types) so you can pick stencils.
pptx_create_deck	Build a deck - from your uploaded template (clone + refill, branding inherited) or from a neutral theme. Self-certifying.
pptx_validate	Structural pass/fail for any .pptx against the 14-rule OOXML checklist.
pptx_audit	Validation plus advisory metrics: alt-text coverage, orphaned/duplicate media, counts, and per-viewer portability risk.
pptx_repair	Auto-fix an existing .pptx's structural problems and report what could not be fixed safely.

Files are returned as a base64 resource block (correct PresentationML MIME type) plus a text summary; structured JSON reports come back in structuredContent.

Bring-your-own-template workflow

1. Call pptx_list_layouts with your company .pptx as template. You get back its slides, each with an index and its placeholder types.
2. Call pptx_create_deck with the same template and a slides array. For each slide, choose an archetype (the content shape) and a stencilSlideIndex (which of your template's slides to clone for its look).
3. Text archetypes (cover, agenda, bullets, quote, ...) refill the cloned slide's placeholders. Rich archetypes (tables, timeline, org chart, matrix, ...) keep the cloned slide's branded chrome and generate their content on top, styled with colors pulled from your template's theme.

New slides are appended after your template's existing slides (this preserves spec-correctness), so your template must contain at least one slide to clone. Omit template entirely to build a fresh deck on a neutral theme.

The 15 layout archetypes

cover, agenda, contentBullets, twoColumns, quote, sectionDivider, closingNextSteps, comparisonTable, dataTable, timeline, statsBanner, cardGrid, orgChart, matrixQuadrant, verticalSteps.

What gets validated (14 rules)

Structural errors (gate valid): dangling relationships; missing presentation ID-list registrations (sldIdLst / sldMasterIdLst / notesMasterIdLst); content-type completeness; stale/contradictory sldSz; slide-layout-master inheritance; duplicate slide IDs; theme color-map breakage; orphaned master/layout chains; duplicate relationship IDs; unregistered slide/layout/master/theme parts.

Advisory warnings (surfaced by pptx_audit): Windows-only platform parts; orphaned media; missing picture alt-text; duplicate media bloat.

Deploying remotely (Streamable HTTP)

The same binary also speaks Streamable HTTP so it can run as a deployable service. node dist/index.js picks the transport at runtime:

• no PORT / MCP_TRANSPORT → stdio (the npx default).
• PORT set (most PaaS set this automatically), or MCP_TRANSPORT=http → Streamable HTTP at POST /mcp, with a GET /healthz check.

The HTTP server is stateless (fresh server per request) - safe because every tool call is a pure function of its inputs; the uploaded template travels in the request bytes, not in server state.

npm run build
npm run start:http      # MCP_TRANSPORT=http PORT=3000 node dist/index.js
# or:
docker build -t deckproof-mcp .
docker run -p 3000:3000 deckproof-mcp

Environment variables (HTTP mode)

Variable	Default	Purpose
PORT	3000	Port to listen on (setting it alone switches to HTTP mode).
MCP_TRANSPORT	(unset)	Set to http to force HTTP mode without PORT.
HOST	0.0.0.0	Interface to bind.
MCP_ALLOWED_HOSTS	(unset)	Comma-separated allowed Host header values (DNS-rebinding protection).

Security

This server ingests untrusted .pptx uploads, so it is hardened accordingly:

• path input is stdio-only. Reading a file from a local path is allowed only on the local stdio transport. Over HTTP the path input is rejected (local-file-read / SSRF protection) - remote callers must pass base64.
• Input limits. Uploads over 50 MB are rejected; packages that decompress past 300 MB are refused (zip-bomb guard); a single call is capped at 200 slides.
• XML entity expansion is disabled (no "billion laughs" amplification on crafted parts).
• No built-in authentication. These tools are read-only pure computations with no network or credential access, but if you expose the HTTP server beyond a trusted network, put it behind a gateway that handles auth and set MCP_ALLOWED_HOSTS.

Development

npm install
npm run build        # tsc -> dist/
npm test             # build + vitest (engine, tools, HTTP tiers)
npm run inspect      # MCP Inspector against the built server

Architecture: pure, dependency-free logic in src/engine/ (OPC package model, one file per validation rule, sanitizer, layout composers) with thin MCP wrappers in src/tools/. Tests build their fixtures in code (no checked-in binaries), so they never drift from what the engine emits.

How it works

• jszip + fast-xml-parser model the .pptx as an OPC package; every rule and fixer operates on that model, never raw bytes.
• pptxgenjs builds from-scratch slides; pptx-automizer clones template stencils and refills placeholders (targeting them by standard placeholder type + nameIdx, robust to duplicate element names).
• The validator runs 14 pure (package) => violations[] rules; the sanitizer runs the safe subset as fixers and re-validates.

License

MIT - see LICENSE.