mes-mcp 0.3.2 → 0.3.4

package/.env.example

@@ -2,6 +2,9 @@ MES_BASE_URL=http://127.0.0.1:6033
 MES_API_PREFIX=/api
 MES_AGENT_TOKEN=
 MES_TIMEOUT_MS=30000
+# 动作目录缓存 TTL（毫秒，兜底），默认 12h。另外跨自然日必刷新：
+# 每天第一次调用 mes_action.* 时自动拉最新动作目录；用户也可用 mes_action.catalog 手动强刷。
+MES_ACTION_CACHE_TTL_MS=43200000
 MES_REGISTER_DYNAMIC_TOOLS=false
 # mes_action.list 动作检索模式：
 #   lexical（默认，推荐）= CJK 词元 BM25 + 双语领域词扩展，离线、零额外依赖、确定性；

package/dist/clients/mes-agent-api.client.js

@@ -26,6 +26,10 @@ function buildMesErrorMessage(path, status, message) {
 export class MesAgentApiClient {
     config;
     businessActionsPromise;
+    // 动作目录缓存最近成功刷新时间；驱动每日首用/TTL 自动刷新，并对外报告。
+    // undefined 且 promise 存在 = 拉取在途（并发复用同一 promise，避免重复请求）。
+    businessActionsFetchedAt;
+    businessActionsVersion = 0;
     constructor(config) {
         this.config = config;
     }
@@ -68,15 +72,51 @@ export class MesAgentApiClient {
         return this.post(normalized, payload);
     }
     async listBusinessActions(options = {}) {
-        if (!options.refresh && this.businessActionsPromise) {
+        // 复用：非强制刷新 + 有缓存/在途 + (在途未定时间 或 仍新鲜)
+        if (!options.refresh &&
+            this.businessActionsPromise &&
+            (this.businessActionsFetchedAt === undefined || this.isCatalogFresh())) {
             return this.businessActionsPromise;
         }
-        this.businessActionsPromise = this.fetchBusinessActions().catch((error) => {
+        // 开新拉取：先清 fetchedAt 标记「在途」，并发调用复用同一 promise 不重复请求
+        this.businessActionsFetchedAt = undefined;
+        this.businessActionsPromise = this.fetchBusinessActions()
+            .then((actions) => {
+            this.businessActionsFetchedAt = new Date();
+            this.businessActionsVersion += 1;
+            return actions;
+        })
+            .catch((error) => {
             this.businessActionsPromise = undefined;
+            this.businessActionsFetchedAt = undefined;
             throw error;
         });
         return this.businessActionsPromise;
     }
+    /**
+     * 动作目录缓存是否仍新鲜：跨自然日或超过 TTL 视为过期。
+     * 跨自然日过期即「每天第一次使用自动拉最新目录」。
+     */
+    isCatalogFresh() {
+        if (!this.businessActionsFetchedAt)
+            return false;
+        const now = new Date();
+        if (now.toDateString() !== this.businessActionsFetchedAt.toDateString()) {
+            return false;
+        }
+        return (now.getTime() - this.businessActionsFetchedAt.getTime() <
+            this.config.actionCacheTtlMs);
+    }
+    /** 动作目录最近一次成功刷新时间（ISO）；未拉取过返回 null。 */
+    businessActionsRefreshedAt() {
+        return this.businessActionsFetchedAt
+            ? this.businessActionsFetchedAt.toISOString()
+            : null;
+    }
+    /** 动作目录缓存版本；每次成功刷新递增，用于让下游检索索引失效。 */
+    businessActionsCatalogVersion() {
+        return this.businessActionsVersion;
+    }
     async getBusinessAction(actionCode) {
         const actions = await this.listBusinessActions();
         const cached = actions.find((action) => action.actionCode === actionCode);

package/dist/config.js

@@ -81,6 +81,10 @@ export function loadConfig() {
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
         throw new Error("MES_TIMEOUT_MS must be a positive number");
     }
+    const actionCacheTtlMs = Number(optionalEnv("MES_ACTION_CACHE_TTL_MS", "43200000"));
+    if (!Number.isFinite(actionCacheTtlMs) || actionCacheTtlMs <= 0) {
+        throw new Error("MES_ACTION_CACHE_TTL_MS must be a positive number");
+    }
     const mesAgentToken = requiredEnv("MES_AGENT_TOKEN");
     const tokenInfo = decodeAgentToken(mesAgentToken);
     const expectedUsername = optionalRawEnv("MES_EXPECTED_USERNAME");
@@ -96,6 +100,7 @@ export function loadConfig() {
         timeoutMs,
         registerDynamicTools: optionalBooleanEnv("MES_REGISTER_DYNAMIC_TOOLS", false),
         actionSearchMode: actionSearchModeEnv("MES_ACTION_SEARCH", "lexical"),
+        actionCacheTtlMs,
         tokenInfo,
         expectedUsername,
         expectedAgentClientId,

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

@@ -19,16 +19,30 @@ export class ActionSearchService {
             this.client.listBusinessActions(),
             createEmbeddingProvider(this.mode),
         ]);
-        return new ActionSearchIndex(actions, provider);
+        return {
+            index: new ActionSearchIndex(actions, provider),
+            version: this.client.businessActionsCatalogVersion(),
+        };
     }
-    async search(query, options) {
+    async getIndex() {
         if (!this.indexPromise) {
             this.indexPromise = this.buildIndex().catch((error) => {
                 this.indexPromise = undefined;
                 throw error;
             });
         }
-        const index = await this.indexPromise;
+        let indexed = await this.indexPromise;
+        if (indexed.version !== this.client.businessActionsCatalogVersion()) {
+            this.indexPromise = this.buildIndex().catch((error) => {
+                this.indexPromise = undefined;
+                throw error;
+            });
+            indexed = await this.indexPromise;
+        }
+        return indexed.index;
+    }
+    async search(query, options) {
+        const index = await this.getIndex();
         const results = await index.search(query, options);
         return { total: index.size, results };
     }

package/dist/prompts/register-prompts.js

@@ -15,7 +15,8 @@ export function registerMesPrompts(server) {
                     text: [
                         "你是 MES 业务助手，必须按当前账号权限和工具返回结果执行。",
                         "不要猜测客户、物料、BOM、工艺路线、仓库等关键主数据；缺失时先查询或要求用户确认。",
-                        "动作目录有数百个动作。发现动作时用 mes_action.list，把你当前要做的事用一句自然语言意图传给 keyword（例如「销售单转生产计划」「采购入库」「报工」），它返回按相关性排序的 top-K 动作；再用 mes_action.detail 查看字段。遇到前置步骤、字段归属或业务口径不清楚时，先用 mes_manual.search 或 mes_workflow.detail 查后端手册索引，最后用 mes_action.execute 执行。不要不带意图地翻页或猜路径，也不要依赖工具列表里必须存在 mes.<动作编码>。",
+                        "处理 MES 任务前、或用户说「更新一下 mes / 看看有哪些动作」时，先调用 mes_action.catalog 加载当前账号权限内的全部动作紧凑目录（它会强制刷新；mcp 每天第一次使用也会自动拉最新目录），把可用动作装进上下文。",
+                        "动作目录有数百个动作。已加载目录后要执行具体某件事，用 mes_action.list 把意图用一句自然语言传给 keyword（例如「销售单转生产计划」「采购入库」「报工」）拿到相关性 top-K，再用 mes_action.detail 查看字段。遇到前置步骤、字段归属或业务口径不清楚时，先用 mes_manual.search 或 mes_workflow.detail 查后端手册索引，最后用 mes_action.execute 执行。不要不带意图地翻页或猜路径，也不要依赖工具列表里必须存在 mes.<动作编码>。",
                         "mes_action.execute 返回的是执行信封，真实业务返回在 data 字段；confirm_required 产生的 invocationId 必须由同一公司/租户下有权限的账号审批。",
                         "mes_api.read 只用于普通业务只读接口，pageSize 最大 100；如果返回 _mcpWarnings 或提示需要动态动作，请按提示调整。",
                         "销售到出库的流程也走动态动作：先查客户和物料，再创建销售单、处理审批、确认销售单、转生产计划、排产或生成工单、报工、质检、生产入库/库存确认、发货出库。",

package/dist/tools/register-tools.js

@@ -193,6 +193,21 @@ function listActionView(action, relevance) {
         relevance: Number(relevance.toFixed(4)),
     };
 }
+// 全量目录用的紧凑视图：只保留识别动作所需字段，不含 path/method/权限/schema，控上下文预算。
+function catalogActionView(action) {
+    const brief = action.description?.trim();
+    return {
+        actionCode: action.actionCode,
+        title: action.title,
+        operation: action.operation,
+        resource: action.resource,
+        isWrite: action.isWrite,
+        riskLevel: action.riskLevel,
+        ...(brief
+            ? { brief: brief.length > 80 ? `${brief.slice(0, 80)}…` : brief }
+            : {}),
+    };
+}
 function registerGenericActionTools(server, client, searchService) {
     server.registerTool("mes_action.list", {
         title: "Search MES business actions",
@@ -260,12 +275,76 @@ function registerGenericActionTools(server, client, searchService) {
             return formatToolResult({
                 query: keyword || null,
                 ranked: Boolean(keyword),
+                catalogVersion: client.businessActionsCatalogVersion(),
+                refreshedAt: client.businessActionsRefreshedAt(),
                 total,
                 returned: results.length,
                 list: results.map((r) => listActionView(r.action, r.score)),
             }, warnings);
         });
     });
+    server.registerTool("mes_action.catalog", {
+        title: "Load full MES action catalog",
+        description: "拉取并刷新当前 AI 凭证和账号权限内【全部】可执行的 MES 页面业务动作紧凑目录（按模块分组），用于把可用动作一次性加载进上下文。当用户说「更新一下 mes / 看看有哪些动作」、你不确定有哪些动作、或距上次加载较久怀疑目录已变时调用。只返回动作码/名称/模块/操作/读写/一句话用途；执行某动作前用 mes_action.detail 看字段，按意图精准找某个动作用 mes_action.list。",
+        inputSchema: z
+            .object({
+            module: z
+                .string()
+                .optional()
+                .describe("只加载某模块的动作（如 sales/purchase/finance），控上下文；不传=全部模块"),
+        })
+            .passthrough(),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async (args) => {
+        return runTool({ toolName: "mes_action.catalog" }, async () => {
+            const parsed = z
+                .object({ module: z.string().optional() })
+                .passthrough()
+                .parse(args ?? {});
+            const moduleFilter = parsed.module?.trim() || undefined;
+            // 强制刷新，保证「更新一下 mes」拿到最新目录
+            const all = await client.listBusinessActions({ refresh: true });
+            const filtered = moduleFilter
+                ? all.filter((a) => a.module === moduleFilter)
+                : all;
+            const warnings = [];
+            if (moduleFilter && filtered.length === 0) {
+                warnings.push({
+                    code: "module_no_match",
+                    message: `模块「${moduleFilter}」下没有可用动作；不传 module 可加载全部模块，或用 mes_action.list 按意图检索。`,
+                });
+            }
+            const byModule = new Map();
+            for (const action of filtered) {
+                const list = byModule.get(action.module) ?? [];
+                list.push(action);
+                byModule.set(action.module, list);
+            }
+            const modules = [...byModule.entries()]
+                .sort((a, b) => a[0].localeCompare(b[0]))
+                .map(([module, actions]) => ({
+                module,
+                count: actions.length,
+                actions: actions
+                    .slice()
+                    .sort((a, b) => a.actionCode.localeCompare(b.actionCode))
+                    .map(catalogActionView),
+            }));
+            return formatToolResult({
+                refreshedAt: client.businessActionsRefreshedAt(),
+                catalogVersion: client.businessActionsCatalogVersion(),
+                total: filtered.length,
+                moduleCount: modules.length,
+                filteredModule: moduleFilter ?? null,
+                modules,
+                note: "以上为当前凭证权限内的全部可用 MES 动作紧凑目录。执行前用 mes_action.detail 看字段/schema；按意图精准找用 mes_action.list。",
+            }, warnings);
+        });
+    });
     server.registerTool("mes_action.detail", {
         title: "Get MES business action detail",
         description: "查询单个 MES 页面业务动作的路径、权限、DTO 名称、输入 schema，以及后端提供的手册引用、字段归属和推荐工作流提示。",

package/package.json

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