mes-mcp 0.2.3 → 0.3.0

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/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,11 @@ 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 或提示需要动态动作，请按提示调整。",
                         "销售到出库的流程也走动态动作：先查客户和物料，再创建销售单、处理审批、确认销售单、转生产计划、排产或生成工单、报工、质检、发货出库。",
+                        "库存盘点差异优先使用 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,12 @@ 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`。",
+                    "",
                     "## 防误连",
                     "",
                     "- MCP 启动时会在 stderr 打印 MES 地址、Token 用户名、apiKeyId、agentClientId 和动态工具状态。",

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.0",
   "type": "module",
   "description": "MES MCP adapter for Marvis and AI agents",
   "license": "UNLICENSED",