@harrylabsj/kiwi 0.8.0 → 0.10.0

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>;