HypeLink MCP — 透過 Claude Code 操作首頁與活動

這是 HypeLink AI 整合底下的 MCP server 文件。 想了解 HypeLink 整體 AI 策略 → AI 整合總覽 想看 MCP 通用協議規格 → Model Context Protocol 

HypeLink MCP server 讓你可以在 Claude Code、Claude Desktop、Cursor，或任何 Model Context Protocol  client 內，用自然語言對你的品牌進行讀寫：

首頁資訊

• 看現在首頁長什麼樣 / 列出所有連結與分頁
• 新增連結與封面圖、調整順序、整理分類
• 改 bio、頭像、社群分享圖、SEO 設定
• 新增 / 修改首頁內容模組（richtext、video、music、shop 等）
• 設定社群連結

首頁設計

• 切換主題（builtin / 上架主題）
• 覆寫 designSettings JSON（accentColor、cardRadius、bottomBar、folderTabs⋯⋯）
• 列出可用的主題清單
• 切換 3D 落地頁優先（透過 profile.update）

活動與其子頁面

• 中央控台 / 活動本體 CRUD（含封面、復製、取消、slug 檢查）
• 設計：活動頁 Puck JSON、報名表單、收款設定、票種、報名完成頁
• 名單：列表 / 改狀態 / 匯出 CSV / 批次匯入 / 邀請 / 贈票 / 現場簽到
• 公告：一般公告 + email 廣播（含受眾預覽與 SP 成本）
• 加值：抽獎 / 點名 / 投票 / Q&A / 投稿 / 身分卡 / 配對 / 問卷
• 活動成效：報名 / 出席 / 時序、成果紀錄資產列表與配額
• 設定：通知、折扣、協作者邀請與角色

會員、商城、3D 空間等將在後續版本開放（參考下方 Roadmap）。

三步驟開始使用

1. 在 dashboard 產生 API Token

到 https://hypelink.app/dashboard/brands/<你的 hypeId>/settings/api-tokens：

1. 按「產生新 Token」
2. 命名（例如 Claude Code on MacBook）— 方便日後辨識
3. 勾選需要的 scope：
   • homeinfo:read — 讀取首頁資訊
   • homeinfo:write — 編輯首頁資訊
   • events:read — 讀取活動列表 / 票種
   • events:write — 建立、編輯、刪除活動與票種
   • leads:read / leads:write — 名單神器（投廣 Landing Page 與名單匣）
   • mall:read / mall:write — Mini 商城（商品與訂單）
   • courses:read / courses:write — Mini 課程（課程/章節/單元/學員）
   • affiliates:read / affiliates:write — 聯盟行銷（夥伴/分潤/出金查詢）
4. 可選：設定存活天數（建議 90 天）
5. 按「產生」→ 立即複製跳出的明文 token（離開頁面就再也看不到）

安全提醒：Token 等同你的品牌寫入權限。請：

• 不要塞進 git
• 不要貼到公開頻道（Slack / Discord）
• 用完即撤銷
• 定期輪換

2. 設定 Claude Code

在 dashboard 產生 token 後，會看到預組好的 .mcp.json 片段。直接複製。

選項 A：專案範圍（建議用於特定 repo 操作）

在你的專案根目錄建立 .mcp.json：

{
  "mcpServers": {
    "hypelink-mybrand": {
      "type": "http",
      "url": "https://api.hypelink.app/mcp",
      "headers": {
        "Authorization": "Bearer hl_pat_xxxxxxxxxxxx"
      }
    }
  }
}

選項 B：全域

加進 ~/.claude.json 的 mcpServers 區塊（同上格式）。

3. 重啟 Claude Code

在 Claude Code 中：

/mcp

應該會列出 hypelink-mybrand，狀態 connected。如果沒看到：

• 檢查 .mcp.json 位置
• 確認 token 沒有複製到多餘空白
• /mcp list-tools hypelink-mybrand 看 server 回什麼

第一次使用：問問現在的狀態

> 用 hypelink mcp 看看我品牌頁現在長什麼樣

Claude 會自動呼叫 homeinfo.get_overview，列出 profile、所有 folders、modules 計數。

常用操作範例

新增連結

> 把我的 IG 連結加到「社群」分頁，標題寫「我的 Instagram」
> 連結是 https://instagram.com/myhandle

Claude 應該會先 list 確認分頁存在，然後 dry-run 顯示要新增的連結， 你確認後才真正寫入。

整理首頁

> 我想重新排我的首頁。先把現在的結構列出來，
> 然後幫我把跟「合作」相關的連結集中到一個新分頁

改 bio / 品牌色

> 把我的 bio 重寫得更專業一點，並把品牌主色改成深紫色 (#5B21B6)

刪除（會要求兩次確認）

> 刪除「舊活動」這個分頁

第一次 Claude 呼叫 folders.delete 會回 { confirmToken, summary }，列出將被刪除的內容；確認後 Claude 第二次帶 confirmToken 真正執行。

建立活動 + 票種

> 幫我在「好攝影」品牌底下建一場活動：
> 名稱「2026 春季婚禮攝影分享會」，2026/04/12 19:00 ~ 21:00，
> 線下，地點台北市信義區，先存草稿。
> 然後加兩個票種：早鳥票 NT$300（限 30 張）、現場票 NT$500。

Claude 會 dry-run 顯示 payload → 你確認後依序呼叫 events.create → events.tickets.create 兩次。

設定活動封面

> 把剛剛那場活動的封面換成這張圖：https://images.unsplash.com/photo-xxxxx

Claude 呼叫 events.set_cover { uuid, url }，後端會下載並 re-host 到 cdn.hypelink.app。

切換首頁主題 / 微調設計

> 我想試試 dark 主題，accentColor 用 #FF6B6B，cardRadius 改成 16。

Claude 先 themes.list 找到 themeId='builtin-dark'，再 design.get 拿現有 designSettings、merge 新欄位後用 design.put 整包覆寫。整段流程 dry-run 預覽過你才會看到實際變動。

可用 Tools

完整清單依首頁資訊 / 活動本體 / 活動加值互動模組分組，並含個資與計費注意點，搬到獨立的一頁：

➡️ MCP 可用 Tools 列表

簡短摘要：

• 首頁資訊（homeinfo:*）：Overview / Profile / Folders / Links / Modules / Socials
• 首頁設計（homeinfo:*）：Design Settings（get / put / set_theme）/ Themes list
• 活動（events:*）：Events / Tickets / Form / Notifications / Attendees / Check-in / Report / Outcomes / Announcements / Broadcasts / Polls / Q&A / Submissions / Surveys / Identity / Pairing / Feature Records / Collaborators
• 名單神器（leads:*）：Landing Pages（模板/建立/發布/A/B 變體）/ 名單匣（狀態/標籤）
• Mini 商城（mall:*）：Products（含庫存）/ Orders（出貨狀態）
• Mini 課程（courses:*）：Courses / Chapters / Lessons / Students / Analytics
• 聯盟行銷（affiliates:*）：Affiliates / 歸因 Orders / Payouts（查詢）

所有 write tool 都支援 dry_run: true；delete_* 預設兩階段 confirmToken；缺 scope 的 tool 會從 tools/list 隱藏。

Resources（自動上下文）

可以用 @ 把品牌資料 attach 進對話，讓 Claude 直接看上下文：

• @hypelink://brand/overview — 一次塞 profile + folders + modules 摘要
• @hypelink://brand/profile
• @hypelink://brand/folders
• @hypelink://brand/folders/123

與 dashboard 的關係

→ MCP 改的東西和在 dashboard 改的東西完全一樣，差別只在介面。

錯誤代碼

安全與最佳實踐

1. 一個 token 只配一個用途：MacBook 一把、CI 一把、團隊成員各一把；外洩時可單獨撤銷。
2. 設過期時間：90 天輪換比永不過期安全得多。
3. read-only 優先：如果只是要看資料（例如備份、分析），不要給 homeinfo:write。
4. 遇可疑活動 → 立即撤銷：dashboard 的 token 列表有「最後使用時間」可比對。
5. 不要把 token 寫進程式碼：請走 .mcp.json 設定檔或環境變數。

給 Claude Code 使用者的 Skill

我們維護了一份官方 Claude Skill：HypeLinkOfficial/hypelink_claude_skill 

安裝後 Claude 會自動：

• 對話開場跑 homeinfo.get_overview 建立上下文
• 寫入前一律 dry_run 預覽 → 你確認後再正式呼叫
• destructive 操作走兩階段 confirmToken
• 個資 / 計費類 tool 加遮罩與安全提醒

詳細安裝與 SOP 看 Claude Skill 文件。

Roadmap

回報問題

• GitHub issues：JienHuaGoo/HypeLink 
• Token / 計費問題：dashboard 右下角的客服