# gongrzhe/office-powerpoint-mcp-server architecture

> Architecture diagram of the GitHub repository gongrzhe/office-powerpoint-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gongrzhe/office-powerpoint-mcp-server
- Repository: https://github.com/gongrzhe/office-powerpoint-mcp-server

## Overview

##### Project type and purpose
- This is a **Python‐based MCP (Model Context Protocol) server** specializing in PowerPoint (.pptx) manipulation.
- It exposes 32 “tools” (APIs) for presentation creation, template application, content management, design enhancements, charts, connectors, transitions, etc., via stdio or HTTP.
- The server is consumed by MCP clients (e.g., Claude Desktop) or via Docker/CLI.

##### File structure
- Top‐level:
- ppt_mcp_server.py – main server entrypoint; handles command‐line flags, transport selection, request routing.
- setup_mcp.py – installer script.
- slide_layout_templates.json, mcp-config.json – configuration/data files.
- Dockerfile, smithery.yaml – deployment config.
- tools/ (11 modules): each implements one category of MCP tools (presentation_tools, content_tools, template_tools, …).
- utils/ (7 modules): shared functions (error handling, pptx object management, design utilities, validation, template helpers).
- requirements.txt/pyproject.toml – dependencies (python‐pptx, Pillow, FontTools, uvx, etc.).

##### README insights
- Describes modular architecture: 11 tool modules, 7 utility modules.
- Two transport modes: stdio (default) and HTTP (via `--transport http --port`).
- Supports external configuration (MCP config), dynamic template loading, Docker deployment.

a. Main components
- Client(s): MCP clients (Claude Desktop, command‐line).
- Transport Layer: StdIO adapter, HTTP server adapter.
- Core Dispatcher: `ppt_mcp_server.py` – parses inbound MCP requests, routes to the correct tool.
- Tool Modules (tools/): grouped rectangles labeled by category (Presentation, Content, Template, Structural, Professional, Hyperlink, Chart, Connector, Master, Transition).
- Utility Modules (utils/): shared services (Error handling, PPTX session management, design utils, template utils, validation).
- External Libraries: python-pptx, Pillow, FontTools, MCP runtime (uvx).
- Configuration/Data: slide_layout_templates.json, mcp-config.json, environment variables (`PPT_TEMPLATE_PATH`), file system persistence (.pptx files).
- Deployment: Docker container boundary.

b. Relationships & interactions
2. **Transport → Core Dispatcher**: inbound JSON requests to dispatcher.
4. **Tools → Utils**: utilities for common operations (e.g., presentation_utils for opening/saving, design_utils for themes, validation_utils for text fitting).
5. **Tools/Utils → External Libraries**: calls into python-pptx to mutate presentation objects, Pillow for image filters, FontTools for font analysis.
6. **Tools → File System**: read/write .pptx, read slide_layout_templates.json, read templates from configured paths.
7. **Dispatcher → Client**: return JSON responses.

c. Architectural patterns & principles
- **Modular plugin‐style**: each tool is an isolated module with a clear responsibility.
- **Separation of concerns**: transport, dispatching, tool logic, shared utilities, and external dependencies are layered.
- **Singleton/global state manager** (in utils) tracks open presentations by ID.
- **Configuration‐driven**: JSON templates and config files decouple layout data from code.

d. Key technologies/frameworks
- python-pptx: core .pptx manipulation
- Pillow: image enhancements
- FontTools: font analysis/optimization
- MCP runtime (stdio/HTTP transports, JSON RPC)
- Docker for containerization
- Smithery for packaging

##### Detailed capture
- **flow**: Client → Transport → Dispatcher → Tool → Utils → External Libs/File System → back.
- **MCP lifecycle**: receive request, parse arguments, apply operation, send JSON response.
- **setup_mcp.py** as a side‐component for installation/configuration generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        CLI["CLI Client"]:::client
        MCP["MCP Clients\n(e.g., Claude)"]:::client
    end

    %% Docker Container Boundary
    subgraph "Docker Container"
        direction TB

        %% Transport Layer
        subgraph "Transport Layer"
            direction TB
            StdIO["StdIO Adapter"]:::transport
            HTTP["HTTP Adapter"]:::transport
        end

        %% Core Dispatcher
        PPTMCP["Core Dispatcher\n(ppt_mcp_server.py)"]:::core

        %% Tool Modules
        subgraph "Tool Modules"
            direction TB
            PRES["Presentation Tools\n(tools/presentation_tools.py)"]:::tool
            CONTENT["Content Tools\n(tools/content_tools.py)"]:::tool
            TEMPLATE["Template Tools\n(tools/template_tools.py)"]:::tool
            STRUCT["Structural Tools\n(tools/structural_tools.py)"]:::tool
            PROFESS["Professional Tools\n(tools/professional_tools.py)"]:::tool
            HYPER["Hyperlink Tools\n(tools/hyperlink_tools.py)"]:::tool
            CHART["Chart Tools\n(tools/chart_tools.py)"]:::tool
            CONNECT["Connector Tools\n(tools/connector_tools.py)"]:::tool
            MASTER["Master Slide Tools\n(tools/master_tools.py)"]:::tool
            TRANS["Transition Tools\n(tools/transition_tools.py)"]:::tool
        end

        %% Utility Modules
        subgraph "Utility Modules"
            direction TB
            COREU["Core Utilities\n(utils/core_utils.py)"]:::util
            PRESU["Presentation Session Utils\n(utils/presentation_utils.py)"]:::util
            CONTU["Content Utils\n(utils/content_utils.py)"]:::util
            DESU["Design Utils\n(utils/design_utils.py)"]:::util
            TEMPU["Template Utils\n(utils/template_utils.py)"]:::util
            VALU["Validation Utils\n(utils/validation_utils.py)"]:::util
        end
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        PYPPTX["python-pptx"]:::external
        PIL["Pillow"]:::external
        FT["FontTools"]:::external
        UVX["MCP Runtime (uvx)"]:::external
    end

    %% Configuration & Data
    subgraph "Configuration & Data"
        direction TB
        MOT["mcp-config.json"]:::config
        SLT["slide_layout_templates.json"]:::config
        ENV["Env Var\nPPT_TEMPLATE_PATH"]:::config
    end

    %% File System Persistence
    FS[".pptx Files\n(mcp_all_tools_templates_effects_demo.pptx)"]:::storage

    %% Side Components
    setup["setup_mcp.py"]:::side
    DockFile["Dockerfile"]:::side
    Smith["smithery.yaml"]:::side
    Req1["requirements.txt"]:::side
    Req2["pyproject.toml"]:::side
    DemoMP4["public/demo.mp4"]:::side

    %% Flows
    CLI -->|request| StdIO
    MCP -->|request| StdIO
    CLI -->|request| HTTP
    MCP -->|request| HTTP
    StdIO -->|JSON RPC| UVX
    HTTP -->|HTTP JSON RPC| UVX
    UVX --> PPTMCP
    PPTMCP -->|routes to| PRES
    PPTMCP -->|routes to| CONTENT
    PPTMCP -->|routes to| TEMPLATE
    PPTMCP -->|routes to| STRUCT
    PPTMCP -->|routes to| PROFESS
    PPTMCP -->|routes to| HYPER
    PPTMCP -->|routes to| CHART
    PPTMCP -->|routes to| CONNECT
    PPTMCP -->|routes to| MASTER
    PPTMCP -->|routes to| TRANS

    PRES --> COREU
    PRES --> PRESU
    PRES --> DESU
    PRES --> VALU

    CONTENT --> COREU
    CONTENT --> CONTU
    CONTENT --> VALU

    TEMPLATE --> COREU
    TEMPLATE --> TEMPU
    TEMPLATE --> VALU

    STRUCT --> COREU
    PROFESS --> COREU
    HYPER --> COREU
    CHART --> COREU
    CONNECT --> COREU
    MASTER --> COREU
    TRANS --> COREU

    PRES --> FF[PYPPTX]
    CONTENT --> FF
    TEMPLATE --> FF
    STRUCT --> FF
    PROFESS --> FF
    HYPER --> FF
    CHART --> FF
    CONNECT --> FF
    MASTER --> FF
    TRANS --> FF

    PRES --> PIL
    CONTENT --> PIL
    PRES --> FT
    CONTENT --> FT

    PPTOOLS[(File System)]:::storage
    FS --> PPTOOLS
    PRES --> PPTOOLS
    TEMPLATE --> PPTOOLS

    PPTMCP --> MOT
    PRES --> SLT
    TEMPLATE --> SLT
    PRES --> ENV
    TEMPLATE --> ENV

    %% Side flows
    setup -->|installs| PPTMCP
    DockFile -->|packages container| DockerContainer
    Smith -->|build config| DockerContainer
    Req1 -->|dependencies| PPTMCP
    Req2 -->|dependencies| PPTMCP
    DemoMP4 -->|demo asset| Clients

    %% Click Events
    click PPTMCP "https://github.com/gongrzhe/office-powerpoint-mcp-server/blob/main/ppt_mcp_server.py"
    click setup "https://github.com/gongrzhe/office-powerpoint-mcp-server/blob/main/setup_mcp.py"
    click DockFile "https://github.com/gongrzhe/office-powerpoint-mcp-server/tree/main/Dockerfile"
    click Smith "https://github.com/gongrzhe/office-powerpoint-mcp-server/blob/main/smithery.yaml"
    click Req1 "https://github.com/gongrzhe/office-powerpoint-mcp-server/blob/main/requirements.txt"
    click Req2 "https://github.com/gongrzhe/office-powerpoint-mcp-server/blob/main/pyproject.toml"
    click MOT "https://github.com/gongrzhe/office-powerpoint-mcp-server/blob/main/mcp-config.json"
    click SLT "https://github.com/gongrzhe/office-powerpoint-mcp-server/blob/main/slide_layout_templates.json"
    click FS "https://github.com/gongrzhe/office-powerpoint-mcp-server/blob/main/mcp_all_tools_templates_effects_demo.pptx"

    %% Styles
    classDef client fill:#d3f4ff,stroke:#066
    classDef transport fill:#c8facc,stroke:#2a
    classDef core fill:#bfd7ff,stroke:#339
    classDef tool fill:#d0e0e3,stroke:#3a
    classDef util fill:#fdf1c7,stroke:#aa3
    classDef external fill:#ffd1d1,stroke:#a33
    classDef config fill:#e2e2e2,stroke:#888
    classDef storage fill:#e6e6e6,stroke:#555,stroke-dasharray:5 5
    classDef side fill:#eeeeee,stroke:#666
```
