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

... View full README on GitHub