Antigravity용 PowerPoint MCP 서버

Google Antigravity를 위한 대화형·결정적 PowerPoint(.pptx) 검사, 정밀 편집, 고해상도 렌더링, 시각적 diff, 규칙 기반 검증을 지원하는 프로덕션 품질의 로컬 Model Context Protocol(MCP) 서버입니다.

1. 개요 및 철학

최신 AI 슬라이드 편집은 LLM이 프레젠테이션 전체를 처음부터 재생성하려고 시도하기 때문에 세밀한 서식이 파괴되고, 글꼴 계층 구조가 무너지며, 복잡한 레이아웃이 초기화되는 경우가 많습니다.

PowerPoint MCP 서버는 결정적이고 최소 변경(minimal-diff)을 지향하는 편집 철학을 구현합니다:

• 변경 전 검사(Inspect Before Mutating): 의미적 역할(title, subtitle, body, diagram, image, footer)과 정확한 EMU/인치 경계 상자는 OpenXML 트리에서 직접 추출됩니다.

• 실행 수준 스타일 보존: 텍스트 편집 시 글꼴 패밀리, 포인트 크기, 색상, 여백, 다중 실행 서식 있는 텍스트 스타일이 보존됩니다.

• 비파괴 작업 복사본: 수정은 .ppt-agent/sessions/<session_id>/working.pptx 아래의 격리된 세션 작업 공간에서 수행되며, 자동으로 타임스탬프가 찍힌 백업(presentation.backup-YYYYMMDD-HHMMSS.pptx)이 생성됩니다.

• 시각적 검증 루프: 통합된 Windows PowerPoint COM 자동화와 헤드리스 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(시스템 PATH의 soffice CLI).

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 서버 실행

표준 입력/출력(stdio)으로 MCP 서버를 실행하려면:

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. 대화형 명령 예시

다음은 PowerPoint MCP 서버를 사용하여 Antigravity가 처리하는 일반적인 자연어 프롬프트입니다:

1. "pitch_deck.pptx를 열고 슬라이드 2를 검사해 줘."

2. "슬라이드 1의 제목을 왼쪽으로 0.2인치 이동해 줘."

3. "슬라이드 1의 세 개 기능 박스를 간격이 동일하게 가로로 분산 배치해 줘."

4. "슬라이드 2의 세 카드를 위쪽 가장자리에 맞춰 정렬해 줘."

5. "도형 4의 본문 텍스트를 'Enterprise Cloud Solutions'로 바꾸고 14pt Calibri 글꼴을 유지하면서 굵게 만들어 줘."

6. "슬라이드 2의 다이어그램 카드를 복제하고 0.5인치 아래로 이동해 줘."

7. "슬라이드 2가 슬라이드 1의 레이아웃과 글꼴 계층 구조와 일치하도록 만들되, 슬라이드 2의 내용은 그대로 유지해 줘."

8. "슬라이드 3에서 겹침이나 슬라이드 밖 요소가 있는지 검증하고 발견된 문제를 수정해 줘."

9. "슬라이드 1을 렌더링하고 이전 버전과의 시각적 diff를 보여줘."

10. "수정된 덱을 final_presentation.pptx로 저장해 줘."

12. 문제 해결 및 FAQ

Windows의 PowerPoint COM 오류

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

• 해결 방법: Windows 작업 관리자에 중단된 POWERPNT.EXE 인스턴스가 없는지 확인하세요. 실행 중인 백그라운드 PowerPoint 프로세스를 종료하거나 재부팅하세요. 서버는 CoInitialize / CoUninitialize를 사용하여 스레드 안전 COM 디스패치를 자동으로 사용합니다.

헤드리스 환경 및 LibreOffice 대체

• Microsoft Office가 없는 헤드리스 CI/CD 환경이나 Linux 서버에서는 LibreOffice를 설치하세요:

  sudo apt-get install libreoffice

• 환경에서 PPT_RENDERER=libreoffice 또는 PPT_RENDERER=auto를 설정하세요.

글꼴 및 타이포그래피 변형

• 렌더링된 슬라이드에 사용자 지정 글꼴이 누락된 경우 호스트 머신에 TrueType/OpenType 글꼴 파일을 설치하세요. 독점 글꼴이 없는 경우 LibreOffice와 PowerPoint는 표준 시스템 글꼴(Calibri, Arial)로 대체합니다.

라이선스

MIT License.