Servidor MCP de PowerPoint para Antigravity

Un servidor local de Model Context Protocol (MCP) de calidad de producción en Python que permite inspección conversacional y determinista de presentaciones PowerPoint (.pptx), edición quirúrgica, renderizado de alta resolución, comparación visual y validación basada en reglas para Google Antigravity.

1. Resumen y Filosofía

La edición moderna de diapositivas con IA a menudo destruye el formato fino, rompe las jerarquías de fuentes y restablece diseños complejos porque los LLM intentan regenerar presentaciones completas desde cero.

El Servidor MCP de PowerPoint implementa una filosofía de edición determinista y de diferencia mínima:

• Inspeccionar antes de mutar: Los roles semánticos (title, subtitle, body, diagram, image, footer) y los cuadros delimitadores exactos en EMU/pulgadas se extraen directamente de los árboles OpenXML.

• Preservación de estilos a nivel de ejecución: Las ediciones de texto preservan las familias de fuentes, tamaños de punto, colores, márgenes y el formato de texto enriquecido de múltiples ejecuciones.

• Copias de trabajo no destructivas: Las modificaciones se realizan en espacios de trabajo de sesión aislados bajo .ppt-agent/sessions/<session_id>/working.pptx con copias de seguridad automáticas con marca de tiempo (presentation.backup-YYYYMMDD-HHMMSS.pptx).

• Bucles de verificación visual: La automatización integrada de PowerPoint COM en Windows y el renderizado headless de LibreOffice generan imágenes PNG de las diapositivas y mapas de calor de diferencias de píxeles para verificar visualmente los cambios de diseño.

Related MCP server: PPTX MCP Server

2. Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                      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. Requisitos y Dependencias

• Sistema operativo: Windows 10/11 (para automatización nativa de PowerPoint COM), macOS o Linux.

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

• Gestor de paquetes: uv (recomendado) o pip.

• Software de presentaciones (opcional pero recomendado para renderizado):

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

  • LibreOffice (CLI soffice en el PATH del sistema).

4. Instalación y Configuración

Clona el repositorio e instala las dependencias usando 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

Alternativamente, con pip estándar:

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

pip install -e .

5. Ejecutar el Servidor MCP

Para ejecutar el servidor MCP sobre entrada/salida estándar (stdio):

uv run python -m powerpoint_mcp.server

O mediante el punto de entrada directo del script:

uv run powerpoint-mcp

6. Configuración del Espacio de Trabajo de Antigravity

Configura tu archivo .agents/mcp_config.json del espacio de trabajo para registrar el servidor:

{
  "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. Instalación de la Habilidad de Antigravity

La definición de la habilidad se encuentra en .agents/skills/powerpoint-editor/SKILL.md. Antigravity descubre automáticamente las habilidades dentro de .agents/skills/.

La habilidad codifica:

• Las 15 Reglas Inmutables de Edición de PowerPoint.

• Árboles de decisión estructurados para ediciones de texto, ajustes de geometría y coincidencia de diapositivas de referencia.

• Reglas de optimización y agrupación de llamadas a herramientas.

8. Referencia de Herramientas MCP Soportadas (19 Herramientas Principales)

9. Recursos MCP Soportados

10. Herramientas de Depuración CLI Independientes

Inspeccionar Presentación o Diapositiva

# 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

Renderizar Diapositiva a PNG

# 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. Ejemplos de Comandos Conversacionales

Aquí hay indicaciones típicas en lenguaje natural manejadas por Antigravity usando el Servidor MCP de PowerPoint:

1. "Abre pitch_deck.pptx e inspecciona la diapositiva 2."

2. "Mueve el título de la diapositiva 1 a la izquierda 0.2 pulgadas."

3. "Distribuye los tres cuadros de características en la diapositiva 1 horizontalmente con espacios iguales."

4. "Alinea las tres tarjetas en la diapositiva 2 a lo largo de sus bordes superiores."

5. "Cambia el texto del cuerpo en la forma 4 a 'Enterprise Cloud Solutions' y ponlo en negrita manteniendo la fuente Calibri de 14pt."

6. "Duplica la tarjeta de diagrama en la diapositiva 2 y desplázala 0.5 pulgadas hacia abajo."

7. "Haz que la diapositiva 2 coincida con el diseño y la jerarquía de fuentes de la diapositiva 1, pero mantén el contenido de la diapositiva 2 intacto."

8. "Valida la diapositiva 3 para superposiciones o elementos fuera de la diapositiva y corrige cualquier problema encontrado."

9. "Renderiza la diapositiva 1 y muéstrame una diferencia visual contra la versión anterior."

10. "Guarda la presentación modificada como final_presentation.pptx."

12. Solución de Problemas y Preguntas Frecuentes

Errores de PowerPoint COM en Windows

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

• Solución: Asegúrate de que no haya instancias colgadas de POWERPNT.EXE en el Administrador de tareas de Windows. Cierra los procesos de PowerPoint en segundo plano existentes o reinicia. El servidor utiliza automáticamente despacho COM seguro para subprocesos con CoInitialize / CoUninitialize.

Entornos Headless y Respaldo de LibreOffice

• En entornos CI/CD headless o servidores Linux sin Microsoft Office, instala LibreOffice:

  sudo apt-get install libreoffice

• Establece PPT_RENDERER=libreoffice o PPT_RENDERER=auto en tu entorno.

Fuentes y Deriva Tipográfica

• Si las diapositivas renderizadas muestran fuentes personalizadas faltantes, instala los archivos de fuentes TrueType/OpenType en la máquina host. Si faltan fuentes propietarias, LibreOffice y PowerPoint sustituirán con fuentes estándar del sistema (Calibri, Arial).

Licencia

Licencia MIT.