@harukibox/mcp 0.1.1

package/README.md

@@ -0,0 +1,97 @@
+# @harukibox/mcp
+
+Model Context Protocol server for [harukibox](https://harukibox.com) — let your AI agent manage your 代購 inventory, orders, buyers and shipments through the official Agent API.
+
+## 安裝
+
+```bash
+npm install -g @harukibox/mcp
+```
+
+或在專案內：
+
+```bash
+npm install @harukibox/mcp
+```
+
+## 取得 API token
+
+透過 `@harukibox/cli` 跑 OAuth 取得（90 天有效）：
+
+```bash
+npm install -g @harukibox/cli
+harukibox login           # PKCE，預設打開瀏覽器
+# 或無 GUI 環境：
+harukibox login --device  # device flow，顯示 user_code 讓你在瀏覽器輸入
+```
+
+跑完 token 會寫進 `~/.config/harukibox/config.json`（mode 0600）。把該 token 設成 `HARUKIBOX_TOKEN` 即可。
+
+## Claude Desktop 設定
+
+編輯 `~/Library/Application Support/Claude/claude_desktop_config.json`：
+
+```json
+{
+  "mcpServers": {
+    "harukibox": {
+      "command": "harukibox-mcp",
+      "env": {
+        "HARUKIBOX_TOKEN": "hrk_live_your_token_here"
+      }
+    }
+  }
+}
+```
+
+### Refresh token (進階, 預設關閉)
+
+如果你跑 long-lived MCP process（不常重啟），可開 refresh：
+
+```json
+"env": {
+  "HARUKIBOX_TOKEN": "hrk_live_...",
+  "HARUKIBOX_ENABLE_REFRESH": "1",
+  "HARUKIBOX_REFRESH_TOKEN": "hrk_refresh_..."
+}
+```
+
+⚠️ **限制**：refresh rotation 後新 refresh 只在 process memory；process 重啟時 env 仍是舊 refresh，server 會視為 reuse 並撤該 user **所有 token**。重啟前請手動執行 `harukibox login` 取新 token。建議 production 不開此選項，依賴 90 天到期後 re-OAuth。
+
+## Claude Code 設定
+
+```bash
+claude mcp add harukibox --command harukibox-mcp --env HARUKIBOX_TOKEN=hrk_live_your_token_here
+```
+
+## 可用工具
+
+| Tool | 必要 scope | 說明 |
+|------|----------|------|
+| `haruki_me` | `me` | 取得當前 user/organization/token info |
+| `haruki_list_products` | `products:read` | 列出商品 |
+| `haruki_get_product` | `products:read` | 取得單一商品 |
+| `haruki_create_product` | `products:write` | 建立商品 |
+| `haruki_list_registrations` | `registrations:read` | 列出訂單 |
+| `haruki_list_buyers` | `buyers:read` | 列出買家 |
+| `haruki_list_shippings` | `shippings:read` | 列出出貨 |
+| `haruki_search` | `search` | 全域搜尋 |
+
+## 安全
+
+- Token 一律以環境變數提供，不會寫入磁碟
+- 所有請求走 HTTPS 並帶 sha256 hash 驗證
+- 過期 / 撤銷 / IP allowlist 不符時請求會立刻被拒
+- 每次呼叫會被寫入伺服器端 audit log（沒有 web UI 查詢；如需匯出請與服務方聯繫）
+
+## 自架 / 私有部署
+
+```bash
+HARUKIBOX_BASE_URL=https://your-instance.example.com/api/agent \
+HARUKIBOX_TOKEN=hrk_live_... \
+harukibox-mcp
+```
+
+## License
+
+MIT

package/bin/harukibox-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Built entry point — assumes `npm run build` has produced dist/.
+import('../dist/index.js').catch((err) => {
+    console.error('[harukibox-mcp] failed to start:', err?.message || err);
+    console.error('[harukibox-mcp] did you run `npm run build` inside packages/haruki-mcp?');
+    process.exit(1);
+});

package/dist/api-client.js

@@ -0,0 +1,133 @@
+/**
+ * Thin fetch wrapper for the harukibox Agent API.
+ */
+const DEFAULT_BASE_URL = 'https://harukibox.com/api/agent';
+export class HarukiAgentClient {
+    token;
+    refreshToken;
+    baseUrl;
+    userAgent;
+    timeoutMs;
+    /** OAuth /token endpoint (computed from baseUrl: strip /api/agent suffix). */
+    tokenEndpoint;
+    constructor(opts) {
+        if (!opts.token)
+            throw new Error('HarukiAgentClient requires a token');
+        this.token = opts.token;
+        this.refreshToken = opts.refreshToken;
+        this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+        this.userAgent = opts.userAgent || 'harukibox-mcp/0.1.1';
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        // baseUrl 通常是 https://harukibox.com/api/agent；OAuth /token 在 https://harukibox.com/api/auth/oauth/token
+        const origin = this.baseUrl.replace(/\/api\/agent$/, '');
+        this.tokenEndpoint = `${origin}/api/auth/oauth/token`;
+    }
+    /** 401 時用 refresh token 換新 access；in-memory swap，process restart 後失效。*/
+    async tryRefresh() {
+        if (!this.refreshToken)
+            return false;
+        try {
+            const res = await fetch(this.tokenEndpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    grant_type: 'refresh_token',
+                    refresh_token: this.refreshToken,
+                    client_id: 'harukibox-cli',
+                }),
+            });
+            if (!res.ok)
+                return false;
+            const j = (await res.json());
+            if (!j.access_token)
+                return false;
+            this.token = j.access_token;
+            if (j.refresh_token)
+                this.refreshToken = j.refresh_token;
+            console.error('[harukibox-mcp] access token expired, refreshed silently');
+            return true;
+        }
+        catch (err) {
+            console.error('[harukibox-mcp] refresh failed:', err);
+            return false;
+        }
+    }
+    async request(method, path, body, query) {
+        const url = new URL(`${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                if (v !== undefined && v !== null && v !== '') {
+                    url.searchParams.set(k, String(v));
+                }
+            }
+        }
+        const doFetch = async () => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                return await fetch(url.toString(), {
+                    method,
+                    headers: {
+                        'Authorization': `Bearer ${this.token}`,
+                        'User-Agent': this.userAgent,
+                        'Accept': 'application/json',
+                        ...(body ? { 'Content-Type': 'application/json' } : {}),
+                    },
+                    body: body ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        try {
+            let res = await doFetch();
+            // 401 + 有 refresh token → refresh + 重試一次
+            if (res.status === 401 && this.refreshToken) {
+                const refreshed = await this.tryRefresh();
+                if (refreshed)
+                    res = await doFetch();
+            }
+            const text = await res.text();
+            let parsed;
+            try {
+                parsed = text ? JSON.parse(text) : { success: res.ok };
+            }
+            catch {
+                return { success: false, message: `Non-JSON response (${res.status})` };
+            }
+            if (!res.ok) {
+                const obj = parsed;
+                return {
+                    success: false,
+                    message: typeof obj?.message === 'string' ? obj.message : `HTTP ${res.status}`,
+                    code: typeof obj?.code === 'string' ? obj.code : undefined,
+                };
+            }
+            return parsed;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { success: false, message: msg };
+        }
+    }
+    me() { return this.request('GET', '/me'); }
+    listProducts(params) {
+        return this.request('GET', '/products', undefined, params);
+    }
+    getProduct(id) { return this.request('GET', `/products/${encodeURIComponent(id)}`); }
+    createProduct(payload) { return this.request('POST', '/products', payload); }
+    listRegistrations(params) {
+        return this.request('GET', '/registrations', undefined, params);
+    }
+    listBuyers(params) {
+        return this.request('GET', '/buyers', undefined, params);
+    }
+    listShippings(params) {
+        return this.request('GET', '/shippings', undefined, params);
+    }
+    search(q, type) {
+        return this.request('GET', '/search', undefined, { q, type });
+    }
+}

package/dist/index.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+/**
+ * harukibox MCP server.
+ *
+ * Connect this server to Claude Desktop, Claude Code or any MCP-compatible
+ * client. It exposes the harukibox Agent API as MCP tools.
+ *
+ * Authentication: set HARUKIBOX_TOKEN env var (run `harukibox login` from
+ * @harukibox/cli to obtain one via OAuth). Base URL can be overridden via
+ * HARUKIBOX_BASE_URL.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { HarukiAgentClient } from './api-client.js';
+const SERVER_NAME = 'harukibox';
+const SERVER_VERSION = '0.1.1';
+function getEnv(name, fallback) {
+    const v = process.env[name];
+    if (v && v.length > 0)
+        return v;
+    return fallback;
+}
+const token = getEnv('HARUKIBOX_TOKEN');
+const enableRefresh = getEnv('HARUKIBOX_ENABLE_REFRESH') === '1';
+const refreshToken = enableRefresh ? getEnv('HARUKIBOX_REFRESH_TOKEN') : undefined;
+const baseUrl = getEnv('HARUKIBOX_BASE_URL', 'https://harukibox.com/api/agent');
+if (!token) {
+    console.error('[harukibox-mcp] Missing HARUKIBOX_TOKEN environment variable.');
+    console.error('[harukibox-mcp] Run `harukibox login` (from @harukibox/cli) to obtain one.');
+    process.exit(1);
+}
+// codex 4th W3：refresh in MCP 預設 disable。
+// 原因：rotation 後新 refresh 只在 process memory，restart 後 env 是舊 refresh
+//      → server 視為 reuse 撤該 user 整條 chain。
+// User 知情後可設 HARUKIBOX_ENABLE_REFRESH=1 開啟（建議搭配 long-lived process / 不重啟）。
+if (enableRefresh && refreshToken) {
+    console.error('[harukibox-mcp] HARUKIBOX_ENABLE_REFRESH=1 + HARUKIBOX_REFRESH_TOKEN detected.');
+    console.error('[harukibox-mcp] 401 will trigger silent refresh; process restart will INVALIDATE the chain.');
+}
+else if (enableRefresh) {
+    console.error('[harukibox-mcp] HARUKIBOX_ENABLE_REFRESH=1 but HARUKIBOX_REFRESH_TOKEN missing; refresh disabled.');
+}
+const client = new HarukiAgentClient({
+    token,
+    refreshToken,
+    baseUrl,
+    userAgent: `${SERVER_NAME}-mcp/${SERVER_VERSION}`,
+});
+/**
+ * Annotations follow the MCP 2025-06 spec:
+ *   - title: human-readable; clients (Claude Desktop, Anthropic Connector review)
+ *     prefer this over tool name when displaying.
+ *   - readOnlyHint: true  → no observable state mutation.
+ *   - destructiveHint: true → this can permanently change data the user cares about.
+ *     Anthropic review requires destructive write tools to be marked.
+ *   - openWorldHint: true → tool reaches out beyond the local process (HTTP API).
+ */
+const tools = [
+    {
+        name: 'haruki_me',
+        title: 'Get account info',
+        description: 'Return the user, organization and token info bound to this MCP connection. Always call first to confirm which harukibox store the agent is operating against.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        annotations: {
+            title: 'Get account info',
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: 'haruki_list_products',
+        title: 'List products',
+        description: 'List products in the connected harukibox store. Supports search (matches name + SKU), status filter and pagination.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                page: { type: 'integer', minimum: 1, default: 1 },
+                limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+                search: { type: 'string', description: 'Match against name and SKU.' },
+                status: { type: 'string', description: '現貨 / 預購 / 售罄 / active 等' },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            title: 'List products',
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: 'haruki_get_product',
+        title: 'Get product',
+        description: 'Fetch a single product by its UUID. Returns 404 if the product is not in the calling organization.',
+        inputSchema: {
+            type: 'object',
+            properties: { id: { type: 'string', description: 'Product UUID' } },
+            required: ['id'],
+            additionalProperties: false,
+        },
+        annotations: {
+            title: 'Get product',
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: 'haruki_create_product',
+        title: 'Create product',
+        description: 'Create a new product. Requires the products:write scope. Will fail with QUOTA_EXCEEDED if the organization plan limit is reached.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                sku: { type: 'string' },
+                priceTwd: { type: 'number' },
+                priceJpy: { type: 'number' },
+                description: { type: 'string' },
+                category: { type: 'string' },
+                status: { type: 'string' },
+                initialStock: { type: 'integer' },
+                releaseDate: { type: 'string' },
+                ipId: { type: 'string' },
+                locationId: { type: 'string' },
+            },
+            required: ['name', 'sku'],
+            additionalProperties: false,
+        },
+        annotations: {
+            title: 'Create product',
+            readOnlyHint: false,
+            destructiveHint: false, // 新建不算破壞性
+            openWorldHint: true,
+        },
+    },
+    {
+        name: 'haruki_list_registrations',
+        title: 'List registrations (orders)',
+        description: 'List orders (registrations) for the connected store. Filter by status or buyer.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                page: { type: 'integer', minimum: 1, default: 1 },
+                limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+                status: { type: 'string' },
+                buyerId: { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            title: 'List registrations',
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: 'haruki_list_buyers',
+        title: 'List buyers',
+        description: 'List buyers in the connected store. Search matches across name / phone / email.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                page: { type: 'integer', minimum: 1, default: 1 },
+                limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+                search: { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            title: 'List buyers',
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: 'haruki_list_shippings',
+        title: 'List shipments',
+        description: 'List shipments. Filter by status if provided.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                page: { type: 'integer', minimum: 1, default: 1 },
+                limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+                status: { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            title: 'List shipments',
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: 'haruki_search',
+        title: 'Global search',
+        description: 'Search across products, buyers and registrations. Pass type to narrow the scope.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: { type: 'string' },
+                type: { type: 'string', enum: ['products', 'buyers', 'registrations'] },
+            },
+            required: ['q'],
+            additionalProperties: false,
+        },
+        annotations: {
+            title: 'Global search',
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+];
+const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({ ...t })),
+}));
+/**
+ * MCP best practice: API failures must not throw at the protocol layer.
+ * Per spec, tool errors return content + isError: true so the LLM can
+ * see and react to them, rather than treat them as a server crash.
+ */
+function toMcpResult(result) {
+    const r = result;
+    const isError = r && typeof r === 'object' && 'success' in r && r.success === false;
+    const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+    return {
+        content: [{ type: 'text', text }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const a = (args ?? {});
+    try {
+        let result;
+        switch (name) {
+            case 'haruki_me':
+                result = await client.me();
+                break;
+            case 'haruki_list_products':
+                result = await client.listProducts(a);
+                break;
+            case 'haruki_get_product':
+                if (typeof a.id !== 'string') {
+                    return toMcpResult({ success: false, message: 'id is required (string)' });
+                }
+                result = await client.getProduct(a.id);
+                break;
+            case 'haruki_create_product':
+                result = await client.createProduct(a);
+                break;
+            case 'haruki_list_registrations':
+                result = await client.listRegistrations(a);
+                break;
+            case 'haruki_list_buyers':
+                result = await client.listBuyers(a);
+                break;
+            case 'haruki_list_shippings':
+                result = await client.listShippings(a);
+                break;
+            case 'haruki_search':
+                if (typeof a.q !== 'string') {
+                    return toMcpResult({ success: false, message: 'q is required (string)' });
+                }
+                result = await client.search(a.q, a.type);
+                break;
+            default:
+                return toMcpResult({ success: false, message: `Unknown tool: ${name}` });
+        }
+        return toMcpResult(result);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return toMcpResult({ success: false, message: `MCP runtime error: ${msg}` });
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[harukibox-mcp] connected, baseUrl=${baseUrl}`);
+}
+main().catch((err) => {
+    console.error('[harukibox-mcp] fatal:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@harukibox/mcp",
+  "version": "0.1.1",
+  "private": false,
+  "description": "Model Context Protocol server for harukibox — let your AI agent manage your inventory, orders, buyers and shipments through the official harukibox API.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "harukibox-mcp": "./bin/harukibox-mcp.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "start": "node ./bin/harukibox-mcp.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://harukibox.com/agent-api",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cosmopig/haruki"
+  }
+}