From 100f89feaaa65d59fef4844c6c6b1756aaed45de Mon Sep 17 00:00:00 2001 From: che cheng Date: Mon, 24 Aug 2026 04:38:13 +0800 Subject: [PATCH 1/5] docs: add che-pptx-mcp usage skill (#159) --- plugins/che-pptx-mcp/CHANGELOG.md | 6 ++ plugins/che-pptx-mcp/README.md | 8 +++ .../che-pptx-mcp/skills/che-pptx-mcp/SKILL.md | 58 +++++++++++++++++++ 3 files changed, 72 insertions(+) create mode 100644 plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md diff --git a/plugins/che-pptx-mcp/CHANGELOG.md b/plugins/che-pptx-mcp/CHANGELOG.md index 830a7843..397c01b3 100644 --- a/plugins/che-pptx-mcp/CHANGELOG.md +++ b/plugins/che-pptx-mcp/CHANGELOG.md @@ -4,6 +4,12 @@ All notable changes to the che-pptx-mcp plugin shell will be documented in this The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +## [Unreleased] + +### Added + +- 新增 `che-pptx-mcp` skill（PsychQuant/macdoc#159）：提供 Direct／Session 工作流、具名 MCP tools、0-based index／EMU 慣例，以及 PDF／render 尚未支援的誠實邊界。 + ## [0.1.2] - 2026-07-02 ### Changed diff --git a/plugins/che-pptx-mcp/README.md b/plugins/che-pptx-mcp/README.md index 37d6719b..6720d779 100644 --- a/plugins/che-pptx-mcp/README.md +++ b/plugins/che-pptx-mcp/README.md @@ -9,6 +9,14 @@ claude plugin marketplace add PsychQuant/macdoc claude plugin install che-pptx-mcp@macdoc ``` +## 使用方式 + +安裝後可由 `che-pptx-mcp` skill 取得具名工具流程、Direct／Session 模式、索引與 EMU 慣例： + +`plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md` + +目前可讀寫 slides、shapes、tables、images、notes、theme，並匯出 Markdown。尚未提供 PDF 匯出、投影片 render／PNG preview 或 cm 幾何工具；`export_image` 只匯出簡報內嵌圖片，不是投影片預覽。 + Wrapper 會自動從 [GitHub Releases](https://github.com/PsychQuant/che-pptx-mcp/releases) 下載 release 的 `ChePPTXMCP` universal binary 到 plugin 層級的 `.bin-cache/`（跨 marketplace 隔離、跨版本持久），安裝前與每次啟動時強制驗證 sha256（安裝時）與 Developer ID Application 簽章鏈（Team `6W377FS7BS`）。release 流程含 Apple notarization（wrapper 不重複檢查 notarization）。 ## 原始碼 diff --git a/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md b/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md new file mode 100644 index 00000000..4b573f0b --- /dev/null +++ b/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md @@ -0,0 +1,58 @@ +--- +name: che-pptx-mcp +description: Use when reading, creating, or editing PowerPoint .pptx presentations with the che-pptx-mcp plugin, especially for slides, shapes, tables, notes, images, themes, or Markdown export. +--- + +# che-pptx-mcp + +Use the Swift-native PresentationML server for `.pptx` work without launching PowerPoint. + +## Choose a mode + +| Need | Mode | Address | +|---|---|---| +| Inspect one file | Direct, read-only | `source_path` | +| Create or edit | Session | `doc_id` after `create_presentation` or `open_presentation` | + +All `slide_index`, row, and column indices are zero-based. Shape edits use the `shape_id` returned by `get_slide_shapes`. Geometry parameters are raw EMU integers; centimetre helpers are not shipped yet. + +## Edit an existing presentation + +```text +1. open_presentation(path: "/in/deck.pptx", doc_id: "deck") +2. get_slide_shapes(doc_id: "deck", slide_index: 1) +3. update_shape_text(doc_id: "deck", slide_index: 1, + shape_id: , text: "New title") +4. save_presentation(doc_id: "deck", path: "/out/deck-edited.pptx") +5. close_presentation(doc_id: "deck") +``` + +Edits stay in memory until `save_presentation` unless the session was opened with `autosave: true`. Use a different output path to preserve the source. + +## Common tools + +| Task | Tools | +|---|---| +| Inspect | `get_presentation_info`, `get_slide_count`, `get_text`, `get_slide_text`, `get_slide_shapes`, `get_shape_text`, `search_text` | +| Slides | `add_slide`, `delete_slide`, `duplicate_slide`, `reorder_slides` | +| Shapes | `insert_text_shape`, `update_shape_text`, `delete_shape`, `set_shape_position`, `set_shape_size`, `set_shape_fill` | +| Tables | `get_tables`, `get_table_data`, `insert_table`, `update_cell` | +| Images | `list_images`, `export_image`, `insert_image`, `delete_image` | +| Notes/theme | `get_slide_notes`, `add_notes`, `set_transition`, `get_theme`, `get_slide_master`, `get_slide_layouts` | +| Export | `export_markdown` | + +Read tools accept either `source_path` or `doc_id` when their schema offers both. Mutation tools require an open session and `doc_id`. + +## Honest boundaries + +- No PDF export, slide rendering, PNG preview, or PowerPoint/Keynote automation tool is currently exposed. Do not promise a visual preview; use another renderer after saving when one is available. +- `export_image` returns an embedded image as base64; it does not render a slide. +- `insert_image`, text-shape placement, position, and size use EMU. +- Rich text runs, layout-based slide creation, and the #90 centimetre geometry tools are not part of the current published surface. + +## Common mistakes + +- Editing with `source_path`: open a session first. +- Treating the second slide as index 2: use `slide_index: 1`. +- Guessing a shape ID: call `get_slide_shapes` and use its returned ID. +- Closing before saving: save the intended output path, then close. From 440b4be492a0895c146b7a3e573ac590ef07eafd Mon Sep 17 00:00:00 2001 From: che cheng <kiki830621@gmail.com> Date: Mon, 24 Aug 2026 04:40:27 +0800 Subject: [PATCH 2/5] docs: address che-pptx skill review findings (#159) --- .claude-plugin/marketplace.json | 2 +- .../che-pptx-mcp/.claude-plugin/plugin.json | 2 +- plugins/che-pptx-mcp/CHANGELOG.md | 2 +- plugins/che-pptx-mcp/README.md | 2 +- .../che-pptx-mcp/skills/che-pptx-mcp/SKILL.md | 28 +++++++++++++++++-- 5 files changed, 29 insertions(+), 7 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 00b7dbe0..3064b56b 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -42,7 +42,7 @@ }, { "name": "che-pptx-mcp", - "version": "0.1.2", + "version": "0.1.3", "description": "PowerPoint (.pptx) MCP server — PresentationML 解析與生成：slides、shapes、tables、notes、theme、markdown 匯出。v0.1.0: 首次 marketplace 發布（signed + notarized universal binary）。", "author": { "name": "Che Cheng" diff --git a/plugins/che-pptx-mcp/.claude-plugin/plugin.json b/plugins/che-pptx-mcp/.claude-plugin/plugin.json index f69dbf80..198bae83 100644 --- a/plugins/che-pptx-mcp/.claude-plugin/plugin.json +++ b/plugins/che-pptx-mcp/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "che-pptx-mcp", "description": "PowerPoint (.pptx) MCP server — PresentationML 解析與生成：slides、shapes、tables、notes、theme、markdown 匯出。 v0.1.0: 首次 marketplace 發布。", - "version": "0.1.2", + "version": "0.1.3", "binary_version": "0.1.0", "author": { "name": "Che Cheng" diff --git a/plugins/che-pptx-mcp/CHANGELOG.md b/plugins/che-pptx-mcp/CHANGELOG.md index 397c01b3..4af303d0 100644 --- a/plugins/che-pptx-mcp/CHANGELOG.md +++ b/plugins/che-pptx-mcp/CHANGELOG.md @@ -4,7 +4,7 @@ All notable changes to the che-pptx-mcp plugin shell will be documented in this The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). -## [Unreleased] +## [0.1.3] - 2026-08-24 ### Added diff --git a/plugins/che-pptx-mcp/README.md b/plugins/che-pptx-mcp/README.md index 6720d779..7358f12a 100644 --- a/plugins/che-pptx-mcp/README.md +++ b/plugins/che-pptx-mcp/README.md @@ -13,7 +13,7 @@ claude plugin install che-pptx-mcp@macdoc 安裝後可由 `che-pptx-mcp` skill 取得具名工具流程、Direct／Session 模式、索引與 EMU 慣例： -`plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md` +[`skills/che-pptx-mcp/SKILL.md`](skills/che-pptx-mcp/SKILL.md) 目前可讀寫 slides、shapes、tables、images、notes、theme，並匯出 Markdown。尚未提供 PDF 匯出、投影片 render／PNG preview 或 cm 幾何工具；`export_image` 只匯出簡報內嵌圖片，不是投影片預覽。 diff --git a/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md b/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md index 4b573f0b..84bcb8cd 100644 --- a/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md +++ b/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md @@ -14,7 +14,28 @@ Use the Swift-native PresentationML server for `.pptx` work without launching Po | Inspect one file | Direct, read-only | `source_path` | | Create or edit | Session | `doc_id` after `create_presentation` or `open_presentation` | -All `slide_index`, row, and column indices are zero-based. Shape edits use the `shape_id` returned by `get_slide_shapes`. Geometry parameters are raw EMU integers; centimetre helpers are not shipped yet. +All `slide_index`, row, and column indices are zero-based. Use `get_slide_shapes` to discover IDs. `update_shape_text`, `set_shape_position`, `set_shape_size`, and `set_shape_fill` accept only entries reported as `Shape`, not picture/table/group IDs; use image or table tools for those elements. Geometry parameters are raw EMU integers; centimetre helpers are not shipped yet. + +## Read without opening a session + +```text +get_presentation_info(source_path: "/in/deck.pptx") +get_slide_count(source_path: "/in/deck.pptx") +get_slide_text(source_path: "/in/deck.pptx", slide_index: 0) +``` + +Direct mode is read-only. Open a session before any mutation. + +## Create a presentation + +```text +1. create_presentation(doc_id: "deck") +2. add_slide(doc_id: "deck") +3. insert_text_shape(doc_id: "deck", slide_index: 0, text: "Title", + x: 720000, y: 720000, width: 7200000, height: 900000) +4. save_presentation(doc_id: "deck", path: "/out/new-deck.pptx") +5. close_presentation(doc_id: "deck") +``` ## Edit an existing presentation @@ -27,12 +48,13 @@ All `slide_index`, row, and column indices are zero-based. Shape edits use the ` 5. close_presentation(doc_id: "deck") ``` -Edits stay in memory until `save_presentation` unless the session was opened with `autosave: true`. Use a different output path to preserve the source. +Edits stay in memory until `save_presentation` unless the session was opened with `autosave: true`. Use `autosave: false` and a different output path to preserve the source; autosave writes edits back to the opened path. ## Common tools | Task | Tools | |---|---| +| Sessions | `create_presentation`, `open_presentation`, `save_presentation`, `close_presentation`, `list_open_presentations` | | Inspect | `get_presentation_info`, `get_slide_count`, `get_text`, `get_slide_text`, `get_slide_shapes`, `get_shape_text`, `search_text` | | Slides | `add_slide`, `delete_slide`, `duplicate_slide`, `reorder_slides` | | Shapes | `insert_text_shape`, `update_shape_text`, `delete_shape`, `set_shape_position`, `set_shape_size`, `set_shape_fill` | @@ -54,5 +76,5 @@ Read tools accept either `source_path` or `doc_id` when their schema offers both - Editing with `source_path`: open a session first. - Treating the second slide as index 2: use `slide_index: 1`. -- Guessing a shape ID: call `get_slide_shapes` and use its returned ID. +- Guessing a shape ID or its element kind: call `get_slide_shapes`; use Shape-only editors only on entries marked `Shape`. - Closing before saving: save the intended output path, then close. From 72c8772828932003eaf6f4a0db94a0d2c85bc853 Mon Sep 17 00:00:00 2001 From: che cheng <kiki830621@gmail.com> Date: Mon, 24 Aug 2026 04:41:16 +0800 Subject: [PATCH 3/5] docs: correct che-pptx creation lifecycle (#159) --- plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md b/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md index 84bcb8cd..14723759 100644 --- a/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md +++ b/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md @@ -24,19 +24,20 @@ get_slide_count(source_path: "/in/deck.pptx") get_slide_text(source_path: "/in/deck.pptx", slide_index: 0) ``` -Direct mode is read-only. Open a session before any mutation. +Direct mode is read-only. Use `create_presentation` to start a new session, or `open_presentation` before modifying an existing file. ## Create a presentation ```text 1. create_presentation(doc_id: "deck") -2. add_slide(doc_id: "deck") -3. insert_text_shape(doc_id: "deck", slide_index: 0, text: "Title", +2. insert_text_shape(doc_id: "deck", slide_index: 0, text: "Title", x: 720000, y: 720000, width: 7200000, height: 900000) -4. save_presentation(doc_id: "deck", path: "/out/new-deck.pptx") -5. close_presentation(doc_id: "deck") +3. save_presentation(doc_id: "deck", path: "/out/new-deck.pptx") +4. close_presentation(doc_id: "deck") ``` +`create_presentation` starts with one blank slide at index 0; call `add_slide` only when another slide is needed. + ## Edit an existing presentation ```text @@ -63,7 +64,7 @@ Edits stay in memory until `save_presentation` unless the session was opened wit | Notes/theme | `get_slide_notes`, `add_notes`, `set_transition`, `get_theme`, `get_slide_master`, `get_slide_layouts` | | Export | `export_markdown` | -Read tools accept either `source_path` or `doc_id` when their schema offers both. Mutation tools require an open session and `doc_id`. +Read tools accept either `source_path` or `doc_id` when their schema offers both. After `create_presentation` or `open_presentation` establishes a session, content mutation tools require its `doc_id`. ## Honest boundaries From a7961ee00b34040ecc5db7b486d78850338b2ea1 Mon Sep 17 00:00:00 2001 From: che cheng <kiki830621@gmail.com> Date: Mon, 24 Aug 2026 04:42:00 +0800 Subject: [PATCH 4/5] docs: clarify che-pptx element editing bounds (#159) --- plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md b/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md index 14723759..54f1dd35 100644 --- a/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md +++ b/plugins/che-pptx-mcp/skills/che-pptx-mcp/SKILL.md @@ -14,7 +14,7 @@ Use the Swift-native PresentationML server for `.pptx` work without launching Po | Inspect one file | Direct, read-only | `source_path` | | Create or edit | Session | `doc_id` after `create_presentation` or `open_presentation` | -All `slide_index`, row, and column indices are zero-based. Use `get_slide_shapes` to discover IDs. `update_shape_text`, `set_shape_position`, `set_shape_size`, and `set_shape_fill` accept only entries reported as `Shape`, not picture/table/group IDs; use image or table tools for those elements. Geometry parameters are raw EMU integers; centimetre helpers are not shipped yet. +All `slide_index`, row, and column indices are zero-based. Use `get_slide_shapes` to discover IDs. `update_shape_text`, `set_shape_position`, `set_shape_size`, and `set_shape_fill` accept only entries reported as `Shape`, not picture/table/group IDs. Use image tools for pictures and table tools for tables. Groups have no text/position/size/fill editor; `delete_shape` can remove one. Geometry parameters are raw EMU integers; centimetre helpers are not shipped yet. ## Read without opening a session @@ -77,5 +77,5 @@ Read tools accept either `source_path` or `doc_id` when their schema offers both - Editing with `source_path`: open a session first. - Treating the second slide as index 2: use `slide_index: 1`. -- Guessing a shape ID or its element kind: call `get_slide_shapes`; use Shape-only editors only on entries marked `Shape`. +- Guessing a shape ID or its element kind: call `get_slide_shapes`; use Shape-only editors only on entries marked `Shape`, and do not treat a Group as editable. - Closing before saving: save the intended output path, then close. From 29bf6c11ea4cf37874093fe459ab6dff9a76d472 Mon Sep 17 00:00:00 2001 From: che cheng <kiki830621@gmail.com> Date: Mon, 24 Aug 2026 04:45:22 +0800 Subject: [PATCH 5/5] docs: correct che-pptx theme capability claim (#159) --- plugins/che-pptx-mcp/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/che-pptx-mcp/README.md b/plugins/che-pptx-mcp/README.md index 7358f12a..1909fbbb 100644 --- a/plugins/che-pptx-mcp/README.md +++ b/plugins/che-pptx-mcp/README.md @@ -15,7 +15,7 @@ claude plugin install che-pptx-mcp@macdoc [`skills/che-pptx-mcp/SKILL.md`](skills/che-pptx-mcp/SKILL.md) -目前可讀寫 slides、shapes、tables、images、notes、theme，並匯出 Markdown。尚未提供 PDF 匯出、投影片 render／PNG preview 或 cm 幾何工具；`export_image` 只匯出簡報內嵌圖片，不是投影片預覽。 +目前可讀寫 slides、shapes、tables、images、notes，可讀取 theme，並匯出 Markdown。尚未提供 theme 寫入、PDF 匯出、投影片 render／PNG preview 或 cm 幾何工具；`export_image` 只匯出簡報內嵌圖片，不是投影片預覽。 Wrapper 會自動從 [GitHub Releases](https://github.com/PsychQuant/che-pptx-mcp/releases) 下載 release 的 `ChePPTXMCP` universal binary 到 plugin 層級的 `.bin-cache/`（跨 marketplace 隔離、跨版本持久），安裝前與每次啟動時強制驗證 sha256（安裝時）與 Developer ID Application 簽章鏈（Team `6W377FS7BS`）。release 流程含 Apple notarization（wrapper 不重複檢查 notarization）。