MCP OMS MCP 技术架构安全 · 调用链 · 工具面 · 共创资料
商派 OMS · Agentic Commerce 技术共创

OMS MCP 技术架构文档

OMS MCP 是大模型访问 OMS 的受控中间层：标准 MCP 协议对外，固定 /mcp-api/v1/* 对内。 AI 只能调用已登记工具；每次请求验钥匙、验工牌、滤组织；写操作走「演习 → 批准 → 写入 → 回读」。 接入支持两种对等方式：本机 npx 拉起，或在内网远程搭建 MCP 服务后由助手连接调用。

89完整面已注册工具（stdio / full）
56HTTP 默认公共面工具
33internal / profile 工具
0直连数据库 / 任意 SQL

阅读地图

关注点章节一句话
系统怎么分层02 分层架构助手 → MCP → MCPAPI → Capability → DB
请求怎么走03 调用链固定正向链，反向同一条，模型不到达库
怎么防越权04 安全模型钥匙跟人走 + 实时工牌 + 部门滤镜
能改什么数据05 受控写入confirmation_token 一次性绑定
现在有哪些工具06 工具面以 mcp/src/server.ts 为 runtime 真相
环境前置07 部署PHP 升到 8.2；本地 npx 或远程 MCP 服务均可
环境硬前置：开通 OMS MCP 前，请将 OMS 运行环境（Web / CLI）升级到 PHP 8.2。低于 8.2 时请先升级，再安装 mcpapi、领取接入凭证；仅部署 MCP 进程而不升级 PHP，无法稳定办事。
接入方式：除本机用 npx shopex-oms-mcp-server 外，也可在内网远程搭建 MCP 服务（如 http://内网主机:8787/mcp），助手通过 URL + 会话请求头携带钥匙调用。两种接法门禁相同，按团队是否需要集中托管选择即可。

01 定位与设计原则

Why

要解决什么

查单、对账、异常定位、规则治理、开箱初始化靠人工；要让 AI 提效，又不能把密码、库连接或超管权限交给模型。

设计原则

  • 只走开好的门（工具白名单）
  • 权限跟人走（无独立超管钥匙）
  • 写操作先演习再批准
  • 公共面与完整面分离

真相顺序

  1. 当前 runtime 代码
  2. 已确认后端路由 / Capability
  3. server.ts 工具注册表
  4. 文档与测试（可能滞后）
一句话：标准 MCP 对接助手，固定接口进 OMS；调度链固定，门始终开在客户手里。 本页工具数量以 mcp/src/server.ts 的 FULL_TOOL_NAMES / TOOL_NAMES / INTERNAL_PROFILE_TOOL_NAMES 为准（2026-08 基线）。

02 分层架构

Architecture
L1 助手

Agent Host（Cursor / Hermes / OpenCode / Claude Desktop …）

理解自然语言、选择工具、展示结果。不持有 OMS DB 连接，不直接访问业务库。

L2 MCP

shopex-oms-mcp-server（Node.js + TypeScript + MCP SDK）

登记工具、校验入参（Zod）、管理 confirmation scope、按 surface 暴露公共面或完整面。传输：stdio（本地）或 Streamable HTTP（:8787/mcp）。

L3 MCPAPI

PHP app/mcpapi · 固定 /mcp-api/v1/*

Basic Client Credentials 认证、实时解析 owner 工牌权限、方法级 requirePermission、组织范围滤镜。禁止任意 SQL / 任意控制器穿透。

L4 业务

既有 Capability / Model / Service

复用 OMS 已验证业务路径（优先与 Vue / 后台同源 Capability），写行为落在业务契约而非平行旁路。

L5 数据

MySQL 等业务库

仅由 L4 访问。大模型、MCP Host、甚至 MCP Server 都不直连数据库。

Skill 文档四层（发现面）

  • 角色入口：客服台 / 运营塔 / 治理 / 开箱 / 经营 / 排障
  • 场景编排：连续工作流，不复制 domain 真相
  • 领域事实：订单、发货、售后、主数据等原子能力
  • 诊断层：日志 / 队列等，默认不进 HTTP 公共面

Runtime Surface 两层

  • public：HTTP 默认暴露（56）——业务角色可发现
  • full：stdio / internal profile（89）——含排障与底层治理原语
  • 文档分类 ≠ 代码权限：真正拦权在 MCPAPI 工牌
  • docs-only / pc-only / blocked 不进注册表
简单说：协议层标准化，业务层固定门；文档发现面分层，不等于绕过权限。

03 端到端调用链

Call Chain

3.1 正向链（人 → 数据）

用户意图
→
Agent Host
→
MCP Tool
→
Zod 校验
→
HTTP Client
Basic Auth
→
MCPAPI
Guard
→
Permission
+ Org Filter
→
Capability
→
DB

3.2 反向链（数据 → 人）

DB
→
业务结果
→
JSON 契约
→
MCP 封装
→
Agent 摘要
→
用户确认
步骤组件安全动作失败语义
1Agent 选工具只能看到当前 surface 已注册工具未知工具不可调用
2MCP Server入参 Zod strict；写操作绑定 session confirmationScope参数错误 / CONFIRMATION_REQUIRED
3mcpApiClientAuthorization: Basic …；会话级 Base URL / Client ID / Secret401 unauthorized
4mcpapi_auth_guard 密钥哈希比对；解析 owner；刷新实时权限与 scopes 401 / 凭证作废即拒
5Router + requirePermission 方法级工牌门禁；非 super 组织可见性 403 permission_denied
6Capability / Model 复用既有业务校验与事务边界 业务错误结构化返回，不暴露堆栈/SQL
关键不变式：大模型永远不直连数据库；MCP 不发明平行业务写路径；所有业务读/写最终落在 MCPAPI 白名单路由上。

3.3 两种接入：本地 npx / 远程 MCP 服务

方式一 · 本地 npx（stdio）

本机拉起管家。进程 env：SHOPEX_OMS_BASE_URL、SHOPEX_OMS_CLIENT_ID、SHOPEX_OMS_CLIENT_SECRET。缺一拒绝启动。默认 surface = full。

方式二 · 远程搭建 MCP 服务（HTTP）

内网部署后连 …:8787/mcp。连接头：X-Shopex-OMS-Base-Url、X-Shopex-OMS-Client-Id、X-Shopex-OMS-Client-Secret。钥匙绑本次会话。默认 surface = public。

简单说：既能 npx，也能远程搭服务再调用；调度链固定，换接入只换「钥匙怎么带」，不换门禁规则。

04 安全模型（重点）

Security
钥匙有效?
→
工牌门禁
→
工具在 surface?
→
部门数据滤镜
→
写? → 批准令牌
→
办事成功

4.1 身份：钥匙跟人走

  • 在 OMS「修改密码 → MCP接入凭证」领取
  • CLIENT SECRET 只亮一次；库中仅存不可逆哈希（password_verify）
  • 绑定员工账号，无独立超级管理员钥匙
  • 领 → 用 → 轮换（旧钥立刻失效）→ 作废
  • 不能自选 / 自提管理员身份

4.2 授权：实时工牌

  • Basic 验钥后解析 owner 当前角色与权限
  • 方法级 requirePermission，缺权 403
  • scopes 被 owner 权限再裁剪（limitScopes）
  • 非 super 受组织可见性约束（订单等）
  • 改密 / 撤权后下一请求即按新工牌执行

4.3 隔离与隐私

  • 固定接口白名单，无任意 SQL
  • 密钥不进聊天、不进仓库、不进日志明文
  • 回复优先业务摘要，避免整包敏感字段外泄
  • 确认令牌按 session scope 隔离，会话结束清空
  • 远程服务建议内网部署，勿裸奔公网
威胁控制措施落点
凭证泄露 / 重放哈希入库、可轮换作废、Secret 单次展示、会话绑定MCPAPI client registry
越权读实时权限 + 组织滤镜；非 super 看不到不可见组织数据auth_guard + controller
越权写写操作需对应工牌；高风险写需 confirmation_tokenprepare/apply 工具对
工具面过大HTTP 默认 public；排障/底层原语进 internalserver.ts surface
模型幻觉乱改未登记工具不存在；写前必须展示影响并获批准MCP + Agent 纪律
旁路业务逻辑禁止平行写路径；复用 Capability / 既有业务入口架构硬规则
能进门 ≠ 能翻所有柜子。 钥匙只证明「是哪位员工的 MCP 接入」；具体能读哪张单、能否改规则，完全由该员工当前 OMS 工牌与组织范围决定。
简单说：IP / 网络管「从哪来」，钥匙管「是谁」，工牌管「能办啥」，滤镜管「能看哪」。 四道关卡叠在一起；任何一关失败，请求立刻拒绝。

05 受控写入：演习 → 批准 → 回读

Write Path
prepare
零写入预演
→
展示影响
hash / plan
→
人明确批准
这一次
→
apply
消费令牌
→
readback
核对结果

令牌语义

  • 随机 confirmation_token（base64url），按 session scope 存放
  • 一次性消费；重复 apply → CONFIRMATION_REQUIRED
  • 内容绑定：operation、文件 hash、bytes、normalized plan、业务键、过期
  • 会话关闭时清空全部 confirmation stores

当前受控写入族

  • 采购导入：purchase_order_prepare_import → purchase_order_import_apply
  • 品牌创建：brand_prepare_create → brand_create
  • 场景规则：automation_rule_prepare_change → automation_rule_apply_change
  • 底层规则原语（internal）：auto_audit / auto_dispatch prepare↔apply
  • 物料分类 CRUD：直接写，但仍受 MCPAPI 工牌约束
prepare(plan) → { confirmation_token, impact, risks } # 向人展示 impact / hash / po_bn … apply({ confirmation_token }) → write once → readback # token 失效或内容不匹配 → 拒绝；不清楚就停下
简单说：先演习、你点头、再真改、再核对。批准只对这一次有效。

06 当前已支持工具面

Tools

以下为 runtime 已注册工具。绿色 = 公共主锚点；金色 = 受控写入相关；灰色 = internal / profile。 完整契约见 docs/oms-mcp/TOOL-CATALOG.md 与各域 SKILL。

Public Core · 经营 / 异常 / 履约 / 治理入口（HTTP 默认可发现）

sales_detail_statistics aftersales_detail_statistics aftersales_lookup shipment_exception_overview shipment_exception_detail order_fulfillment_overview order_fulfillment_detail delivery_execution_detail automation_rule_overview automation_rule_detail automation_rule_prepare_change automation_rule_apply_change

Public Support · 订单 / 发货 / 售后下钻

order_listorder_get delivery_listdelivery_get refund_listrefund_get return_listreturn_get reship_listreship_get shipment_anomaly_listshipment_anomaly_get

Public Support · 主数据 / 采购 / 库存 / 物流

org_listorg_getorg_create shop_listshop_get branch_listbranch_get brand_listbrand_get brand_prepare_createbrand_create material_listmaterial_get material_category_listmaterial_category_get material_category_creatematerial_category_update material_category_deletematerial_category_sort material_type_listmaterial_type_get sales_material_listsales_material_get supplier_listsupplier_get purchase_order_listpurchase_order_get purchase_order_prepare_import purchase_order_import_apply inventory_list logistics_corp_listlogistics_corp_get

Internal / Profile · 仅 stdio 完整面（不进 HTTP 默认发现面）

排障日志、模板原语、候选资源、底层规则治理、第二波库存核对。

health_check api_log_listapi_log_get shipment_log_listshipment_log_get material_import_template_get sales_material_import_template_get sales_material_import branch_get_wms_listbranch_get_branch_types branch_get_shop_listbranch_get_corp_list shop_add_formshop_edit_form inventory_get_by_material_warehouse inventory_diff_check auto_audit_rule_* auto_dispatch_rule_*
角色入口 Skill典型依赖工具用途
customer-service-deskorder_* / delivery_* / aftersales_lookup / refund|return|reship_*统一查单、物流、售后解释
operations-control-towershipment_exception_* / shipment_anomaly_* / aftersales_*异常与待办优先级
governance-adminautomation_rule_* /（底层）auto_*_rule_*规则治理闭环
onboarding-commanderorg/shop/branch/brand/material_* / purchase_order_*开箱与主数据准备
business-insight-copilotsales_detail_statistics / aftersales_detail_statistics经营复盘
technical-triageapi_log_* / shipment_log_*（internal）证据链排障
简单说：公共面给业务角色；完整面给实施与排障；未注册的不承诺。

07 部署与前置条件

Deploy

两种对等接入（门禁规则相同）

除本机 npx 外，也可以在内网远程搭建 MCP 服务，由 Cursor / Hermes 等助手连接调用。差别只在管家怎么起、钥匙怎么带，不在权限模型。

OMS 侧必须先就绪

  • 先升级 PHP 至 8.2（Web / CLI 均需对齐；低于 8.2 不支持正式开通）
  • 安装并启用 mcpapi APP
  • 执行配置更新（如 php app/base/cmd update）
  • 为合适员工账号领取 MCP 接入凭证

只部署 MCP 进程、不升级 OMS / PHP，无法办事。

怎么选

  • 本地 npx：个人试用、开发调试；助手本机自动拉起，无需单独服务器
  • 远程 MCP 服务：团队共用、集中托管与运维；助手只连内网地址
  • 不是全服务器共用一把钥匙——每人/每会话仍带自己的 Client 凭证
  • 远程服务建议放内网 / 受信网络，勿裸奔公网

方式一 · 本地 npx

适合个人试用。不需要单独部署 MCP 服务器。

"shopex-oms": { "command": "npx", "args": ["-y", "shopex-oms-mcp-server"], "env": { "SHOPEX_OMS_BASE_URL": "https://OMS域名/index.php", "SHOPEX_OMS_CLIENT_ID": "…", "SHOPEX_OMS_CLIENT_SECRET": "…" } }

钥匙写在 env；缺一拒绝启动。默认完整工具面（full）。

方式二 · 远程搭建 MCP 服务

内网先起 MCP HTTP 服务（如端口 8787），助手连 …/mcp。适合团队共用。

"shopex-oms": { "url": "http://内网MCP主机:8787/mcp", "headers": { "X-Shopex-OMS-Base-Url": "https://OMS域名/index.php", "X-Shopex-OMS-Client-Id": "…", "X-Shopex-OMS-Client-Secret": "…" } }

钥匙绑本次会话请求头；办完断开清空。HTTP 默认公共工具面（public）。

本地 npx远程 MCP 服务
怎么接本机自动拉起 shopex-oms-mcp-server连内网已部署的 …/mcp
钥匙配置 env会话请求头
适合个人试用、开发团队共用、集中托管
注意缺配置拒绝启动先搭服务再连；勿裸奔公网
再次提醒：系统 PHP 版本需升级到 8.2，这是 MCP / MCPAPI 的环境门槛，不是可选项。升级完成后再做 APP 安装、凭证领取与助手接入（无论本地 npx 还是远程服务）。
简单说：先升 PHP 8.2；既能本机 npx，也能远程搭 MCP 服务再调用——门禁规则一样。

08 能力边界与非目标

Boundary

范围内

  • 交易查询：订单 / 发货 / 退款 / 售后 / 补寄
  • 异常与履约场景总览 / 详情
  • 经营与售后统计（只读）
  • 主数据查询与受控创建 / 导入
  • 自动化规则治理（prepare / apply）
  • 受限诊断（internal surface）

范围外（明确不做）

  • 直连数据库 / 任意 SQL
  • 未开放的改单、发货、退款执行动作
  • 代做平台扫码授权
  • 自提权成管理员
  • 把 docs-only / blocked 能力包装成已交付
  • 用 MCP 绕过桌面端既有业务校验
若某能力仅在文档或规划中出现、未出现在 FULL_TOOL_NAMES，则不是当前可调用 runtime 能力。共创讨论请以注册表为准。
简单说：只走开好的门；未开放的不夸大、不演示成已上线。

技术架构共创页 · 风格对齐 Agentic Commerce 资料包 / 客户介绍页 · 相关：docs/oms-mcp/TOOL-CATALOG.md · docs/oms-mcp/customer-intro.html · docs/oms-mcp/customer-deploy.md