MES MCP

MES MCP 是 MES 开放集成体系的 MCP 协议适配层，用于 Marvis 或其他 AI Agent 调用 MES 的后端动态业务动作目录。

边界

• 只负责 MCP 工具、资源、提示词和协议输入输出。
• 写入类工具只调用 mes-node 的 /integration/agent/* 接口；通用读取工具只调用当前账号可读的业务接口。
• 不直连数据库，不复制 MES 业务 Service，不绕过 companyId、RBAC、状态机、库存、质量和审计规则。
• 不保存用户明文账号密码；运行时使用 mes-node 创建的 agent_mcp 连接凭证 JWT。

配置

复制 .env.example 为 .env，填入开放集成里生成的 AI 智能体凭证：

MES_BASE_URL=http://127.0.0.1:6033
MES_API_PREFIX=/api
MES_AGENT_TOKEN=BearerTokenWithoutBearerPrefix
MES_TIMEOUT_MS=30000
MES_MAX_CONCURRENT_REQUESTS=4
MES_MAX_QUEUED_REQUESTS=8
MES_REGISTER_DYNAMIC_TOOLS=false

MES_REGISTER_DYNAMIC_TOOLS 默认关闭。关闭时 MCP 只注册稳定接口工具，通过后端动作目录发现并执行全部授权业务能力；打开后会把所有授权页面动作额外展开成 mes.<动作编码> 工具，适合明确需要工具直出且客户端能承载大量工具的场景。

运行

正式接入推荐用 npx 拉取 npm 上的最新版本，不需要全局安装：

npx -y mes-mcp@latest

MCP 客户端配置建议使用：

{
  "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 连接。

开发

npm install
npm run build
npm run dev

工具

默认使用后端动态业务动作接口：

• mes_action.list：查询当前凭证和当前账号权限允许调用的 MES 页面业务动作。
• mes_action.detail：查看某个业务动作的路径、权限、DTO 名称和输入 schema。
• mes_action.execute：按动作编码执行业务动作。
• 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 为准。

写入类动作通过 confirm_required 或 commit 执行时需要幂等键。调用方没有显式传入时，mes-mcp 会为当前工具调用生成一条集成幂等键；需要跨重试严格复用同一幂等键的批处理场景，仍建议调用方显式传入 idempotencyKey。

• mes_api.read：按当前 MES 账号权限读取普通业务接口，例如 /sale-order/list、/material/detail。支持 GET 和 POST；GET 查询条件放在 payload，POST 使用 JSON 请求体。后端只放行声明读取权限的路由和明确标记的账号级读取路由，写入动作必须使用动态业务动作。二进制下载和导出以 MCP 文件资源返回。
• mes_manual.list：列出正式 MES 产品手册和 App 操作手册的章节目录。
• mes_manual.search：按自然语言检索完整操作手册和 AI 操作指引；结果包含章节摘要和命中摘录。
• mes_manual.get：按章节 ID 读取完整 Markdown 内容；章节 ID 可从 mes_manual.list 或 mes_manual.search 结果中获取。
• mes://agent/context：MES Agent 通用操作边界、工具顺序和安全规则。
• mes://manuals/{id}：按章节读取正式产品手册或 App 操作手册全文；resources/list 会列出可读章节。
• mes://flows/sale-delivery：销售出库上下文资源，只描述读取顺序和阻断处理；可出库状态、库存和质量判断仍以后端接口返回为准。

写入类工具支持 executionMode：

• preview：只预览，不写入。
• confirm_required：生成待确认单，不写入；后端要求幂等键，未传时 MCP 会为本次工具调用自动生成。
• commit：提交到 MES，按当前账号权限、工具白名单、业务规则和幂等键执行；后端要求幂等键，未传时 MCP 会为本次工具调用自动生成。

跨重试或批处理场景如果需要严格复用同一次业务请求，调用方应显式传入同一个 idempotencyKey；单次交互式调用可以依赖 MCP 自动生成。

mes_action.execute 的文件字段使用 { "fileName", "mimeType", "contentBase64" }，多个文件使用 files 数组。Agent 通道单文件最大 10 MiB，多文件请求总内容最大 12 MiB，单次最多 20 个文件；业务接口自身的文件格式、租户归属和权限校验仍由 mes-node 执行。由于待确认记录不保存文件正文，含文件的写入只允许使用凭证策略允许的 commit 模式，并必须提供幂等键。Agent 下载/导出响应最大 50 MiB，超限时应使用普通 API Token 直接调用对应业务接口。

普通 API Token 与 AI Agent 凭证是两种用途不同的凭证：普通 API Token 可按所属用户现有认证、RBAC 和租户规则直接调用普通 MES 业务 API；AI Agent 凭证通过动态动作目录执行写入、通过 mes_api.read 执行读取，并继续受工具范围与执行策略控制。

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 识别成结构化草稿，再用 mes_api.read 或动态列表动作查询客户、物料等主数据，最后通过 mes_action.detail 和 mes_action.execute 执行创建、审批、确认、排产、质检、出库等页面业务动作。