AI 整合
HypeLink 把品牌操作的「動作 API」開放給 AI agent 使用，讓你可以在 Claude Code、Claude Desktop、Cursor，或任何支援 Model Context Protocol 的 client，用自然語言操作自己的品牌頁、活動、會員、票券、公告⋯⋯不必離開編輯器或聊天視窗。
目前範圍
| 整合方式 | 範圍 | 狀態 | 文件 |
|---|---|---|---|
| MCP server | 首頁資訊 + 首頁設計 + 活動全套（含 outcomes、設計、收款、票種、名單、簽到、公告、廣播、加值、報表、協作者）+ webhook 設定 | ✅ 開放中 | MCP - Getting Start |
| OpenAPI / REST | 148 個 tools 的 REST 鏡像（自動 OpenAPI 3.1 spec + Swagger UI），共用 MCP 的 token / scope / audit | ✅ 開放中 | OpenAPI 文件 |
| Webhook（🪄 Max 方案專屬） | 報名 / 付款 / 連結 / profile 等 11 個事件即時推送，HMAC 簽名 + 自動 retry（1m/5m/30m/4h/24h） | ✅ 開放中 | Webhook 文件 |
| Claude Skill | 官方維護的 Claude SOP — 安裝後 Claude 自動知道怎麼安全用 HypeLink MCP（dry-run 預覽、兩階段確認、個資遮罩） | ✅ 公開 repo | Claude Skill |
三個典型使用情境
1. 把 AI 變成你的活動企劃助理
> 幫我建一場 6/28 的同學會活動，三種票（早鳥、現場、+1 親屬），
> 報名表單加「當年班級」自訂欄位，截止前一天寄提醒信。Claude / GPT 會透過 MCP 依序呼叫 events.create、events.tickets.create、events.form.put、events.notifications.put，全程 dry-run 預覽，你確認後才寫入。
2. 從 CMS / 試算表自動同步內容到品牌頁
> 把這個 Google Sheets 第 1～20 列的連結同步到「商品」分頁，
> 名稱 = A 欄、網址 = B 欄、描述 = C 欄。AI 透過 folders.list 找到分頁 id → 逐筆呼叫 links.create。寫入後 dashboard 與公開頁立即反映（與你自己手動編輯走同一條 pipeline）。
3. 讓客服 / 主辦團隊在 Claude 內查名單與處理狀態
> 列出「2026 春季婚禮分享會」目前所有匯款狀態為「未付款」的報名者，
> 把超過 3 天還沒匯款的標記為「已取消」並寄通知。AI 用 events.attendees.list 過濾未付款 → 逐筆 events.attendees.patch_status，每一筆都會經過兩階段 confirmToken（破壞性操作預設要二次確認）。
MCP 或 OpenAPI 怎麼選？
| MCP | OpenAPI | |
|---|---|---|
| 適合 | Claude / Cursor 等 LLM client，對話式整合 | Make / n8n / Zapier、自家後端 axios、CI 排程 |
| 傳輸 | JSON-RPC over HTTP | REST + JSON，每個 tool 一個 path |
| Token | 同一把 hl_pat_* | 同一把 hl_pat_* |
| Schema | client 自己呼 tools/list | OpenAPI 3.1 + Swagger UI |
| 互動測試 | 透過 client | Swagger UI 直接試打 |
| SDK 自動產生 | — | 餵 spec 給 codegen（TS / Python / Go⋯⋯） |
兩邊完全等價（共用 100 個 tools 與所有安全機制），看哪個適合你的整合工具就用哪個，也可以混用。
為什麼用 MCP？
| 自己串 REST API | 走 MCP | |
|---|---|---|
| 連線設定 | 在每個 client 手寫 SDK / fetch | 一份 .mcp.json，所有 MCP client 共用 |
| 權限 | 全有全無的 JWT | scope 細粒度（homeinfo:read / events:write …） |
| Schema 描述 | 你自己寫 prompt 講解 | server 直接吐 tools/list，LLM 自己讀懂 |
| 變更追蹤 | 沒有 | 全部寫進 mcp_audit_log |
| 防呆 | 自己寫 dry-run / confirm | server 內建 dry_run / confirmToken 兩階段 |
簡單講：MCP 就是把「給 AI 操作的 API」做成標準格式，你不用為了 Claude / Cursor 寫不同的整合。
安全模型
- API Token 在 dashboard > 設定 > API Token 一鍵產生，按 scope 細粒度授權
- 每個 token 都看得到「最後使用時間」，懷疑外洩可一鍵撤銷
- Token 寫入時走獨立的
mcp_audit_log（不混在主操作 log），owner 看得到誰、什麼時候、用哪個 token 改了什麼 delete_*/cancel/send_email/pairing.reset等破壞性操作預設兩階段confirmToken，AI 第一次呼叫只拿到 token + summary，第二次帶 token 才真正執行
開始使用
直接跳 MCP 文件 — 三步驟設定 + 完整 tool 表。
Last updated on