How gongrzhe/office-powerpoint-mcp-server works
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.