feature: che-keynote-mcp — Swift-native Keynote MCP server（NSAppleScript 路線；references 先行）

[kiki830621]

Problem

Original text:
「我想要做che-keynote-mcp ，你可以先派sonnet deep search目前有的mcp，下載進che-keynote-mcp的references之後再來做」
— Source: 使用者 session 指示（2026-07-18）

che-mcps 家族已覆蓋 Word（che-word-mcp 245 tools）、PPTX（che-pptx-mcp）、PDF（che-pdf-mcp），缺 Apple Keynote surface。目標：建立 Swift-native 的 che-keynote-mcp，讓 Claude 能建立／編輯／匯出 Keynote 簡報。前置：先完成現有生態 deep search（已完成，見下）並把參考 repo 下載進新 repo 的 references/ 再開工。

Type

feature

Expected

1. 新 repo PsychQuant/che-keynote-mcp：Swift binary MCP server，走 che-mcps 標準 pipeline（Developer ID sign + notarize、mcpb、macdoc marketplace 發布）
2. references/ 含 deep search 選定的參考 repo（clone-on-demand、僅 README 入版控——沿 macdoc reference/ 慣例）
3. v1 tool surface：AppleScript 能力邊界內的 Keynote 驅動（簡報/slide CRUD、文字、圖片、匯出 PDF/images）

Research Summary（sonnet deep search，2026-07-18；完整報告見附件）

Top-5 reference 候選：

#	Repo	Verdict
1	PsychQuant/che-logic-pro-mcp	家族內先例、最佳起手骨架——已驗證 NSAppleScript（in-process）+ actor 架構 + Developer ID 簽章
2	obriensp/iWorkFileFormat	.key/IWA/Protobuf 格式逆向文件，理解 iWork 檔案結構的第一手資料
3	psobot/keynote-parser	最成熟的 .key round-trip 實作（Python/MIT/206★）；「從本機 Keynote.app 動態萃取 Protobuf schema」方法論值得參考
4	6over3/WorkKit	唯一 Swift-native iWork parser（visitor pattern 可讀）——⚠️ AGPL-3.0 與封閉發布衝突，只讀不依賴
5	josephyooo/keynote-cli	AppleScript 能力邊界踩坑清單（shape fill/equation/hyperlink 打不到、並發不安全）——risk register 比程式碼更值得抄進設計

技術路線建議（研究報告結論）：

驅動 Keynote 採 NSAppleScript（in-process，com.apple.security.automation.apple-events entitlement + NSAppleEventsUsageDescription）而非社群常見的 shell-out osascript——Apple DTS 官方建議路徑（TCC 歸因正確），且 che-logic-pro-mcp 已在 che-mcps 簽章/公證 pipeline 下驗證可行。che-keynote-mcp 會是生態系中第一個 Swift-native、走此路徑的 Keynote MCP（現有 Keynote MCP 全是 Python/TS 包裝 osascript）。.key 直接解析（IWA/Protobuf）列 v2+ 評估項而非 v1 主幹——Apple 不定期改 schema，版本相容性是結構性負擔。

實作路線 sketch（由後續 /idd-diagnose 正式化）

1. 建 repo + scaffold：以 che-logic-pro-mcp 為骨架（NSAppleScript in-process + actor；Entitlements 加 apple-events；sign pipeline 用 che-mcps-notary profile）
2. references/ 下載上表 2/3/5（WorkKit 因 AGPL 只在報告中引用結論，不 clone 進發布 repo）＋ README-only tracked
3. v1 tool surface 依 keynote-cli 的能力邊界清單界定（明確列「AppleScript 打不到」的誠實邊界進 tool descriptions）
4. macOS 26 TCC：AppleEvents 是 TCC-protected —— ad-hoc 簽章不可行，first release 前跑 ./scripts/audit-security.sh（common-release-flow 新 repo gate）

Impact

• 新 repo PsychQuant/che-keynote-mcp（Swift Package + mcpb）
• macdoc marketplace：新 plugin entry（plugins/che-keynote-mcp/ shell + marketplace.json）
• 無既有程式碼變更

---

Attachments

• 完整 deep search 報告（sonnet，2026-07-18）

Clarity Surface(idd-clarify run 2026-07-18T14:38:28Z)

Type	Source	Suggested canonical	Status
ambiguity	"v1 tool surface：AppleScript 能力邊界內的 Keynote 驅動（簡報/slide CRUD、文字、圖片、匯出 PDF/images）"	v1 具體 tool 清單未列舉——CRUD 覆蓋哪些操作（new/delete/reorder slide？master/theme 選擇？speaker notes？）、匯出格式範圍（PDF/PNG/QuickTime？）需在 diagnose 界定	resolved @ 2026-07-18T22:24:36Z (reason: user 拍板——由 diagnose 依研究報告（keynote-cli 能力邊界 + AppleScript dictionary）界定 v1 清單，寫進 Strategy)
missing-context	"AppleScript 能力邊界內"	目標 baseline 未指定：支援的 macOS／Keynote 最低版本（AppleScript dictionary 隨版本變動，keynote-cli 的踩坑清單對應的版本也需對齊）	resolved @ 2026-07-18T22:24:36Z (reason: user 拍板——baseline = macOS 26 + 當前 Mac App Store Keynote，以維護者機實測為準；舊版不保證)

---

Current Status

• Phase: diagnosed（2026-07-19；https://github.com/PsychQuant/macdoc/issues/140#issuecomment-5013162485）
• Complexity: Spectra（Layer 2：新 published MCP tool surface ~22 tools；Layer 3：NSAppleScript 架構選型 + v1/v2 邊界為長期結構決策）
• Clarity: 2 rows resolved（v1 清單由 diagnose 界定；baseline = macOS 26 + 當前 Keynote）
• Conflict Class: A_parallel_safe（新 repo；僅 ship 段觸 macdoc marketplace.json）
• Spectra change: che-keynote-mcp（proposal/design/spec/tasks 完成並 parked，2026-07-19；/spectra-apply che-keynote-mcp 開工）

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis

需求拆解（deep search 報告為 source of truth，附件；兩個 clarity 決策已由 user 拍板——v1 清單由本 diagnose 依報告界定、baseline = macOS 26 + 當前 Mac App Store Keynote）：

A. 架構主幹（研究 §6 結論，採納）

• NSAppleScript（in-process） 驅動 Keynote——Apple DTS 官方建議路徑（TCC 歸因正確），家族內 che-logic-pro-mcp 已驗證（NSAppleScript(source:).executeAndReturnError() + actor 模式 + Developer ID 簽章公證通過）。不用 shell-out osascript（DTS 明示非官方支援、TCC 歸因錯誤）、不用 JXA、ScriptingBridge 列可選不採。
• Entitlements：com.apple.security.automation.apple-events + Info.plist NSAppleEventsUsageDescription；走既有 che-mcps-notary sign+notarize pipeline。
• 併發與效能（研究 §3 實測數據）：Keynote scripting 非並發安全 → 單一 KeynoteController actor 序列化；每次 AppleEvent ~430ms overhead → 多張投影片操作用批次腳本模式（比照 keynote-cli 的 20 張/批）。

B. v1 tool surface（~22 tools，六類——分類法參照 iwork_mcp 41-tool 分類、範圍受 keynote-cli risk register 約束）

類別	Tools
Presentation lifecycle	create_presentation（theme 選擇）/ open_presentation / save_presentation / close_presentation / list_presentations / get_presentation_info
Slide CRUD	add_slide（layout 選擇）/ delete_slide / duplicate_slide / move_slide / list_slides / get_slide_info / set_slide_skipped
Content	set_slide_title / set_slide_body / add_text_item / set_text_item / list_text_items / add_image
Presenter notes	set_presenter_notes / get_presenter_notes
Export	export_pdf / export_images（單張匯出用 skipped toggle 手法）
Playback	start_slideshow / stop_slideshow

誠實邊界（v1 明確不含，寫進 tool descriptions）：shape fill color、slide background 顏色、equation、hyperlink 插入（AppleScript dictionary 缺口，僅 UI-scripting 可達——列 v2 輔助層評估）；chart 自訂（Apple 未開放）；.key 直讀（IWA/Protobuf，v2+ 評估）。

C. references/（user 指示的前置）

• Clone（README-only tracked，沿 macdoc reference/ 慣例）：psobot/keynote-parser（schema 萃取方法論）、josephyooo/keynote-cli（能力邊界 risk register）、obriensp/iWorkFileFormat（格式文件）
• 不 clone：6over3/WorkKit（AGPL-3.0 與封閉發布衝突——僅閱讀）；easychen/keynote-mcp／reichenbach/iwork_mcp（語言/架構不同，僅工具分類參考）

Impact

• 新 repo PsychQuant/che-keynote-mcp：Package.swift、Sources/CheKeynoteMCP/（main / Server / KeynoteController actor / Entitlements.plist）、scripts/release.sh（照 che-word-mcp 的 signature-gate 版）、Tests/、mcpb/、README、references/
• macdoc（ship 時）：plugins/che-keynote-mcp/ shell + .claude-plugin/marketplace.json entry
• 使用者流程：Claude 可建立/編輯/匯出 Keynote 簡報——生態系首個 Swift-native、NSAppleScript 正路的 Keynote MCP

Strategy

• 建 repo + Swift Package scaffold（che-logic-pro-mcp 骨架：NSAppleScript + KeynoteController actor；Entitlements apple-events + usage description；NSAppleEventDescriptor 傳參防字串注入）
• references/ 下載三個選定 repo（README-only tracked）＋把 keynote-cli 的能力邊界清單抄錄為 docs/applescript-boundary.md risk register
• v1 ~22 tools 實作（上表六類；批次腳本模式；誠實邊界進 descriptions）
• 測試：AppleScript 原始碼生成單元測試（無 Keynote 可跑）＋ env-gated 真 Keynote 整合測試（RUN_KEYNOTE_INTEGRATION=1，macOS 26 實機）
• 簽章驗證：release pipeline（簽章 gate + notarize）＋ macOS 26 實機 AppleEvents TCC 授權流程實測
• Ship：GitHub release + macdoc marketplace plugin shell；first-release 前跑 ./scripts/audit-security.sh che-keynote-mcp（common-release-flow 新 repo gate）

Conflict Class

A_parallel_safe — 全新獨立 repo，無共享 mutable 資源；僅 ship 段觸及 macdoc marketplace.json（屆時與其他 marketplace 變更相鄰序列化）。

Complexity

Spectra

Layer 2：新增 published MCP tool surface（~22 tools 給 future callers），behavior contract（含誠實邊界）應寫成 documented spec。Layer 3：架構決定被未來 maintainer 繼承——NSAppleScript in-process vs shell-out 的選型、v1/v2 邊界（UI-scripting 輔助層、.key 直讀）是 long-term roadmap 結構決策。

Hard-gate: not triggered — greenfield 新 repo，「單一概念散佈既有檔案」判準不適用；Spectra 已由 Layer 2+3 決定

Risks

• AppleScript dictionary 缺口造成的期望落差 → 誠實邊界寫進 descriptions，不 overpromise（keynote-cli risk register 為準）
• Keynote scripting 非並發安全 → actor 序列化是硬性設計約束，不可繞
• AppleEvent per-call ~430ms → 大簡報操作必須批次，否則 tool latency 不可用
• macOS 26 TCC：AppleEvents 授權需實機測試（簽章後才會正確跳授權框——ad-hoc 必 SIGKILL）；Apple 改 dictionary 的版本漂移風險由 baseline 拍板（macOS 26 + 當前 Keynote）承接
• Apple sdef 未提供 SwiftPM 自動化 pipeline → 不採 ScriptingBridge，避免 check-in 生成碼的維護負擔

Residue

「像 Word/PPTX 一樣完整操作 Keynote」的完整願景受 AppleScript dictionary 結構性限制（shape 顏色/equation/chart 等 Apple 未開放）——v1 明確不含。UI-scripting 輔助層與 .key 直讀（IWA/Protobuf）列 v2+ 評估；後者屆時需論證 native-macos-compat.md 的依賴例外（Protobuf/Snappy 非現行允許清單）。pptx↔keynote 互通（家族內 pptx-swift 對稱基礎）研究判為非本次範圍，日後另案。

Vagueness Pre-check

• V1: 2 — WHAT 明確（新 MCP server + 六類 tool 清單已界定；兩個 clarity 決策已 user 拍板）
• V4: 3 — 驗收隱含（v1 tools 於 macOS 26 實機可用 + 簽章 pipeline 通過）；具體 scenarios 由 Spectra 階段落成
• Triggered: no — both axes ≤ 3

Hard-gate: not triggered — 見 Complexity 段

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

（none surfaced — pptx↔keynote 互通已於研究報告 §4 判為非範圍並記入 Residue，暫不 file；無其他旁支）