{
  "markdown": "# harukibox-agent\n\n> **Bring Your Own Agent for harukibox.** \n> The official open-source CLI + MCP server + integration recipes for connecting **any AI agent** to your harukibox account.\n\n[![npm @harukibox/cli](https://img.shields.io/npm/v/@harukibox/cli?label=%40harukibox%2Fcli)](https://www.npmjs.com/package/@harukibox/cli)\n[![npm @harukibox/mcp](https://img.shields.io/npm/v/@harukibox/mcp?label=%40harukibox%2Fmcp)](https://www.npmjs.com/package/@harukibox/mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n---\n\n## 我們的承諾：harukibox 不做 AI 助理\n\n> **You choose the AI. You train the AI. Your AI, your call.**\n\n很多 SaaS 賣給你它家的 AI chatbot — 綁死、貴、且通常不好用。我們選擇做相反的事：把 harukibox 的訂單、買家、運費分攤、AI 趨勢分析全部 expose 成標準 OAuth + REST + MCP，**讓你接你信任的任何 agent**。\n\n- ChatGPT / Custom GPT\n- Claude Desktop / Claude API\n- Cursor / Windsurf\n- Apple Siri / Apple Intelligence\n- n8n / Zapier / Make\n- 你自己 Python / Node 寫的 agent\n\n不會程式？沒關係 —— 我們提供 **30 秒 ChatGPT 一鍵接入** 與 **5 分鐘 iOS Shortcut import**。\n\n---\n\n## 三個 Tier，從 0 技術到 power user\n\n### Tier 1（30 秒 / 不寫程式）\n\n```\n你 ──→ ChatGPT (custom GPT) ──→ harukibox API\n```\n\n直接到 chatgpt.com 建一個 GPT Action，貼 OpenAPI URL 完成 OAuth setup：\n\n```\nhttps://harukibox.com/api/agent/openapi.json\n```\n\n[詳細教學 →](examples/chatgpt-gpt-action.md)\n\n### Tier 2（5 分鐘 / 一行 JSON）\n\n```\n你 ──→ Claude Desktop ──→ MCP server ──→ harukibox API\n```\n\n```bash\nnpm install -g @harukibox/cli\nharukibox login\n# 完成後 token 在 ~/.config/harukibox/config.json\n```\n\n```json\n// ~/Library/Application Support/Claude/claude_desktop_config.json\n{\n  \"mcpServers\": {\n    \"harukibox\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@harukibox/mcp\"],\n      \"env\": { \"HARUKIBOX_TOKEN\": \"hrk_live_...\" }\n    }\n  }\n}\n```\n\n[詳細教學 →](examples/claude-desktop-config.json)\n\n### Tier 3（power user / 開發者）\n\n```\n你 ──→ 你寫的 agent ──→ OAuth 2.1 + REST API ──→ harukibox\n```\n\n- OAuth flow: PKCE (RFC 7636) 或 device flow (RFC 8628)\n- 8 個 REST endpoints + OpenAPI 3.1 schema\n- Refresh token rotation + reuse detection\n- 完整 spec compliant: RFC 6749 / 6750 / 7009 / 8414 / 9728 + **MCP 2026-07-28**\n\n[完整 docs →](docs/)\n[範例 Python agent →](examples/python-agent-demo.py)\n[n8n workflow →](examples/n8n-workflow.json)\n\n---\n\n## Packages\n\n| Package | npm | What |\n|---|---|---|\n| `@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 |\n| `@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 |\n\n---\n\n## MCP 2026-07-28\n\nBoth MCP surfaces implement the **2026-07-28** revision — the one that made MCP\nstateless — and stay **dual-era**, so clients still on the `initialize`\nhandshake keep working while they migrate.\n\n| Surface | Transport | Endpoint |\n|---|---|---|\n| `@harukibox/mcp` | stdio | `npx -y @harukibox/mcp` |\n| Remote MCP | Streamable HTTP | `https://harukibox.com/api/agent/mcp` |\n\nWhat changed with 2026-07-28:\n\n- **No handshake.** Every request carries its own protocol version, client\n  identity and capabilities in `_meta`. No sessions, no `Mcp-Session-Id`.\n- **`server/discover`** replaces `initialize` for capability discovery.\n- **Standard headers** (`MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name`) mirror\n  the body and are validated against it — mismatches get `-32020`.\n- **Cacheable lists.** `tools/list` returns `ttlMs` + `cacheScope`, in a\n  deterministic order, so clients can cache and prompt caches keep hitting.\n- **`GET` / `DELETE` are gone** (405): the standalone SSE stream and session\n  teardown were removed from the transport.\n\nCheck any deployment against the spec:\n\n```bash\nharukibox mcp check\n```\n\n[Protocol details + error codes →](docs/mcp-tools.md#protocol-mcp-2026-07-28)\n\n---\n\n## Available agent capabilities\n\n**Read** (scope: `me` / `*:read` / `search`)\n- List products with search, status filter, pagination\n- Get product by id\n- List orders (registrations) by status / buyer\n- List buyers (search by name / phone / email)\n- List shipments\n- Cross-resource search\n- Self-introspect own tokens\n\n**Write** (scope: `*:write`)\n- Create product (with plan quota enforcement)\n- Revoke own tokens\n\n詳細 schema 看 [openapi.json](https://harukibox.com/api/agent/openapi.json)。\n\n---\n\n## Security\n\n- **Multi-tenant isolation**: every request re-validates `organization_id` membership (IDOR 防護)\n- **2FA gate**: OAuth approve requires verified 2FA cookie if user has 2FA on\n- **Refresh rotation + reuse detection**: stolen refresh token gets the entire chain revoked\n- **Rate limits per grant type**: refresh 20/min, auth_code 10/min, device poll 200/min\n- **Audit log**: every API call + revoke + reuse detection event\n- **WWW-Authenticate** on 401 / 403 with proper RFC 6750 §3 fields\n- **Cache-Control: no-store** on all token responses (RFC 6749 §5.1)\n- **Constant-time compare** on HMAC\n\nFull audit log: [docs/security-audit.md](docs/security-audit.md)\n\n---\n\n## Examples directory\n\n| File | What |\n|---|---|\n| `examples/chatgpt-gpt-action.md` | ChatGPT Custom GPT setup with OAuth |\n| `examples/claude-desktop-config.json` | Ready-to-paste Claude Desktop MCP config |\n| `examples/ios-shortcut.md` | Apple Shortcuts: Siri 「問 harukibox 我今天訂單」 |\n| `examples/n8n-workflow.json` | Threads/IG private message → harukibox quote |\n| `examples/python-agent-demo.py` | 50-line Python OAuth + agent example |\n| `examples/apple-app-intents-swift.md` | iOS 18+ App Intents + Apple Intelligence integration |\n\n---\n\n## Contributing\n\nPRs welcome. Particularly looking for:\n- Translations (English README, JP README)\n- More integration examples (LangChain / LlamaIndex / DSPy)\n- iOS / Android shortcuts library\n- n8n / Zapier / Make community templates\n\nFor questions → [Issues](https://github.com/cosmopig/harukibox-agent/issues) | [Discussions](https://github.com/cosmopig/harukibox-agent/discussions)\n\nFor harukibox SaaS itself → [harukibox.com](https://harukibox.com) | support@harukibox.com\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 6148,
  "sha": "33079d86baf5a311d9aaca7e1290cc520d6d4a7c4c1364d7af2b5265e47c4c07",
  "repo_slug": "cosmopig/harukibox-agent",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_harukibox_harukibox_498ef1f9/readme"
}