Slides and Shapes¶

Reference for the slide tool (add-blank, get-count, delete, duplicate, move-to, set-background-color, get-background-color, visibility, sections, comments, import) and the shape tool (add-rectangle, add-text-box, add-text-effect, add-auto-shape, add-line, add-connector, add-attached-connector, get-count, delete, set-position, set-size, align, distribute, merge, plus the fill/line/rotation/flip/z-order/shadow/glow/ reflection/soft-edge/bevel/group/name/alt-text/hyperlink formatting actions below).

Slide Actions¶

Slides always append at the end via add-blank — there is no "insert blank at position N" action; use add-blank then move-to if you need a blank slide inserted mid-deck. See deck-builder.md for planning multi-slide order.

MCP clients can use slide_read for the explicitly read-only slide actions, including inspect, get-count, and background, section, comment, and tag queries. The original slide tool remains available unchanged. pptcli continues to use pptcli slide <action>.

Sections¶

Sections group contiguous ranges of slides for organizational purposes (visible in PowerPoint's slide thumbnail panel) — they do not affect slide content or rendering. A slide's section membership is purely positional (determined by where the slide sits between section boundaries), so reordering slides with move-to can move them into a different section.

slide(action: "add-section", presentation_session_id: ..., section_index: 1, section_name: "Introduction")
slide(action: "add-section", presentation_session_id: ..., section_index: 2, section_name: "Deep Dive")
  → splits the deck into two sections at the current slide count boundary

slide(action: "get-section-count", presentation_session_id: ...) → sectionCount: 2
slide(action: "rename-section", presentation_session_id: ..., section_index: 2, section_name: "Details")

Shape Actions¶

All position/size values are points (see deck-builder.md for the 960×540pt 16:9 reference).

Align and Distribute¶

Use shape(action: "align", ..., shape_indexes: [3, 1, 2], align_cmd: "msoAlignTops") to align a selection. align_cmd accepts msoAlignLefts, msoAlignCenters, msoAlignRights, msoAlignTops, msoAlignMiddles, or msoAlignBottoms. Names are case-insensitive; numeric enum values are rejected.

By default, alignment uses the selection's original bounding rectangle and needs two shapes. Set relative_to_slide: true to use slide bounds; this also allows one shape. Array order does not choose an anchor shape.

Use shape(action: "distribute", ..., shape_indexes: [3, 1, 2], distribute_cmd: "msoDistributeHorizontally") for equal horizontal edge gaps, or msoDistributeVertically for vertical gaps. At least three shapes are required. By default the outer shapes retain the selection's original span. With relative_to_slide: true, equal gaps include the margins at both slide edges. This spaces edges, not centers: unequal-sized shapes have unequal center distances.

Both actions require presentation_session_id, slide_index, and distinct 1-based top-level shape_indexes. Invalid indexes, duplicates, or commands fail before any movement. The result returns the total slide shapeCount. No shapes are resized or regrouped. Groups are treated as whole top-level shapes; rotated shapes use native PowerPoint geometry. This is not collision avoidance: insufficient space can produce overlap. Export the slide to verify the result after arranging it.

Shape Formatting Actions¶

Finding a just-grouped shape's index: group does not return the new group shape's own shapeIndex — reading .Index off a freshly-created COM group object is unreliable in this codebase's NoPIA late-binding setup. If the shapes you grouped were the last shapes added to the slide (highest indices, nothing added after them), the resulting group occupies the new, smaller shapeCount as its index (since grouping N shapes always removes N-1 from the slide's shape list). Otherwise, call shape(action: "get-count", ...) before and after grouping and inspect via a follow-up read if you need to confirm which index now holds the group.

Hyperlinks¶

set-hyperlink/get-hyperlink/remove-hyperlink manage a shape's mouse-click action — clicking the shape at presentation time navigates to address (an absolute URL like "https://example.com", or a local file path). There is no separate mouse-hover hyperlink action, and no text-run-level hyperlink (a whole-shape hyperlink is the only granularity this tool surface exposes) — to make specific words within a text box clickable, put that text in its own shape.

address is normalized by PowerPoint itself (e.g. "https://example.com" round-trips as "https://example.com/" with a trailing slash) — compare against the returned hyperlinkAddress rather than assuming an exact byte-for-byte match of what you passed in.

shape(action: "set-hyperlink", presentation_session_id: ..., slide_index: ..., shape_index: ...,
  address: "https://example.com", screen_tip: "Visit our site")
shape(action: "get-hyperlink", presentation_session_id: ..., slide_index: ..., shape_index: ...)
  → hasHyperlink: true, hyperlinkAddress: "https://example.com/", hyperlinkScreenTip: "Visit our site"
shape(action: "remove-hyperlink", presentation_session_id: ..., slide_index: ..., shape_index: ...)
  → hasHyperlink: false

Linked Pictures¶

File links are separate from click hyperlinks. Add a linked picture with image(action: "add-picture", ..., link_to_file: true), then use get-link-info, update-link, set-link-auto-update, or break-link on that picture's 1-based shape index. break-link retains the picture as an embedded shape. Link operations on rectangles, text boxes, embedded pictures, or other non-linked shapes return a validation error. Unexpected PowerPoint errors from typed link members propagate to the MCP or CLI boundary.

Dash Styles (dash_style for set-line)¶

Must match a real MsoLineDashStyle enum member name exactly: msoLineSolid, msoLineSquareDot, msoLineRoundDot, msoLineDash, msoLineDashDot, msoLineDashDotDot, msoLineLongDash, msoLineLongDashDot.

Z-Order Commands (z_order_command for set-z-order)¶

bring-to-front, send-to-back, bring-forward, send-backward. (PowerPoint's Word-only z-order members — bring/send relative to text — are intentionally not exposed here.)

Auto Shape Types¶

shape_type for add-auto-shape must match a real MsoAutoShapeType enum member name exactly (case-sensitive, mso-prefixed PascalCase) — this is a curated subset (not the full Office enum):

Passing an unrecognized string returns success: false — double-check spelling rather than guessing variants (e.g. star/callout shapes are not in this curated set).

For lines and connectors, connector_type must be one of msoConnectorStraight, msoConnectorElbow, or msoConnectorCurve.

Shape Indexing Within a Slide¶

shape_index is 1-based and reflects the order shapes were added to that slide (and any built-in placeholders from the applied layout, if present). After adding several shapes, use shape(action: "get-count", ...) to confirm the current total before referencing an index you didn't just create yourself — don't assume index 1 is always the title.

shape(action: "add-text-box", presentation_session_id: ..., slide_index: 1, ..., text: "Title")   → shapeIndex 1 (assuming a blank slide)
shape(action: "add-rectangle", presentation_session_id: ..., slide_index: 1, ...)                  → shapeIndex 2
shape(action: "add-text-box", presentation_session_id: ..., slide_index: 1, ..., text: "Body")     → shapeIndex 3
shape(action: "get-count", presentation_session_id: ..., slide_index: 1) → 3                        → confirms the count before further edits

Building a Text Box + Table/Chart Combo Slide¶

Tables and charts are added by their own domain tools (table(action: "add-table", ...), chart(action: "add-chart", ...) — see tables.md and charts.md) but they are shapes on the slide like any other, and share the same shape_index numbering with rectangles and text boxes added on that slide. Track the returned shapeIndex from each add call (or re-check with shape(action: "get-count", ...)) so subsequent position/size/format calls target the right shape.

Repositioning and Resizing¶

Use shape(action: "set-position", ...) / shape(action: "set-size", ...) for targeted layout fixes instead of deleting and re-adding a shape:

CORRECT — nudge a shape that overlaps another after visual verification
shape(action: "set-position", presentation_session_id: ..., slide_index: ..., shape_index: ..., left: 500, top: 120)

AVOID — delete and recreate to move a shape
shape(action: "delete", presentation_session_id: ..., slide_index: ..., shape_index: ...)
shape(action: "add-rectangle", presentation_session_id: ..., slide_index: ..., left: 500, top: 120, width: ..., height: ...)

Deleting and recreating loses the shape's text content and any formatting already applied to it — prefer targeted set-position/set-size (see anti-patterns.md).