用 Claude / ChatGPT 操作後台：MCP 與 Agent API

透過 Agent API、MCP Server、CLI 讓 Claude / ChatGPT / 自架 LLM 代你管理 harukibox

為什麼有 Agent API

許多代購賣家同時用 Claude、ChatGPT 處理日常工作。harukibox 不內建 AI 助理，而是開放官方 Agent API + MCP Server + CLI，讓你把後台接到自己已經在用的那個 AI：查商品、查訂單、看統計， 也能建立商品與品項、把一整批喊單解析成登記、更新訂單與出貨狀態、分攤運費、 把到貨的品項指派到箱子。 全部走 OAuth 2.1 + scope 控制權限 + audit log 留底，跟 web app 同樣的多租戶隔離保護。

三條接入路徑

  • Remote MCP（推薦） — 在 Claude 或 ChatGPT（需 Plus 以上）的「連接器 / Connectors」 設定貼上 https://harukibox.com/api/agent/mcp，授權畫面按一次同意就好。 不必申請 API key、不必手動產生 token：client 註冊走 CIMD（Client ID Metadata Documents）， OAuth 2.1 PKCE 全自動。協定為 MCP 2026-07-28（stateless Streamable HTTP）， 同時相容 2025-06-18 的 initialize 交握。
  • 本地 stdio MCP — npm i -g @harukibox/mcp，加到 Claude Desktop 設定即可。 最低延遲；也適合不支援遠端連接器的 client。
  • REST + CLI — npm i -g @harukibox/cli 後 harukibox login， 支援 PKCE 與 device flow。直接 curl 走 OpenAPI 描述的 REST endpoint 也 OK。

三步驟 Quick Start

  1. 貼上連接器網址：在 AI 的連接器設定新增https://harukibox.com/api/agent/mcp。沒登入 harukibox 會先跳登入頁， 登入後自動回到授權畫面。
  2. 在授權畫面勾權限：讀取與寫入分開勾，可以只給讀取。 每個授權都能在設定裡單獨撤銷。
  3. 確認接對帳號：直接問 AI「我是哪家店」（它會呼叫 haruki_me）， 或用 CLI harukibox products list --limit 3。
工具清單更新了要重新連一次
ChatGPT 只在「新增連接器」時抓一次 tools/list，開新對話不會重抓。 我們加了新工具之後，你得把連接器移除再重新加入才看得到——這是 client 端的快取行為，不是授權失效。
不用自己教 AI 流程
伺服器透過 MCP prompts 提供現成工作流程（解析喊單、每日概況、查買家訂單）。 支援的 client 會呈現成斜線指令之類的入口，選一下就把完整流程與注意事項載進去， 不必每次開新對話都重打一遍說明。

Scope 與 Token

Token 格式 hrk_live_<base32>（access，90 天）和 hrk_refresh_<base32>（refresh，365 天，rotation + reuse detection）。 Scope 以最小權限原則設計：me、products:read/write、registrations:read/write、buyers:read/write、shippings:read/write、search。:write 自動包含對應的 :read。

新增的 endpoint 沿用既有 scope，沒有再擴充清單：統計走 registrations:read、 運費計算與倉儲查詢走 products:read、把品項指派到箱子走 products:write（品項掛在商品底下）、買家歸戶走 buyers:read/write。

寫入需要付費方案
讀取所有方案都能用，包含免費版。寫入（讓 AI 直接建訂單、改狀態）需要方案的limits.canIntegrate 為 true——專業版與商業版都有，免費版沒有。免費版呼叫寫入會拿到 HTTP 402 與PLAN_UPGRADE_REQUIRED，回應裡帶明確的升級說明，不是模糊的權限錯誤。 另外，品項數量不計入方案配額；商品與登記筆數照原本的配額計算。
還沒開放給 agent 的操作
刪除任何資料、建立倉庫結構本身（地點／區域／箱）——這些只能在網頁或 App 操作。 批次寫入一次上限 50 筆（品項 100 筆，倉儲指派 200 筆）。

安全保證

  • OAuth 2.1（PKCE S256 強制）+ RFC 8628 device flow
  • Refresh token rotation + reuse detection（第二次用同一個 refresh 在 5 秒 grace 後撤整條 chain）
  • 2FA gate 在 OAuth approve 階段（縱深防禦）
  • 每個 token 可設 IP allowlist + 自訂 rate limit/分鐘
  • 401 / 403 回應帶 WWW-Authenticate，符合 RFC 6750 + RFC 9728
  • RFC 8707 Resource Indicators：token 請求帶未知的 resource 會被拒（invalid_target）， 避免 token 被拿去對別的 resource server 重放
  • 寫入另有方案閘門（canIntegrate），與 scope 各自獨立檢查
  • 每個 API 呼叫寫入 agent_api_audit_log，使用者可在設定查
  • 每個 request 重驗 organization_id（防 IDOR）

機讀資源

原始碼與支援

CLI + MCP package 開源在 github.com/cosmopig/harukibox-agent。 Issue 用 GitHub issues 回報；商業支援寫到 support@harukibox.com。