@jparkerdiamond/chatppt

ChatPPT

ChatPPT is a Model Context Protocol (MCP) server for programmatic, AI-assisted PowerPoint creation and editing. Built on Node.js 20+ and @office-kit/pptx, ChatPPT exposes a safe, structured, resource-oriented CRUD API over stdio for connected LLMs in Visual Studio Code and other MCP-compatible clients.

Key Features

• Stable Opaque IDs: Every presentation deck, slide, slide collection, and slide element is tracked with a stable UUID.
• Dual Storage Model:
  • Presentation files are stored under presentations/<deckId>.pptx.
  • Server metadata, slide collections, and element mapping are tracked in .chatppt/registry.json.
• Atomic Operations & Consistency: All file writes use temporary files and atomic renames to prevent partial file corruption.
• Visual Slide Previews: Render any slide to a PNG image for agent visual feedback using @office-kit/pptx-preview.
• Vectorized / Batch Operations: Create, update, or delete multiple slides or elements in a single tool call to optimize LLM interactions.
• Rich Elements: Create and update text boxes, preset shapes (180+ DrawingML geometries), lines, tables, charts (column, bar, line, pie, doughnut, area), and images.
• Full Typography & Styling: Custom fonts, font sizes, bold, italic, text colors, fills, borders/strokes, alignment, and z-index ordering.

Installing & Configuring in VS Code

Option 1: Workspace MCP Configuration (.vscode/mcp.json)

To use ChatPPT in your VS Code workspace, add or update .vscode/mcp.json in the root of your workspace:

{
  "servers": {
    "chatppt": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"]
    }
  }
}

Option 2: Published Package or npx Execution

When running via npx or published binary, ChatPPT can be configured to target a specific workspace using the --workspace flag or environment variables:

{
  "servers": {
    "chatppt": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jparkerdiamond/chatppt", "--workspace", "${workspaceFolder}"]
    }
  }
}

Workspace Behavior & Security Boundaries

ChatPPT operates on a deterministic workspace root resolved in the following priority order:

• Command line argument: --workspace <path> or -w <path>
• Environment variable: CHATPPT_WORKSPACE_ROOT or WORKSPACE_ROOT
• Fallback: process.cwd() (current working directory)

Files & Directories Managed

• Presentations: <workspace>/presentations/<deckId>.pptx
• Registry & Metadata: <workspace>/.chatppt/registry.json

Security & Trust Boundaries

• Path Isolation: All deck paths, temporary write buffers, and image element paths are strictly checked to ensure they reside within the configured workspace.
• Path Traversal Protection: Deck IDs must match ^[a-zA-Z0-9_-]+$. Absolute paths or relative paths attempting directory traversal (..) outside the workspace root are caught and rejected with ValidationError.

Known Limitations

• Encrypted Presentations: Encrypted or password-protected .pptx presentations are detected and rejected.
• Master / Theme Layout Authoring: Slide creation uses layouts built into the deck template; creating custom slide master themes from scratch is deferred to post-1.0.

Available MCP Tools

Deck Management (deck_*)

• deck_create: Create a new blank presentation deck.
• deck_list: List all managed decks in the workspace.
• deck_read: Read metadata and slide/collection list for a deck.
• deck_update: Update deck metadata (title) with optional optimistic revision check (expectedRevision).
• deck_delete: Permanently delete a deck and its .pptx file.
• deck_validate: Run diagnostic invariant checks across PPTX content and registry metadata.

Slide Management (slide_*)

• slide_create: Add one or multiple slides in batch (supports title and notes).
• slide_list: List slides in presentation order with 0-based position indexes.
• slide_read: Read slide metadata and its element listing.
• slide_render: Render a slide to a PNG image preview for visual feedback. Accepts an optional width in pixels, defaulting to 1280, and returns an MCP image content item.
• slide_update: Update slide title and speaker notes in batch.
• slide_delete: Permanently delete slides and clean up collection references.
• slide_move: Move a slide or reorder slides by providing a slideOrder array.
• slide_duplicate: Duplicate a slide with new stable IDs for the slide and all elements.

Slide Collection Management (slide_collection_*)

• slide_collection_create: Create a named ordered group of existing slides.
• slide_collection_list: List collections in a presentation.
• slide_collection_read: Read collection details and slide membership.
• slide_collection_update: Rename a collection or replace slide membership.
• slide_collection_delete: Delete a collection without deleting the slides.

Slide Element Management (element_*)

• element_create: Create text boxes, preset shapes, lines, tables, charts, or images in batch (supports optional clientId correlation).
• element_list: List all elements on a slide in z-index order.
• element_read: Read element metadata and styling properties.
• element_update: Update position, size, text, fill, font, size, bold, italic, text color, stroke, and alignment in batch.
• element_delete: Delete elements from a slide in batch.
• element_reorder: Adjust element z-index (bringToFront, sendToBack, bringForward, sendBackward).

Rendering a Slide Preview

Call slide_render with the deck and slide UUIDs. The response includes a base64-encoded image/png content item that MCP clients can display directly:

{
  "deckId": "<deck UUID>",
  "slideId": "<slide UUID>",
  "width": 1280
}

The renderer is a deterministic approximation of PowerPoint output and runs in Node.js without a headless browser.

Development & Testing

Prerequisites

• Node.js >= 20
• npm >= 10

Setup & Build

npm install
npm run build

Running Tests

npm test

Development Mode

npm run dev

License

MIT