English Français العربية

harukibox

Official registry E-commerce

Run a Japan proxy-buying business from your AI: inventory, orders, buyers, shipping fee split.

Source code Website Documentation

What can you do with harukibox?

  • 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
  • Create product (with plan quota enforcement)

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

Remote (streamable-http)
Claude Code 
claude mcp add --transport http harukibox 'https://harukibox.com/api/agent/mcp'
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "harukibox": {
            "type": "http",
            "url": "https://harukibox.com/api/agent/mcp"
        }
    }
}
NPM package @harukibox/mcp
Claude Code 
claude mcp add harukibox -e 'HARUKIBOX_TOKEN=<your harukibox_token>' -e 'HARUKIBOX_BASE_URL=<HARUKIBOX_BASE_URL>' -- npx -y @harukibox/mcp@0.2.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "harukibox": {
            "command": "npx",
            "args": [
                "-y",
                "@harukibox/mcp@0.2.1"
            ],
            "env": {
                "HARUKIBOX_TOKEN": "<your harukibox_token>",
                "HARUKIBOX_BASE_URL": "<HARUKIBOX_BASE_URL>"
            }
        }
    }
}

Environment variables

  • HARUKIBOX_TOKEN required secret harukibox API token (hrk_live_…). 用 `harukibox login` 取得，或到 harukibox.com 設定頁產生。
  • HARUKIBOX_BASE_URL Self-hosted 或測試環境的 API base URL。留空即用官方 https://harukibox.com/api/agent。

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. harukibox-agent
  2. 我們的承諾：harukibox 不做 AI 助理
  3. 三個 Tier，從 0 技術到 power user
  4. Packages
  5. MCP 2026-07-28
  6. Available agent capabilities
  7. Security
  8. Examples directory
  9. Contributing
  10. License

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

PackagenpmWhat
@harukibox/cliCommand-line interface, OAuth login, business commands, MCP client + conformance checker
@harukibox/mcpModel 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.

SurfaceTransportEndpoint
@harukibox/mcpstdionpx -y @harukibox/mcp
Remote MCPStreamable HTTPhttps://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

FileWhat
examples/chatgpt-gpt-action.mdChatGPT Custom GPT setup with OAuth
examples/claude-desktop-config.jsonReady-to-paste Claude Desktop MCP config
examples/ios-shortcut.mdApple Shortcuts: Siri 「問 harukibox 我今天訂單」
examples/n8n-workflow.jsonThreads/IG private message → harukibox quote
examples/python-agent-demo.py50-line Python OAuth + agent example
examples/apple-app-intents-swift.mdiOS 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.

Frequently asked questions

What is harukibox?

Run a Japan proxy-buying business from your AI: inventory, orders, buyers, shipping fee split.

How do I install harukibox?

It runs as a remote server. In Claude Code: claude mcp add --transport http harukibox 'https://harukibox.com/api/agent/mcp'. For other clients, paste the JSON configuration from this page into their MCP settings.

Does harukibox need an API key?

Yes. It expects HARUKIBOX_TOKEN, which you set in its configuration.

Is harukibox open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains harukibox?

It is published by cosmopig. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.