ChatPPT

ChatPPT

ChatPPT は、プログラムによる AI 支援の PowerPoint 作成・編集を実現する Model Context Protocol（MCP）サーバーです。Node.js 20+ と @office-kit/pptx を基盤とし、Visual Studio Code やその他の MCP 対応クライアントに接続した LLM に対して、stdio 経由で安全かつ構造化されたリソース指向の CRUD API を提供します。

---

主な機能

• 安定した不透明 ID：すべてのプレゼンテーションデッキ、スライド、スライドコレクション、スライド要素を安定した UUID で追跡します。
• 二重ストレージモデル：
  • プレゼンテーションファイルは presentations/<deckId>.pptx に保存されます。
  • サーバーのメタデータ、スライドコレクション、要素のマッピングは .chatppt/registry.json で追跡されます。
• アトミック操作と一貫性：部分的なファイル破損を防ぐため、すべてのファイル書き込みに一時ファイルとアトミックな名前変更を使用します。
• スライドのビジュアルプレビュー：@office-kit/pptx-preview を使用して任意のスライドを PNG 画像にレンダリングし、エージェントが視覚的なフィードバックを得られます。
• ベクトル化／バッチ操作：1 回のツール呼び出しで複数のスライドや要素を作成、更新、削除し、LLM とのやり取りを効率化できます。
• 豊富な要素：テキストボックス、プリセット図形（180 種類以上の DrawingML ジオメトリ）、線、表、グラフ（縦棒、横棒、折れ線、円、ドーナツ、面）、画像を作成・更新できます。
• 充実したタイポグラフィとスタイル設定：カスタムフォント、フォントサイズ、太字、斜体、テキストの色、塗りつぶし、枠線／ストローク、配置、z-index の順序を設定できます。

---

VS Code でのインストールと設定

オプション 1：ワークスペースの MCP 設定（.vscode/mcp.json）

VS Code のワークスペースで ChatPPT を使用するには、ワークスペースのルートにある .vscode/mcp.json を追加または更新します。

{
  "servers": {
    "chatppt": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"]
    }
  }
}

オプション 2：公開パッケージまたは npx による実行

npx または公開済みバイナリで実行する場合、--workspace フラグまたは環境変数を使って、ChatPPT の対象ワークスペースを指定できます。

{
  "servers": {
    "chatppt": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jparkerdiamond/chatppt", "--workspace", "${workspaceFolder}"]
    }
  }
}

同梱のエージェントスキル

npm パッケージには、ポータブルな create-deck-skeleton エージェントスキルが skills/create-deck-skeleton/SKILL.md に含まれています。MCP クライアントは、サーバーへの接続時にエージェントスキルを自動的に読み込みません。このスキルを使用するには、エージェントのホストがサポートするスキル検出先（.github/skills/、.agents/skills/、.claude/skills/ など）に、そのディレクトリをインストールまたはコピーしてください。このスキルは ChatPPT の MCP ツールを使用し、特定のオペレーティングシステムやエディターには依存しません。

---

ワークスペースの動作とセキュリティ境界

ChatPPT は、次の優先順位で解決される決定的なワークスペースルート上で動作します。

1. コマンドライン引数：--workspace <path> または -w <path>
2. 環境変数：CHATPPT_WORKSPACE_ROOT または WORKSPACE_ROOT
3. フォールバック：process.cwd()（現在の作業ディレクトリ）

管理対象のファイルとディレクトリ

• プレゼンテーション：<workspace>/presentations/<deckId>.pptx
• レジストリとメタデータ：<workspace>/.chatppt/registry.json

セキュリティと信頼境界

• パスの隔離：すべてのデッキパス、一時書き込みバッファー、画像要素のパスを厳密に検証し、設定されたワークスペース内にあることを確認します。
• パストラバーサル対策：デッキ ID は ^[a-zA-Z0-9_-]+$ に一致する必要があります。絶対パスや、ワークスペースルートの外へのディレクトリトラバーサル（..）を試みる相対パスは検出され、ValidationError として拒否されます。

---

既知の制限事項

• 暗号化されたプレゼンテーション：暗号化またはパスワード保護された .pptx プレゼンテーションは検出され、拒否されます。
• マスター／テーマのレイアウト作成：スライドの作成にはデッキテンプレートに組み込まれたレイアウトを使用します。カスタムのスライドマスターテーマを一から作成する機能は、1.0 以降に延期されています。

---

利用可能な MCP ツール

デッキ管理（deck_*）

• deck_create：新しい空のプレゼンテーションデッキを作成します。
• deck_import：既存のPowerPointファイルを管理対象のワークスペースにインポートし、そのスライドを登録します。
• deck_list：ワークスペース内のすべての管理対象デッキを一覧表示します。
• deck_read：デッキのメタデータとスライド／コレクションの一覧を読み取ります。
• deck_update：オプションの楽観的リビジョンチェック（expectedRevision）を使用して、デッキのメタデータ（タイトル）を更新します。
• deck_delete：デッキとその.pptxファイルを完全に削除します。
• deck_validate：PPTXの内容とレジストリのメタデータ全体に対して、診断用の不変条件チェックを実行します。

スライド管理（slide_*）

• slide_create：1枚または複数のスライドをまとめて追加します（titleとnotesに対応）。
• slide_list：プレゼンテーションの順序に従って、0始まりのpositionインデックス付きでスライドを一覧表示します。
• slide_read：スライドのメタデータと要素の一覧を読み取ります。
• slide_render：視覚的なフィードバック用に、スライドをプレビューPNG画像にレンダリングします。ピクセル単位のwidthを任意で指定できます。デフォルトは1280で、MCPのimageコンテンツ項目を返します。
• slide_update：スライドのタイトルと発表者ノートをまとめて更新します。
• slide_delete：スライドを完全に削除し、コレクションの参照を整理します。
• slide_move：スライドを移動するか、slideOrder配列を指定して並べ替えます。
• slide_duplicate：スライドとすべての要素に新しい安定IDを付与して、スライドを複製します。

スライドコレクション管理（slide_collection_*）

• slide_collection_create：既存のスライドをまとめた、名前付きの順序付きグループを作成します。
• slide_collection_list：プレゼンテーション内のコレクションを一覧表示します。
• slide_collection_read：コレクションの詳細と、コレクションに含まれるスライドを読み取ります。
• slide_collection_update：コレクションの名前を変更するか、含まれるスライドを入れ替えます。
• slide_collection_delete：スライドを削除せずにコレクションを削除します。

スライド要素管理（element_*）

• element_create：テキストボックス、プリセット図形、線、表、グラフ、画像をまとめて作成します（任意のclientIdによる関連付けに対応）。
• element_list：スライド上のすべての要素を、Zインデックス順に一覧表示します。
• element_read：要素のメタデータとスタイル設定を読み取ります。
• element_update：位置、サイズ、テキスト、塗りつぶし、フォント、サイズ、太字、斜体、テキスト色、線、配置をまとめて更新します。
• element_delete：スライド上の要素をまとめて削除します。
• element_reorder：要素のZインデックスを調整します（bringToFront、sendToBack、bringForward、sendBackward）。

スライドプレビューのレンダリング

デッキとスライドのUUIDを指定してslide_renderを呼び出します。レスポンスには、MCPクライアントが直接表示できる、base64エンコードされたimage/pngコンテンツ項目が含まれます。

{
  "deckId": "<deck UUID>",
  "slideId": "<slide UUID>",
  "width": 1280
}

レンダラーはPowerPoint出力を決定論的に近似するもので、ヘッドレスブラウザーを使わずにNode.jsで動作します。

---

開発とテスト

前提条件

• Node.js >= 20
• npm >= 10

セットアップとビルド

npm install
npm run build

テストの実行

npm test

開発モード

npm run dev

---

npm Trusted Publishing

publish.yml GitHub Actionsワークフローは、一致するv*タグがプッシュされると、パッケージをステージングします。パッケージはあらかじめnpmに存在している必要があります。このワークフローはnpm Trusted Publishingを通じてGitHub OIDCを使用するため、npmトークンは不要です。ステージングされたパッケージは、メンテナーがnpm上で2FAを使用してレビューし、承認するまで公開されません。

npmパッケージのTrusted PublisherをGitHub Actionsで設定し、リポジトリにParkerDiamond/ChatPPT、ワークフローファイルにpublish.ymlを指定して、npm stage publishアクションを有効にしてください。ステージングジョブではNode.js 24とnpm 11.15.0以降を使用します。

MCP Registryへの公開

同じpublish.ymlワークフローは、v*バージョンタグがプッシュされると、server.jsonをMCP Registryに公開します。GitHub OIDCで認証するため、レジストリシークレットは不要です。レジストリジョブはnpmのステージング完了を待ちますが、MCP Registryの検証では、参照先のnpmバージョンが一般公開されている必要があります。ワークフローの実行時にnpmの承認が保留中の場合は、ステージングされたnpmリリースを承認し、失敗したレジストリジョブを再実行してください。

---

ライセンス

MIT