mes-mcp 0.2.0 → 0.2.1

package/.env.example

@@ -2,3 +2,4 @@ MES_BASE_URL=http://127.0.0.1:6033
 MES_API_PREFIX=/api
 MES_AGENT_TOKEN=
 MES_TIMEOUT_MS=30000
+MES_REGISTER_DYNAMIC_TOOLS=false

package/README.md

@@ -18,8 +18,11 @@ MES_BASE_URL=http://127.0.0.1:6033
 MES_API_PREFIX=/api
 MES_AGENT_TOKEN=BearerTokenWithoutBearerPrefix
 MES_TIMEOUT_MS=30000
+MES_REGISTER_DYNAMIC_TOOLS=false
 ```
 
+`MES_REGISTER_DYNAMIC_TOOLS` 默认关闭。关闭时 MCP 只注册稳定接口工具，通过后端动作目录发现并执行全部授权业务能力；打开后会把所有授权页面动作额外展开成 `mes.<动作编码>` 工具，适合明确需要工具直出且客户端能承载大量工具的场景。
+
 ## 开发
 
 ```bash
@@ -30,22 +33,26 @@ npm run dev
 
 ## 工具
 
-使用后端动态业务动作：
+默认使用后端动态业务动作接口：
 
 - `mes_action.list`：查询当前凭证和当前账号权限允许调用的 MES 页面业务动作。
 - `mes_action.detail`：查看某个业务动作的路径、权限、DTO 名称和输入 schema。
 - `mes_action.execute`：按动作编码执行业务动作。
-- `mes.<动作编码>`：启动时从 `mes-node` 自动发现并注册的动态工具，例如 `mes.sale_order.create`、`mes.approval.handle`、`mes.quality_inspection.submit`、`mes.sale_delivery.confirm`。
+- `mes.<动作编码>`：仅在 `MES_REGISTER_DYNAMIC_TOOLS=true` 时，从 `mes-node` 自动发现并注册的动态工具，例如 `mes.sale_order.create`、`mes.approval.handle`、`mes.quality_inspection.submit`、`mes.sale_delivery.confirm`。
+
+动态动作只调用 `mes-node` 的 `/integration/agent/actions/*` 接口。MCP 不保存字段 schema，不复制状态机，不做业务默认值；后端会复用页面 Controller、DTO、权限、租户、状态、审批、库存、质量和 AI 调用日志。默认不把全部动作展开成独立工具，是为了避免 MCP 客户端一次性加载数百个工具；能力覆盖仍以 `mes_action.list/detail/execute` 为准。
 
-动态工具只调用 `mes-node` 的 `/integration/agent/actions/*` 接口。MCP 不保存字段 schema，不复制状态机，不做业务默认值；后端会复用页面 Controller、DTO、权限、租户、状态、审批、库存、质量和 AI 调用日志。
+写入类动作通过 `confirm_required` 或 `commit` 执行时需要幂等键。调用方没有显式传入时，`mes-mcp` 会为当前工具调用生成一条集成幂等键；需要跨重试严格复用同一幂等键的批处理场景，仍建议调用方显式传入 `idempotencyKey`。
 
 - `mes_api.read`：按当前 MES 账号权限读取普通业务接口，例如 `/sale-order/list`、`/material/detail`。后端只放行只读类接口，写入动作必须使用动态业务动作；读取调用会在 MES AI 调用日志里记录路径、请求摘要和结果摘要。
 
 写入类工具支持 `executionMode`：
 
 - `preview`：只预览，不写入。
-- `confirm_required`：生成待确认单，不写入；必须传 `idempotencyKey`。
-- `commit`：提交到 MES，按当前账号权限、工具白名单、业务规则和幂等键执行；必须传 `idempotencyKey`。
+- `confirm_required`：生成待确认单，不写入；后端要求幂等键，未传时 MCP 会为本次工具调用自动生成。
+- `commit`：提交到 MES，按当前账号权限、工具白名单、业务规则和幂等键执行；后端要求幂等键，未传时 MCP 会为本次工具调用自动生成。
+
+跨重试或批处理场景如果需要严格复用同一次业务请求，调用方应显式传入同一个 `idempotencyKey`；单次交互式调用可以依赖 MCP 自动生成。
 
 ## Marvis 接入建议
 
@@ -53,4 +60,4 @@ npm run dev
 2. `agentClientId` 建议填写 `marvis` 或具体渠道名。
 3. 授权范围建议先选“跟随账号权限”，最高执行模式建议先用 `confirm_required`；如果只想开放少量动作，再切换为“仅允许指定工具”。只读型 AI 凭证可以只选择 `mes_api.read`。
 4. 将返回的 JWT 配置为 `MES_AGENT_TOKEN`。
-5. Marvis 侧通过 MCP 调用工具；图片、PDF、Excel 可先由 Marvis 识别成结构化草稿，再用 `mes_api.read` 或动态列表动作查询客户、物料等主数据，最后通过 `mes.<动作编码>` 或 `mes_action.execute` 执行创建、审批、确认、排产、质检、出库等页面业务动作。
+5. Marvis 侧通过 MCP 调用工具；图片、PDF、Excel 可先由 Marvis 识别成结构化草稿，再用 `mes_api.read` 或动态列表动作查询客户、物料等主数据，最后通过 `mes_action.detail` 和 `mes_action.execute` 执行创建、审批、确认、排产、质检、出库等页面业务动作。

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

@@ -1,5 +1,6 @@
 export class MesAgentApiClient {
     config;
+    businessActionsPromise;
     constructor(config) {
         this.config = config;
     }
@@ -41,7 +42,26 @@ export class MesAgentApiClient {
         }
         return this.post(normalized, payload);
     }
-    async listBusinessActions() {
+    async listBusinessActions(options = {}) {
+        if (!options.refresh && this.businessActionsPromise) {
+            return this.businessActionsPromise;
+        }
+        this.businessActionsPromise = this.fetchBusinessActions().catch((error) => {
+            this.businessActionsPromise = undefined;
+            throw error;
+        });
+        return this.businessActionsPromise;
+    }
+    async getBusinessAction(actionCode) {
+        const actions = await this.listBusinessActions();
+        const cached = actions.find((action) => action.actionCode === actionCode);
+        if (cached)
+            return cached;
+        const refreshedActions = await this.listBusinessActions({ refresh: true });
+        return (refreshedActions.find((action) => action.actionCode === actionCode) ??
+            null);
+    }
+    async fetchBusinessActions() {
         const pageSize = 100;
         const firstPage = await this.post("/integration/agent/actions/list", { page: 1, pageSize });
         if (firstPage.total <= firstPage.list.length)

package/dist/config.js

@@ -10,6 +10,16 @@ function requiredEnv(name) {
     }
     return value;
 }
+function optionalBooleanEnv(name, fallback) {
+    const value = process.env[name]?.trim().toLowerCase();
+    if (!value)
+        return fallback;
+    if (["1", "true", "yes", "on"].includes(value))
+        return true;
+    if (["0", "false", "no", "off"].includes(value))
+        return false;
+    throw new Error(`${name} must be a boolean`);
+}
 export function loadConfig() {
     const timeoutMs = Number(optionalEnv("MES_TIMEOUT_MS", "30000"));
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
@@ -20,5 +30,6 @@ export function loadConfig() {
         mesApiPrefix: optionalEnv("MES_API_PREFIX", "/api").replace(/\/+$/, ""),
         mesAgentToken: requiredEnv("MES_AGENT_TOKEN"),
         timeoutMs,
+        registerDynamicTools: optionalBooleanEnv("MES_REGISTER_DYNAMIC_TOOLS", false),
     };
 }

package/dist/index.js

@@ -13,7 +13,9 @@ async function main() {
         name: "mes-mcp",
         version: "0.2.0",
     });
-    await registerAllAgentTools(server, client);
+    await registerAllAgentTools(server, client, {
+        registerDynamicTools: config.registerDynamicTools,
+    });
     registerMesResources(server, client);
     registerMesPrompts(server);
     await server.connect(new StdioServerTransport());

package/dist/prompts/register-prompts.js

@@ -15,9 +15,9 @@ export function registerMesPrompts(server) {
                     text: [
                         "你是 MES 业务助手，必须按当前账号权限和工具返回结果执行。",
                         "不要猜测客户、物料、BOM、工艺路线、仓库等关键主数据；缺失时先查询或要求用户确认。",
-                        "先用 mes_action.list 或 mes://agent/actions 发现当前账号能做的页面业务动作；发现到动态工具 mes.<动作编码> 时，直接调用对应工具。",
+                        "默认先用 mes_action.list 或 mes://agent/actions 发现当前账号能做的页面业务动作，再用 mes_action.detail 查看字段，最后用 mes_action.execute 执行；不要依赖工具列表里必须存在 mes.<动作编码>。",
                         "销售到出库的流程也走动态动作：先查客户和物料，再创建销售单、处理审批、确认销售单、转生产计划、排产或生成工单、报工、质检、发货出库。",
-                        "写入类动作默认先使用 confirm_required 或 preview；confirm_required 和 commit 都必须传 idempotencyKey，preview 不写入。",
+                        "写入类动作默认先使用 confirm_required 或 preview；preview 不写入，confirm_required 生成待确认记录，commit 只有凭证允许时才真实提交。",
                         context ? `当前上下文：${context}` : "",
                     ]
                         .filter(Boolean)

package/dist/resources/register-resources.js

@@ -4,18 +4,57 @@ export function registerMesResources(server, client) {
         description: "当前 AI 凭证和账号权限可调用的 MES 页面业务动作目录，来源于 mes-node 后端 Controller、权限和 DTO 元数据。",
         mimeType: "application/json",
     }, async (uri) => {
-        const actions = await client.post("/integration/agent/actions/list", {
-            page: 1,
-            pageSize: 100,
-        });
+        const actions = await client.listBusinessActions();
         return {
             contents: [
                 {
                     uri: uri.href,
                     mimeType: "application/json",
-                    text: JSON.stringify(actions, null, 2),
+                    text: JSON.stringify({
+                        list: actions,
+                        total: actions.length,
+                        page: 1,
+                        pageSize: actions.length,
+                    }, null, 2),
                 },
             ],
         };
     });
+    server.registerResource("mes_agent_context", "mes://agent/context", {
+        title: "MES Agent Context",
+        description: "MES AI Agent 操作边界、标准链路和安全规则摘要，用于提示客户端按受控接口完成业务闭环。",
+        mimeType: "text/markdown",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "text/markdown",
+                text: [
+                    "# MES Agent Context",
+                    "",
+                    "MES MCP 只做协议适配，业务事实、权限、租户隔离、状态机、库存、质量、幂等和审计均由 mes-node 负责。",
+                    "",
+                    "## 工具使用顺序",
+                    "",
+                    "1. 使用 `mes_action.list` 或 `mes://agent/actions` 发现当前凭证和账号权限允许的动作。",
+                    "2. 使用 `mes_action.detail` 查看目标动作的路径、权限、DTO 名称和输入 schema。",
+                    "3. 只读查询使用 `mes_api.read` 调用普通业务只读 POST 接口。",
+                    "4. 写入、确认、下达、报工、质检、出入库等动作使用 `mes_action.execute` 或可选的 `mes.<动作编码>`。",
+                    "",
+                    "## 写入规则",
+                    "",
+                    "- `preview` 不写入业务数据。",
+                    "- `confirm_required` 生成待确认调用，不直接写入。",
+                    "- `commit` 只有凭证最高执行模式允许时才真实提交。",
+                    "- 写入类 `confirm_required` 和 `commit` 必须有幂等键；MCP 会为单次工具调用自动生成，跨重试批处理应显式传入同一个 `idempotencyKey`。",
+                    "",
+                    "## 禁止事项",
+                    "",
+                    "- 不猜客户、物料、BOM、工艺路线、仓库、批次、数量、价格等关键业务事实。",
+                    "- 不通过 `mes_api.read` 调用创建、更新、删除、确认、下达等写入接口。",
+                    "- 不绕过当前账号权限、公司隔离、状态机、库存规则、质量规则和审计。",
+                ].join("\n"),
+            },
+        ],
+    }));
 }

package/dist/tools/register-tools.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { z } from "zod";
 const ExecutionModeSchema = z
     .enum(["preview", "confirm_required", "commit"])
@@ -10,7 +11,7 @@ const DynamicActionSchema = z
         .min(1)
         .max(160)
         .optional()
-        .describe("写入动作 confirm_required 或 commit 时必填，用于后端幂等。"),
+        .describe("写入动作 confirm_required 或 commit 时用于后端幂等；不传时 MCP 会为本次工具调用自动生成。"),
     payload: z
         .record(z.string(), z.unknown())
         .optional()
@@ -71,12 +72,19 @@ function normalizeDynamicArgs(args) {
         payload: payload ?? rest,
     };
 }
+function buildIdempotencyKey(actionCode) {
+    const normalizedActionCode = actionCode.replace(/[^a-zA-Z0-9._-]+/g, "_");
+    return `mcp-${normalizedActionCode}-${Date.now().toString(36)}-${randomUUID()}`.slice(0, 160);
+}
+function shouldEnsureIdempotencyKey(action, executionMode) {
+    return Boolean(action?.isWrite && executionMode !== "preview");
+}
 function actionDescription(action) {
     const permissionText = action.permissions.length > 0
         ? `需要权限：${action.permissions.join("、")}。`
         : "按后端业务方法自行校验权限。";
     const modeText = action.isWrite
-        ? "写入动作，confirm_required 会生成待确认单，commit 会真实写入 MES；两种模式都必须提供 idempotencyKey，preview 不写入。"
+        ? "写入动作，confirm_required 会生成待确认单，commit 会真实写入 MES；两种模式可显式提供 idempotencyKey，不传时 MCP 会为本次工具调用自动生成，preview 不写入。"
         : "只读动作，固定按 preview 执行。";
     return [
         action.description,
@@ -154,10 +162,14 @@ function registerGenericActionTools(server, client) {
             .passthrough()
             .parse(args ?? {});
         const { actionCode, executionMode, idempotencyKey, payload, ...rest } = parsed;
+        const action = await client.getBusinessAction(actionCode);
         const result = await client.post("/integration/agent/actions/execute", {
             actionCode,
             executionMode,
-            idempotencyKey,
+            idempotencyKey: idempotencyKey ??
+                (shouldEnsureIdempotencyKey(action, executionMode)
+                    ? buildIdempotencyKey(actionCode)
+                    : undefined),
             payload: payload ?? rest,
         });
         return formatToolResult(result);
@@ -185,14 +197,20 @@ async function registerDynamicBusinessActionTools(server, client) {
             const result = await client.post("/integration/agent/actions/execute", {
                 actionCode: action.actionCode,
                 ...normalized,
+                idempotencyKey: normalized.idempotencyKey ??
+                    (shouldEnsureIdempotencyKey(action, normalized.executionMode)
+                        ? buildIdempotencyKey(action.actionCode)
+                        : undefined),
             });
             return formatToolResult(result);
         });
     }
 }
-export async function registerAllAgentTools(server, client) {
+export async function registerAllAgentTools(server, client, options = {}) {
     registerAgentTools(server, client);
     registerGenericActionTools(server, client);
+    if (!options.registerDynamicTools)
+        return;
     try {
         await registerDynamicBusinessActionTools(server, client);
     }

package/package.json

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