Antigravity 向け PowerPoint MCP サーバー

Google Antigravity 向けに、会話型・決定論的な PowerPoint（.pptx）の検査、精密編集、高解像度レンダリング、ビジュアル差分、ルールベース検証を実現する、本番品質のローカル Model Context Protocol（MCP）サーバー（Python 製）。

1. 概要と設計思想

最新の AI スライド編集は、LLM がプレゼンテーション全体をゼロから再生成しようとするため、細かな書式を破壊し、フォント階層を崩し、複雑なレイアウトをリセットしてしまうことがよくあります。

PowerPoint MCP サーバーは、決定論的かつ最小差分の編集哲学を実装しています。

• 変更前の検査: 意味的役割（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/ 内のスキルを自動的に検出します。

このスキルには以下が含まれます:

• PowerPoint 編集に関する 15 の不変ルール。

• テキスト編集、ジオメトリ調整、参照スライド照合のための構造化された決定ツリー。

• ツール呼び出しの最適化とバッチ処理のルール。

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 の 3 つのフィーチャーボックスを、等間隔で水平に分布させてください。」

4. 「スライド 2 の 3 つのカードを上端に沿って整列させてください。」

5. 「図形 4 の本文テキストを『Enterprise Cloud Solutions』に変更し、14pt の Calibri フォントを維持したまま太字にしてください。」

6. 「スライド 2 のダイアグラムカードを複製し、0.5 インチ下にシフトしてください。」

7. 「スライド 2 をスライド 1 のレイアウトとフォント階層に合わせてください。ただし、スライド 2 のコンテンツはそのまま保持してください。」

8. 「スライド 3 の重なりやスライド外の要素を検証し、見つかった問題を修正してください。」

9. 「スライド 1 をレンダリングして、以前のバージョンとのビジュアル差分を表示してください。」

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。