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.

harukibox

Links

README