Agent / AI 整合（Early Access）

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

Early Access
Agent API / MCP / CLI 仍在 Early Access。介面已穩定，但 ChatGPT Connector / Anthropic Connector Store 上架仍在規劃中。問題回報歡迎開 issue。

為什麼有 Agent API

許多代購賣家同時用 Claude Desktop、Claude Code、ChatGPT 處理日常工作。harukibox 提供官方 Agent API + MCP Server + CLI，讓 AI agent 可以代你查商品、查訂單、新增商品 — 全部走 OAuth 2.1 + scope 控制權限 + audit log 留底， 跟 web app 同樣的多租戶隔離保護。

三條接入路徑

  • 本地 stdio MCP — npm i -g @harukibox/mcp，加到 Claude Desktop 設定即可。 最低延遲，最適合本機開發機。
  • Remote MCP（Streamable HTTP） — POST https://harukibox.com/api/agent/mcp+ Bearer token，JSON-RPC 2.0 規格（MCP 2025-06-18）。給雲端 agent 或不方便裝 npm 的場景用。
  • REST + CLI — npm i -g @harukibox/cli 後 harukibox login， 支援 PKCE 與 device flow。直接 curl 走 OpenAPI 描述的 REST endpoint 也 OK。

三步驟 Quick Start

  1. 裝 CLI 並登入：
    npm install -g @harukibox/cli
harukibox login
    OAuth 流程會在瀏覽器開啟 PKCE 授權頁，授權後 token 自動寫進你 home 目錄。
  2. 確認 token 綁對 store：harukibox products list --limit 3 或直接打 haruki_me MCP tool。
  3. 接到 AI client：把 @harukibox/mcp 加到 Claude Desktop 設定，或讓 ChatGPT GPT Action 讀 /api/agent/openapi.json。

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。

目前 write 限制
POST /products 已實作（會檢查 plan quota）。registrations:write、buyers:write、shippings:write為 scope 預留位，對應 endpoint 還在開發中。

安全保證

  • 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
  • 每個 API 呼叫寫入 agent_api_audit_log，使用者可在設定查
  • 每個 request 重驗 organization_id（防 IDOR）

機讀資源

原始碼與支援

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