Skip to main content
Glama
Sign In
ppt-generator

ppt-generator

by haandol
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

PPT Generator

An MCP (Model Context Protocol) server that automatically generates presentations from a given topic.

LLM generation is offloaded to the client. The server owns the prompts, the output JSON schemas, and all deterministic post-processing (validation, layout, lint, HTML/PPTX render); it never calls a model itself. Each generation step is a prepare_* / ingest_* pair — prepare_* hands the client the prompt + schema, the client generates the JSON, and ingest_* validates and post-processes it. This means no AWS/Anthropic credentials and no per-call model cost on the server side — the client's own model does the generating. See the ADR index under docs/adr/ for the design rationale.

Prerequisites

  1. Python 3.13+

  2. uv package manager

  3. Claude Code (recommended — the plugin bundles the MCP server + workflow skills). Any MCP client that can generate JSON also works — no model API keys needed on the server.

Related MCP server: worklab-tools

1. Install as a Claude Code plugin (recommended)

The repo ships as a Claude Code plugin (manifest at .claude-plugin/plugin.json) that registers the MCP server and the ppt-outline / ppt-design / ppt-speaker-script / ppt-modify / ppt-visual-qa skills which drive the prepare→generate→ingest workflow.

Add the marketplace and install the plugin from within Claude Code:

/plugin marketplace add haandol/ppt-generator
/plugin install ppt-generator@ppt-generator

The plugin runs the MCP server via uv run against the plugin's own checkout (${CLAUDE_PLUGIN_ROOT}), so uv must be on your PATH and the plugin's dependencies must be synced. If the server fails to start, sync deps once from the plugin directory:

uv sync   # run inside the installed plugin's directory

No model API keys are required — the client supplies the generation.

Alternative — clone and register the MCP server directly

If you are not using the Claude Code plugin system (e.g. Kiro / Claude Desktop, or you prefer a local clone), clone the repo and register just the MCP server:

git clone https://github.com/haandol/ppt-generator.git
cd ppt-generator
uv sync
{
  "mcpServers": {
    "ppt-generator": {
      "command": "uv",
      "args": ["--directory", "/path/to/ppt-generator", "run", "ppt-generator"]
    }
  }
}

Replace /path/to/ppt-generator with the actual project path. This registers the MCP server only; the workflow skills are Claude Code plugin skills.

Use it as a skill in Kiro / Codex

The workflow is just the MCP server plus the prepare_*/ingest_* handshake, so any MCP client that can generate JSON can drive it — including Kiro and Codex. The repo ships the entry points each harness loads automatically (Kiro steering at .kiro/steering/ppt-generator.md, Codex guidance in AGENTS.md), so you get the same skill-level guidance without duplicating the prompts.

First clone and sync once (no model API keys needed):

git clone https://github.com/haandol/ppt-generator.git
cd ppt-generator
uv sync

Kiro — copy the bundled example and fix the path, then Kiro auto-loads the steering:

cp .kiro/settings/mcp.json.example .kiro/settings/mcp.json
# edit .kiro/settings/mcp.json → replace /path/to/ppt-generator with your clone path
{
  "mcpServers": {
    "ppt-generator": {
      "command": "uv",
      "args": ["--directory", "/path/to/ppt-generator", "run", "ppt-generator"],
      "disabled": false,
      "autoApprove": ["export_html", "load_project_status", "list_projects"]
    }
  }
}

Use ~/.kiro/settings/mcp.json instead for a global (all-workspace) registration.

Codex — register the MCP server via CLI or ~/.codex/config.toml:

codex mcp add ppt-generator -- uv --directory /path/to/ppt-generator run ppt-generator
# ~/.codex/config.toml
[mcp_servers.ppt-generator]
command = "uv"
args = ["--directory", "/path/to/ppt-generator", "run", "ppt-generator"]

Codex reads the repo's AGENTS.md for the prepare/ingest workflow guidance. See docs/harness/kiro-codex.md for the full walkthrough (Visual QA setup, custom Codex prompt, per-harness entry-point table).

For the full list of environment variables and detailed client / plugin configurations, see docs/harness/environment.md.

2. Usage

You interact in natural language; the client drives the prepare→generate→ingest handshake behind the scenes (guided by the bundled skills). You don't call the prepare_*/ingest_* tools by hand — just describe what you want.

Tool-client update for 0.8.1

Visual QA clients must pass the prepared_context returned by prepare_visual_qa_analysis to ingest_visual_qa_analysis. The bundled skill does this automatically. Restart in-flight analysis from prepare after upgrading; results without that context, or with changed slide/intent/screenshot inputs, are rejected before they can authorize a visual fix.

Step 1 — Generate or Import PPT

Create new — Prepare your content in a file like context.md, then request via your MCP client:

Read @context.md and generate a PPT using ppt-generator.

The client generates the outline JSON, then the per-slide design specs, following the prompts and schemas the server hands back — no model credentials on the server side. The ppt-speaker-script skill then writes the spoken script from the actual deck. Its writing guide covers read-aloud wording, grounded claims, slide transitions, and timing without tying the workflow to a particular customer or language.

Import existing PPTX — You can also import an existing PPTX file for editing:

Import @presentation.pptx using import_pptx.

Importing automatically generates an HTML preview. You can skip Step 2 and directly use per-slide editing, Visual QA, and export features. Parsing is deterministic with no LLM calls.

Step 2 — Provide Project Information

Before outline generation, you will be asked for the following:

  • Presentation purpose — e.g., "internal tech sharing", "client proposal", "conference talk"

  • Presentation duration — 3–60 minutes (default: 15 minutes)

  • Audience type — general / technical / executive

  • Presenter info — name / title / organization

The flow proceeds Outline → DESIGN.md (design intent) → per-slide Design Spec → Speaker Script → deck review → Visual QA → final export. A complete-deck request can proceed through these stages without a separate outline approval. You can request an outline-only result, omit script generation, or edit at each stage.

Speaker scripts and notes

Ask for a script or revise notes without regenerating the visual slides:

Write an English speaker script for this deck for a 15-minute online introduction.
Revise only slide 3's notes and keep the rest of the script unchanged.

The skill uses prepare_speaker_script / ingest_speaker_script to validate and save only the notes. Generated and imported decks both work. Preparation includes the actual slides and existing notes; stale submissions are rejected if the deck changes. The completion checkpoint exports speaker-script.md, HTML, and PPTX from the same saved notes. Re-export the script with export_speaker_script after slide moves or edits so its order and headings match the current deck. Calculated timing is an estimate; a read-through still verifies the presenter's actual pace.

Step 3 — Edit Individual Slides (Optional)

After design spec generation (or PPTX import), you can modify individual slides. Instead of regenerating everything, you can add, update, delete, move, or make narrow single-component edits:

Add a bar chart comparing performance data below the diagram on slide 3.
Slide 5 has too much text — reduce it to key bullet points with icon layout.
Add a Q&A slide after slide 7.
Make the "LLM" box on slide 4 red.
Move slide 6 to position 2.

Add/update/component edits use the prepare/ingest handshake; move and delete are pure file operations with no generation.

Step 4 — Visual QA

Detects and fixes visual defects (line breaks, overlaps, margin misalignment, etc.). The server captures screenshots (Playwright); the client analyzes them and generates fixes via the prepare/ingest handshake. Does not run automatically — must be explicitly requested.

Prerequisites:

uv sync --group visual-qa
uv run --group visual-qa playwright install chromium
Run visual QA.

End-to-end deck requests include read-only Visual QA and issue-scoped low-risk patches. If Playwright is unavailable, provide a client-captured PNG through screenshot_path. Content, data, element-count, and slide-count changes still require user confirmation.

Step 5 — Export Files

After the design spec is finalized, request an HTML preview:

Export as HTML and open it.

To export in PPTX format:

Export as PPT and open it.

Debug Logging

The MCP server uses stdio communication, so stdout logs cannot be viewed directly. Enable file logging to write debug-level logs to a file.

Configuration

When registering the MCP server directly, add PPT_LOG_DIR to the env section:

{
  "mcpServers": {
    "ppt-generator": {
      "command": "uv",
      "args": ["--directory", "/path/to/ppt-generator", "run", "ppt-generator"],
      "env": {
        "PPT_LOG_DIR": "/tmp/ppt-generator"
      }
    }
  }
}

When installed as a Claude Code plugin, set PPT_LOG_DIR in your Claude Code MCP environment for the ppt-generator server. See docs/harness/environment.md.

Environment Variables

Variable

Description

VISUAL_QA_PARALLEL

Number of parallel screenshot-capture workers for Visual QA (Playwright, server-side; default: 8). Analysis/fix generation runs on the client

VISUAL_QA_MAX_ITERATIONS

Maximum fix iterations for Visual QA (default: 2)

SCREENSHOT_TIMEOUT

Per-slide screenshot capture timeout in seconds (default: 60)

PPT_LOG_DIR

Directory for per-project log files (recommended). e.g., /tmp/ppt-generator

PPT_LOG_FILE

Single log file path (legacy). Ignored when PPT_LOG_DIR is set

  • Log files rotate at 10MB with 2 backups retained.

  • When PPT_LOG_DIR is set, a <project_id>.log file is created for each project.

Viewing Logs

# View logs for a specific project
tail -f /tmp/ppt-generator/<project_id>.log

# View all logs
tail -f /tmp/ppt-generator/*.log

Development

uv run ppt-generator          # Run MCP server (stdio mode)
python3 scripts/verify.py      # Locked checks, tests, build, and wheel smoke
uv run --locked pytest        # Run tests directly while debugging

Documentation

Available Tools

35 tools
capture_slidesA

Captures slide screenshots via Playwright (server-side). No LLM call.

Phase 1 of visual QA. Renders the current slide HTML to PNG so the CLIENT can analyze them for visual defects. Requires: playwright install chromium.

Args: project_id: Target project ID (required). slide_indices: 1-based comma-separated indices (e.g. "1,3,5"). Empty = all. iteration: Iteration counter (0-based) — screenshots are versioned per iteration.

Returns: JSON with project_id, iteration, screenshots: [{slide_index, screenshot_path}].

Next: for each captured slide, call prepare_visual_qa_analysis.

Inputs: project_id (required), iteration, slide_indices. Returns: result

delete_slideA

Deletes a slide. No LLM call — pure file removal + reindex.

Args: project_id: Target project ID (required) slide_index: Slide position to delete (1-based).

Returns: JSON string containing project_id and the new slide_count.

After this call, call export_html(project_id=<project_id>) to refresh HTML.

Inputs: project_id (required), slide_index (required). Returns: result

export_htmlA

Generates per-slide HTML files and an iframe container based on the design spec.

Operates in two modes:

  1. When design_spec_json is provided: Deterministically converts design spec to HTML (no LLM, fast and accurate)

  2. When only project_id is provided: Auto-loads design spec from project directory for HTML conversion (recommended)

Each slide is generated as slides/slide_NN.html, and slides.html is the iframe container.

Args: design_spec_json: Design spec JSON string project_id: Project ID (auto-generated if not specified). When provided alone, auto-loads the design spec

Returns: JSON string containing session_id, slides_html_path, slide_count, project_id

Inputs: project_id, design_spec_json. Returns: result

export_pptxB

Exports the design spec as an editable PPTX file.

Operates in two modes:

  1. When design_spec_json is provided: Generates PPTX directly from design spec (fast and accurate)

  2. When only project_id is provided: Auto-loads design spec from project directory to generate PPTX (recommended)

Args: design_spec_json: Design spec JSON string project_id: Project ID (auto-generated if not specified). When provided alone, auto-loads the design spec

Returns: JSON string containing project_id and pptx_path

Inputs: project_id, design_spec_json. Returns: result

export_speaker_scriptA

Exports speaker-script.md from current saved notes without generation.

Call again at the stable checkpoint after slide edits, moves, or deletion. Preserves slide order and the notes' meaningful line breaks.

Args: project_id: Existing generated or imported project.

Inputs: project_id (required). Returns: result

finalize_design_specA

Finalizes a freshly generated deck: builds slides.html, runs deck-wide lint.

No LLM call. Call ONCE after all slides have been ingested via ingest_design_slide. Pass the collected overflow items (if any) as JSON.

Args: project_id: Project ID (required). overflow_json: JSON array of overflow items collected from ingest calls (optional, "" if none).

Returns: JSON with design_spec_dir, slide_count, slides_html_path, lint, overflow.

IMPORTANT — Required follow-up: call export_html(project_id=<project_id>) and share slides_html_path with the user.

Inputs: project_id (required), overflow_json. Returns: result

finalize_visual_qaA

Rebuilds the deck container HTML + full export after visual QA fixes. No LLM call.

Call ONCE after all fix iterations are done.

Args: project_id: Target project ID (required).

Returns: JSON with project_id, slides_html_path, and pptx_path when export succeeds.

Inputs: project_id (required). Returns: result

import_pptxA

Imports an external PPTX file and converts it to a design spec for editing.

Reads the PPTX file, extracts all design elements (shapes, textboxes, images, backgrounds, speaker notes), and creates a new project with the design spec. HTML preview is automatically generated.

After import, you can use prepare_slide_edit / ingest_slide_edit, prepare_modify_component / ingest_modify_component, export_html, export_pptx, and the visual QA tools on the imported project.

Args: file_path: Absolute path to the PPTX file to import project_id: Project ID (auto-generated if not specified)

Returns: JSON string containing project_id, num_slides, slides_html_path, lint, and warnings

Inputs: file_path (required), project_id. Returns: result

ingest_backfillA

Ingests the design_doc backfill for an imported slide (stage="backfill").

Call AFTER a prepare_modify_component that returned stage="backfill". Saves the backfilled design_doc and returns available_components. Pick a component id and call prepare_modify_component again.

Args: project_id: Target project ID (required). slide_index: 1-based slide position. backfill_json: The backfill JSON generated by the client.

Returns: JSON with status="backfilled", available_components.

Inputs: project_id (required), slide_index (required), backfill_json (required). Returns: result

ingest_deck_reviewC

Validates a deck review result and reports semantic issues without editing.

Inputs: project_id (required), review_json (required), review_context (required). Returns: result

ingest_design_doc_draftA

Ingests the client-generated DESIGN.md draft and saves DESIGN.md.

Call AFTER prepare_design_doc_draft with the draft JSON you generated.

Args: project_id: Project ID (required). draft_json: Draft JSON (theme + tone + anti_slop + page_requests) from the client. color_theme: Color theme (stored into the theme).

Returns: JSON with project_id and design_doc_path.

Inputs: draft_json (required), project_id (required), color_theme. Returns: result

ingest_design_slideA

Ingests the client-generated slide spec: validate, normalize, save, render, lint.

Call AFTER prepare_design_slide with the spec JSON you generated.

Args: project_id: Project ID (required). slide_index: 1-based slide number (same as prepare). spec_json: The slide spec JSON generated by the client, matching the schema. generation_context: Opaque token returned by prepare_design_slide. color_theme: Color theme ("dark" or "light").

Returns: JSON with status, slide_file, slide_html_path, optional lint and overflow.

After ingesting ALL slides, call finalize_design_spec once.

Inputs: spec_json (required), project_id (required), slide_index (required), generation_context (required), +1 more. Returns: result

ingest_modify_componentA

Ingests a single-component edit: validate, apply to exactly one element, save, render.

Call AFTER a prepare_modify_component that returned stage="modify".

Args: project_id: Target project ID (required). slide_index: 1-based slide position. component_id: Target component id (same as prepare). modify_json: The ComponentModify JSON generated by the client. edit_context: Opaque context returned by prepare_modify_component. color_theme: Color theme ("dark" or "light").

Returns: JSON with modified_element, slide_html_path, optional lint.

After this call, share the returned slide_html_path with the user.

Inputs: project_id (required), modify_json (required), slide_index (required), component_id (required), +2 more. Returns: result

ingest_outlineA

Ingests the client-generated outline JSON: validates, injects presenter info, saves.

Call this AFTER prepare_outline, passing the outline JSON you generated following the returned response_schema.

An end-to-end deck request may proceed directly to design after this call. Stop for confirmation only when the user requested an outline-only result or explicitly asked to approve the slide composition.

Args: project_id: Project ID returned by prepare_outline (required). outline_json: The outline JSON generated by the client, matching the schema from prepare_outline ({"slides": [...]}).

Returns: JSON string containing outline_path and project_id.

Inputs: project_id (required), outline_json (required). Returns: result

ingest_reviewA

Ingests a slide's review result: validate, return issues (report-only).

Call AFTER prepare_review. Does NOT auto-regenerate. If has_high_severity, the response includes fix_feedback — pass it into prepare_slide_edit( action="update") to regenerate the slide with the review feedback applied.

Args: project_id: Target project ID (required). slide_index: 1-based slide position. review_json: The review result JSON generated by the client. review_context: Opaque token returned by prepare_review.

Returns: JSON with has_high_severity, issues, optional fix_feedback.

Inputs: project_id (required), review_json (required), slide_index (required), review_context (required). Returns: result

ingest_slide_editA

Ingests an add/update slide spec: validate, save (insert for add), render, lint.

Call AFTER prepare_slide_edit with the same action/slide_index, returned edit_context, and your spec JSON.

Args: project_id: Target project ID (required). action: "add" | "update" (same as prepare). slide_index: 1-based position (same as prepare; use the insertion point for add). spec_json: The slide spec JSON generated by the client. edit_context: Opaque token returned by prepare_slide_edit. color_theme: Color theme ("dark" or "light").

Returns: JSON with design_spec_dir, slide_count, slide_index, slide_html_path, optional lint.

IMPORTANT — Required follow-up: call export_html(project_id=<project_id>).

Inputs: action (required), spec_json (required), project_id (required), slide_index (required), +2 more. Returns: result

ingest_speaker_scriptA

Validates and saves notes only, preserving the deck's visual content.

Rejects stale context, missing/duplicate/out-of-range slides, and schema violations before saving. Synchronizes existing outline notes and writes speaker-script.md from the same source. Export HTML/PPTX at the final checkpoint to refresh those artifacts.

Args: project_id: Same project used in prepare_speaker_script. script_json: JSON matching the response_schema returned by prepare. script_context: Opaque context returned by that prepare call, unchanged.

Inputs: project_id (required), script_json (required), script_context (required). Returns: result

ingest_visual_qa_analysisA

Ingests the client-generated analysis: validate, report issues. No fix applied.

Call AFTER prepare_visual_qa_analysis and echo its prepared_context token. Missing or stale context is rejected; restart from prepare after upgrading an older client. If has_issues, pass analysis_context to prepare_visual_qa_fix.

Args: project_id: Target project ID (required). slide_index: 1-based slide position. analysis_json: The analysis JSON generated by the client. prepared_context: Opaque token from the same analysis prepare response.

Returns: JSON with has_issues, issues (dicts to feed into the fix step), overall_quality.

Inputs: project_id (required), slide_index (required), analysis_json (required), prepared_context. Returns: result

ingest_visual_qa_fixA

Ingests the client-generated fix: validate, save, re-render HTML.

Call AFTER prepare_visual_qa_fix. Restores images/slide_type the LLM can't produce. Re-run capture → analysis on this slide to verify (up to max_iterations).

Args: project_id: Target project ID (required). slide_index: 1-based slide position. fix_json: The visual patch JSON generated by the client. fix_context: Opaque context returned by prepare_visual_qa_fix.

Returns: JSON with status ("fixed" | "unfixed" | "unresolved"), slide_html_path.

Inputs: fix_json (required), project_id (required), fix_context (required), slide_index (required). Returns: result

list_projectsA

Retrieves the list of existing projects.

Checks the ~/.ppt-generator/ directory and returns the list of saved projects. Includes each project's ID, topic, slide count, completed steps, source, and creation time. Most recent projects are listed first.

The "source" field indicates how the project was created:

  • "generated": Created via the prepare_outline / ingest_outline pipeline (has outline)

  • "imported": Created via import_pptx (no outline — edit the design spec directly)

When to use: Always call this tool first before starting the PPT generation pipeline.

  • If no projects exist: Start a new project (call prepare_outline).

  • If projects exist: Guide the user to choose whether to continue an existing project or start a new one.

  • For imported projects: Skip outline step and work directly with design spec.

Returns: Project list JSON string. Empty array [] if no projects exist.

Inputs: no named parameters. Returns: result

load_design_specA

Loads the saved design spec.

Retrieves the previously generated design spec (PptxSlideSpec JSON) from the project directory. The project_id can be passed to export_html(project_id=...) or export_pptx(project_id=...).

Args: project_id: Project ID

Returns: JSON string containing design_spec_dir, slide_count, slide_files

Inputs: project_id (required). Returns: result

load_outlineA

Loads the saved outline JSON.

Retrieves the previously generated slide outline from the project directory. The loaded result can be used directly as input for prepare_design_slide or export_html.

Args: project_id: Project ID include_content: If True, returns full slide outline content alongside path. Defaults to False (path and slide_count only).

Returns: JSON string containing outline_path, slide_count, and optionally slides array

Inputs: project_id (required), include_content. Returns: result

load_project_statusA

Loads project status and metadata.

Checks the saved project's topic, slide count, and completion status of each step. The "source" field indicates how the project was created:

  • "generated": Created via the prepare_outline / ingest_outline pipeline (has outline)

  • "imported": Created via import_pptx (no outline available)

For imported projects: Since there is no outline, skip outline modification steps. Use prepare_slide_edit / ingest_slide_edit or prepare_design_slide / ingest_design_slide directly to modify slides.

Args: project_id: Project ID

Returns: Project metadata JSON string including source field

Inputs: project_id (required). Returns: result

move_slideA

Moves a slide from one position to another. No LLM call — pure file reordering.

Reorders all related files (outline, design_spec, slide HTML) atomically. After this call, you must call export_html(project_id=<project_id>) to refresh HTML.

Args: project_id: Target project ID (required) from_index: Current slide position (1-based). to_index: Desired slide position (1-based).

Returns: JSON string containing project_id, slide_count, from_index, to_index.

Inputs: to_index (required), from_index (required), project_id (required). Returns: result

prepare_deck_reviewB

Prepares one read-only grounding and narrative review for the whole deck.

Generate JSON matching the returned response_schema, then call ingest_deck_review. This checks evidence, assumptions, duplicate content, terminology, mandatory agenda/body/closing alignment, and time density.

Inputs: project_id (required). Returns: result

prepare_design_doc_draftA

Prepares the prompt for the CLIENT to draft DESIGN.md (design intent).

No LLM call. If DESIGN.md already exists, returns {"skip": true} — reuse the existing design intent (do not regenerate). Otherwise returns system_prompt, user_prompt, response_schema, and project_id. Generate the draft JSON (theme + tone + anti_slop + page_requests) matching response_schema, then call ingest_design_doc_draft.

Call this ONCE before generating slides, so every slide shares one design theme and narrative arc.

Args: project_id: Project ID. Loads outline from the saved project. outline_json: Full outline JSON. Optional if project_id is given. color_theme: Color theme ("dark" or "light", default: "dark").

Returns: JSON with system_prompt, user_prompt, response_schema, project_id, color_theme — or {"skip": true}.

Inputs: project_id, color_theme, outline_json. Returns: result

prepare_design_slideA

Prepares the prompt + JSON schema for the CLIENT to generate ONE slide's design spec.

No LLM call. Returns the system prompt, user prompt (with adjacent-slide context and DESIGN.md directives baked in), the response_schema the spec must match, and a thinking_budget hint. Generate the slide spec JSON that conforms to response_schema, then call ingest_design_slide.

Parallelize across slides: call prepare→generate→ingest for each slide concurrently. Slides are independent server-side. Call prepare_design_doc_draft/ingest_design_doc_draft FIRST so all slides share one theme.

Args: project_id: Project ID (required). slide_index: 1-based slide number to generate. outline_json: Full outline JSON. Optional if project_id has a saved outline. total_slides: Total slide count (0 = infer from outline). color_theme: Color theme ("dark" or "light").

Returns: JSON with system_prompt, user_prompt, response_schema, slide_type, thinking_budget, project_id, slide_index.

Inputs: project_id (required), slide_index (required), color_theme, outline_json, +1 more. Returns: result

prepare_modify_componentA

Prepares a narrow single-component edit on a content slide.

No LLM call. Returns a generation task with stage:

  • stage="modify": generate the ComponentModify JSON, then call ingest_modify_component.

  • stage="backfill" (imported slides with no design_doc): generate the backfill JSON, call ingest_backfill to get available_components, then call prepare_modify_component again with a valid component_id.

Use for narrow changes like "make the LLM box red". For broader changes use prepare_slide_edit(action="update").

Args: project_id: Target project ID (required). slide_index: 1-based slide position. component_id: Target component id from design_doc.layout leaf. instruction: Natural-language description of the change. color_theme: Color theme ("dark" or "light").

Returns: JSON with system_prompt, user_prompt, response_schema, stage, project_id, slide_index, component_id.

Inputs: project_id (required), instruction (required), slide_index (required), component_id (required), +1 more. Returns: result

prepare_outlineA

Prepares the prompt + JSON schema for the CLIENT to generate a slide outline.

This tool does NOT call an LLM. It normalizes inputs, creates/loads the project, saves the presentation metadata, and returns the system prompt, user prompt, and the JSON schema the outline must conform to. You (the client) then generate the outline JSON that follows response_schema, and pass it to ingest_outline.

Missing non-sensitive presentation conditions may use the defaults below or be inferred from the user's brief. Do not invent presenter identity.

Args: topic: Presentation topic (e.g., "2024 Cloud Computing Trends") purpose: Presentation purpose (empty = general presentation). audience_type: "general" | "technical" | "executive". presentation_minutes: 3~60 min. num_slides: Recommended number of slides (0 = auto-calculate from presentation time). presenter_name: Presenter's name (empty = omit presenter block). presenter_title: Presenter's job title. presenter_org: Presenter's organization. project_id: Project ID (auto-generated if not specified)

Returns: JSON string with: system_prompt, user_prompt, response_schema, project_id.

Next step: Generate the outline JSON matching response_schema, then call ingest_outline(project_id=<project_id>, outline_json=<your JSON>).

Inputs: topic (required), purpose, num_slides, project_id, +5 more. Returns: result

prepare_reviewA

Prepares a design-rule review task for ONE slide (mechanical lint baked in as a hint).

No LLM call. Returns the review prompt + response_schema. Generate the review JSON, then call ingest_review. Review slides in parallel.

Args: project_id: Target project ID (required). slide_index: 1-based slide position.

Returns: JSON with system_prompt, user_prompt, response_schema, project_id, slide_index.

Inputs: project_id (required), slide_index (required). Returns: result

prepare_slide_editA

Prepares to add or update ONE slide without changing project files.

No LLM call. Returns the slide generation prompt, response_schema, and an immutable edit_context. Generate the slide spec JSON, then call ingest_slide_edit with the SAME action, slide_index, and edit_context.

For narrow single-element tweaks, use prepare_modify_component instead.

Args: project_id: Target project ID (required). action: "add" | "update". slide_index: 1-based position. add: insertion point (-1 = end). update: target. title: Slide title (required for add; required for update on imported projects). content_summary: Content description (required for add; required for update on imported). component_hint: Layout hint (default: "bullets"). slide_type: "title" | "content" | "closing" | "agenda" (default: "content"). speaker_notes: Optional speaker notes. color_theme: Color theme ("dark" or "light").

Returns: JSON with prompts, response_schema, action, project_id, edit_context.

Inputs: action (required), project_id (required), title, slide_type, +5 more. Returns: result

prepare_speaker_scriptA

Prepares a deck-wide spoken script task for the ppt-speaker-script skill.

Use after design or PPTX import. Returns actual slide specs, existing notes, outline evidence when available, presentation context, response_schema, and script_context. The client writes the script; the server never calls an LLM.

Args: project_id: Existing project with a completed design spec. brief: User's language, audience, time, delivery, and Q&A preferences.

Inputs: project_id (required), brief. Returns: result

prepare_visual_qa_analysisA

Prepares the vision analysis task for ONE captured slide. No LLM call.

Returns the system prompt, user prompt, response_schema, and images (the screenshot path to read). Read the screenshot, analyze it against the spec, generate the analysis JSON matching response_schema, then call ingest_visual_qa_analysis. Analyze slides in parallel.

Args: project_id: Target project ID (required). slide_index: 1-based slide position. iteration: Iteration counter matching the capture (default 0). screenshot_path: Optional client-captured PNG path. When supplied, it is validated and used instead of requiring Playwright capture.

Returns: JSON with system_prompt, user_prompt, response_schema, images, project_id, slide_index.

Inputs: project_id (required), slide_index (required), iteration, screenshot_path. Returns: result

prepare_visual_qa_fixA

Prepares the fix task for a slide with detected issues. No LLM call.

Returns the fix prompt, response_schema, and images (the screenshot). Generate the minimal visual patch JSON, then call ingest_visual_qa_fix.

Args: project_id: Target project ID (required). slide_index: 1-based slide position. analysis_context: Opaque context returned by ingest_visual_qa_analysis. iteration: Iteration counter matching the capture (default 0).

Returns: JSON with system_prompt, user_prompt, response_schema, images, project_id, slide_index.

Inputs: project_id (required), slide_index (required), analysis_context (required), iteration. Returns: result

save_outline_slideA

Saves (overwrites) a single slide outline to the project.

Creates or overwrites the outline file for a specific slide index. Use this before calling prepare_slide_edit(action="update") to provide the updated slide content that the LLM will use for design spec generation.

For adding new slides: Use prepare_slide_edit(action="add") directly — it accepts outline parameters (title, content_summary, etc.) and handles all file shifts automatically. No need to call this tool first.

For updating existing slides:

  1. Call save_outline_slide to overwrite the outline at slide_index.

  2. Call prepare_slide_edit(action="update", slide_index=...) to regenerate the design. (Or pass title/content_summary directly to the slide_edit update.)

Args: project_id: Target project ID (required) slide_index: Target slide position (1-based). E.g., 1 for the first slide. title: Slide title content_summary: Detailed slide content description for the LLM component_hint: Layout hint ("bullets", "step_cards", "comparison_table", "arch_diagram", etc.) slide_type: Slide type ("title", "content", "closing", "agenda") speaker_notes: Optional speaker notes layout_plan: Content layout plan (arrangement direction, elements, relationships)

Returns: JSON string containing project_id, slide_index, outline_path

Inputs: title (required), project_id (required), slide_index (required), content_summary (required), +4 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.6/5.0

    Scored across 35 tools

    Disambiguation4/5

    The prepare_X/ingest_X pairing gives each tool a clear role, and descriptions carefully distinguish overlapping tools (e.g., prepare_modify_component is "narrow" vs prepare_slide_edit "broad", per-slide review vs prepare_deck_review). A few boundaries remain blurry — prepare_design_slide vs prepare_slide_edit(action=update) both generate slide specs, and prepare_review vs prepare_visual_qa_analysis are adjacent QA steps — but the docs resolve most of it.

    Naming Consistency5/5

    Every tool follows a predictable snake_case verb_noun pattern (prepare_*, ingest_*, export_*, load_*, save_*, finalize_*), with the prepare/ingest symmetry making the two-phase pipeline obvious. Minor outliers like move_slide, delete_slide, capture_slides, and import_pptx still fit the same verb_noun convention.

    Tool Count2/5

    At 35 tools this is well above the well-scoped range, and the count is inflated by the prepare/ingest doubling of nearly every operation. Each tool has a role, but the surface is heavy for what is fundamentally a deck-build/edit/export pipeline.

    Completeness5/5

    The surface covers the full lifecycle: import, outline, design doc, per-slide design, slide add/update, component edits, move/delete, per-slide and deck review, visual QA capture/analyze/fix, speaker script, and HTML/PPTX export plus project management. No obvious dead ends for the stated purpose.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • google-slides-mcp

      ryanvo162
      A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants to create, read, and edit Google Slides presentations directly from chat, with 39 tools for presentations, slides, elements, and export.
      41 npm
      1
      MIT

    • crepe-mcp

      mariolpantunes
      A
      license
      A
      quality
      B
      maintenance
      An MCP server that turns an AI agent into a slide author, enabling drafting decks in Pandoc Markdown, compiling to PDF or PowerPoint, validating with PNG exports, and pulling in research from the web, Wikipedia, and Semantic Scholar.
      17
      2
      MIT