PowerPoint MCP Server für Antigravity

Ein produktionsreifer lokaler Model Context Protocol (MCP)-Server in Python, der konversationelle, deterministische PowerPoint-Inspektion (.pptx), chirurgische Bearbeitung, hochauflösendes Rendering, visuelles Diffing und regelbasierte Validierung für Google Antigravity ermöglicht.

1. Überblick & Philosophie

Moderne KI-gestützte Folienbearbeitung zerstört oft feingranulare Formatierungen, bricht Schrifthierarchien und setzt komplexe Layouts zurück, weil LLMs versuchen, ganze Präsentationen von Grund auf neu zu generieren.

Der PowerPoint MCP Server implementiert eine deterministische, minimal-diff-basierte Bearbeitungsphilosophie:

• Erst prüfen, dann ändern: Semantische Rollen (title, subtitle, body, diagram, image, footer) und exakte EMU/Zoll-Begrenzungsrahmen werden direkt aus OpenXML-Bäumen extrahiert.

• Stilerhaltung auf Run-Ebene: Textbearbeitungen bewahren Schriftarten, Punktgrößen, Farben, Ränder und mehrteilige Rich-Text-Formatierung.

• Zerstörungsfreie Arbeitskopien: Änderungen erfolgen in isolierten Sitzungs-Arbeitsbereichen unter .ppt-agent/sessions/<session_id>/working.pptx mit automatischen, zeitgestempelten Sicherungen (presentation.backup-YYYYMMDD-HHMMSS.pptx).

• Visuelle Verifikationsschleifen: Integrierte Windows-PowerPoint-COM-Automatisierung und Headless-LibreOffice-Rendering erzeugen PNG-Folienbilder und Pixel-Differenz-Heatmaps, um Layoutänderungen visuell zu verifizieren.

Related MCP server: PPTX MCP Server

2. Architektur

┌─────────────────────────────────────────────────────────────────┐
│                      Antigravity CLI Agent                      │
│        (Skill: .agents/skills/powerpoint-editor/SKILL.md)       │
└───────────────────────────────┬─────────────────────────────────┘
                                │ JSON-RPC 2.0 via Stdio
┌───────────────────────────────▼─────────────────────────────────┐
│              PowerPoint MCP Server (server.py)                  │
│       19 FastMCP / MCPServer Tools  &  3 MCP Resources          │
└───────┬───────────────────────┼─────────────────────────┬───────┘
        │                       │                         │
┌───────▼──────────────┐ ┌──────▼───────────────┐  ┌──────▼───────────────┐
│ Inspection & Models  │ │  Editing & Geometry  │  │ Rendering & Diffing  │
│ - Shape Hierarchies  │ │ - Move / Resize      │  │ - Windows PPT COM    │
│ - Semantic Inference │ │ - Align / Distribute │  │ - LibreOffice CLI    │
│ - Multi-Factor Match │ │ - Text Run Styling   │  │ - Pixel Diff Heatmaps│
│ - Rule Validation    │ │ - Safe OOXML Helpers │  │ - Bounding Clusters  │
└──────────────────────┘ └──────────────────────┘  └──────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────────┐
│                  Session & Safety Layer                         │
│   .ppt-agent/sessions/<session_id>/working.pptx + backups/      │
└─────────────────────────────────────────────────────────────────┘

3. Voraussetzungen & Anforderungen

• Betriebssystem: Windows 10/11 (für native PowerPoint-COM-Automatisierung), macOS oder Linux.

• Python: Python 3.10, 3.11, 3.12 oder 3.13+.

• Paketmanager: uv (empfohlen) oder pip.

• Präsentationssoftware (optional, aber für das Rendering empfohlen):

  • Microsoft PowerPoint 2016 / 2019 / 2021 / Office 365 (Windows).

  • LibreOffice (soffice-CLI im System-PATH).

4. Installation & Einrichtung

Klonen Sie das Repository und installieren Sie die Abhängigkeiten mit uv:

# Clone the repository
git clone https://github.com/example/powerpoint-mcp.git
cd powerpoint-mcp

# Create and sync virtual environment with uv
uv sync

Alternativ mit Standard-pip:

python -m venv .venv
# On Windows PowerShell:
.venv\Scripts\Activate.ps1
# On macOS/Linux:
source .venv/bin/activate

pip install -e .

5. Ausführen des MCP-Servers

Um den MCP-Server über Standard-Eingabe/Ausgabe (stdio) auszuführen:

uv run python -m powerpoint_mcp.server

Oder über den direkten Skript-Einstiegspunkt:

uv run powerpoint-mcp

6. Antigravity-Arbeitsbereichskonfiguration

Konfigurieren Sie Ihren Arbeitsbereich .agents/mcp_config.json, um den Server zu registrieren:

{
  "mcpServers": {
    "powerpoint-mcp": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "powerpoint_mcp.server"
      ],
      "env": {
        "PPT_RENDERER": "auto",
        "PPT_WORKSPACE_DIR": ".ppt-agent",
        "PPT_BACKUP_ENABLED": "true",
        "PPT_DEFAULT_OUTPUT_DIR": "./output"
      }
    }
  }
}

7. Installation der Antigravity-Fähigkeit

Die Fähigkeitsdefinition befindet sich unter .agents/skills/powerpoint-editor/SKILL.md. Antigravity erkennt Fähigkeiten automatisch innerhalb von .agents/skills/.

Die Fähigkeit kodiert:

• Die 15 unveränderlichen PowerPoint-Bearbeitungsregeln.

• Strukturierte Entscheidungsbäume für Textbearbeitungen, Geometrieanpassungen und Referenzfolienabgleich.

• Optimierung von Tool-Aufrufen und Batching-Regeln.

8. Referenz der unterstützten MCP-Tools (19 Kern-Tools)

9. Unterstützte MCP-Ressourcen

10. Eigenständige CLI-Debugging-Tools

Präsentation oder Folie untersuchen

# Inspect entire presentation metadata
python scripts/inspect_pptx.py presentation.pptx

# Inspect specific slide as ASCII tree
python scripts/inspect_pptx.py presentation.pptx --slide 1

# Inspect single shape in JSON format
python scripts/inspect_pptx.py presentation.pptx --slide 1 --shape 2 --json

Folie als PNG rendern

# Render all slides to ./renders/
python scripts/render_pptx.py presentation.pptx --output ./renders

# Render single slide at 300 DPI using PowerPoint COM
python scripts/render_pptx.py presentation.pptx --slide 1 --dpi 300 --renderer powerpoint

11. Beispielhafte Konversationsbefehle

Hier sind typische natürlichsprachliche Aufforderungen, die von Antigravity mit dem PowerPoint-MCP-Server verarbeitet werden:

1. "Öffne pitch_deck.pptx und untersuche Folie 2."

2. "Verschiebe den Titel auf Folie 1 um 0,2 Zoll nach links."

3. "Verteile die drei Feature-Boxen auf Folie 1 horizontal mit gleichen Abständen."

4. "Richte die drei Karten auf Folie 2 an ihren oberen Kanten aus."

5. "Ändere den Fließtext in Form 4 zu 'Enterprise Cloud Solutions' und mache ihn fett, während die 14pt Calibri-Schriftart beibehalten wird."

6. "Dupliziere die Diagrammkarte auf Folie 2 und verschiebe sie um 0,5 Zoll nach unten."

7. "Bringe Folie 2 in Übereinstimmung mit dem Layout und der Schrifthierarchie von Folie 1, aber behalte den Inhalt von Folie 2 bei."

8. "Validiere Folie 3 auf Überlappungen oder Elemente außerhalb der Folie und behebe alle gefundenen Probleme."

9. "Rendere Folie 1 und zeige mir einen visuellen Diff gegen die vorherige Version."

10. "Speichere das geänderte Deck als final_presentation.pptx."

12. Fehlerbehebung & FAQ

PowerPoint-COM-Fehler unter Windows

• Symptom: pywintypes.com_error: (-2147417848, 'The object invoked has disconnected from its clients.')

• Lösung: Stellen Sie sicher, dass keine hängenden POWERPNT.EXE-Instanzen im Windows Task-Manager vorhanden sind. Schließen Sie vorhandene PowerPoint-Hintergrundprozesse oder starten Sie neu. Der Server verwendet automatisch thread-sichere COM-Dispatch mit CoInitialize / CoUninitialize.

Headless-Umgebungen & LibreOffice-Fallback

• In Headless-CI/CD-Umgebungen oder Linux-Servern ohne Microsoft Office installieren Sie LibreOffice:

  sudo apt-get install libreoffice

• Setzen Sie PPT_RENDERER=libreoffice oder PPT_RENDERER=auto in Ihrer Umgebung.

Schriftarten und Typografie-Drift

• Wenn gerenderte Folien fehlende benutzerdefinierte Schriftarten aufweisen, installieren Sie die TrueType/OpenType-Schriftdateien auf dem Host. Wenn proprietäre Schriftarten fehlen, ersetzen LibreOffice und PowerPoint sie durch Standard-Systemschriftarten (Calibri, Arial).

Lizenz

MIT License.