mes-mcp 0.3.1 → 0.3.3

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,9 @@ function buildMesErrorMessage(path, status, message) {
 export class MesAgentApiClient {
     config;
     businessActionsPromise;
+    // 动作目录缓存最近成功刷新时间；驱动每日首用/TTL 自动刷新，并对外报告。
+    // undefined 且 promise 存在 = 拉取在途（并发复用同一 promise，避免重复请求）。
+    businessActionsFetchedAt;
     constructor(config) {
         this.config = config;
     }
@@ -68,15 +71,46 @@ 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();
+            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;
+    }
     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/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_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/resources/register-resources.js

@@ -37,10 +37,11 @@ export function registerMesResources(server, client) {
                     "## 工具使用顺序",
                     "",
                     "1. 使用 `mes_action.list` 或 `mes://agent/actions` 发现当前凭证和账号权限允许的动作。",
-                    "2. 使用 `mes_action.detail` 查看目标动作的路径、权限、DTO 名称和输入 schema。",
-                    "3. 只读查询使用 `mes_api.read` 调用普通业务只读 POST 接口。",
-                    "4. 写入、确认、下达、报工、质检、出入库等动作使用 `mes_action.execute` 或可选的 `mes.<动作编码>`。",
-                    "5. `MES_REGISTER_DYNAMIC_TOOLS=false` 是默认推荐配置；此时工具列表只有 `mes_api.read`、`mes_action.list`、`mes_action.detail`、`mes_action.execute` 等基础工具。只有客户端必须直观看到 `mes.<动作编码>` 时才开启动态工具展开。",
+                    "2. 使用 `mes_action.detail` 查看目标动作的路径、权限、DTO 名称、输入 schema、字段归属和推荐工作流提示。",
+                    "3. 如果业务链路或字段归属不清楚，使用 `mes_manual.search` / `mes_manual.get` / `mes_workflow.detail` 查询后端提供的 AI 操作手册索引。",
+                    "4. 只读查询使用 `mes_api.read` 调用普通业务只读 POST 接口。",
+                    "5. 写入、确认、下达、报工、质检、出入库等动作使用 `mes_action.execute` 或可选的 `mes.<动作编码>`。",
+                    "6. `MES_REGISTER_DYNAMIC_TOOLS=false` 是默认推荐配置；此时工具列表包含 `mes_api.read`、`mes_action.list/detail/execute`、`mes_manual.search/get`、`mes_workflow.detail` 等基础工具。只有客户端必须直观看到 `mes.<动作编码>` 时才开启动态工具展开。",
                     "",
                     "## 写入规则",
                     "",

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",
@@ -266,9 +281,70 @@ function registerGenericActionTools(server, client, searchService) {
             }, 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(),
+                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。",
+        description: "查询单个 MES 页面业务动作的路径、权限、DTO 名称、输入 schema，以及后端提供的手册引用、字段归属和推荐工作流提示。",
         inputSchema: z.object({
             actionCode: z.string().min(1),
         }),
@@ -288,6 +364,100 @@ function registerGenericActionTools(server, client, searchService) {
             return formatToolResult(result);
         });
     });
+    server.registerTool("mes_manual.search", {
+        title: "Search MES operation manual",
+        description: "检索后端提供的 MES AI 操作手册索引，用于补充字段归属、前置动作、推荐流程和常见误用。适合在只看 action schema 不确定业务链路时调用。",
+        inputSchema: z
+            .object({
+            query: z.string().optional().describe("自然语言查询词"),
+            keyword: z.string().optional().describe("兼容字段：自然语言查询词"),
+            module: z.string().optional().describe("业务模块，如 schedule"),
+            actionCode: z
+                .string()
+                .optional()
+                .describe("相关动作编码，如 schedule.plan.auto"),
+            field: z
+                .string()
+                .optional()
+                .describe("字段名或字段归属，如 planStartDate"),
+            page: z.number().int().positive().optional(),
+            pageSize: z
+                .number()
+                .int()
+                .positive()
+                .max(MAX_MES_PAGE_SIZE)
+                .optional(),
+        })
+            .passthrough(),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async (args) => {
+        return runTool({ toolName: "mes_manual.search" }, async () => {
+            const parsed = z
+                .object({
+                query: z.string().optional(),
+                keyword: z.string().optional(),
+                module: z.string().optional(),
+                actionCode: z.string().optional(),
+                field: z.string().optional(),
+                page: z.number().int().positive().optional(),
+                pageSize: z.number().int().positive().optional(),
+            })
+                .passthrough()
+                .parse(args ?? {});
+            const warnings = [];
+            const payload = normalizePageSize(parsed, warnings);
+            const result = await client.post("/integration/agent/manual/search", payload);
+            return formatToolResult(result, warnings);
+        });
+    });
+    server.registerTool("mes_manual.get", {
+        title: "Get MES operation manual section",
+        description: "按手册章节 ID 获取后端提供的 MES AI 操作手册详情，返回动作链、字段归属、步骤和常见误用。",
+        inputSchema: z.object({
+            id: z.string().min(1).describe("手册章节 ID"),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async (args) => {
+        return runTool({ toolName: "mes_manual.get" }, async () => {
+            const parsed = z
+                .object({
+                id: z.string().min(1),
+            })
+                .parse(args ?? {});
+            const result = await client.post("/integration/agent/manual/detail", parsed);
+            return formatToolResult(result);
+        });
+    });
+    server.registerTool("mes_workflow.detail", {
+        title: "Get MES recommended workflow",
+        description: "按工作流 ID 获取后端推荐的 MES 业务动作链。用于需要多个动作配合完成的场景，例如先更新生产计划开始日期，再从生产计划排产。",
+        inputSchema: z.object({
+            id: z.string().min(1).describe("业务工作流 ID"),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async (args) => {
+        return runTool({ toolName: "mes_workflow.detail" }, async () => {
+            const parsed = z
+                .object({
+                id: z.string().min(1),
+            })
+                .parse(args ?? {});
+            const result = await client.post("/integration/agent/workflows/detail", parsed);
+            return formatToolResult(result);
+        });
+    });
     server.registerTool("mes_action.execute", {
         title: "Execute MES business action",
         description: "执行一个由 mes_action.list 发现的 MES 页面业务动作。后端复用页面 Controller、DTO、权限、租户、状态机和调用日志。返回体是执行信封：真实业务结果在 data 字段；confirm_required 返回待确认 invocationId，必须由同一公司/租户下有权限的账号审批。",

package/package.json

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