# harukibox [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/cosmopig/harukibox-agent  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/harukibox

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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "harukibox": {
    "command": "npx",
    "args": ["-y","@harukibox/mcp"]
  }
}
```

## Documentation & README

# 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.

[![npm @harukibox/cli](https://img.shields.io/npm/v/@harukibox/cli?label=%40harukibox%2Fcli)](https://www.npmjs.com/package/@harukibox/cli)
[![npm @harukibox/mcp](https://img.shields.io/npm/v/@harukibox/mcp?label=%40harukibox%2Fmcp)](https://www.npmjs.com/package/@harukibox/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

---

## 我們的承諾：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
```

[詳細教學 →](https://github.com/cosmopig/harukibox-agent/blob/HEAD/examples/chatgpt-gpt-action.md)

### Tier 2（5 分鐘 / 一行 JSON）

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

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

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

[詳細教學 →](https://github.com/cosmopig/harukibox-agent/blob/HEAD/examples/claude-desktop-config.json)

### 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 →](https://github.com/cosmopig/harukibox-agent/blob/HEAD/docs/)
[範例 Python agent →](https://github.com/cosmopig/harukibox-agent/blob/HEAD/examples/python-agent-demo.py)
[n8n workflow →](https://github.com/cosmopig/harukibox-agent/blob/HEAD/examples/n8n-workflow.json)

---

## Packages

| Package | npm | What |
|---|---|---|
| `@harukibox/cli` | [![npm](https://img.shields.io/npm/v/@harukibox/cli)](https://www.npmjs.com/package/@harukibox/cli) | Command-line interface, OAuth login, business commands, MCP client + conformance checker |
| `@harukibox/mcp` | [![npm](https://img.shields.io/npm/v/@harukibox/mcp)](https://www.npmjs.com/package/@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:

```bash
harukibox mcp check
```

[Protocol details + error codes →](https://github.com/cosmopig/harukibox-agent/blob/HEAD/docs/mcp-tools.md#protocol-mcp-2026-07-28)

---

## 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](https://harukibox.com/api/agent/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](https://github.com/cosmopig/harukibox-agent/blob/HEAD/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](https://github.com/cosmopig/harukibox-agent/issues) | [Discussions](https://github.com/cosmopig/harukibox-agent/discussions)

For harukibox SaaS itself → [harukibox.com](https://harukibox.com) | support@harukibox.com

---

## License

MIT — see [LICENSE](https://github.com/cosmopig/harukibox-agent/blob/HEAD/LICENSE).