@harukibox/mcp 0.1.1 → 0.2.0

package/README.md

@@ -2,6 +2,18 @@
 
 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.
 
+## 協定版本
+
+實作 **MCP 2026-07-28**（stateless、`server/discover`、`resultType`、cacheable
+`tools/list`），同時維持 **dual-era**：舊版的 `initialize` handshake 照樣回應。
+
+也就是說現在的 Claude Desktop / Claude Code（仍在 2025-11-25 以前）**不用改任何設定
+就能繼續用**；等 client 升級到 2026-07-28 後會自動走新路徑，一樣不用改設定。
+
+> `@modelcontextprotocol/sdk` 最新的 1.30.0 仍停在 `2025-11-25`，沒有
+> `server/discover` / `resultType` / `CacheableResult`，所以本 server 直接輸出 wire
+> format 而不透過 SDK（也因此本套件零 runtime 相依）。SDK 支援新版後會換回去。
+
 ## 安裝
 
 ```bash

package/bin/harukibox-mcp.js

@@ -2,6 +2,6 @@
 // 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?');
+    console.error('[harukibox-mcp] did you run `npm run build` inside packages/mcp?');
     process.exit(1);
 });

package/dist/index.js

@@ -1,20 +1,45 @@
 #!/usr/bin/env node
 /**
- * harukibox MCP server.
+ * harukibox MCP server (stdio transport).
  *
  * Connect this server to Claude Desktop, Claude Code or any MCP-compatible
  * client. It exposes the harukibox Agent API as MCP tools.
  *
+ * Protocol: **dual-era**.
+ *   - Modern (2026-07-28): stateless. No `initialize`; every request carries
+ *     its protocol version and client capabilities in `_meta`. Implements the
+ *     mandatory `server/discover` RPC. Every result carries `resultType`.
+ *   - Legacy (2025-11-25 and earlier): the `initialize` handshake still works,
+ *     so today's clients — none of which speak 2026-07-28 yet — keep working
+ *     unchanged.
+ *
  * 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 { createInterface } from 'node:readline';
 import { HarukiAgentClient } from './api-client.js';
+import { findTool, TOOLS, toolDescriptor } from './tools.js';
+import { buildCacheableResult, buildResult, getClientInfo, getDeclaredProtocolVersion, INTERNAL_ERROR, INVALID_REQUEST, LATEST_PROTOCOL_VERSION, METHOD_NOT_FOUND, negotiateLegacyVersion, PARSE_ERROR, resolveEra, SUPPORTED_PROTOCOL_VERSIONS, UNSUPPORTED_PROTOCOL_VERSION, unsupportedVersionData, } from './protocol.js';
 const SERVER_NAME = 'harukibox';
-const SERVER_VERSION = '0.1.1';
+const SERVER_VERSION = '0.2.0';
+const SERVER_IDENTITY = { name: SERVER_NAME, version: SERVER_VERSION };
+/**
+ * Natural-language guidance surfaced by `server/discover`. Clients may feed it
+ * to the model, so it covers what tool descriptions can't: call order and the
+ * multi-tenant caveat.
+ */
+const INSTRUCTIONS = [
+    'harukibox is a Japan-import (代購) inventory system: products, orders (registrations), buyers and shipments.',
+    'Call haruki_me first to confirm which store/organization the token is bound to before acting on data.',
+    'All tools operate only within that one organization; ids from another store return 404.',
+    'List endpoints are paginated — limit is capped at 100.',
+].join(' ');
+/**
+ * How long a client may cache `tools/list` / `server/discover`. The tool list
+ * is static per release, so an hour is safe and keeps prompt caches warm.
+ */
+const LIST_TTL_MS = 3_600_000;
 function getEnv(name, fallback) {
     const v = process.env[name];
     if (v && v.length > 0)
@@ -47,247 +72,238 @@ const client = new HarukiAgentClient({
     baseUrl,
     userAgent: `${SERVER_NAME}-mcp/${SERVER_VERSION}`,
 });
+/* ------------------------------------------------------------------ state */
 /**
- * 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).
+ * Set once a client sends `initialize`. Per spec, that request selects legacy
+ * semantics for the lifetime of the stdio process.
  */
-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 })),
-}));
+let legacyLatched = false;
+/**
+ * Requests cancelled via `notifications/cancelled`. The spec requires we send
+ * no further messages for them, so the response is dropped when the handler
+ * eventually resolves. (The in-flight HTTP call itself still runs to
+ * completion — our tools are short single requests, so there is nothing worth
+ * tearing down mid-flight.)
+ */
+const cancelled = new Set();
+/**
+ * Requests currently being handled.
+ *
+ * The spec says to exit promptly once stdin closes, but exiting the instant we
+ * see EOF would drop replies for anything still in flight — a client that
+ * writes a batch of requests and immediately closes stdin would silently lose
+ * every answer. So EOF starts a drain instead of an immediate exit.
+ */
+const inFlight = new Set();
+let stdinClosed = false;
+/** How long to keep draining after EOF before giving up on stragglers. */
+const DRAIN_TIMEOUT_MS = 35_000;
+function maybeExit() {
+    if (stdinClosed && inFlight.size === 0)
+        process.exit(0);
+}
+/* ------------------------------------------------------------- transport */
+function writeMessage(msg) {
+    // stdout carries MCP messages only, one per line, no embedded newlines.
+    process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+function sendResult(id, result) {
+    if (id !== null && cancelled.has(String(id))) {
+        cancelled.delete(String(id));
+        return;
+    }
+    writeMessage({ jsonrpc: '2.0', id, result });
+}
+function sendError(id, code, message, data) {
+    if (id !== null && cancelled.has(String(id))) {
+        cancelled.delete(String(id));
+        return;
+    }
+    writeMessage({
+        jsonrpc: '2.0',
+        id,
+        error: data === undefined ? { code, message } : { code, message, data },
+    });
+}
+/* -------------------------------------------------------------- handlers */
+/** `tools/call` — API failures come back as `isError` results, not RPC errors. */
+async function callTool(era, params) {
+    const name = typeof params.name === 'string' ? params.name : '';
+    const tool = findTool(name);
+    if (!tool) {
+        return toolResult(era, { success: false, message: `Unknown tool: ${name || '(empty)'}` });
+    }
+    const args = params.arguments && typeof params.arguments === 'object'
+        ? params.arguments
+        : {};
+    try {
+        return toolResult(era, await tool.call(client, args));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return toolResult(era, { success: false, message: `MCP runtime error: ${msg}` });
+    }
+}
 /**
- * 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.
+ * MCP requires tool-level failures to surface as `content` + `isError: true`
+ * rather than a JSON-RPC error, so the model can see and react to them instead
+ * of treating the call as a transport crash.
  */
-function toMcpResult(result) {
+function toolResult(era, result) {
     const r = result;
-    const isError = r && typeof r === 'object' && 'success' in r && r.success === false;
+    const isError = Boolean(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 } : {}),
-    };
+    return buildResult(era, { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) }, SERVER_IDENTITY);
 }
-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;
+function listToolsResult(era) {
+    return buildCacheableResult(era, { tools: TOOLS.map(toolDescriptor) }, SERVER_IDENTITY, LIST_TTL_MS, 
+    // The tool list is identical for every token — no user data in it.
+    'public');
+}
+function discoverResult() {
+    return buildCacheableResult('modern', {
+        supportedVersions: SUPPORTED_PROTOCOL_VERSIONS,
+        capabilities: { tools: { listChanged: false } },
+        instructions: INSTRUCTIONS,
+    }, SERVER_IDENTITY, LIST_TTL_MS, 'public');
+}
+/** Route one request. Returns nothing; responses are written as a side effect. */
+async function handleRequest(req) {
+    const id = req.id ?? null;
+    const era = resolveEra(req, legacyLatched);
+    const params = (req.params ?? {});
+    if (era === 'modern') {
+        // Stateless: validate the declared version on every single request.
+        // `server/discover` is exempt — it is precisely the RPC a client uses
+        // to find out which versions we accept.
+        const declared = getDeclaredProtocolVersion(req);
+        if (req.method !== 'server/discover' && declared !== LATEST_PROTOCOL_VERSION) {
+            // `supported` lists only the modern revision: retrying a legacy
+            // version in modern shape would just fail again. Legacy versions
+            // are reachable through `initialize`, and are advertised by
+            // `server/discover`.
+            sendError(id, UNSUPPORTED_PROTOCOL_VERSION, 'Unsupported protocol version', unsupportedVersionData(declared, [LATEST_PROTOCOL_VERSION]));
+            return;
+        }
+        switch (req.method) {
+            case 'server/discover':
+                sendResult(id, discoverResult());
+                return;
+            case 'tools/list':
+                sendResult(id, listToolsResult(era));
+                return;
+            case 'tools/call':
+                sendResult(id, await callTool(era, params));
+                return;
             default:
-                return toMcpResult({ success: false, message: `Unknown tool: ${name}` });
+                // `initialize`, `ping` and `logging/setLevel` no longer exist in
+                // the modern era; they fall through to method-not-found.
+                sendError(id, METHOD_NOT_FOUND, `Method not found: ${req.method}`);
+                return;
         }
-        return toMcpResult(result);
     }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return toMcpResult({ success: false, message: `MCP runtime error: ${msg}` });
+    switch (req.method) {
+        case 'initialize': {
+            legacyLatched = true;
+            const requested = params.protocolVersion;
+            const negotiated = negotiateLegacyVersion(requested);
+            const info = getClientInfo(req);
+            console.error(`[harukibox-mcp] legacy initialize (client=${info ? `${info.name}/${info.version}` : 'unknown'}, ` +
+                `requested=${String(requested ?? 'none')}, negotiated=${negotiated})`);
+            sendResult(id, {
+                protocolVersion: negotiated,
+                serverInfo: SERVER_IDENTITY,
+                capabilities: { tools: { listChanged: false } },
+                instructions: INSTRUCTIONS,
+            });
+            return;
+        }
+        case 'ping':
+            sendResult(id, {});
+            return;
+        case 'tools/list':
+            sendResult(id, listToolsResult('legacy'));
+            return;
+        case 'tools/call':
+            sendResult(id, await callTool('legacy', params));
+            return;
+        case 'server/discover':
+            // Unreachable — resolveEra always routes discover to the modern
+            // branch — but kept explicit so the intent survives refactoring.
+            sendResult(id, discoverResult());
+            return;
+        default:
+            sendError(id, METHOD_NOT_FOUND, `Method not found: ${req.method}`);
+            return;
     }
-});
-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);
-});
+/** Notifications carry no id and MUST NOT be answered. */
+function handleNotification(req) {
+    switch (req.method) {
+        case 'notifications/initialized':
+            legacyLatched = true;
+            return;
+        case 'notifications/cancelled': {
+            const target = req.params?.requestId;
+            if (typeof target === 'string' || typeof target === 'number') {
+                cancelled.add(String(target));
+            }
+            return;
+        }
+        default:
+            // Unknown notifications are ignored, per JSON-RPC.
+            return;
+    }
+}
+function handleLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return;
+    let msg;
+    try {
+        msg = JSON.parse(trimmed);
+    }
+    catch {
+        sendError(null, PARSE_ERROR, 'Parse error: line is not valid JSON');
+        return;
+    }
+    if (!msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+        sendError(msg?.id ?? null, INVALID_REQUEST, 'Invalid Request');
+        return;
+    }
+    // No `id` → notification.
+    if (msg.id === undefined || msg.id === null) {
+        handleNotification(msg);
+        return;
+    }
+    const task = handleRequest(msg)
+        .catch((err) => {
+        const detail = err instanceof Error ? err.message : String(err);
+        console.error('[harukibox-mcp] handler failed:', err);
+        sendError(msg.id ?? null, INTERNAL_ERROR, `Internal error: ${detail}`);
+    })
+        .finally(() => {
+        inFlight.delete(task);
+        maybeExit();
+    });
+    inFlight.add(task);
+}
+function main() {
+    const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    rl.on('line', handleLine);
+    // Closing stdin is the portable graceful-shutdown signal. Drain whatever is
+    // still in flight first so no reply is lost, then exit.
+    rl.on('close', () => {
+        stdinClosed = true;
+        maybeExit();
+        if (inFlight.size > 0) {
+            setTimeout(() => {
+                console.error(`[harukibox-mcp] drain timed out with ${inFlight.size} request(s) outstanding; exiting`);
+                process.exit(0);
+            }, DRAIN_TIMEOUT_MS).unref();
+        }
+    });
+    console.error(`[harukibox-mcp] ready — protocol ${LATEST_PROTOCOL_VERSION} ` +
+        `(legacy fallback: ${SUPPORTED_PROTOCOL_VERSIONS.slice(1).join(', ')}), baseUrl=${baseUrl}`);
+}
+main();

package/dist/protocol.js

@@ -0,0 +1,129 @@
+/**
+ * MCP protocol constants and helpers shared by the stdio server.
+ *
+ * Targets revision **2026-07-28** while remaining dual-era: the same process
+ * still answers the `initialize` handshake used by 2025-11-25 and earlier.
+ *
+ * Why hand-rolled instead of @modelcontextprotocol/sdk: as of SDK 1.30.0 the
+ * TypeScript SDK's LATEST_PROTOCOL_VERSION is still '2025-11-25' and it has no
+ * `server/discover`, no `resultType` and no `CacheableResult`. There is no way
+ * to emit a 2026-07-28-shaped response through it, so the wire format is
+ * produced directly here. Swap back to the SDK once it ships the new revision.
+ *
+ * Spec: https://modelcontextprotocol.io/specification/2026-07-28
+ */
+/** The modern (stateless, per-request metadata) revision this server speaks. */
+export const LATEST_PROTOCOL_VERSION = '2026-07-28';
+/**
+ * Legacy revisions still answered through the `initialize` handshake.
+ * Ordered newest-first — the first entry is what we negotiate down to when a
+ * legacy client asks for something we don't recognise.
+ */
+export const LEGACY_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26'];
+/** Everything this server can speak, newest first. Advertised by server/discover. */
+export const SUPPORTED_PROTOCOL_VERSIONS = [
+    LATEST_PROTOCOL_VERSION,
+    ...LEGACY_PROTOCOL_VERSIONS,
+];
+/* ------------------------------------------------------------------ _meta */
+export const META_PROTOCOL_VERSION = 'io.modelcontextprotocol/protocolVersion';
+export const META_CLIENT_INFO = 'io.modelcontextprotocol/clientInfo';
+export const META_CLIENT_CAPABILITIES = 'io.modelcontextprotocol/clientCapabilities';
+export const META_SERVER_INFO = 'io.modelcontextprotocol/serverInfo';
+/* ---------------------------------------------------------------- errors */
+/** JSON-RPC standard codes. */
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+/**
+ * MCP-allocated codes (2026-07-28 reserves -32020..-32099 for the spec;
+ * -32000..-32019 stays implementation-defined).
+ */
+export const HEADER_MISMATCH = -32020;
+export const MISSING_REQUIRED_CLIENT_CAPABILITY = -32021;
+export const UNSUPPORTED_PROTOCOL_VERSION = -32022;
+/* --------------------------------------------------------------- helpers */
+/** Read the request's `_meta` object, if any. */
+export function getRequestMeta(req) {
+    const meta = req.params?._meta;
+    return meta && typeof meta === 'object' ? meta : {};
+}
+/** The protocol version declared in `_meta`, or undefined for legacy requests. */
+export function getDeclaredProtocolVersion(req) {
+    const v = getRequestMeta(req)[META_PROTOCOL_VERSION];
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/** Self-reported client identity. Display/logging only — never a security input. */
+export function getClientInfo(req) {
+    const v = getRequestMeta(req)[META_CLIENT_INFO];
+    if (!v || typeof v !== 'object')
+        return undefined;
+    const o = v;
+    if (typeof o.name !== 'string' || typeof o.version !== 'string')
+        return undefined;
+    return { name: o.name, version: o.version };
+}
+/**
+ * Decide which era a request belongs to.
+ *
+ * Per spec §Versioning, a dual-era server picks behaviour from how the client
+ * opens: a request carrying modern `_meta` is served statelessly, while an
+ * `initialize` request selects legacy semantics for the rest of the process.
+ *
+ * `server/discover` is modern-only — it is also the documented stdio probe a
+ * dual-era *client* uses to detect our era, so it must always answer modern
+ * even when the client sent no `_meta` at all.
+ */
+export function resolveEra(req, legacyLatched) {
+    if (req.method === 'server/discover')
+        return 'modern';
+    if (getDeclaredProtocolVersion(req) !== undefined)
+        return 'modern';
+    if (legacyLatched)
+        return 'legacy';
+    // No `_meta`, no prior `initialize`: an older client that skipped the
+    // handshake. Serving it legacy-shaped is the lenient, compatible choice.
+    return 'legacy';
+}
+/** Negotiate a legacy `initialize`: echo the client's version if we know it. */
+export function negotiateLegacyVersion(requested) {
+    if (typeof requested === 'string' && LEGACY_PROTOCOL_VERSIONS.includes(requested)) {
+        return requested;
+    }
+    return LEGACY_PROTOCOL_VERSIONS[0];
+}
+/**
+ * Wrap a result payload for the wire.
+ *
+ * Modern results MUST carry `resultType` and SHOULD carry `serverInfo` in
+ * `_meta`. Legacy results must carry neither — older clients validate against
+ * their own schema, where those fields are unknown.
+ */
+export function buildResult(era, payload, server) {
+    if (era === 'legacy')
+        return payload;
+    return {
+        ...payload,
+        resultType: 'complete',
+        _meta: { [META_SERVER_INFO]: { name: server.name, version: server.version } },
+    };
+}
+/**
+ * Wrap a list-style result, which in 2026-07-28 additionally MUST carry the
+ * `CacheableResult` fields.
+ *
+ * @param ttlMs      how long the client may cache this, in ms.
+ * @param cacheScope 'public' when the payload holds no user-specific data and
+ *                   shared intermediaries may reuse it across auth contexts.
+ */
+export function buildCacheableResult(era, payload, server, ttlMs, cacheScope) {
+    if (era === 'legacy')
+        return payload;
+    return { ...buildResult(era, payload, server), ttlMs, cacheScope };
+}
+/** `UnsupportedProtocolVersionError` data payload (-32022). */
+export function unsupportedVersionData(requested, supported) {
+    return { supported, requested: requested ?? null };
+}

package/dist/tools.js

@@ -0,0 +1,172 @@
+/**
+ * harukibox MCP tool definitions.
+ *
+ * Kept deliberately in the same order as the array literal: 2026-07-28 asks
+ * servers to return `tools/list` in a deterministic order so clients can cache
+ * the list and LLM prompt caches keep hitting.
+ *
+ * Annotations follow the spec's `ToolAnnotations`:
+ *   - readOnlyHint    — no observable state mutation.
+ *   - destructiveHint — can permanently change data the user cares about.
+ *   - openWorldHint   — reaches beyond the local process (our HTTP API).
+ */
+function requireString(args, key) {
+    const v = args[key];
+    if (typeof v !== 'string' || v.length === 0)
+        return { error: `${key} is required (non-empty string)` };
+    return v;
+}
+export 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 },
+        call: (client) => client.me(),
+    },
+    {
+        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 },
+        call: (client, a) => client.listProducts(a),
+    },
+    {
+        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 },
+        call: async (client, a) => {
+            const id = requireString(a, 'id');
+            if (typeof id !== 'string')
+                return { success: false, message: id.error };
+            return client.getProduct(id);
+        },
+    },
+    {
+        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,
+        },
+        // Creating is a write but not destructive — nothing existing is lost.
+        annotations: { title: 'Create product', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+        call: (client, a) => client.createProduct(a),
+    },
+    {
+        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 },
+        call: (client, a) => client.listRegistrations(a),
+    },
+    {
+        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 },
+        call: (client, a) => client.listBuyers(a),
+    },
+    {
+        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 },
+        call: (client, a) => client.listShippings(a),
+    },
+    {
+        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 },
+        call: async (client, a) => {
+            const q = requireString(a, 'q');
+            if (typeof q !== 'string')
+                return { success: false, message: q.error };
+            return client.search(q, a.type);
+        },
+    },
+];
+export function findTool(name) {
+    return TOOLS.find((t) => t.name === name);
+}
+/** The wire shape of a tool, as returned by `tools/list`. */
+export function toolDescriptor(t) {
+    return {
+        name: t.name,
+        title: t.title,
+        description: t.description,
+        inputSchema: t.inputSchema,
+        annotations: t.annotations,
+    };
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@harukibox/mcp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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.",
+  "description": "Model Context Protocol server for harukibox (MCP 2026-07-28, dual-era) — let your AI agent manage your inventory, orders, buyers and shipments through the official harukibox API.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -18,9 +18,6 @@
     "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"
@@ -28,9 +25,14 @@
   "engines": {
     "node": ">=18"
   },
-  "homepage": "https://harukibox.com/agent-api",
+  "homepage": "https://github.com/cosmopig/harukibox-agent#readme",
+  "bugs": {
+    "url": "https://github.com/cosmopig/harukibox-agent/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/cosmopig/haruki"
-  }
+    "url": "https://github.com/cosmopig/harukibox-agent.git",
+    "directory": "packages/mcp"
+  },
+  "keywords": ["harukibox", "mcp", "model-context-protocol", "mcp-2026-07-28", "claude", "agent", "japan-import", "代購"]
 }