MCP Integration (Drive It from an AI Agent)
SlideCraft ships a headless stdio MCP server (slidecraft serve) that lets upstream AI agents such as Claude Desktop or Claude Code assemble slides.
The agent (the LLM) decides what goes into the slides, while SlideCraft's deterministic engine handles layout selection, body-text splitting, validation, and PPTX generation. Separating these roles lets you hand slide creation to an AI that produces polished decks without breaking your template's fonts or color scheme.
- The agent is the LLM: The server never calls an LLM itself. It exposes only deterministic engine operations.
- Headless: It is a Node process that needs no webview and no browser (it runs independently of the GUI version).
- No cloud transmission:
slidecraft serveitself sends nothing externally (see the egress section below).
What this page is
This is a user-oriented overview to help you grasp the "why and how" of connecting. The full specification — every tool's arguments, return values, and error contract — is collected in docs/mcp-server.md (GitHub).
Why MCP
Separate from the visual editor (writing in Markdown notation and checking in WYSIWYG) and the built-in offline AI, MCP adds value in situations like these.
- You want to hand slide creation to your own agent — Ask "turn this into slides" in the flow of a conversation, and the agent calls SlideCraft's tools to assemble them and write out a
.pptx. - You want to run batches without launching the GUI — Because it is headless, you can generate deterministically from a script or agent without starting a webview.
- You want the engine's guarantees as-is — The engine guarantees automatic layout selection, splitting of overflowing body text, and template compliance, so the agent can focus on content (harness-over-model).
Because of this division of labor, the server exposes only deterministic operations — "read," "edit," "validate," "output" — and leaves the intelligence (what to write) on the agent side.
Setup — Two Paths
The MCP server communicates over stdio (standard input/output), and the agent normally spawns the process. The MCP server is bundled with the app, so in most cases no build is required.
A. Use the packaged version (no build required, recommended)
The distribution installers (brew / .msi / .AppImage) bundle a self-contained MCP server (cli.cjs) together with a Node runtime (bundled since v0.2.0). It works even if Node is not installed on the system and without cloning the source.
macOS (Homebrew) — the cask places slidecraft-mcp on your PATH, so you can register it as-is:
brew install --cask zyuuryuu/slidecraft/slidecraft # skip if already installed
claude mcp add slidecraft -- slidecraft-mcp # for Claude CodeWhen registering via mcp.json in Claude Desktop / Cursor, write {"command": "slidecraft-mcp"}. To point directly at the bundled node plus cli.cjs without using the launcher, see "Two ways to use it" in the MCP server specification.
B. Launch from source (development version)
Clone the source and build it. This path is for customizing agent integration or debugging the engine.
npm install
npm run build:mcp # → generates dist/mcp/cli.js (esbuild, Node ESM; node_modules externalized = run inside the repo)
node dist/mcp/cli.js # waits as an MCP server over stdio (normally the agent launches it)Default is --no-fs (base64)
By default the server never touches the filesystem. The bytes of .slidecraft / .pptx are exchanged as base64 over stdio (the trust boundary is "the parent agent that launched it" = the OS user). Passing --root <dir> enables scoped fs output: export_pptx / save_project write under <dir> instead and return a path (output side only for now — see the MCP server spec).
Prerequisites for running from source
slidecraft serve imports only the pure TS engine (src/engine/*) and does not depend on DOM/Tauri. Building from source requires Node.js 20+ (see "Running from source" in Installation).
Connecting from an Agent
Below are registration examples for the packaged version (A, recommended). On macOS with brew installed, slidecraft-mcp works as-is.
Claude Code
claude mcp add slidecraft -- slidecraft-mcpClaude Desktop / Cursor
Register it under mcpServers in claude_desktop_config.json (Cursor: ~/.cursor/mcp.json, or .cursor/mcp.json in the project root).
{
"mcpServers": {
"slidecraft": {
"command": "slidecraft-mcp"
}
}
}GitHub Copilot (VS Code)
Copilot uses a different config schema. The key is servers (not mcpServers), and each server needs "type": "stdio". For a workspace, put this in .vscode/mcp.json:
{
"servers": {
"slidecraft": {
"type": "stdio",
"command": "slidecraft-mcp"
}
}
}To register it for your whole user profile, use the same shape under "mcp": { "servers": { ... } } in VS Code's settings.json.
Registering on Windows / Linux, or with the source version (B)
PATH registration of slidecraft-mcp is currently macOS/Homebrew only. On Windows/Linux, register with the absolute path to the bundled node plus cli.cjs (confirm the install location — set command to the bundled node and args to ["/absolute/path/resources/cli.cjs"]). For the source version (B), set command to node and args to ["/absolute/path/to/slidecraft/dist/mcp/cli.js"] (an absolute path). In Claude Code: claude mcp add slidecraft -- node /absolute/path/to/slidecraft/dist/mcp/cli.js. In all of these cases Copilot also needs "type": "stdio". For details on direct paths, see the MCP server specification.
After registration, SlideCraft's tools (described below) become visible to the agent.
Don't register the HTTP endpoint directly (anti-pattern)
For every client, register the stdio command (slidecraft-mcp) only — the single entry shown above. Do not register the collab host's HTTP endpoint (http://127.0.0.1:PORT/mcp + bearer token) with your agent directly. The collab host's port is ephemeral and its token rotates on every launch by design (deliberately not pinned, for security), so a direct registration forces you to rewrite the config every time you restart the GUI.
If you register slidecraft-mcp instead, the CLI discovers the host at startup and forwards to its HTTP endpoint while the GUI is running (the CLI fetches the port/token internally — you never touch them); with no GUI it runs solo. So one static config auto-switches between collab and solo, and the port/token chase disappears (the adaptive front, ADR-0033).
If you're already registering the HTTP endpoint directly, remove it and switch to the stdio command (Claude Code: claude mcp remove slidecraft → claude mcp add slidecraft -- slidecraft-mcp).
Setting Up the Skill (SKILL.md)
An MCP connection hands over tools (engine operations). In addition, giving the agent a procedure for "how to author" lets it reliably produce the deck you intend. That procedure lives in SKILL.md — it condenses onto a single page the flow of connect → provision a template → get_authoring_guide → set_slide_markdown → diagrams → the get_deck_issues feedback loop → validate_deck/export_pptx, along with contracts such as never-silent, the envelope, and data:image only.
How to hand it over (by agent):
- Claude Code / Agent Skills — place
SKILL.mdas a skill (withname/descriptionin the frontmatter). When working inside the repository, it is read as-is. - Claude Desktop and the like — at the start of the conversation, hand over the contents of
SKILL.mdas system instructions / context (paste or attach).
The runtime contract takes precedence
SKILL.md is a generic procedure. The exact formatting, layout names, and body budget for the template currently loaded are always most-current and authoritative in the self-describing contract that get_authoring_guide() returns at runtime. Tell the agent to "read get_authoring_guide first" (SKILL.md states this too).
Overview of the Main Tools
The server exposes many tools, but the flow you need to remember is simple. First, use get_authoring_guide to receive "how to write for this template," then author accordingly. That is the basic loop.
Entry points (open / create a project)
| Tool | Role |
|---|---|
open_project(dataBase64) | Loads a base64 .slidecraft. Returns {slideCount, diagnostics, contract} |
new_project(templateBase64, markdown?) | Creates a new project from a base64 .pptx template (plus optional Markdown). Goes through the same formatting path as the GUI's Draft |
create_template(spec?) | When there are no template bytes, generates a template PPTX from a name, fonts, and a 9-color palette and returns it. Missing pieces are filled from a preset |
Read the contract (learn how to write)
| Tool | Role |
|---|---|
get_authoring_guide() | The entry point for authoring. Markdown formatting resolved to this template's layout names, separator comments (<!-- col/kpi/step -->), tables/code, the body budget, and pointers to the diagram guide |
get_diagram_types() | The menu of diagram kinds (the 12 authorable types) |
get_diagram_guide(type) | The syntax plus a JSON example for the chosen diagram type |
Choosing between diagram styles works the same as in the visual editor. The 12 native types go in ```diagram (DiagramSpec), while class / state / ER / mindmap go in ```mermaid. See Diagrams for details.
Read / edit slide content
| Tool | Role |
|---|---|
get_slide(index) | A structured read of one slide (resolved layout, presence of a diagram, bullet count, budget, capacity — measured body usage, predictedSplit — a split dry-run, that slide's issues, Markdown). One call is enough to plan an edit |
get_slide_markdown(index) | The raw Markdown of one slide (layout already resolved) |
get_slide_image(index) | Returns the slide's current rendering as a PNG (the AI's visual design check). Screenshots the same shared rendering as the preview / HTML export, using a locally installed Chrome/Edge. Optional feature (see below) |
get_slide_html(index) | Returns the slide's current rendering as a self-contained HTML string (the same shared rendering get_slide_image screenshots — zero <script>, fonts embedded). Works even without a local Chrome/Edge — rasterize it with whatever means the caller has |
set_slide_markdown(index, markdown) | Replaces one slide (diagrams/mermaid are auto-preserved, validated, and invalid input is never-silent rejected) |
set_slide_diagram(index, source, format, ...) | Sets a diagram from DiagramSpec/Mermaid. Replaces an existing diagram, or adds to the body area on a text slide |
apply_design_intent(index, intent) | Applies spatial intent to a diagram (text left / diagram right, node emphasis, orientation change). Only for slides that have a diagram |
Beware of replacing the whole deck
set_deck_markdown(markdown) replaces the entire deck, and diagrams are not preserved. When you want to fix just one slide, use set_slide_markdown or insert_slide.
The visual check (get_slide_image) needs a browser
get_slide_image shoots with a locally installed Chrome/Edge only — it is never bundled or auto-downloaded (so a stale, unpatched browser is never shipped). If none is found it does not fail silently but returns {ok:false, code:"browser-not-found"} with guidance (set SLIDECRAFT_BROWSER to point at one). Capture runs network-dead in a throwaway profile, and embedded fonts keep CJK from tofu-ing. It is an optional feature — authoring and export work fine without a browser.
Structure operations (slide order)
| Tool | Role |
|---|---|
insert_slide(index, markdown, position?) | Inserts one slide before/after (other slides' diagrams are preserved = surgical) |
delete_slide(index) | Deletes (the last remaining slide is never-silent rejected) |
move_slide(fromIndex, toIndex) | Reorders (diagrams/layout preserved) |
duplicate_slide(index, position?) | Duplicates (diagrams/tables/code byte-identical) |
Deterministic levers (automatic handling of overflow and formatting)
| Tool | Role |
|---|---|
split_overflowing_slides() | Splits overflowing body text across multiple slides without shrinking the font |
convert_bullets_to_table(index) | Key-value bullets → GFM table (succeeds with "nothing applicable" when there is no target) |
Validate, save, and output
| Tool | Role |
|---|---|
validate_deck() | Deck validation plus exportReadiness (scans for un-convertible Mermaid) |
save_project() | Generates a .slidecraft and returns {dataBase64} |
export_pptx(onUnsupportedMermaid?) | Generates a .pptx headlessly as native vectors and returns {dataBase64, skipped} |
Handling un-convertible Mermaid
The 12 native diagram types and tables come out as editable PPTX shapes. Convertible Mermaid also becomes native diagrams automatically. On the other hand, gitGraph / sankey / C4 and the like cannot be drawn headlessly, so export_pptx rejects them by default (it does not silently drop them). Passing onUnsupportedMermaid: "skip" omits those slides and reports them in skipped. You can check in advance via exportReadiness from validate_deck.
The Typical Loop (from the Agent's Point of View)
The flow an agent follows is roughly as follows.
- Provision a template — Pass an existing
.slidecrafttoopen_project, or a.pptxtonew_project. If there are no bytes, generate one withcreate_template(...)and pass the returnedtemplateBase64tonew_project. - Read the contract — Grasp the formatting from the
contractreturned on open and fromget_authoring_guide. To include a diagram, get the syntax viaget_diagram_types→get_diagram_guide(type). - Author / edit — One slide at a time with
set_slide_markdown(i, md)(stay within the budget). For structure,insert_/delete_/move_/duplicate_slide; for diagrams,set_slide_diagram. Check state as a structured read withget_slide(i). - Follow the next move — Follow the
hintsattached to each edit's return (deterministic — the same deck yields the same hints). Overflow →split_overflowing_slides; key-value →convert_bullets_to_table(i). - Validate — Check
exportReadinesswithvalidate_deck. - Output — Write out the
dataBase64fromexport_pptxto a.pptxyourself (or save a.slidecraftwithsave_project).
How errors are returned (overview)
Every rejection returns as JSON with { ok: false }, and only unexpected exceptions become isError: true. Domain rejections (invalid Markdown, deleting the last remaining slide, etc.) carry only error; guard rejections (out-of-range index, not open, etc.) carry a machine-readable code. For the full contract, see docs/mcp-server.md.
Collaborative Host Mode (GUI Launches → AI Rides Along on the Same Deck)
You register one command (slidecraft serve / slidecraft mcp), and it decides at startup whether the GUI is already running (an adaptive front — ADR-0033). If the GUI is hosting a collab session, the AI rides along on it and edits the deck the human is watching (otherwise it runs solo). You never write two MCP configs.
- Lifecycle for multiple documents —
list_documents/select_document/close_document. Under GUI collab you can span multiple docs (the same tools exist in solo mode too, but with one doc they are effectively no-ops). - Server-side
undo/redo— step the deck's truth back / forward. These work in solo mode too (the payoff of unifying onto a single control plane — ADR-0033 D1). - Using registered templates — Once the GUI feeds a master registry into the host with
register_templates, the AI can browse the list withlist_templatesand mint a new project withuse_template(id, markdown?). Because it can pick a template without carrying the bytes, this is the shortest path via the host (in solo mode, bring the template bytes or usecreate_template).
This enables collaboration where the AI rides along on a deck the human is viewing in the GUI, and the human reviews the result. When the GUI and AI edits conflict, it is detected via optimistic locking and the client re-fetches.
About Data Transmission (Egress)
slidecraft serveitself sends nothing to the cloud or to an LLM.- However, the moment you connect to an agent, the deck's contents are passed to that agent's model. The very choice to "connect" is opt-in egress. When handling confidential slides, make the call based on whether you are connecting to a local or cloud agent.
- The GUI's AI Assist has a separate "local-model-only mode," which governs GUI → LLM transmission (a different boundary from the MCP path). See AI Setup for details.
Related Pages
- Diagrams — the 12 kinds of the
diagramfence and how to writemermaid - Markdown Notation — the grammar of the Markdown the agent writes
- Templates — importing
.pptxand creating new ones - AI Setup — the built-in offline AI and local-model-only mode
- FAQ — frequently asked questions
- docs/mcp-server.md (GitHub) — the full specification of all tools, resources, and the error contract