Slides & Presentation Generation

Relevant source files

The following files were used as context for generating this wiki page:

• packages/google-workspace-mcp/src/google_workspace_mcp/services/slides.py
• packages/google-workspace-mcp/src/google_workspace_mcp/tools/slides.py
• packages/google-workspace-mcp/src/google_workspace_mcp/utils/markdown_slides.py
• packages/markdowndeck/README.md
• packages/google-workspace-mcp/src/google_workspace_mcp/resources/slides.py
• packages/markdowndeck/src/markdowndeck/parser/slide_extractor.py
• packages/markdowndeck/src/markdowndeck/layout/constants.py

The Slides & Presentation Generation system is a sophisticated framework within the Arclio MCP Tooling project designed to transform structured Markdown into professional Google Slides presentations. It bridges the gap between high-level content definition and the complex, nested JSON payloads required by the Google Slides API. The system handles layout calculations, content overflow across multiple slides, and granular styling through a specialized Markdown dialect.

At its core, the system utilizes the markdowndeck library as a foundational engine, which is exposed through the Model Context Protocol (MCP) as a set of tools and resources. This allows AI assistants to generate complex presentations programmatically while maintaining precise control over positioning, typography, and theme integration.

Sources: packages/markdowndeck/README.md:14-25, packages/google-workspace-mcp/src/google_workspace_mcp/resources/slides.py:25-30

System Architecture

The generation process follows a structured pipeline that ensures content is correctly parsed, laid out, and converted into API-compliant requests.

Conversion Pipeline

The conversion from Markdown to a Google Slides presentation occurs in four distinct stages:

1. Parsing: The SlideExtractor and DirectiveParser identify slides, sections, and embedded styling directives, converting them into internal data models.
2. Layout Calculation: The LayoutCalculator plans the spatial arrangement of elements based on rules defined in constants.py.
3. Overflow Handling: The OverflowHandler recursively distributes content that exceeds slide boundaries across new, sequentially linked slides.
4. API Generation: The ApiRequestGenerator produces the final validated JSON payloads for the Google Slides API.

Sources: packages/markdowndeck/README.md:52-64, packages/markdowndeck/src/markdowndeck/parser/slide_extractor.py:15-30

The diagram above illustrates the data flow from raw Markdown through the internal pipeline stages to the final Google Slides API call.

Markdown Specification & Directives

The system utilizes an enhanced Markdown dialect that supports slide separators, sectioning, and layout directives enclosed in square brackets.

Slide and Section Separation

Content is divided using specific character markers:

• Slide Separator (===): Transitions to a new slide.
• Vertical Section (---): Creates stacked containers within a single slide.
• Horizontal Section (***): Creates side-by-side columns within a slide.
• Footer Separator (@@@): Defines content for the slide footer.

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/resources/slides.py:32-60, packages/markdowndeck/src/markdowndeck/parser/slide_extractor.py:100-110

Styling Directives

Directives allow for granular control over element appearance and positioning:

Directive	Description	Example Values
width	Sets the width of a section or element	1/3, 50%, 300
height	Sets the height of a section or element	25%, 200
background	Sets background color or image URL	#f5f5f5, ACCENT1
align	Horizontal text alignment	left, center, right
valign	Vertical alignment within container	top, middle, bottom
fontsize	Numeric font size in points	18, 24
border	Border specification	1pt solid black

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/resources/slides.py:65-100, packages/markdowndeck/src/markdowndeck/layout/constants.py:180-195

Service Implementation

The SlidesService in the google-workspace-mcp package acts as the interface between MCP tools and the Google Slides API. It leverages both the markdowndeck library for bulk generation and internal utilities like MarkdownSlidesConverter for granular updates.

Key Service Methods

• create_presentation_from_markdown: The primary entry point for full deck generation. It invokes the markdowndeck pipeline.
• add_formatted_text: Handles Markdown-style formatting (bold/italic) by calculating text ranges and applying updateTextStyle requests.
• create_slide: Adds a new slide with a specific predefined layout (e.g., TITLE_AND_BODY, BLANK).

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/services/slides.py:17-45, packages/google-workspace-mcp/src/google_workspace_mcp/services/slides.py:165-185

The sequence diagram shows the interaction between the AI model, the MCP tool layer, the underlying service logic, and the external Google API.

Layout & Spatial Planning

The system operates on a "Zero Default Spacing" principle, where margins and gaps are explicitly managed or set to zero to provide a blank canvas for the layout engine.

Spatial Constants

Standard dimensions and typography rules are defined to ensure consistency:

• Standard Slide Dimensions: 720pt x 405pt (16:9 aspect ratio).
• Zone Heights: Header (90pt), Footer (30pt).
• Default Font Sizes: H1 (24pt), Paragraph (14pt), Footer (10pt).

Sources: packages/markdowndeck/src/markdowndeck/layout/constants.py:10-25, packages/markdowndeck/src/markdowndeck/layout/constants.py:35-50, packages/markdowndeck/src/markdowndeck/layout/constants.py:170-175

Markdown Slides Converter

For granular tool calls, the MarkdownSlidesConverter utility provides simplified parsing:

1. split_slides: Uses regex to find H2 headers or horizontal rules as split points.
2. parse_slide_markdown: Uses BeautifulSoup to extract HTML elements (tags like <h1>, <ul>, <table>) and map them to slide components.
3. _determine_layout: Heuristically selects a Google Slides layout based on the presence of titles, subtitles, and body elements.

Sources: packages/google-workspace-mcp/src/google_workspace_mcp/utils/markdown_slides.py:48-75, packages/google-workspace-mcp/src/google_workspace_mcp/utils/markdown_slides.py:110-140

Conclusion

The Slides & Presentation Generation module provides a robust, multi-layered architecture for turning text into visual presentations. By combining a sophisticated layout engine in markdowndeck with flexible MCP tools, the system allows for both rapid automated deck creation and precise, element-level manipulation of Google Slides resources.