mes-mcp 0.2.0 → 0.2.2

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,31 @@
+function buildMesErrorMessage(path, status, message) {
+    const hints = [];
+    if (/pageSize must not be greater than 100/i.test(message)) {
+        hints.push("MES 分页上限是 100；请把 pageSize 调整到 100 或更小。");
+    }
+    if (message.includes("AI Agent 凭证只能访问动态业务动作接口")) {
+        hints.push("该路径可能属于受控动态业务动作或当前凭证未允许 mes_api.read；请优先用 mes_action.list/detail/execute 调用对应 actionCode。");
+    }
+    if (message.includes("最高只允许")) {
+        hints.push("当前 AI 凭证最高执行模式不足；请改用 preview/confirm_required，或在 MES 开放集成里创建允许 commit 的 AI 凭证。");
+    }
+    if (message.includes("待确认 AI 调用不存在")) {
+        hints.push("AI 待确认单按公司/租户隔离；请使用生成该确认单的同一公司账号审批，并确认 invocationId 未过期或未被处理。");
+    }
+    if (/^\/?integration\/agent(\/|$)/i.test(path)) {
+        hints.push("不要通过 mes_api.read 访问 /integration/agent/*；请使用 mes_action.* 专用工具。");
+    }
+    return [
+        `MES ${status}: ${message}`,
+        `path: ${path}`,
+        hints.length > 0 ? `hints: ${hints.join(" ")}` : undefined,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
 export class MesAgentApiClient {
     config;
+    businessActionsPromise;
     constructor(config) {
         this.config = config;
     }
@@ -20,10 +46,10 @@ export class MesAgentApiClient {
             const body = this.parseBody(text);
             if (!response.ok) {
                 const message = body?.msg || body?.message || text || response.statusText;
-                throw new Error(`MES ${response.status}: ${message}`);
+                throw new Error(buildMesErrorMessage(path, response.status, message));
             }
             if (body && typeof body.code === "number" && body.code !== 0) {
-                throw new Error(body.msg || body.message || `MES code ${body.code}`);
+                throw new Error(buildMesErrorMessage(path, body.code, body.msg || body.message || `MES code ${body.code}`));
             }
             return (body && "data" in body ? body.data : body);
         }
@@ -41,7 +67,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

@@ -3,6 +3,10 @@ function optionalEnv(name, fallback) {
     const value = process.env[name]?.trim();
     return value && value.length > 0 ? value : fallback;
 }
+function optionalRawEnv(name) {
+    const value = process.env[name]?.trim();
+    return value && value.length > 0 ? value : undefined;
+}
 function requiredEnv(name) {
     const value = process.env[name]?.trim();
     if (!value) {
@@ -10,15 +14,81 @@ 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`);
+}
+function decodeBase64UrlJson(segment) {
+    try {
+        const normalized = segment.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4)) % 4), "=");
+        return JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : undefined;
+}
+function decodeAgentToken(token) {
+    const [, payloadSegment] = token.split(".");
+    if (!payloadSegment)
+        return {};
+    const payload = decodeBase64UrlJson(payloadSegment);
+    if (!payload)
+        return {};
+    return {
+        subject: asString(payload.sub),
+        username: asString(payload.username),
+        tokenType: asString(payload.tokenType),
+        apiKeyId: asString(payload.apiKeyId),
+        clientType: asString(payload.clientType),
+        agentClientId: asString(payload.agentClientId),
+        issuedAt: asNumber(payload.iat),
+        expiresAt: asNumber(payload.exp),
+    };
+}
+function assertExpectedTokenValue(label, actual, expected) {
+    if (!expected)
+        return;
+    if (actual === expected)
+        return;
+    throw new Error(`${label} mismatch for MES_AGENT_TOKEN: expected ${expected}, got ${actual ?? "<missing>"}`);
+}
 export function loadConfig() {
     const timeoutMs = Number(optionalEnv("MES_TIMEOUT_MS", "30000"));
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
         throw new Error("MES_TIMEOUT_MS must be a positive number");
     }
+    const mesAgentToken = requiredEnv("MES_AGENT_TOKEN");
+    const tokenInfo = decodeAgentToken(mesAgentToken);
+    const expectedUsername = optionalRawEnv("MES_EXPECTED_USERNAME");
+    const expectedAgentClientId = optionalRawEnv("MES_EXPECTED_AGENT_CLIENT_ID");
+    const expectedApiKeyId = optionalRawEnv("MES_EXPECTED_API_KEY_ID");
+    assertExpectedTokenValue("username", tokenInfo.username, expectedUsername);
+    assertExpectedTokenValue("agentClientId", tokenInfo.agentClientId, expectedAgentClientId);
+    assertExpectedTokenValue("apiKeyId", tokenInfo.apiKeyId, expectedApiKeyId);
     return {
         mesBaseUrl: optionalEnv("MES_BASE_URL", "http://127.0.0.1:6033").replace(/\/+$/, ""),
         mesApiPrefix: optionalEnv("MES_API_PREFIX", "/api").replace(/\/+$/, ""),
-        mesAgentToken: requiredEnv("MES_AGENT_TOKEN"),
+        mesAgentToken,
         timeoutMs,
+        registerDynamicTools: optionalBooleanEnv("MES_REGISTER_DYNAMIC_TOOLS", false),
+        tokenInfo,
+        expectedUsername,
+        expectedAgentClientId,
+        expectedApiKeyId,
     };
 }

package/dist/index.js

@@ -6,14 +6,50 @@ import { MesAgentApiClient } from "./clients/mes-agent-api.client.js";
 import { registerMesPrompts } from "./prompts/register-prompts.js";
 import { registerMesResources } from "./resources/register-resources.js";
 import { registerAllAgentTools } from "./tools/register-tools.js";
+function maskId(value) {
+    if (!value)
+        return "<unknown>";
+    if (value.length <= 12)
+        return value;
+    return `${value.slice(0, 8)}...${value.slice(-4)}`;
+}
+function formatUnixSeconds(value) {
+    if (!value)
+        return "<unknown>";
+    const date = new Date(value * 1000);
+    if (Number.isNaN(date.getTime()))
+        return "<invalid>";
+    return date.toISOString();
+}
+function logStartupDiagnostics(config) {
+    const lines = [
+        "[mes-mcp] starting",
+        `[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"})`,
+    ];
+    if (config.expectedUsername) {
+        lines.push(`[mes-mcp] expected username=${config.expectedUsername}`);
+    }
+    if (config.expectedAgentClientId) {
+        lines.push(`[mes-mcp] expected agentClientId=${config.expectedAgentClientId}`);
+    }
+    if (config.expectedApiKeyId) {
+        lines.push(`[mes-mcp] expected apiKeyId=${maskId(config.expectedApiKeyId)}`);
+    }
+    console.error(lines.join("\n"));
+}
 async function main() {
     const config = loadConfig();
+    logStartupDiagnostics(config);
     const client = new MesAgentApiClient(config);
     const server = new McpServer({
         name: "mes-mcp",
-        version: "0.2.0",
+        version: "0.2.2",
+    });
+    await registerAllAgentTools(server, client, {
+        registerDynamicTools: config.registerDynamicTools,
     });
-    await registerAllAgentTools(server, client);
     registerMesResources(server, client);
     registerMesPrompts(server);
     await server.connect(new StdioServerTransport());

package/dist/prompts/register-prompts.js

@@ -15,9 +15,11 @@ 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.<动作编码>。",
+                        "mes_action.execute 返回的是执行信封，真实业务返回在 data 字段；confirm_required 产生的 invocationId 必须由同一公司/租户下有权限的账号审批。",
+                        "mes_api.read 只用于普通业务只读接口，pageSize 最大 100；如果返回 _mcpWarnings 或提示需要动态动作，请按提示调整。",
                         "销售到出库的流程也走动态动作：先查客户和物料，再创建销售单、处理审批、确认销售单、转生产计划、排产或生成工单、报工、质检、发货出库。",
-                        "写入类动作默认先使用 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,71 @@ 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.<动作编码>`。",
+                    "5. `MES_REGISTER_DYNAMIC_TOOLS=false` 是默认推荐配置；此时工具列表只有 `mes_api.read`、`mes_action.list`、`mes_action.detail`、`mes_action.execute` 等基础工具。只有客户端必须直观看到 `mes.<动作编码>` 时才开启动态工具展开。",
+                    "",
+                    "## 写入规则",
+                    "",
+                    "- `preview` 不写入业务数据。",
+                    "- `confirm_required` 生成待确认调用，不直接写入。",
+                    "- `commit` 只有凭证最高执行模式允许时才真实提交。",
+                    "- 写入类 `confirm_required` 和 `commit` 必须有幂等键；MCP 会为单次工具调用自动生成，跨重试批处理应显式传入同一个 `idempotencyKey`。",
+                    "- `mes_action.execute` 返回执行信封，真实业务返回在 `data` 字段；`invocationId` 是 AI 调用日志 / 待确认单的标识。",
+                    "- 待确认单按公司/租户隔离，必须由生成确认单的同一公司下有权限的账号审批。",
+                    "",
+                    "## 读取和分页",
+                    "",
+                    "- `mes_api.read` 只用于普通业务只读接口，不用于 `/integration/agent/*`。",
+                    "- MES 分页 `pageSize` 最大为 100；MCP 会裁剪超限值，并通过 `_mcpWarnings` 返回提示。",
+                    "- 如果只读路径被提示需要动态业务动作，请改用 `mes_action.list/detail/execute` 查找并调用对应 actionCode。",
+                    "",
+                    "## 防误连",
+                    "",
+                    "- MCP 启动时会在 stderr 打印 MES 地址、Token 用户名、apiKeyId、agentClientId 和动态工具状态。",
+                    "- 可配置 `MES_EXPECTED_USERNAME`、`MES_EXPECTED_AGENT_CLIENT_ID`、`MES_EXPECTED_API_KEY_ID` 做本地启动校验，避免使用旧 `.env` 误连错误账号或凭证。",
+                    "",
+                    "## 禁止事项",
+                    "",
+                    "- 不猜客户、物料、BOM、工艺路线、仓库、批次、数量、价格等关键业务事实。",
+                    "- 不通过 `mes_api.read` 调用创建、更新、删除、确认、下达等写入接口。",
+                    "- 不绕过当前账号权限、公司隔离、状态机、库存规则、质量规则和审计。",
+                ].join("\n"),
+            },
+        ],
+    }));
 }

package/dist/tools/register-tools.js

@@ -1,4 +1,6 @@
+import { randomUUID } from "node:crypto";
 import { z } from "zod";
+const MAX_MES_PAGE_SIZE = 100;
 const ExecutionModeSchema = z
     .enum(["preview", "confirm_required", "commit"])
     .optional();
@@ -10,30 +12,101 @@ 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()
         .describe("MES 页面业务动作请求体；也可以直接把 DTO 字段放在顶层。"),
 })
     .passthrough();
-function formatToolResult(result) {
+function withWarnings(result, warnings) {
+    if (result && typeof result === "object" && !Array.isArray(result)) {
+        return {
+            ...result,
+            ...(warnings.length > 0 ? { _mcpWarnings: warnings } : {}),
+        };
+    }
+    return {
+        value: result,
+        ...(warnings.length > 0 ? { _mcpWarnings: warnings } : {}),
+    };
+}
+function formatToolResult(result, warnings = []) {
+    const structuredContent = withWarnings(result, warnings);
+    return {
+        structuredContent,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(structuredContent, null, 2),
+            },
+        ],
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function errorHints(message) {
+    const hints = [];
+    if (/pageSize/i.test(message)) {
+        hints.push("MES 分页上限是 100；MCP 会对 mes_api.read 和 mes_action.list 自动裁剪 pageSize。");
+    }
+    if (message.includes("AI Agent 凭证只能访问动态业务动作接口")) {
+        hints.push("请改用 mes_action.list/detail/execute 查找并调用对应 actionCode。");
+    }
+    if (message.includes("最高只允许")) {
+        hints.push("请改用 preview/confirm_required，或重新创建允许 commit 的 AI 凭证。");
+    }
+    if (message.includes("待确认 AI 调用不存在")) {
+        hints.push("确认单按公司/租户隔离；请切回生成确认单的同一公司账号审批。");
+    }
+    return hints;
+}
+function formatToolError(error, context) {
+    const message = errorMessage(error);
+    const structuredContent = {
+        error: {
+            message,
+            toolName: context.toolName,
+            ...(context.actionCode ? { actionCode: context.actionCode } : {}),
+            ...(context.path ? { path: context.path } : {}),
+            hints: errorHints(message),
+        },
+    };
     return {
-        structuredContent: result && typeof result === "object" && !Array.isArray(result)
-            ? result
-            : { value: result },
+        isError: true,
+        structuredContent,
         content: [
             {
                 type: "text",
-                text: JSON.stringify(result, null, 2),
+                text: JSON.stringify(structuredContent, null, 2),
             },
         ],
     };
 }
+async function runTool(context, handler) {
+    try {
+        return await handler();
+    }
+    catch (error) {
+        return formatToolError(error, context);
+    }
+}
+function normalizePageSize(payload, warnings) {
+    const pageSize = payload.pageSize;
+    if (typeof pageSize !== "number" || pageSize <= MAX_MES_PAGE_SIZE) {
+        return payload;
+    }
+    warnings.push({
+        code: "pageSize_clamped",
+        message: `MES pageSize 最大为 ${MAX_MES_PAGE_SIZE}，已从 ${pageSize} 自动调整为 ${MAX_MES_PAGE_SIZE}。`,
+    });
+    return { ...payload, pageSize: MAX_MES_PAGE_SIZE };
+}
 export function registerAgentTools(server, client) {
     server.registerTool("mes_api.read", {
         title: "Read MES API",
-        description: "按当前 MES 账号权限读取系统内业务信息。仅用于 list/detail/view/read/export/stats/options 等只读类 POST 接口；创建、更新、删除、确认、下达等写入动作必须使用专门的 Agent 工具。",
+        description: "按当前 MES 账号权限读取系统内业务信息。仅用于普通业务的 list/detail/view/read/export/stats/options 等只读类 POST 接口；创建、更新、删除、确认、下达等写入动作必须使用 mes_action.execute。分页 pageSize 最大为 100，MCP 会自动裁剪超限值并在 _mcpWarnings 中提示。",
         inputSchema: z
             .object({
             path: z
@@ -52,14 +125,18 @@ export function registerAgentTools(server, client) {
             idempotentHint: true,
         },
     }, async (args) => {
-        const parsed = z
-            .object({
-            path: z.string().min(1),
-            payload: z.record(z.string(), z.unknown()).optional(),
-        })
-            .parse(args);
-        const result = await client.postApiPath(parsed.path, parsed.payload ?? {});
-        return formatToolResult(result);
+        return runTool({ toolName: "mes_api.read" }, async () => {
+            const parsed = z
+                .object({
+                path: z.string().min(1),
+                payload: z.record(z.string(), z.unknown()).optional(),
+            })
+                .parse(args);
+            const warnings = [];
+            const payload = normalizePageSize(parsed.payload ?? {}, warnings);
+            const result = await client.postApiPath(parsed.path, payload);
+            return formatToolResult(result, warnings);
+        });
     });
 }
 function normalizeDynamicArgs(args) {
@@ -71,19 +148,28 @@ 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 执行。";
+    const resultText = "返回格式固定为 { actionCode, executionMode, status, invocationId, bizObjectType, bizObjectId, data }；真实业务返回在 data 字段。";
     return [
         action.description,
         `页面接口：POST ${action.path}。`,
         action.inputDto ? `请求 DTO：${action.inputDto}。` : undefined,
         permissionText,
         modeText,
+        resultText,
     ]
         .filter(Boolean)
         .join("\n");
@@ -109,8 +195,24 @@ function registerGenericActionTools(server, client) {
             idempotentHint: true,
         },
     }, async (args) => {
-        const result = await client.post("/integration/agent/actions/list", args ?? {});
-        return formatToolResult(result);
+        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(),
+                module: z.string().optional(),
+                resource: z.string().optional(),
+                operation: z.string().optional(),
+                write: z.boolean().optional(),
+            })
+                .passthrough()
+                .parse(args ?? {});
+            const warnings = [];
+            const payload = normalizePageSize(parsed, warnings);
+            const result = await client.post("/integration/agent/actions/list", payload);
+            return formatToolResult(result, warnings);
+        });
     });
     server.registerTool("mes_action.detail", {
         title: "Get MES business action detail",
@@ -124,12 +226,19 @@ function registerGenericActionTools(server, client) {
             idempotentHint: true,
         },
     }, async (args) => {
-        const result = await client.post("/integration/agent/actions/detail", args ?? {});
-        return formatToolResult(result);
+        return runTool({ toolName: "mes_action.detail" }, async () => {
+            const parsed = z
+                .object({
+                actionCode: z.string().min(1),
+            })
+                .parse(args ?? {});
+            const result = await client.post("/integration/agent/actions/detail", parsed);
+            return formatToolResult(result);
+        });
     });
     server.registerTool("mes_action.execute", {
         title: "Execute MES business action",
-        description: "执行一个由 mes_action.list 发现的 MES 页面业务动作。后端复用页面 Controller、DTO、权限、租户、状态机和调用日志。",
+        description: "执行一个由 mes_action.list 发现的 MES 页面业务动作。后端复用页面 Controller、DTO、权限、租户、状态机和调用日志。返回体是执行信封：真实业务结果在 data 字段；confirm_required 返回待确认 invocationId，必须由同一公司/租户下有权限的账号审批。",
         inputSchema: z
             .object({
             actionCode: z.string().min(1),
@@ -144,23 +253,29 @@ function registerGenericActionTools(server, client) {
             idempotentHint: true,
         },
     }, async (args) => {
-        const parsed = z
-            .object({
-            actionCode: z.string().min(1),
-            executionMode: ExecutionModeSchema,
-            idempotencyKey: z.string().min(1).max(160).optional(),
-            payload: z.record(z.string(), z.unknown()).optional(),
-        })
-            .passthrough()
-            .parse(args ?? {});
-        const { actionCode, executionMode, idempotencyKey, payload, ...rest } = parsed;
-        const result = await client.post("/integration/agent/actions/execute", {
-            actionCode,
-            executionMode,
-            idempotencyKey,
-            payload: payload ?? rest,
+        return runTool({ toolName: "mes_action.execute" }, async () => {
+            const parsed = z
+                .object({
+                actionCode: z.string().min(1),
+                executionMode: ExecutionModeSchema,
+                idempotencyKey: z.string().min(1).max(160).optional(),
+                payload: z.record(z.string(), z.unknown()).optional(),
+            })
+                .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 ??
+                    (shouldEnsureIdempotencyKey(action, executionMode)
+                        ? buildIdempotencyKey(actionCode)
+                        : undefined),
+                payload: payload ?? rest,
+            });
+            return formatToolResult(result);
         });
-        return formatToolResult(result);
     });
 }
 async function registerDynamicBusinessActionTools(server, client) {
@@ -181,18 +296,26 @@ async function registerDynamicBusinessActionTools(server, client) {
                 idempotentHint: true,
             },
         }, async (args) => {
-            const normalized = normalizeDynamicArgs(args);
-            const result = await client.post("/integration/agent/actions/execute", {
-                actionCode: action.actionCode,
-                ...normalized,
+            return runTool({ toolName, actionCode: action.actionCode }, async () => {
+                const normalized = normalizeDynamicArgs(args);
+                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);
             });
-            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.2",
   "type": "module",
   "description": "MES MCP adapter for Marvis and AI agents",
   "license": "UNLICENSED",