ChatPPT MCP Server

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:

1. Command line argument: --workspace <path> or -w <path>
2. Environment variable: CHATPPT_WORKSPACE_ROOT or WORKSPACE_ROOT
3. 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

---

npm Trusted Publishing

The publish.yml GitHub Actions workflow stages a package when a matching v* tag is pushed. The package must already exist on npm. The workflow uses GitHub OIDC through npm trusted publishing and does not require an npm token. A staged package is not public until a maintainer reviews and approves it with 2FA on npm.

Configure the npm package's trusted publisher with GitHub Actions, repository ParkerDiamond/ChatPPT, workflow filename publish.yml, and the npm stage publish action enabled. The staging job uses Node.js 24 and npm 11.15.0 or later.

---

License

MIT