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}"]
    }
  }
}

Bundled Agent Skill

The npm package includes the portable create-deck-skeleton Agent Skill at skills/create-deck-skeleton/SKILL.md. MCP clients do not automatically load agent skills when connecting to a server. To use the skill, install or copy that directory into the skill-discovery location supported by your agent host, such as .github/skills/, .agents/skills/, or .claude/skills/. The skill uses ChatPPT's MCP tools and does not depend on a particular operating system or editor.

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_import: Import an existing PowerPoint file into the managed workspace and register its slides.
• 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.

MCP Registry Publishing

The same publish.yml workflow publishes server.json to the MCP Registry when a v* version tag is pushed. It authenticates with GitHub OIDC and does not require a registry secret. The registry job waits for npm staging, but MCP Registry validation requires the referenced npm version to be publicly available. If npm approval is still pending when the workflow runs, approve the staged npm release and rerun the failed registry job.

License

MIT