feature: che-excel-mcp — 沉澱 Excel 自動化實戰(xlsx/xlsm 產生、VBA 注入、真 Excel 驗證)成 MCP server

[kiki830621]

Problem

Original text:
「我覺得這些經驗可以用來發展che-excel-mcp,你覺得呢」
— Source: 使用者(2026-07-17,一個顧問案 Excel 交付工具鏈收尾後)

macdoc 的 mcp/ 家族已有 che-word-mcp / che-pptx-mcp / che-pdf-mcp,Excel 是 Office 文件家族的最後一個缺口。最近一輪實戰(用 openpyxl + LibreOffice + AppleScript + VBA 打通「產生 xlsx/xlsm → 注入巨集 → 真 Excel 驗證」全鏈)踩出了一批 generic 的 Excel 自動化知識,值得沉澱成 MCP server,讓之後任何 session 不必重踩。

Type

feature

實戰經驗清單(全部可轉化為 MCP 功能或內建 workaround)

1. xlsx 產物相容性

• openpyxl 3.x 寫 inline strings(無 xl/sharedStrings.xml),部分 Excel 版本直接拒開
• Workaround:LibreOffice headless round-trip(soffice --headless --convert-to xlsx)正規化結構
• → MCP 產表工具應內建正規化(或原生寫 sharedStrings)

2. .xlsm 巨集注入(零 GUI)

• openpyxl 無法建立 VBA 專案;可用 OPC zip 手術把現成 vbaProject.bin 縫進 xlsx:
  [Content_Types].xml workbook 型別改 macroEnabled + 加 bin Default + rels 加 vbaProject relationship
• 保真可測:除 3 處預期改動外,逐 zip 條目 byte-identical
• → inject_vba(xlsx, bin) → xlsm 工具

3. VBA .bas 匯入的編碼陷阱

• VBE 用 legacy codepage 解 .bas;UTF-8 中文字串的尾 byte(如「率」的 0x87)會與後面的 " 配成 double-byte 字、吞掉閉引號 → 編譯錯誤
• 解法:.bas 全 ASCII;中文 sheet 名用 ChrW(&H....) 組字
• → MCP 產 .bas / 驗 .bas 時 lint 這個

4. 真 Excel AppleScript 驅動的地雷(Mac)

• run VB macro 對不存在的巨集 silent no-op(exit 0,無錯誤)— 必須先驗巨集清單
• VBA 編譯錯誤讓 VBE 進 break mode,之後所有 run VB macro 靜默吞掉
• 巨集 MsgBox 會擋 AppleEvent 回傳;自動化要能偵測/關閉 dialog
• save workbook as 到 File Provider 路徑(Dropbox 等)回 -50;寫 ~/Documents 觸發 sandbox「授與檔案存取權」dialog;正解是 VBA 自己 SaveAs(Excel 進程內,無 sandbox 限制)
• 舊 API make new button 建的 form control 會讓 save-as-xlsm 序列化失敗(「移除或修復部分功能」錯誤)
• GUI scripting(keystroke/click)會搶焦點,使用者同時在用機器時有誤擊風險 — 讀值/按鈕盡量走 AX API(不 activate)

5. 驗證方法論

• 工作簿內建「比較」活公式頁(整表 SUMPRODUCT 逐格比對)= 交付檔自帶驗證器
• AppleScript 靜默讀 range value(不搶焦點)做 round-trip 驗證
• 雙實作交叉驗證:Python 引擎 vs Excel/VBA 對同一組測試向量必須逐格一致

提議的 tool surface(草案)

Tool	功能
open_workbook / close_workbook	開關檔(處理巨集安全提示)
list_sheets / read_range / write_range	讀寫(AX 級,不搶焦點)
read_formula / set_formula	公式層存取
recalculate	強制重算
list_macros / run_macro	巨集(先驗存在,偵測 break mode / MsgBox)
save_as	由 VBA 進程內執行,繞 sandbox
build_xlsx / inject_vba	離線產表 + 巨集注入(不需開 Excel)
normalize_xlsx	LibreOffice 正規化
compare_ranges	兩表逐格 diff(容差參數)

架構同 che-ical/mail/notes 家族:Swift + AppleScript/ScriptingBridge 驅動真 Excel;離線部分(zip 手術、xlsx 產生)純 Swift。sign + notarize pipeline(che-mcps-notary)現成。

Impact

• Office MCP 家族補齊(word/pptx/pdf/excel)
• 精算/財務類顧問案的 Excel 交付自動化(產表 → 巨集 → 驗證)變成可重用能力
• 上面每一條地雷都是踩過一次就該封裝的知識;不沉澱下次照踩

Priority

P2

[kiki830621]

設計補充:AppleScript alignment(雙向橋)

Original text:
「而且有趣的是可以跟apple scripts alignment,這是目前沒有想到的做法」
— Source: 使用者(2026-07-17,follow-up)

這個 alignment 有三層,其中第三層是 macdoc 家族目前完全沒有的維度:

1. 驅動方向:AppleScript → Excel(已實戰驗證)

MCP tool 內部以 AppleScript/ScriptingBridge 驅動活的 Excel(開簿、讀寫 range、run VB macro、偵測 dialog)。macdoc 既有三個 MCP(word/pptx/pdf)都是離線檔案轉換;Excel 是家族第一個需要「app 在跑」的成員——這個模式 che-ical-mcp / che-apple-mail-mcp 已驗證,搬過來即可。

2. 語意對齊:tool surface 對齊 Excel 的 AppleScript dictionary

tool 命名與參數語意直接對齊官方 scripting dictionary(worksheet / range / value / formula / run VB macro),而不是自創抽象 — 行為可預測、文件可互查,也把 dictionary 沒暴露的部分(如 VBE 操作)明確標為「需走其他路徑」。

3. 回呼方向:VBA → AppleScript(AppleScriptTask)— 新做法

Mac Office sandbox 提供官方橋:放在 ~/Library/Application Scripts/com.microsoft.Excel/ 的 .scpt 可被 VBA 以 AppleScriptTask("script.scpt", "handler", "arg") 呼叫,以完整使用者權限執行(繞開 VBA 自身的 sandbox 限制)。這開啟一個沒想過的架構:

• MCP 安裝時把 helper .scpt 部署進該目錄
• MCP 注入的 VBA 巨集透過 AppleScriptTask 回呼系統能力:寫任意路徑(取代 Grant-File-Access dialog 地獄)、發通知、觸發外部驗證、甚至回報執行狀態給 MCP
• 等於 MCP ⇄ AppleScript ⇄ Excel/VBA 三方閉環:MCP 產巨集 → 巨集在 Excel 內算 → 算完經 AppleScriptTask 把結果/狀態送回系統側 → MCP 讀取,全程零 GUI scripting、零搶焦點

實戰註腳:本輪 SaveAs 的 sandbox 迷宮(File Provider 路徑 -50、~/Documents 要授權 dialog)如果當時有第 3 層,巨集直接 AppleScriptTask 存檔即可,整段 GUI 纏鬥都不會發生。

[kiki830621]

Rule 已落地:docs/applescript-swift-parity.md — 每個 AppleScript 能力都必須有型別化 Swift 函數對應;tool handler 永不直呼 osascript。含五條精確化(capability 粒度、唯一入口可 lint、錯誤路徑型別化、AppleScriptTask 資產的對應物、integration test 義務)與 che-excel-mcp 草案簽名。