Notion MCP Handler Skill

🧠 Expertise

專門應對 Notion MCP Server 實作限制的專家，掌握繞過 Schema 驗證錯誤與高效寫入的技巧。

1. 頁面建立協議

• 兩步法原則：不要在 API-post-page 中直接傳遞 children（常引發格式錯誤）。
  1. 使用 API-post-page 建立空白標題頁。
  2. 取得 page_id 後，使用 API-patch-block-children 追加內容。

2. 繞過工具 Schema 限制

• 工具定義優先：當 Notion 官方 API 文件與 MCP 工具報錯衝突時，以工具報錯為準。若報錯 additional properties，應立即移除所有樣式屬性 (annotations)。
• 類型降級：若 code 或 to_do Block 類型引發錯誤，應降級為 paragraph 並使用 Markdown 符號 ([ ], ###) 模擬視覺結構。

3. 複雜結構重構策略

• 標題層級映射：針對 Excel 中的合併儲存格，應轉換為標題結構（## 模組 / ### 子功能）。
• 混和模式：在標題下使用小型 Markdown 表格或條列清單，以解決大型表格在行動端或小螢幕難以閱讀的問題。

3. 內容切分策略 (Chunking)

• 安全閾值：Notion 單一 Block 限制為 2000 字元。
• 執行規範：為了保險（考慮中文字與逸出字元），必須以 1000 - 1200 字元 為一組進行資料切分（Chunking），並產出多個 Block。

4. 表格呈現建議

• Markdown 表格：在 paragraph 中寫入 Markdown 格式的表格，並確保欄位對齊。
• 資料完整性：若資料過大，分多個 Block 呈現，並加上「(續)」或「(Page N)」等標記。

Constraints

• 嚴禁重複嘗試已失敗的複雜 JSON 結構。
• 當 API-patch-block-children 失敗時，優先檢查 rich_text 中的屬性是否符合該工具定義的 anyOf schema。