harukibox

@harukibox/mcp

Model Context Protocol server for harukibox — let your AI agent manage your 代購 inventory, orders, buyers and shipments through the official Agent API.

協定版本

實作 MCP 2026-07-28（stateless、server/discover、resultType、cacheable tools/list），同時維持 dual-era：舊版的 initialize handshake 照樣回應。

也就是說現在的 Claude Desktop / Claude Code（仍在 2025-11-25 以前）不用改任何設定 就能繼續用；等 client 升級到 2026-07-28 後會自動走新路徑，一樣不用改設定。

@modelcontextprotocol/sdk 最新的 1.30.0 仍停在 2025-11-25，沒有 server/discover / resultType / CacheableResult，所以本 server 直接輸出 wire format 而不透過 SDK（也因此本套件零 runtime 相依）。SDK 支援新版後會換回去。

安裝

npm install -g @harukibox/mcp

或在專案內：

npm install @harukibox/mcp

取得 API token

透過 @harukibox/cli 跑 OAuth 取得（90 天有效）：

npm install -g @harukibox/cli
harukibox login           # PKCE，預設打開瀏覽器
# 或無 GUI 環境：
harukibox login --device  # device flow，顯示 user_code 讓你在瀏覽器輸入

跑完 token 會寫進 ~/.config/harukibox/config.json（mode 0600）。把該 token 設成 HARUKIBOX_TOKEN 即可。

Claude Desktop 設定

編輯 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "harukibox": {
      "command": "harukibox-mcp",
      "env": {
        "HARUKIBOX_TOKEN": "hrk_live_your_token_here"
      }
    }
  }
}

Refresh token (進階, 預設關閉)

如果你跑 long-lived MCP process（不常重啟），可開 refresh：

"env": {
  "HARUKIBOX_TOKEN": "hrk_live_...",
  "HARUKIBOX_ENABLE_REFRESH": "1",
  "HARUKIBOX_REFRESH_TOKEN": "hrk_refresh_..."
}

⚠️ 限制：refresh rotation 後新 refresh 只在 process memory；process 重啟時 env 仍是舊 refresh，server 會視為 reuse 並撤該 user 所有 token。重啟前請手動執行 harukibox login 取新 token。建議 production 不開此選項，依賴 90 天到期後 re-OAuth。

Claude Code 設定

claude mcp add harukibox --command harukibox-mcp --env HARUKIBOX_TOKEN=hrk_live_your_token_here

可用工具

Tool	必要 scope	說明
haruki_me	me	取得當前 user/organization/token info
haruki_list_products	products:read	列出商品
haruki_get_product	products:read	取得單一商品
haruki_create_product	products:write	建立商品
haruki_list_registrations	registrations:read	列出訂單
haruki_list_buyers	buyers:read	列出買家
haruki_list_shippings	shippings:read	列出出貨
haruki_search	search	全域搜尋

安全

• Token 一律以環境變數提供，不會寫入磁碟
• 所有請求走 HTTPS 並帶 sha256 hash 驗證
• 過期 / 撤銷 / IP allowlist 不符時請求會立刻被拒
• 每次呼叫會被寫入伺服器端 audit log（沒有 web UI 查詢；如需匯出請與服務方聯繫）

自架 / 私有部署

HARUKIBOX_BASE_URL=https://your-instance.example.com/api/agent \
HARUKIBOX_TOKEN=hrk_live_... \
harukibox-mcp

License

MIT