PowerPoint MCP Server для Antigravity

Производственный локальный сервер Model Context Protocol (MCP) на Python, обеспечивающий диалоговый, детерминированный просмотр PowerPoint (.pptx), хирургическое редактирование, рендеринг в высоком разрешении, визуальное сравнение и проверку на основе правил для Google Antigravity.

1. Обзор и философия

Современное редактирование слайдов с помощью LLM часто разрушает тонкое форматирование, ломает иерархию шрифтов и сбрасывает сложные макеты, потому что LLM пытаются регенерировать целые презентации с нуля.

PowerPoint MCP Server реализует детерминированную философию редактирования с минимальными изменениями:

• Проверка перед изменением: Семантические роли (title, subtitle, body, diagram, image, footer) и точные ограничивающие рамки в EMU/дюймах извлекаются непосредственно из деревьев OpenXML.

• Сохранение стилей на уровне прогонов: Текстовые правки сохраняют гарнитуры, размеры пунктов, цвета, поля и многострочное форматирование с несколькими прогонами.

• Нерабочие копии: Изменения выполняются в изолированных рабочих областях сеанса в .ppt-agent/sessions/<session_id>/working.pptx с автоматическими резервными копиями с отметкой времени (presentation.backup-YYYYMMDD-HHMMSS.pptx).

• Циклы визуальной проверки: Встроенная автоматизация PowerPoint COM для Windows и безголовый рендеринг LibreOffice создают PNG-изображения слайдов и тепловые карты попиксельных различий для визуальной проверки изменений макета.

Related MCP server: PPTX MCP Server

2. Архитектура

┌─────────────────────────────────────────────────────────────────┐
│                      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. Предварительные требования и требования

• Операционная система: Windows 10/11 (для нативной автоматизации PowerPoint COM), macOS или Linux.

• Python: Python 3.10, 3.11, 3.12 или 3.13+.

• Менеджер пакетов: uv (рекомендуется) или pip.

• Программное обеспечение для презентаций (необязательно, но рекомендуется для рендеринга):

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

  • LibreOffice (CLI soffice в системном PATH).

4. Установка и настройка

Клонируйте репозиторий и установите зависимости с помощью 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

В качестве альтернативы, со стандартным pip:

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

pip install -e .

5. Запуск MCP-сервера

Чтобы запустить MCP-сервер через стандартный ввод/вывод (stdio):

uv run python -m powerpoint_mcp.server

Или через прямой скриптовый вход:

uv run powerpoint-mcp

6. Конфигурация рабочей области Antigravity

Настройте файл .agents/mcp_config.json в вашей рабочей области для регистрации сервера:

{
  "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. Установка навыка Antigravity

Определение навыка находится в .agents/skills/powerpoint-editor/SKILL.md. Antigravity автоматически обнаруживает навыки внутри .agents/skills/.

Навык кодирует:

• 15 неизменных правил редактирования PowerPoint.

• Структурированные деревья решений для текстовых правок, корректировки геометрии и сопоставления эталонных слайдов.

• Оптимизацию вызовов инструментов и правила пакетной обработки.

8. Справочник поддерживаемых инструментов MCP (19 основных инструментов)

9. Поддерживаемые ресурсы MCP

10. Автономные инструменты отладки CLI

Проверка презентации или слайда

# 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

Рендеринг слайда в 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. Примеры диалоговых команд

Вот типичные запросы на естественном языке, обрабатываемые Antigravity с помощью PowerPoint MCP Server:

1. "Открой pitch_deck.pptx и проверь слайд 2."

2. "Перемести заголовок на слайде 1 влево на 0,2 дюйма."

3. "Распредели три блока функций на слайде 1 по горизонтали с равными промежутками."

4. "Выровняй три карточки на слайде 2 по верхним краям."

5. "Измени текст тела в фигуре 4 на 'Enterprise Cloud Solutions' и сделай его жирным, сохранив шрифт Calibri 14pt."

6. "Дублируй карточку диаграммы на слайде 2 и сдвинь её на 0,5 дюйма вниз."

7. "Сделай слайд 2 соответствующим макету и иерархии шрифтов слайда 1, но сохрани содержимое слайда 2 нетронутым."

8. "Проверь слайд 3 на перекрытия или элементы за пределами слайда и исправь все найденные проблемы."

9. "Отрендерь слайд 1 и покажи мне визуальное различие с предыдущей версией."

10. "Сохрани изменённую презентацию как final_presentation.pptx."

12. Устранение неполадок и FAQ

Ошибки PowerPoint COM в Windows

• Симптом: pywintypes.com_error: (-2147417848, 'The object invoked has disconnected from its clients.')

• Решение: Убедитесь, что в диспетчере задач Windows нет зависших экземпляров POWERPNT.EXE. Закройте существующие фоновые процессы PowerPoint или перезагрузите систему. Сервер автоматически использует потокобезопасный COM-вызов с CoInitialize / CoUninitialize.

Безголовые среды и запасной вариант LibreOffice

• В безголовых средах CI/CD или на серверах Linux без Microsoft Office установите LibreOffice:

  sudo apt-get install libreoffice

• Установите PPT_RENDERER=libreoffice или PPT_RENDERER=auto в вашем окружении.

Дрейф шрифтов и типографики

• Если в отрендеренных слайдах отсутствуют пользовательские шрифты, установите файлы шрифтов TrueType/OpenType на хост-машине. Если проприетарные шрифты отсутствуют, LibreOffice и PowerPoint заменят их стандартными системными шрифтами (Calibri, Arial).

Лицензия

MIT License.