harukibox-agent

Bring Your Own Agent for harukibox. The official open-source CLI + MCP server + integration recipes for connecting any AI agent to your harukibox account.

我們的承諾：harukibox 不做 AI 助理

You choose the AI. You train the AI. Your AI, your call.

很多 SaaS 賣給你它家的 AI chatbot — 綁死、貴、且通常不好用。我們選擇做相反的事：把 harukibox 的訂單、買家、運費分攤、AI 趨勢分析全部 expose 成標準 OAuth + REST + MCP，讓你接你信任的任何 agent。

• ChatGPT / Custom GPT
• Claude Desktop / Claude API
• Cursor / Windsurf
• Apple Siri / Apple Intelligence
• n8n / Zapier / Make
• 你自己 Python / Node 寫的 agent

不會程式？沒關係 —— 我們提供 30 秒 ChatGPT 一鍵接入 與 5 分鐘 iOS Shortcut import。

三個 Tier，從 0 技術到 power user

Tier 1（30 秒 / 不寫程式）

你 ──→ ChatGPT (custom GPT) ──→ harukibox API

直接到 chatgpt.com 建一個 GPT Action，貼 OpenAPI URL 完成 OAuth setup：

https://harukibox.com/api/agent/openapi.json

詳細教學 →

Tier 2（5 分鐘 / 一行 JSON）

你 ──→ Claude Desktop ──→ MCP server ──→ harukibox API

npm install -g @harukibox/cli
harukibox login
# 完成後 token 在 ~/.config/harukibox/config.json

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "harukibox": {
      "command": "npx",
      "args": ["-y", "@harukibox/mcp"],
      "env": { "HARUKIBOX_TOKEN": "hrk_live_..." }
    }
  }
}

詳細教學 →

Tier 3（power user / 開發者）

你 ──→ 你寫的 agent ──→ OAuth 2.1 + REST API ──→ harukibox

• OAuth flow: PKCE (RFC 7636) 或 device flow (RFC 8628)
• 8 個 REST endpoints + OpenAPI 3.1 schema
• Refresh token rotation + reuse detection
• 完整 spec compliant: RFC 6749 / 6750 / 7009 / 8414 / 9728 + MCP 2026-07-28

完整 docs → 範例 Python agent → n8n workflow →

Packages

Package	npm	What
@harukibox/cli		Command-line interface, OAuth login, business commands, MCP client + conformance checker
@harukibox/mcp		Model Context Protocol server (stdio), 8 tools for Claude Desktop / Claude Code

MCP 2026-07-28

Both MCP surfaces implement the 2026-07-28 revision — the one that made MCP stateless — and stay dual-era, so clients still on the initialize handshake keep working while they migrate.

What changed with 2026-07-28:

• No handshake. Every request carries its own protocol version, client identity and capabilities in _meta. No sessions, no Mcp-Session-Id.
• server/discover replaces initialize for capability discovery.
• Standard headers (MCP-Protocol-Version, Mcp-Method, Mcp-Name) mirror the body and are validated against it — mismatches get -32020.
• Cacheable lists. tools/list returns ttlMs + cacheScope, in a deterministic order, so clients can cache and prompt caches keep hitting.
• GET / DELETE are gone (405): the standalone SSE stream and session teardown were removed from the transport.

Check any deployment against the spec:

harukibox mcp check

Protocol details + error codes →

Available agent capabilities

Read (scope: me / *:read / search)

• List products with search, status filter, pagination
• Get product by id
• List orders (registrations) by status / buyer
• List buyers (search by name / phone / email)
• List shipments
• Cross-resource search
• Self-introspect own tokens

Write (scope: *:write)

• Create product (with plan quota enforcement)
• Revoke own tokens

詳細 schema 看 openapi.json。

Security

• Multi-tenant isolation: every request re-validates organization_id membership (IDOR 防護)
• 2FA gate: OAuth approve requires verified 2FA cookie if user has 2FA on
• Refresh rotation + reuse detection: stolen refresh token gets the entire chain revoked
• Rate limits per grant type: refresh 20/min, auth_code 10/min, device poll 200/min
• Audit log: every API call + revoke + reuse detection event
• WWW-Authenticate on 401 / 403 with proper RFC 6750 §3 fields
• Cache-Control: no-store on all token responses (RFC 6749 §5.1)
• Constant-time compare on HMAC

Full audit log: docs/security-audit.md

Examples directory

Contributing

PRs welcome. Particularly looking for:

• Translations (English README, JP README)
• More integration examples (LangChain / LlamaIndex / DSPy)
• iOS / Android shortcuts library
• n8n / Zapier / Make community templates

For questions → Issues | Discussions

For harukibox SaaS itself → harukibox.com | support@harukibox.com

License

MIT — see LICENSE.