mes-mcp 0.2.1 → 0.2.3

package/README.md

@@ -23,6 +23,36 @@ MES_REGISTER_DYNAMIC_TOOLS=false
 
 `MES_REGISTER_DYNAMIC_TOOLS` 默认关闭。关闭时 MCP 只注册稳定接口工具，通过后端动作目录发现并执行全部授权业务能力；打开后会把所有授权页面动作额外展开成 `mes.<动作编码>` 工具，适合明确需要工具直出且客户端能承载大量工具的场景。
 
+## 运行
+
+正式接入推荐用 `npx` 拉取 npm 上的最新版本，不需要全局安装：
+
+```bash
+npx -y mes-mcp@latest
+```
+
+MCP 客户端配置建议使用：
+
+```json
+{
+  "mcpServers": {
+    "mes-mcp": {
+      "command": "npx",
+      "args": ["-y", "mes-mcp@latest"],
+      "env": {
+        "MES_BASE_URL": "https://your-mes.example.com",
+        "MES_API_PREFIX": "/api",
+        "MES_AGENT_TOKEN": "BearerTokenWithoutBearerPrefix",
+        "MES_TIMEOUT_MS": "30000",
+        "MES_REGISTER_DYNAMIC_TOOLS": "false"
+      }
+    }
+  }
+}
+```
+
+`npx` 会在 MCP 客户端启动或重连时使用 npm 上的最新版本；已经运行中的 `mes-mcp` 进程不会热更新，发版后需要重启或刷新当前 AI 助手的 MCP 连接。
+
 ## 开发
 
 ```bash

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

@@ -1,3 +1,28 @@
+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;
@@ -21,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);
         }

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) {
@@ -20,16 +24,71 @@ function optionalBooleanEnv(name, fallback) {
         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,12 +6,46 @@ 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.3",
     });
     await registerAllAgentTools(server, client, {
         registerDynamicTools: config.registerDynamicTools,

package/dist/prompts/register-prompts.js

@@ -16,6 +16,8 @@ export function registerMesPrompts(server) {
                         "你是 MES 业务助手，必须按当前账号权限和工具返回结果执行。",
                         "不要猜测客户、物料、BOM、工艺路线、仓库等关键主数据；缺失时先查询或要求用户确认。",
                         "默认先用 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；preview 不写入，confirm_required 生成待确认记录，commit 只有凭证允许时才真实提交。",
                         context ? `当前上下文：${context}` : "",

package/dist/resources/register-resources.js

@@ -40,6 +40,7 @@ export function registerMesResources(server, client) {
                     "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.<动作编码>` 时才开启动态工具展开。",
                     "",
                     "## 写入规则",
                     "",
@@ -47,6 +48,19 @@ export function registerMesResources(server, client) {
                     "- `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` 误连错误账号或凭证。",
                     "",
                     "## 禁止事项",
                     "",

package/dist/tools/register-tools.js

@@ -1,5 +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();
@@ -18,23 +19,94 @@ const DynamicActionSchema = z
         .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
@@ -53,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) {
@@ -86,12 +162,14 @@ function actionDescription(action) {
     const modeText = action.isWrite
         ? "写入动作，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");
@@ -117,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",
@@ -132,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),
@@ -152,27 +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 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 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) {
@@ -193,16 +296,18 @@ 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,
-                idempotencyKey: normalized.idempotencyKey ??
-                    (shouldEnsureIdempotencyKey(action, normalized.executionMode)
-                        ? buildIdempotencyKey(action.actionCode)
-                        : undefined),
+            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);
         });
     }
 }

package/package.json

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