mes-mcp 0.2.3 → 0.3.1

package/.env.example

@@ -3,3 +3,8 @@ MES_API_PREFIX=/api
 MES_AGENT_TOKEN=
 MES_TIMEOUT_MS=30000
 MES_REGISTER_DYNAMIC_TOOLS=false
+# mes_action.list 动作检索模式：
+#   lexical（默认，推荐）= CJK 词元 BM25 + 双语领域词扩展，离线、零额外依赖、确定性；
+#   hybrid / semantic    = 额外融合本地语义向量，需手动安装可选依赖 @huggingface/transformers
+#                          （含原生 onnxruntime，部分受限环境装不上，届时自动退化为 lexical）。
+MES_ACTION_SEARCH=lexical

package/README.md

@@ -75,6 +75,8 @@ npm run dev
 写入类动作通过 `confirm_required` 或 `commit` 执行时需要幂等键。调用方没有显式传入时，`mes-mcp` 会为当前工具调用生成一条集成幂等键；需要跨重试严格复用同一幂等键的批处理场景，仍建议调用方显式传入 `idempotencyKey`。
 
 - `mes_api.read`：按当前 MES 账号权限读取普通业务接口，例如 `/sale-order/list`、`/material/detail`。后端只放行只读类接口，写入动作必须使用动态业务动作；读取调用会在 MES AI 调用日志里记录路径、请求摘要和结果摘要。
+- `mes://agent/context`：MES Agent 通用操作边界、工具顺序和安全规则。
+- `mes://flows/sale-delivery`：销售出库上下文资源，只描述读取顺序和阻断处理；可出库状态、库存和质量判断仍以后端接口返回为准。
 
 写入类工具支持 `executionMode`：
 

package/dist/config.js

@@ -24,6 +24,15 @@ function optionalBooleanEnv(name, fallback) {
         return false;
     throw new Error(`${name} must be a boolean`);
 }
+function actionSearchModeEnv(name, fallback) {
+    const value = process.env[name]?.trim().toLowerCase();
+    if (!value)
+        return fallback;
+    if (value === "lexical" || value === "hybrid" || value === "semantic") {
+        return value;
+    }
+    throw new Error(`${name} must be one of lexical | hybrid | semantic`);
+}
 function decodeBase64UrlJson(segment) {
     try {
         const normalized = segment.replace(/-/g, "+").replace(/_/g, "/");
@@ -86,6 +95,7 @@ export function loadConfig() {
         mesAgentToken,
         timeoutMs,
         registerDynamicTools: optionalBooleanEnv("MES_REGISTER_DYNAMIC_TOOLS", false),
+        actionSearchMode: actionSearchModeEnv("MES_ACTION_SEARCH", "lexical"),
         tokenInfo,
         expectedUsername,
         expectedAgentClientId,

package/dist/discovery/action-search.service.js

@@ -0,0 +1,35 @@
+import { ActionSearchIndex, } from "./action-search.js";
+import { createEmbeddingProvider } from "./embedding-provider.js";
+/**
+ * 包装「全量动作缓存 + 相关性索引」。索引在首次检索时懒构建并缓存。
+ *
+ * `client.listBusinessActions()` 已按当前 AI 凭证 + 账号 RBAC 过滤过（后端动作目录过滤逻辑），
+ * 所以在这份缓存上检索天然遵守权限，不会暴露当前账号无权的动作。
+ */
+export class ActionSearchService {
+    client;
+    mode;
+    indexPromise;
+    constructor(client, mode) {
+        this.client = client;
+        this.mode = mode;
+    }
+    async buildIndex() {
+        const [actions, provider] = await Promise.all([
+            this.client.listBusinessActions(),
+            createEmbeddingProvider(this.mode),
+        ]);
+        return new ActionSearchIndex(actions, provider);
+    }
+    async search(query, options) {
+        if (!this.indexPromise) {
+            this.indexPromise = this.buildIndex().catch((error) => {
+                this.indexPromise = undefined;
+                throw error;
+            });
+        }
+        const index = await this.indexPromise;
+        const results = await index.search(query, options);
+        return { total: index.size, results };
+    }
+}

package/dist/discovery/embedding-provider.js

@@ -0,0 +1,55 @@
+/**
+ * 本地语义向量 provider。
+ *
+ * 使用 `@huggingface/transformers` 的 all-MiniLM-L6-v2（384 维），完全本地运行、离线、
+ * 业务数据不出机器。该依赖在 package.json 中声明为 optionalDependencies：
+ * - 装上了 + 模式为 hybrid/semantic → 启用语义融合；
+ * - 没装（受限运行时）或模式为 lexical → 返回 null，检索退化为纯 CJK 词法 BM25（仍然可用）。
+ *
+ * 这里的「装不上就退化为词法」是检索排序能力的降级（并在 stderr 明示），
+ * 不是用兜底数据掩盖业务错误——词法检索本身是完整可用的检索实现。
+ */
+// 多语言模型，覆盖中文业务意图（MES 动作标题/描述以中文为主）。
+const MODEL_ID = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
+// 用变量 specifier 引入可选依赖，避免 tsc 在未安装时报「找不到模块」。
+const TRANSFORMERS_MODULE = "@huggingface/transformers";
+async function importTransformers() {
+    return (await import(TRANSFORMERS_MODULE));
+}
+class LocalEmbeddingProvider {
+    pipelinePromise = null;
+    async getPipeline() {
+        if (!this.pipelinePromise) {
+            this.pipelinePromise = (async () => {
+                const mod = await importTransformers();
+                return mod.pipeline("feature-extraction", MODEL_ID);
+            })();
+        }
+        return this.pipelinePromise;
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const extractor = await this.getPipeline();
+        const output = await extractor(texts, { pooling: "mean", normalize: true });
+        return output.tolist();
+    }
+}
+/**
+ * 按检索模式创建 provider：
+ * - lexical → 始终返回 null（纯词法）。
+ * - hybrid/semantic → 探测可选向量库是否可用；可用则返回本地 provider，否则 null + 警告。
+ */
+export async function createEmbeddingProvider(mode) {
+    if (mode === "lexical")
+        return null;
+    try {
+        // 探测可选依赖是否安装；未安装时 import 抛错，退化为词法。
+        await importTransformers();
+    }
+    catch {
+        console.error(`[mes-mcp] MES_ACTION_SEARCH=${mode} 需要可选依赖 @huggingface/transformers，未检测到，已退化为词法检索（lexical）。如需语义检索，请在 mes-mcp 安装该依赖后重启。`);
+        return null;
+    }
+    return new LocalEmbeddingProvider();
+}

package/dist/index.js

@@ -27,6 +27,7 @@ function logStartupDiagnostics(config) {
         `[mes-mcp] endpoint=${config.mesBaseUrl}${config.mesApiPrefix}`,
         `[mes-mcp] token username=${config.tokenInfo.username ?? "<unknown>"} apiKeyId=${maskId(config.tokenInfo.apiKeyId)} agentClientId=${config.tokenInfo.agentClientId ?? "<unknown>"} expiresAt=${formatUnixSeconds(config.tokenInfo.expiresAt)}`,
         `[mes-mcp] dynamicTools=${config.registerDynamicTools ? "enabled" : "disabled"} (${config.registerDynamicTools ? "mes.<actionCode> tools will be registered" : "use mes_action.list/detail/execute; set MES_REGISTER_DYNAMIC_TOOLS=true only when the client needs expanded tools"})`,
+        `[mes-mcp] actionSearch=${config.actionSearchMode} (mes_action.list 按相关性检索动作目录；hybrid/semantic 需安装可选依赖 @huggingface/transformers，否则自动退化为 lexical)`,
     ];
     if (config.expectedUsername) {
         lines.push(`[mes-mcp] expected username=${config.expectedUsername}`);
@@ -45,10 +46,11 @@ async function main() {
     const client = new MesAgentApiClient(config);
     const server = new McpServer({
         name: "mes-mcp",
-        version: "0.2.3",
+        version: "0.3.0",
     });
     await registerAllAgentTools(server, client, {
         registerDynamicTools: config.registerDynamicTools,
+        actionSearchMode: config.actionSearchMode,
     });
     registerMesResources(server, client);
     registerMesPrompts(server);

package/dist/prompts/register-prompts.js

@@ -15,10 +15,12 @@ export function registerMesPrompts(server) {
                     text: [
                         "你是 MES 业务助手，必须按当前账号权限和工具返回结果执行。",
                         "不要猜测客户、物料、BOM、工艺路线、仓库等关键主数据；缺失时先查询或要求用户确认。",
-                        "默认先用 mes_action.list 或 mes://agent/actions 发现当前账号能做的页面业务动作，再用 mes_action.detail 查看字段，最后用 mes_action.execute 执行；不要依赖工具列表里必须存在 mes.<动作编码>。",
+                        "动作目录有数百个动作。发现动作时用 mes_action.list，把你当前要做的事用一句自然语言意图传给 keyword（例如「销售单转生产计划」「采购入库」「报工」），它返回按相关性排序的 top-K 动作；再用 mes_action.detail 查看字段，最后用 mes_action.execute 执行。不要不带意图地翻页或猜路径，也不要依赖工具列表里必须存在 mes.<动作编码>。",
                         "mes_action.execute 返回的是执行信封，真实业务返回在 data 字段；confirm_required 产生的 invocationId 必须由同一公司/租户下有权限的账号审批。",
                         "mes_api.read 只用于普通业务只读接口，pageSize 最大 100；如果返回 _mcpWarnings 或提示需要动态动作，请按提示调整。",
-                        "销售到出库的流程也走动态动作：先查客户和物料，再创建销售单、处理审批、确认销售单、转生产计划、排产或生成工单、报工、质检、发货出库。",
+                        "销售到出库的流程也走动态动作：先查客户和物料，再创建销售单、处理审批、确认销售单、转生产计划、排产或生成工单、报工、质检、生产入库/库存确认、发货出库。",
+                        "涉及销售出库时先读取 `mes://flows/sale-delivery`。不要从工单状态或销售订单状态自行推断可出库；必须先查询后端销售订单行、剩余可出库数量、目标仓库存证据和相关入库事实。有 blockers 时停止写入并向用户说明原因。",
+                        "库存盘点差异优先使用 stock.stock_count.create/update/start/submit/approve 盘点单流程；stock.batch_adjust 只适合非批次物料的简化批量差异调整，批次追踪物料请使用 stock.adjust 并指定 batchNo。",
                         "写入类动作默认先使用 confirm_required 或 preview；preview 不写入，confirm_required 生成待确认记录，commit 只有凭证允许时才真实提交。",
                         context ? `当前上下文：${context}` : "",
                     ]

package/dist/resources/register-resources.js

@@ -57,6 +57,20 @@ export function registerMesResources(server, client) {
                     "- MES 分页 `pageSize` 最大为 100；MCP 会裁剪超限值，并通过 `_mcpWarnings` 返回提示。",
                     "- 如果只读路径被提示需要动态业务动作，请改用 `mes_action.list/detail/execute` 查找并调用对应 actionCode。",
                     "",
+                    "## 库存盘点和调整",
+                    "",
+                    "- 正式库存盘点差异优先走 `stock.stock_count.create` -> `stock.stock_count.update` -> `stock.stock_count.start` -> `stock.stock_count.submit` -> `stock.stock_count.approve`。",
+                    "- `stock.out` 只用于无来源直接出库，类型限定为 `out_scrap` 或 `out_other`；销售发货不要绕过销售出库单。",
+                    "- `stock.batch_adjust` 只适合非批次物料的简化批量差异调整；批次追踪物料请使用 `stock.adjust` 并传 `batchNo`。",
+                    "",
+                    "## 销售出库防误操作",
+                    "",
+                    "- 销售出库必须以后端返回的销售订单、订单行、库存和动作详情为准，不能从工单状态自行推断可出库。",
+                    "- 用户说“已完工 / finished”时，先读取 `work_order.list` 的动作详情或接口 schema 确认合法状态枚举；不要把自然语言状态原样传给接口。",
+                    "- 工单完工只代表生产执行状态，不代表成品已经确认入库；出库前必须查询后端库存或后端候选/预检接口。",
+                    "- 没有明确的销售订单行、客户、出库仓库、剩余可出库数量和后端库存证据时，不要创建或确认销售出库单。",
+                    "- 如果库存不足、缺少生产入库单、缺少客户或状态不允许，停止写入动作并向用户说明阻断原因和下一步查询建议。",
+                    "",
                     "## 防误连",
                     "",
                     "- MCP 启动时会在 stderr 打印 MES 地址、Token 用户名、apiKeyId、agentClientId 和动态工具状态。",
@@ -71,4 +85,49 @@ export function registerMesResources(server, client) {
             },
         ],
     }));
+    server.registerResource("mes_sale_delivery_flow", "mes://flows/sale-delivery", {
+        title: "MES Sales Delivery Flow",
+        description: "销售出库 AI 执行上下文：说明读取顺序、后端事实来源和阻断处理，避免 AI 从工单或销售单状态自行推断可出库。",
+        mimeType: "text/markdown",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "text/markdown",
+                text: [
+                    "# MES Sales Delivery Flow",
+                    "",
+                    "本资源只描述 AI 应如何读取后端事实，不承载 MES 业务规则。状态、权限、库存、质量、可执行性和审计均以后端接口返回为准。",
+                    "",
+                    "## 核心原则",
+                    "",
+                    "- 不要把“工单已完工”当成“可销售出库”。工单、生产入库单、库存和销售出库单是不同业务事实。",
+                    "- 不要在 MCP 端维护可出库状态白名单、库存扣减规则或质量规则。",
+                    "- 写入前必须用后端只读接口或动作详情取得当前事实；事实不完整时停止写入并说明缺口。",
+                    "",
+                    "## 推荐读取顺序",
+                    "",
+                    "1. 用 `mes_action.list` 搜索“销售出库 / 创建出库单 / 确认出库单”，再用 `mes_action.detail` 读取 `sale_delivery.create` 和 `sale_delivery.confirm` 的最新 schema。",
+                    "2. 用 `mes_api.read` 查询 `/sale-order/list` 或 `/sale-order/detail`，确认销售订单、客户、订单行和后端返回的剩余可出库信息。",
+                    "3. 对每个订单行，用 `mes_api.read` 查询 `/stock/list`，按物料和候选出库仓库读取后端库存行；没有库存证据时不要继续确认出库。",
+                    "4. 如果用户从工单切入，先查询 `/work-order/list` 或 `/work-order/detail` 只确认工单事实，再查询 `/production-receipt/list`、`/production-receipt/output-buffer/list` 和 `/stock/list` 确认是否已经形成可用库存。",
+                    "5. 只有后端事实齐全且没有阻断时，才用 `mes_action.execute` 执行 `sale_delivery.create`；确认出库使用 `sale_delivery.confirm`，最终库存扣减仍由后端复验。",
+                    "",
+                    "## 阻断时的回答",
+                    "",
+                    "- 库存不足：不要创建或确认出库单；说明目标仓库库存不足，并建议查询生产入库单、生产输出暂存、调拨或采购入库。",
+                    "- 没有销售订单行：不要用工单直接拼出库单；要求用户指定销售订单或先查询待出库销售订单。",
+                    "- 状态或字段不合法：引用后端错误或 schema 合法枚举，改用后端合法值重新查询。",
+                    "- 缺客户、仓库、批次、库位等关键事实：先查询或要求用户确认，不要伪造默认值。",
+                    "",
+                    "## 写入模式",
+                    "",
+                    "- 优先使用 `preview` 或 `confirm_required`。",
+                    "- `preview` 只校验工具调用形态，不代表业务已成功写入。",
+                    "- `confirm_required` 生成待确认调用，最终是否执行仍由同公司有权限账号确认。",
+                    "- `commit` 只有当前凭证允许且用户明确要求时才使用。",
+                ].join("\n"),
+            },
+        ],
+    }));
 }

package/dist/tools/register-tools.js

@@ -1,6 +1,9 @@
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
+import { ActionSearchService } from "../discovery/action-search.service.js";
 const MAX_MES_PAGE_SIZE = 100;
+const DEFAULT_ACTION_LIST_TOPK = 20;
+const MAX_ACTION_LIST_TOPK = 50;
 const ExecutionModeSchema = z
     .enum(["preview", "confirm_required", "commit"])
     .optional();
@@ -174,15 +177,39 @@ function actionDescription(action) {
         .filter(Boolean)
         .join("\n");
 }
-function registerGenericActionTools(server, client) {
+function listActionView(action, relevance) {
+    return {
+        actionCode: action.actionCode,
+        title: action.title,
+        description: action.description,
+        module: action.module,
+        resource: action.resource,
+        operation: action.operation,
+        path: action.path,
+        method: action.method,
+        isWrite: action.isWrite,
+        permissions: action.permissions,
+        riskLevel: action.riskLevel,
+        relevance: Number(relevance.toFixed(4)),
+    };
+}
+function registerGenericActionTools(server, client, searchService) {
     server.registerTool("mes_action.list", {
-        title: "List MES business actions",
-        description: "动态查询当前 AI 凭证和当前账号权限允许调用的 MES 页面业务动作。新业务页面只要后端有权限和 DTO 元数据，就会出现在这里。",
+        title: "Search MES business actions",
+        description: "按相关性检索当前 AI 凭证和账号权限允许调用的 MES 页面业务动作。动作目录有数百个，请把要做的事用一句自然语言意图放进 keyword（例如「销售单转生产计划」「采购入库」「报工」），返回的是按相关性排序的 top-K 动作（不是分页字母序）。可选 module/resource/operation/write 做精确过滤。拿到 actionCode 后用 mes_action.detail 看字段、mes_action.execute 执行。",
         inputSchema: z
             .object({
-            page: z.number().int().positive().optional(),
-            pageSize: z.number().int().positive().max(100).optional(),
-            keyword: z.string().optional(),
+            keyword: z
+                .string()
+                .optional()
+                .describe("要做的事的自然语言意图，用于相关性检索"),
+            topK: z
+                .number()
+                .int()
+                .positive()
+                .max(MAX_ACTION_LIST_TOPK)
+                .optional()
+                .describe("返回的最相关动作数量，默认 20，最大 50"),
             module: z.string().optional(),
             resource: z.string().optional(),
             operation: z.string().optional(),
@@ -198,9 +225,8 @@ function registerGenericActionTools(server, client) {
         return runTool({ toolName: "mes_action.list" }, async () => {
             const parsed = z
                 .object({
-                page: z.number().int().positive().optional(),
-                pageSize: z.number().int().positive().optional(),
                 keyword: z.string().optional(),
+                topK: z.number().int().positive().optional(),
                 module: z.string().optional(),
                 resource: z.string().optional(),
                 operation: z.string().optional(),
@@ -209,9 +235,35 @@ function registerGenericActionTools(server, client) {
                 .passthrough()
                 .parse(args ?? {});
             const warnings = [];
-            const payload = normalizePageSize(parsed, warnings);
-            const result = await client.post("/integration/agent/actions/list", payload);
-            return formatToolResult(result, warnings);
+            let topK = parsed.topK ?? DEFAULT_ACTION_LIST_TOPK;
+            if (topK > MAX_ACTION_LIST_TOPK) {
+                warnings.push({
+                    code: "topK_clamped",
+                    message: `topK 最大为 ${MAX_ACTION_LIST_TOPK}，已从 ${topK} 调整为 ${MAX_ACTION_LIST_TOPK}。`,
+                });
+                topK = MAX_ACTION_LIST_TOPK;
+            }
+            const keyword = parsed.keyword?.trim() ?? "";
+            const { total, results } = await searchService.search(keyword, {
+                module: parsed.module,
+                resource: parsed.resource,
+                operation: parsed.operation,
+                write: parsed.write,
+                topK,
+            });
+            if (keyword && results.length === 0) {
+                warnings.push({
+                    code: "no_match",
+                    message: "没有命中相关动作。换一个更贴近业务的意图词（如把「转计划」换成「销售单转生产计划」），或用 module/operation 过滤。",
+                });
+            }
+            return formatToolResult({
+                query: keyword || null,
+                ranked: Boolean(keyword),
+                total,
+                returned: results.length,
+                list: results.map((r) => listActionView(r.action, r.score)),
+            }, warnings);
         });
     });
     server.registerTool("mes_action.detail", {
@@ -312,8 +364,9 @@ async function registerDynamicBusinessActionTools(server, client) {
     }
 }
 export async function registerAllAgentTools(server, client, options = {}) {
+    const searchService = new ActionSearchService(client, options.actionSearchMode ?? "lexical");
     registerAgentTools(server, client);
-    registerGenericActionTools(server, client);
+    registerGenericActionTools(server, client, searchService);
     if (!options.registerDynamicTools)
         return;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mes-mcp",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "type": "module",
   "description": "MES MCP adapter for Marvis and AI agents",
   "license": "UNLICENSED",