harukibox

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.

Surface	Transport	Endpoint
@harukibox/mcp	stdio	npx -y @harukibox/mcp
Remote MCP	Streamable HTTP	https://harukibox.com/api/agent/mcp

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

File	What
examples/chatgpt-gpt-action.md	ChatGPT Custom GPT setup with OAuth
examples/claude-desktop-config.json	Ready-to-paste Claude Desktop MCP config
examples/ios-shortcut.md	Apple Shortcuts: Siri 「問 harukibox 我今天訂單」
examples/n8n-workflow.json	Threads/IG private message → harukibox quote
examples/python-agent-demo.py	50-line Python OAuth + agent example
examples/apple-app-intents-swift.md	iOS 18+ App Intents + Apple Intelligence integration

---

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.