@harrylabsj/kiwi 0.7.22 → 0.9.0

package/dist/mcp/merchant-auth.js

@@ -0,0 +1,146 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Merchant MCP Server 入站认证（WorkBuddy Buddy 应用开发计划 阶段二）。
+ *
+ * 兼容「用户自填 Token」模式：静态 Bearer token，恒定时间比较。
+ * 正式 WorkBuddy 连接器使用 OAuth；此校验器保留给显式 token 过渡包。
+ * 校验器接口（MerchantMcpAuthVerifier）让两种方案共用 server 传输层。
+ *
+ * Token 来源与 A2A 一致的安全惯例：profile 只存环境变量名
+ * （merchant_mcp.token_env，缺省 KIWI_MERCHANT_MCP_TOKEN），secret 值绝不写
+ * profile / 日志 / 返回值。
+ *
+ * fail-closed（对齐 A2A 公网广告形态的守卫语义）：
+ *   - 监听非 loopback 地址且未配置校验器 → 拒绝启动；
+ *   - loopback 监听且未配置校验器 → 允许启动，但返回警告文案（调用方打 stderr）。
+ */
+import { timingSafeEqual } from "node:crypto";
+import { matchesPairedCredential } from "../auth/merchant-pairing.js";
+import { isLoopbackHost } from "../a2a/client/url-policy.js";
+/** 缺省 token 环境变量名（profile merchant_mcp.token_env 可覆盖）。 */
+export const DEFAULT_MERCHANT_MCP_TOKEN_ENV = "KIWI_MERCHANT_MCP_TOKEN";
+/** 常量时间 token 比较：长度恒等预检 + timingSafeEqual（与
+ *  a2a/server/auth.ts tokenEquals、agent/memory/vault.ts fingerprintEquals
+ *  同一模式——逐字节短路会构成时序侧信道）。 */
+function bearerTokenEquals(presented, expected) {
+    const a = Buffer.from(presented, "utf8");
+    const b = Buffer.from(expected, "utf8");
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** 静态 Bearer token 校验（`Authorization: Bearer <token>`）。 */
+export class StaticBearerTokenVerifier {
+    name = "static-bearer";
+    token;
+    constructor(token) {
+        if (token.length === 0) {
+            throw new Error("StaticBearerTokenVerifier requires a non-empty token");
+        }
+        this.token = token;
+    }
+    verify(ctx) {
+        const header = ctx.authorizationHeader;
+        if (header === undefined || header === "") {
+            return { ok: false, reason: "missing Authorization header" };
+        }
+        const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+        if (match === null) {
+            return { ok: false, reason: "Authorization header is not a bearer token" };
+        }
+        if (!bearerTokenEquals(match[1] ?? "", this.token)) {
+            return { ok: false, reason: "invalid bearer token" };
+        }
+        return { ok: true };
+    }
+}
+/**
+ * 配对凭据校验器（设计 §8.4 第二期，最小授权）：接受由**本实例**签发、
+ * 网关持有的那份凭据（`paired-credential.json`，只存摘要，逐请求恒定时间比较）。
+ * 与静态令牌并存——静态令牌是运维自己的入口，配对凭据是可随时轮换的那份。
+ */
+export class PairedCredentialVerifier {
+    dir;
+    name = "paired-credential";
+    constructor(dir) {
+        this.dir = dir;
+    }
+    verify(ctx) {
+        const header = ctx.authorizationHeader;
+        if (header === undefined || header === "") {
+            return { ok: false, reason: "missing Authorization header" };
+        }
+        const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+        if (match === null) {
+            return { ok: false, reason: "Authorization header is not a bearer token" };
+        }
+        if (!matchesPairedCredential(this.dir, match[1] ?? "")) {
+            return { ok: false, reason: "invalid paired credential" };
+        }
+        // 与静态令牌同语义：不带 scope（undefined = 全量），工具级门禁由网关侧
+        // 按**用户 OAuth 令牌**的 scope 逐次执行（mcp-proxy），实例不重复判定。
+        return { ok: true };
+    }
+}
+/**
+ * 组合校验器：任一子校验器通过即通过（静态令牌 + 配对凭据并存）。
+ * 全部失败时返回最后一个原因，不回显任何凭据内容。
+ */
+export class CompositeMerchantMcpVerifier {
+    verifiers;
+    name = "composite";
+    constructor(verifiers) {
+        this.verifiers = verifiers;
+    }
+    verify(ctx) {
+        let last = { ok: false, reason: "no verifier configured" };
+        for (const verifier of this.verifiers) {
+            const result = verifier.verify(ctx);
+            if (result.ok)
+                return result;
+            last = result;
+        }
+        return last;
+    }
+}
+/**
+ * 从环境变量解析 Bearer 校验器。tokenEnv 缺省 DEFAULT_MERCHANT_MCP_TOKEN_ENV；
+ * 环境变量未设置或为空 → undefined（由 fail-closed 判定决定是否允许启动）。
+ */
+export function resolveMerchantMcpVerifier(tokenEnv, env = process.env) {
+    const envName = tokenEnv ?? DEFAULT_MERCHANT_MCP_TOKEN_ENV;
+    const token = (env[envName] ?? "").trim();
+    if (token === "")
+        return undefined;
+    return new StaticBearerTokenVerifier(token);
+}
+/**
+ * 启动前 fail-closed 判定。
+ * - 非 loopback host + 无校验器 → 抛错（拒绝启动）；
+ * - loopback host + 无校验器 → 返回警告文案（允许启动，调用方打 stderr）；
+ * - 有校验器 → undefined（无警告）。
+ */
+export function assertMerchantMcpAuthPolicy(host, verifier) {
+    if (verifier !== undefined)
+        return undefined;
+    if (!isLoopbackHost(host)) {
+        throw new Error(`merchant MCP server 监听非 loopback 地址（${host}）但未配置认证 token，` +
+            `fail-closed 拒绝启动：请设置 ${DEFAULT_MERCHANT_MCP_TOKEN_ENV} 环境变量` +
+            "（或 profile merchant_mcp.token_env 指向的环境变量），或改用 127.0.0.1 监听。");
+    }
+    return (`⚠️ [kiwi] merchant MCP server 未配置认证 token（${DEFAULT_MERCHANT_MCP_TOKEN_ENV}），` +
+        `仅接受 ${host} 上的本地连接；公网暴露前务必配置 Bearer token。`);
+}
+//# sourceMappingURL=merchant-auth.js.map

package/dist/mcp/merchant-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merchant-auth.js","sourceRoot":"","sources":["../../src/mcp/merchant-auth.ts"],"names":[],"mappings":"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"}

package/dist/mcp/merchant-dirs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** 无状态传输的固定会话标识（仅观测用；绝不参与路径派生）。 */
+export declare const STATELESS_TRANSPORT_SESSION_ID = "stateless";
+export interface MerchantMcpRuntimeDirs {
+    merchantDataDir: string;
+    principalDataDir: string;
+    transportSessionId: string;
+}
+export declare function resolveMerchantMcpDirs(options: {
+    dataDir?: string;
+    agentId: string;
+}): MerchantMcpRuntimeDirs;

package/dist/mcp/merchant-dirs.js

@@ -0,0 +1,44 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Merchant MCP 运行时的数据目录接线（V2 §5.1）。
+ *
+ * 显式三个槽位分别注入，互不派生：
+ *   - merchantDataDir   商家维度数据（a2a ledger、stats、oauth.sqlite）——
+ *                       同一商家的多个传输会话共享同一目录；
+ *   - principalDataDir  principal 维度数据（审批候选 state.sqlite 等）——
+ *                       当前与 merchantDataDir 同址（单商家实例唯一 principal），
+ *                       槽位分离是为多 principal 演进留的机械拆分点；
+ *   - transportSessionId 传输会话标识（无状态 streamableHttp 固定 "stateless"）——
+ *                       只是观测标签，绝不参与数据目录派生（修掉「HTTP adapter
+ *                       按 sessionId 建 dataDir」的接线形态：会话不得影响持久路径）。
+ *
+ * 不变量：路径是 (dataDir?, agentId) 的纯函数——重启后路径稳定；
+ * 任何传输会话的加入/退出都不改变目录。
+ */
+import { agentDataDir } from "../agent/agent-db.js";
+/** 无状态传输的固定会话标识（仅观测用；绝不参与路径派生）。 */
+export const STATELESS_TRANSPORT_SESSION_ID = "stateless";
+export function resolveMerchantMcpDirs(options) {
+    // agentDataDir 经 agentDirName 消毒（防路径逃逸），与 chat kernel 同一缺省。
+    const merchantDataDir = options.dataDir ?? agentDataDir(options.agentId);
+    return {
+        merchantDataDir,
+        principalDataDir: merchantDataDir,
+        transportSessionId: STATELESS_TRANSPORT_SESSION_ID,
+    };
+}
+//# sourceMappingURL=merchant-dirs.js.map

package/dist/mcp/merchant-dirs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merchant-dirs.js","sourceRoot":"","sources":["../../src/mcp/merchant-dirs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,mCAAmC;AACnC,MAAM,CAAC,MAAM,8BAA8B,GAAG,WAAW,CAAC;AAQ1D,MAAM,UAAU,sBAAsB,CAAC,OAGtC;IACC,4DAA4D;IAC5D,MAAM,eAAe,GAAG,OAAO,CAAC,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,OAAO;QACL,eAAe;QACf,gBAAgB,EAAE,eAAe;QACjC,kBAAkB,EAAE,8BAA8B;KACnD,CAAC;AACJ,CAAC"}

package/dist/mcp/merchant-resources.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { PresentationContext } from "../agent/presentation/types.js";
+export declare const MERCHANT_RESOURCE_PREFIX = "kiwi-merchant://presentation/";
+export interface MerchantResourceDef {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: "application/json";
+}
+export interface MerchantResourceContent {
+    uri: string;
+    mimeType: string;
+    text: string;
+}
+/** 等效文本摘要（降级路径；不丢关键字段：数量/金额/状态/时间）。 */
+export declare function textSummary(component: string, payload: unknown): string;
+export declare function buildMerchantPresentationResources(deps: {
+    context: PresentationContext;
+}): {
+    list: () => MerchantResourceDef[];
+    read: (uri: string) => Promise<{
+        contents: MerchantResourceContent[];
+    }>;
+};

package/dist/mcp/merchant-resources.js

@@ -0,0 +1,146 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 七类 merchant presentation 的 MCP Apps 资源映射（V2 阶段二）。
+ *
+ * V1 的 present_* 工具发内部 ui 事件（宿主不渲染等于丢失）；本模块把同一套
+ * PresentationRegistry 组件映射为 MCP 资源：
+ *   kiwi-merchant://presentation/<component>[?参数]
+ *
+ * 每个资源 read 返回两个 content：
+ *   1. application/json — 结构化 payload（经 sanitizePresentationValue 既有脱敏）；
+ *   2. text/plain — 等效文本摘要（宿主不支持 MCP Apps 时的降级，不丢关键字段）。
+ *
+ * 私密类内容（阈值/成本/底价）没有任何对应资源——私密面板走管理面接缝
+ * （merchant-core readPrivateThresholds），不进工具结果与资源。
+ */
+import { createMerchantPresentationRegistry } from "../agent/merchant/merchant-presentations.js";
+import { sanitizePresentationValue } from "../agent/presentation/sanitize.js";
+export const MERCHANT_RESOURCE_PREFIX = "kiwi-merchant://presentation/";
+/** 需要查询参数的资源（缺参数时 read 返回可读错误）。 */
+const REQUIRED_QUERY = {
+    metrics: { param: "metric", hint: "?metric=<指标名>（如 contact_events）" },
+    change_preview: { param: "candidate_id", hint: "?candidate_id=<候选 id>" },
+    suggestions: { param: "items", hint: "?items=<建议1,建议2>（1–4 条，逗号分隔）" },
+};
+/** 等效文本摘要（降级路径；不丢关键字段：数量/金额/状态/时间）。 */
+export function textSummary(component, payload) {
+    const p = (payload ?? {});
+    switch (component) {
+        case "merchant_digest": {
+            const snapshot = (p.snapshot ?? {});
+            const alerts = snapshot.alerts ?? {};
+            return [
+                `${String(p.title ?? "经营摘要")}：进行中磋商 ${alerts.active_negotiations ?? "?"}，` +
+                    `人工待处理 ${alerts.human_reviews ?? "?"}，待审批 ${alerts.pending_actions ?? "?"}，` +
+                    `低库存 ${alerts.low_stock ?? "不可得"}`,
+            ].join("");
+        }
+        case "metrics": {
+            const points = Array.isArray(p.points) ? p.points.length : 0;
+            return `指标 ${String(p.metric ?? "?")}：${points} 个数据点（${String(p.granularity ?? "day")} 粒度）`;
+        }
+        case "catalog": {
+            const products = Array.isArray(p.products) ? p.products.length : 0;
+            const health = (p.health ?? {});
+            return `商品目录：${products} 个商品（总数 ${health.total ?? "?"}，缺货 ${health.out_of_stock ?? "不可得"}）`;
+        }
+        case "negotiations": {
+            const rows = Array.isArray(p) ? p : [];
+            return `磋商列表：${rows.length} 笔`;
+        }
+        case "human_review": {
+            const reviews = Array.isArray(p.reviews) ? p.reviews.length : 0;
+            return `人工处理队列：${reviews} 项`;
+        }
+        case "change_preview": {
+            return `变更预览：${String(p.headline ?? "变更预览")}（candidate ${String(p.candidate_id ?? "?")}；展示不批准不执行）`;
+        }
+        case "suggestions": {
+            const items = Array.isArray(p.suggestions) ? p.suggestions : [];
+            return `下一步建议：${items.join("；")}`;
+        }
+        default:
+            return JSON.stringify(payload);
+    }
+}
+export function buildMerchantPresentationResources(deps) {
+    const registry = createMerchantPresentationRegistry();
+    const defs = registry.list().map((c) => ({
+        uri: `${MERCHANT_RESOURCE_PREFIX}${c.component}`,
+        name: c.component,
+        description: c.description,
+        mimeType: "application/json",
+    }));
+    const read = async (uri) => {
+        if (!uri.startsWith(MERCHANT_RESOURCE_PREFIX)) {
+            throw new Error(`未知资源 ${uri}（前缀 ${MERCHANT_RESOURCE_PREFIX}）`);
+        }
+        const rest = uri.slice(MERCHANT_RESOURCE_PREFIX.length);
+        const qIndex = rest.indexOf("?");
+        const componentName = qIndex === -1 ? rest : rest.slice(0, qIndex);
+        const query = new URLSearchParams(qIndex === -1 ? "" : rest.slice(qIndex + 1));
+        const component = registry.list().find((c) => c.component === componentName);
+        if (component === undefined) {
+            throw new Error(`未知 presentation 资源 ${componentName}`);
+        }
+        // 参数化资源的必填查询参数
+        const required = REQUIRED_QUERY[componentName];
+        let input = {};
+        if (required !== undefined) {
+            const value = query.get(required.param);
+            if (value === null || value === "") {
+                throw new Error(`资源 ${componentName} 需要查询参数 ${required.hint}`);
+            }
+            input =
+                componentName === "suggestions"
+                    ? {
+                        suggestions: value
+                            .split(",")
+                            .map((s) => s.trim())
+                            .filter((s) => s !== ""),
+                    }
+                    : { [required.param]: value };
+        }
+        // 可选通用参数（period/granularity/limit/status/headline/note）
+        for (const key of ["period", "granularity", "status", "headline", "note"]) {
+            const v = query.get(key);
+            if (v !== null)
+                input[key] = v;
+        }
+        const limit = query.get("limit");
+        if (limit !== null && /^\d+$/.test(limit))
+            input.limit = Number(limit);
+        const validated = component.validate(input);
+        const payload = sanitizePresentationValue(await component.enrich(validated, deps.context));
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: "application/json",
+                    text: JSON.stringify(payload),
+                },
+                {
+                    uri,
+                    mimeType: "text/plain",
+                    text: textSummary(componentName, payload),
+                },
+            ],
+        };
+    };
+    return { list: () => defs, read };
+}
+//# sourceMappingURL=merchant-resources.js.map

package/dist/mcp/merchant-resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merchant-resources.js","sourceRoot":"","sources":["../../src/mcp/merchant-resources.ts"],"names":[],"mappings":"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"}

package/dist/mcp/merchant-server.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { MerchantWorkbenchSurface } from "../merchant/workbench-service.js";
+import type { MerchantOAuthServer } from "../auth/merchant-oauth.js";
+import type { MerchantMcpAuthVerifier } from "./merchant-auth.js";
+import { type MerchantMcpCallResult, type MerchantMcpToolDefinition } from "./merchant-tools.js";
+import type { buildMerchantPresentationResources } from "./merchant-resources.js";
+import { type MerchantAdminSurface } from "../merchant-admin/pending-page.js";
+import { type MerchantAdminSessions } from "../auth/merchant-sessions.js";
+import type { MerchantOAuthStore } from "../auth/merchant-oauth.js";
+/** 缺省监听地址（远程连接器形态；fail-closed 由 merchant-auth 守卫）。 */
+export declare const DEFAULT_MERCHANT_MCP_HOST = "0.0.0.0";
+/** 缺省端口（与 A2A 9000 分离）。 */
+export declare const DEFAULT_MERCHANT_MCP_PORT = 9100;
+/** 缺省 MCP endpoint 路径。 */
+export declare const DEFAULT_MERCHANT_MCP_PATH = "/mcp";
+export interface MerchantMcpServerOptions {
+    service: MerchantWorkbenchSurface;
+    host?: string;
+    port?: number;
+    path?: string;
+    /** 入站认证校验器；提供时所有请求必须携带有效 Bearer token。 */
+    auth?: MerchantMcpAuthVerifier;
+    /** OAuth 授权服务器（V2 阶段一）：提供时挂载
+     *  /.well-known/oauth-*、/oauth/register|authorize|token|revoke 端点。 */
+    oauth?: MerchantOAuthServer;
+    /** 七类 presentation 的 MCP 资源（V2 阶段二；提供时挂载 resources/list|read）。 */
+    presentations?: ReturnType<typeof buildMerchantPresentationResources>;
+    /** 配套商家确认页面（V2 阶段三；BUG-01/03 修复后：cookie 会话 + 一次性
+     *  确认凭证；write 面由会话主体逐次校验）。 */
+    admin?: {
+        merchantName: string;
+        surface: MerchantAdminSurface;
+        sessions: MerchantAdminSessions;
+        /** 一次性确认凭证存储（oauth.sqlite）。 */
+        store: MerchantOAuthStore;
+        /** 管理员凭据目录（admin-credentials.json）。 */
+        adminDir: string;
+        /** https 部署置 true（cookie 加 Secure）。 */
+        secureCookies?: boolean;
+    };
+    /**
+     * 一次性配对码兑换（设计 §8.4 第二期）：挂载 `POST /pairing/redeem`。
+     * 商家在实例机器上 `kiwi merchant mcp pair` 生成码，网关用它兑换内部凭据，
+     * 从而无需把长期令牌贴进表单。仅 token 模式（存在静态内部令牌）才有意义。
+     */
+    pairing?: {
+        /**
+         * 配对码与配对凭据所在目录（通常为实例数据目录）。兑换时会**新签**一份
+         * 配对凭据（最小授权：由实例签发并持有，网关只拿到调用凭据；重配对即轮换）。
+         */
+        dir: string;
+        /** 实例身份（回给网关留痕；不含任何凭据）。 */
+        instance: () => {
+            ownerId: string;
+            principalId: string;
+        };
+    };
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+    /** 响应体大小上限（字符）。 */
+    maxChars?: number;
+    /** 单次工具调用超时（ms）。 */
+    requestTimeoutMs?: number;
+}
+export interface MerchantMcpServerHandle {
+    host: string;
+    port: number;
+    path: string;
+    url: string;
+    close: () => Promise<void>;
+}
+/** 带 scope 的 MCP 工具束形状（merchant 工具与商家连接器目录工具共用）。 */
+export interface ScopedMcpTools {
+    /** 允许异步（网关需要先向实例取工具清单）；协议层会 await。 */
+    listTools(scopes: string[] | undefined): MerchantMcpToolDefinition[] | Promise<MerchantMcpToolDefinition[]>;
+    call(name: string, args: Record<string, unknown>, scopes: string[] | undefined): Promise<MerchantMcpCallResult>;
+}
+/** 每个请求独立的协议 Server（无状态模式），handlers 引用共享的工具分发器。
+ *  scopes 来自本次请求的授权上下文（OAuth access_token）；undefined = 静态
+ *  token 过渡模式（全量 scope）。tools/list 按 scope 过滤，tools/call 逐次强制。 */
+export declare function createProtocolServer(serverInfo: {
+    name: string;
+    version: string;
+}, toolsBundle: ScopedMcpTools, scopes: string[] | undefined, presentations?: ReturnType<typeof buildMerchantPresentationResources>): Server;
+/**
+ * 启动 Merchant MCP Server（streamable HTTP，无状态）。
+ * 返回 handle 含实际 host/port（port 传 0 时取 ephemeral 端口）与优雅关闭。
+ */
+export declare function startMerchantMcpServer(options: MerchantMcpServerOptions): Promise<MerchantMcpServerHandle>;