mes-mcp 0.1.0

package/.env.example

@@ -0,0 +1,4 @@
+MES_BASE_URL=http://127.0.0.1:6033
+MES_API_PREFIX=/api
+MES_AGENT_TOKEN=
+MES_TIMEOUT_MS=30000

package/README.md

@@ -0,0 +1,60 @@
+# MES MCP
+
+MES MCP 是 MES 开放集成体系的 MCP 协议适配层，用于 Marvis 或其他 AI Agent 调用 MES 的 Agent OpenAPI 合同。
+
+## 边界
+
+- 只负责 MCP 工具、资源、提示词和协议输入输出。
+- 写入类工具只调用 `mes-node` 的 `/integration/agent/*` 接口；通用读取工具只调用账号权限内的只读业务接口。
+- 不直连数据库，不复制 MES 业务 Service，不绕过 `companyId`、RBAC、状态机、库存、质量和审计规则。
+- 不保存用户明文账号密码；运行时使用 `mes-node` 创建的 `agent_mcp` 连接凭证 JWT。
+
+## 配置
+
+复制 `.env.example` 为 `.env`，填入开放集成里生成的 AI 智能体凭证：
+
+```bash
+MES_BASE_URL=http://127.0.0.1:6033
+MES_API_PREFIX=/api
+MES_AGENT_TOKEN=BearerTokenWithoutBearerPrefix
+MES_TIMEOUT_MS=30000
+```
+
+## 开发
+
+```bash
+npm install
+npm run build
+npm run dev
+```
+
+## 工具
+
+工具名与 `mes-node` Agent 合同编码一致：
+
+- `document_intake.parse`
+- `customer.match`
+- `material.match`
+- `sale_order.create`
+- `sale_order.confirm`
+- `production_plan.create_from_sale_order`
+- `work_order.create_from_plan`
+- `work_order.release`
+- `sale_order.query`
+- `work_order.query`
+- `inventory.query`
+- `mes_api.read`：按当前 MES 账号权限读取普通业务接口，例如 `/sale-order/list`、`/material/detail`。后端只放行只读类接口，写入动作必须使用专门 Agent 工具；读取调用会在 MES AI 调用日志里记录路径、请求摘要和结果摘要。
+
+写入类工具支持 `executionMode`：
+
+- `preview`：只预览，不写入。
+- `confirm_required`：返回待确认内容，不写入。
+- `commit`：提交到 MES，按当前账号权限、工具白名单、业务规则和幂等键执行。
+
+## Marvis 接入建议
+
+1. 在 MES 管理端“开放集成”创建凭证，类型选择 AI 智能体。
+2. `agentClientId` 建议填写 `marvis` 或具体渠道名。
+3. 授权范围建议先选“跟随账号权限”，最高执行模式建议先用 `confirm_required`；如果只想开放少量动作，再切换为“仅允许指定工具”。只读型 AI 凭证可以只选择 `mes_api.read`。
+4. 将返回的 JWT 配置为 `MES_AGENT_TOKEN`。
+5. Marvis 侧通过 MCP 调用工具；图片、PDF、Excel 可先由 Marvis 识别成结构化草稿，再调用 `document_intake.parse`、`customer.match`、`material.match` 和后续写入工具。

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

@@ -0,0 +1,152 @@
+export class MesAgentApiClient {
+    config;
+    static WRITE_PATH_TOKENS = new Set([
+        "create",
+        "update",
+        "delete",
+        "remove",
+        "revoke",
+        "toggle",
+        "confirm",
+        "cancel",
+        "approve",
+        "reject",
+        "release",
+        "start",
+        "complete",
+        "close",
+        "submit",
+        "import",
+        "run",
+        "cleanup",
+        "rotate",
+        "test",
+        "retry",
+        "allocate",
+        "unallocate",
+        "reverse",
+        "convert",
+        "send",
+        "recall",
+        "scrap",
+        "activate",
+        "deprecate",
+        "purge",
+        "adjust",
+        "freeze",
+        "end",
+        "configure",
+        "generate",
+        "save",
+        "copy",
+        "archive",
+        "publish",
+        "restore",
+        "execute",
+        "handle",
+        "verify",
+        "pass",
+        "fail",
+        "lock",
+        "unlock",
+        "enable",
+        "disable",
+        "bind",
+        "unbind",
+        "link",
+        "unlink",
+        "upload",
+        "assign",
+        "claim",
+        "dispatch",
+        "receive",
+        "issue",
+        "return",
+        "split",
+        "mark",
+        "change",
+        "transfer",
+        "in",
+        "out",
+    ]);
+    static WRITE_PATH_SEGMENTS = new Set([
+        "report",
+        "quick-report",
+        "report-operation",
+        "report-direct",
+        "batch-report",
+    ]);
+    constructor(config) {
+        this.config = config;
+    }
+    async post(path, payload) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            const response = await fetch(this.buildUrl(path), {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.config.mesAgentToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(payload ?? {}),
+                signal: controller.signal,
+            });
+            const text = await response.text();
+            const body = this.parseBody(text);
+            if (!response.ok) {
+                const message = body?.msg || body?.message || text || response.statusText;
+                throw new Error(`MES ${response.status}: ${message}`);
+            }
+            if (body && typeof body.code === "number" && body.code !== 0) {
+                throw new Error(body.msg || body.message || `MES code ${body.code}`);
+            }
+            return (body && "data" in body ? body.data : body);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async postApiPath(path, payload) {
+        if (/^https?:\/\//i.test(path) || path.includes("..")) {
+            throw new Error("MES API path must be a relative API path");
+        }
+        const normalized = path.replace(/^\/+api\/?/i, "/").replace(/^\/?/, "/");
+        if (/^\/integration\/agent(\/|$)/i.test(normalized)) {
+            throw new Error("Use dedicated Agent tools for /integration/agent paths");
+        }
+        if (this.isWriteLikePath(normalized)) {
+            throw new Error("mes_api.read only supports read-only MES API paths");
+        }
+        return this.post(normalized, payload);
+    }
+    isWriteLikePath(path) {
+        const actionSegments = path
+            .toLowerCase()
+            .split(/[?#]/)[0]
+            .split("/")
+            .filter(Boolean);
+        const lastSegment = actionSegments[actionSegments.length - 1] ?? "";
+        if (MesAgentApiClient.WRITE_PATH_SEGMENTS.has(lastSegment)) {
+            return true;
+        }
+        return lastSegment
+            .split(/[._-]+/)
+            .filter(Boolean)
+            .some((token) => MesAgentApiClient.WRITE_PATH_TOKENS.has(token));
+    }
+    buildUrl(path) {
+        const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+        return `${this.config.mesBaseUrl}${this.config.mesApiPrefix}${normalizedPath}`;
+    }
+    parseBody(text) {
+        if (!text)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/config.js

@@ -0,0 +1,24 @@
+import "dotenv/config";
+function optionalEnv(name, fallback) {
+    const value = process.env[name]?.trim();
+    return value && value.length > 0 ? value : fallback;
+}
+function requiredEnv(name) {
+    const value = process.env[name]?.trim();
+    if (!value) {
+        throw new Error(`${name} is required`);
+    }
+    return value;
+}
+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");
+    }
+    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"),
+        timeoutMs,
+    };
+}

package/dist/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { MesAgentApiClient } from "./clients/mes-agent-api.client.js";
+import { registerMesPrompts } from "./prompts/register-prompts.js";
+import { registerMesResources } from "./resources/register-resources.js";
+import { registerAgentTools } from "./tools/register-tools.js";
+async function main() {
+    const config = loadConfig();
+    const client = new MesAgentApiClient(config);
+    const server = new McpServer({
+        name: "mes-mcp",
+        version: "0.1.0",
+    });
+    registerAgentTools(server, client);
+    registerMesResources(server, client);
+    registerMesPrompts(server);
+    await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/prompts/register-prompts.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export function registerMesPrompts(server) {
+    server.registerPrompt("mes_order_to_work_order", {
+        title: "MES order to work order flow",
+        description: "把图片/文本订单录入 MES 并逐步生成销售订单、生产计划和工单的标准提示词。",
+        argsSchema: {
+            context: z.string().optional(),
+        },
+    }, ({ context }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "你是 MES 业务助手，必须按当前账号权限和工具返回结果执行。",
+                        "不要猜测客户、物料、BOM、工艺路线、仓库等关键主数据；缺失时先查询或要求用户确认。",
+                        "推荐流程：document_intake.parse -> customer.match / material.match -> sale_order.create -> sale_order.confirm -> production_plan.create_from_sale_order -> work_order.create_from_plan -> work_order.release。",
+                        "写入类动作默认先使用 confirm_required 或 preview；用户明确确认后再使用 commit，并传 idempotencyKey。",
+                        context ? `当前上下文：${context}` : "",
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            },
+        ],
+    }));
+}

package/dist/resources/register-resources.js

@@ -0,0 +1,21 @@
+export function registerMesResources(server, client) {
+    server.registerResource("mes_agent_contracts", "mes://agent/contracts", {
+        title: "MES Agent Contracts",
+        description: "当前 AI 凭证允许调用的 MES Agent 合同列表。",
+        mimeType: "application/json",
+    }, async (uri) => {
+        const contracts = await client.post("/integration/agent/contracts/list", {
+            page: 1,
+            pageSize: 100,
+        });
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify(contracts, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/agent-tools.js

@@ -0,0 +1,209 @@
+import { z } from "zod";
+const ExecutionModeSchema = z
+    .enum(["preview", "confirm_required", "commit"])
+    .optional();
+const IdempotencySchema = z.string().min(1).max(160).optional();
+const QuerySchema = z
+    .object({
+    page: z.number().int().positive().optional(),
+    pageSize: z.number().int().positive().max(100).optional(),
+    keyword: z.string().optional(),
+})
+    .passthrough();
+export const AGENT_TOOL_SPECS = [
+    {
+        name: "document_intake.parse",
+        title: "Parse order document",
+        description: "接收 Marvis/上游 AI 从图片、PDF、Excel、文本中识别出的订单资料，返回可确认的销售订单草稿。",
+        path: "/integration/agent/document-intake/parse",
+        readOnlyHint: true,
+        schema: z
+            .object({
+            executionMode: ExecutionModeSchema,
+            idempotencyKey: IdempotencySchema,
+            rawText: z.string().optional(),
+            imageUrl: z.string().url().optional(),
+            fileUrl: z.string().url().optional(),
+            extractedOrder: z
+                .object({
+                orderNo: z.string().optional(),
+                customerId: z.string().uuid().optional(),
+                customerName: z.string().optional(),
+                deliveryDate: z.string().optional(),
+                remarks: z.string().optional(),
+                items: z
+                    .array(z
+                    .object({
+                    materialId: z.string().uuid().optional(),
+                    materialCode: z.string().optional(),
+                    materialName: z.string().optional(),
+                    quantity: z.number().positive().optional(),
+                    unitPrice: z.number().min(0).optional(),
+                    remarks: z.string().optional(),
+                })
+                    .passthrough())
+                    .optional(),
+            })
+                .passthrough()
+                .optional(),
+            sourceMeta: z.record(z.string(), z.unknown()).optional(),
+        })
+            .passthrough(),
+    },
+    {
+        name: "customer.match",
+        title: "Match customer",
+        description: "按当前 MES 账号权限匹配启用中的客户主数据；创建销售单前用于确认客户 ID，避免 AI 直接猜测客户。",
+        path: "/integration/agent/customer/match",
+        readOnlyHint: true,
+        schema: QuerySchema.extend({
+            customerCode: z.string().optional(),
+            name: z.string().optional(),
+            contactName: z.string().optional(),
+            contactPhone: z.string().optional(),
+        }).passthrough(),
+    },
+    {
+        name: "material.match",
+        title: "Match material",
+        description: "按当前 MES 账号权限匹配启用中的物料主数据；创建销售单前用于确认物料 ID，避免用图片识别文本直接写入。",
+        path: "/integration/agent/material/match",
+        readOnlyHint: true,
+        schema: QuerySchema.extend({
+            code: z.string().optional(),
+            name: z.string().optional(),
+            spec: z.string().optional(),
+            barcode: z.string().optional(),
+        }).passthrough(),
+    },
+    {
+        name: "sale_order.create",
+        title: "Create sale order",
+        description: "按当前 MES 账号权限创建销售订单；commit 才写入，preview/confirm_required 只返回待确认内容。",
+        path: "/integration/agent/sale-order/create",
+        destructiveHint: true,
+        schema: z
+            .object({
+            executionMode: ExecutionModeSchema,
+            idempotencyKey: IdempotencySchema,
+            orderNo: z.string().optional(),
+            customerId: z.string().uuid().optional(),
+            salesRepId: z.string().uuid().optional(),
+            deliveryDate: z.string().optional(),
+            paymentTerms: z.string().optional(),
+            remarks: z.string().optional(),
+            items: z.array(z
+                .object({
+                materialId: z.string().uuid(),
+                quantity: z.number().positive(),
+                unitPrice: z.number().min(0).optional(),
+                customerMaterialCode: z.string().optional(),
+                customerMaterialName: z.string().optional(),
+                customerMaterialSpec: z.string().optional(),
+                remarks: z.string().optional(),
+            })
+                .passthrough()),
+        })
+            .passthrough(),
+    },
+    {
+        name: "sale_order.confirm",
+        title: "Confirm sale order",
+        description: "确认销售订单，复用 MES 的审批门控、状态规则和明细校验；销售订单转生产计划前必须先确认。",
+        path: "/integration/agent/sale-order/confirm",
+        destructiveHint: true,
+        schema: z
+            .object({
+            executionMode: ExecutionModeSchema,
+            idempotencyKey: IdempotencySchema,
+            id: z.string().uuid(),
+        })
+            .passthrough(),
+    },
+    {
+        name: "production_plan.create_from_sale_order",
+        title: "Create production plan from sale order",
+        description: "将已确认销售订单转为生产计划，复用 MES 原有数量、BOM 和工艺校验。",
+        path: "/integration/agent/production-plan/create-from-sale-order",
+        destructiveHint: true,
+        schema: z
+            .object({
+            executionMode: ExecutionModeSchema,
+            idempotencyKey: IdempotencySchema,
+            saleOrderId: z.string().uuid(),
+            planStartDate: z.string(),
+            planEndDate: z.string(),
+            priority: z.number().int().min(1).max(10).optional(),
+            description: z.string().optional(),
+            items: z.array(z
+                .object({
+                saleOrderItemId: z.string().uuid(),
+                requiredQty: z.number().positive().optional(),
+                plannedLossRate: z.number().min(0).optional(),
+                plannedQty: z.number().positive().optional(),
+                bomHeaderId: z.string().uuid().optional(),
+                routeId: z.string().uuid().optional(),
+            })
+                .passthrough()),
+        })
+            .passthrough(),
+    },
+    {
+        name: "work_order.create_from_plan",
+        title: "Create work order from production plan",
+        description: "确认生产计划并自动创建工单，复用 MES 的 BOM 展开和工艺工序生成规则。",
+        path: "/integration/agent/work-order/create-from-plan",
+        destructiveHint: true,
+        schema: z
+            .object({
+            executionMode: ExecutionModeSchema,
+            idempotencyKey: IdempotencySchema,
+            planId: z.string().uuid(),
+            routeId: z.string().uuid().optional(),
+            bomHeaderId: z.string().uuid().optional(),
+            assigneeId: z.string().uuid().optional(),
+            receiptWarehouseId: z.string().uuid().optional(),
+        })
+            .passthrough(),
+    },
+    {
+        name: "work_order.release",
+        title: "Release work order",
+        description: "下达工单，复用 MES 状态机、审批门控、物料需求展开和事件推送。",
+        path: "/integration/agent/work-order/release",
+        destructiveHint: true,
+        schema: z
+            .object({
+            executionMode: ExecutionModeSchema,
+            idempotencyKey: IdempotencySchema,
+            id: z.string().uuid(),
+            assigneeId: z.string().uuid().optional(),
+            receiptWarehouseId: z.string().uuid().optional(),
+        })
+            .passthrough(),
+    },
+    {
+        name: "sale_order.query",
+        title: "Query sale orders",
+        description: "按当前 MES 账号权限查询销售订单列表。",
+        path: "/integration/agent/sale-order/query",
+        readOnlyHint: true,
+        schema: QuerySchema,
+    },
+    {
+        name: "work_order.query",
+        title: "Query work orders",
+        description: "按当前 MES 账号权限查询工单列表。",
+        path: "/integration/agent/work-order/query",
+        readOnlyHint: true,
+        schema: QuerySchema,
+    },
+    {
+        name: "inventory.query",
+        title: "Query inventory",
+        description: "按当前 MES 账号权限查询库存现有量和可用量。",
+        path: "/integration/agent/inventory/query",
+        readOnlyHint: true,
+        schema: QuerySchema,
+    },
+];

package/dist/tools/register-tools.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { AGENT_TOOL_SPECS } from "./agent-tools.js";
+function formatToolResult(result) {
+    return {
+        structuredContent: result && typeof result === "object" && !Array.isArray(result)
+            ? result
+            : { value: result },
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+}
+export function registerAgentTools(server, client) {
+    for (const spec of AGENT_TOOL_SPECS) {
+        server.registerTool(spec.name, {
+            title: spec.title,
+            description: spec.description,
+            inputSchema: spec.schema,
+            annotations: {
+                readOnlyHint: spec.readOnlyHint ?? false,
+                destructiveHint: spec.destructiveHint ?? false,
+                idempotentHint: true,
+            },
+        }, async (args) => {
+            const result = await client.post(spec.path, args ?? {});
+            return formatToolResult(result);
+        });
+    }
+    server.registerTool("mes_api.read", {
+        title: "Read MES API",
+        description: "按当前 MES 账号权限读取系统内业务信息。仅用于 list/detail/view/read/export/stats/options 等只读类 POST 接口；创建、更新、删除、确认、下达等写入动作必须使用专门的 Agent 工具。",
+        inputSchema: z
+            .object({
+            path: z
+                .string()
+                .min(1)
+                .describe("MES API 相对路径，例如 /sale-order/list 或 /api/material/detail"),
+            payload: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("POST 请求体，按对应 MES 页面接口参数传入"),
+        })
+            .passthrough(),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            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);
+    });
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "mes-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MES MCP adapter for Marvis and AI agents",
+  "license": "UNLICENSED",
+  "main": "dist/index.js",
+  "bin": {
+    "mes-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.29",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  }
+}