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_REGISTER_DYNAMIC_TOOLS=false

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

开发

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。后端只放行只读类接口，写入动作必须使用动态业务动作；读取调用会在 MES AI 调用日志里记录路径、请求摘要和结果摘要。

写入类工具支持 executionMode：

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

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

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 执行创建、审批、确认、排产、质检、出库等页面业务动作。