SAP Commerce MCP 服务器

本项目为 SAP Commerce Cloud 提供了一个 MCP 服务器，专注于 ASM（辅助服务模块）员工工作流：搜索客户、模拟客户、绑定或管理购物车，并通过面向任务的 MCP 工具完成基于 OCC 的商务操作。

该仓库现在采用本地优先原则：预期的默认目标是 https://localhost:9002，由 SAP_BASE_URL 控制实际主机。虽然仍可使用远程租户，但文档、测试和验证流程应以本地 SAP Commerce 运行时为准。

该服务器目前的功能

• ASM 优先的客户操作：搜索客户、模拟客户并继续代表他们进行操作

• 会话感知的购物车管理：创建、检查、更新、移除和清空购物车，无需手动管理购物车

• 结账流程：送货地址、送货方式、访客电子邮件和订单提交

• 产品和发现工具：搜索产品、获取详情、检查库存、浏览基础站点/商店/目录/类别

• 双层工具架构：高级代理友好型工具加上低级 OCC/ASM 封装

• 会话导向：get_session_status 帮助代理了解当前的购物车/用户/基础站点上下文

• FastMCP 传输：支持 stdio 和 SSE 传输，适用于本地或远程 MCP 客户端

请求流程

1. 架构概览

来源：docs/diagrams/architecture.mmd

2. 请求泳道示例

这是典型的“代理模拟客户，然后代表他们继续购物”的路径。

来源：docs/diagrams/example-request.mmd

MCP 工具

高级工具

这些是 ASM 员工工作流的主要契约。

发现和产品

• search_products — 关键词产品发现

• get_product — 获取单个产品详情

• get_session_status — 检查当前会话状态

客户 / ASM

• search_customer — 快速查找客户

• impersonate_customer — 开始模拟客户

• end_impersonation — 返回匿名模式

购物车和结账

• add_to_cart — 添加一个产品

• get_cart — 读取当前购物车

• update_cart_entry — 更改条目数量

• remove_from_cart — 删除一个条目

• clear_cart — 清空购物车

• set_delivery_address — 附加送货地址

• set_delivery_mode — 选择送货方式

• get_delivery_modes — 列出送货选项

• set_guest_email — 设置访客结账电子邮件

• place_order — 提交订单

低级工具

这些工具暴露了更细粒度的 OCC / ASM 原语，以实现精确控制。

• basesites.list — 列出可用的基础站点

• catalogs.list — 列出站点的目录

• catalogs.get — 获取一个目录

• catalogVersions.get — 获取一个目录版本

• categories.products — 按类别浏览产品

• stores.list — 列出站点的商店

• stores.get — 获取一个基础商店

• products.get — 获取一个 OCC 产品

• products.stock — 检查库存数据

• products.stockCount — 统计库存位置

• asm.customer360 — 获取客户 360 片段

• asm.customers.create — 创建客户

• asm.customers.search — 运行 ASM 客户搜索

• asm.customers.suggest — 获取客户建议

• carts.list — 列出购物车

• carts.create — 创建或恢复购物车

• carts.get — 获取一个购物车

• carts.delete — 删除一个购物车

• cartEntries.list — 列出购物车条目

• cartEntries.add — 添加一个条目

• cartEntries.get — 获取一个条目

• cartEntries.update — 替换条目负载

• cartEntries.patch — 部分更新条目

• cartEntries.delete — 删除一个条目

配置

1. 安装依赖：

   uv sync

2. 复制环境模板：

   cp .env.example .env

3. 对于本地 SAP Commerce 实例，设置：

   SAP_BASE_URL=https://localhost:9002

4. 如果您的 SAP 部署有所不同，请保留或调整这些路径片段：

   • OCC_API_PATH=/occ/v2

   • OAUTH_PATH=/authorizationserver/oauth/token

   • ASM_PATH=/assistedservicewebservices

5. 为您正在验证的本地租户或远程租户配置 OAuth 凭据。 对于标准的本地示例数据设置，这些是预期的默认值：

   OAUTH_CLIENT_ID=mobile_android
   OAUTH_CLIENT_SECRET=secret
   OAUTH_USERNAME=asmagent
   OAUTH_PASSWORD=nimda
   OAUTH_SCOPE=basic

运行

• Stdio:

  python -m app.server

• SSE:

  fastmcp serve app/server.py --sse :8080

测试

• 完整验证套件：

  uv run ruff check app tests
  uv run mypy app
  uv run pytest -q

• 冒烟测试：

  uv run pytest tests/integration/test_smoke.py -q

• 实时发现流程：

  uv run pytest tests/integration/test_integration_live.py -s

注意 实时测试旨在验证当前契约与真实 SAP Commerce 运行时的兼容性。当 SAP_BASE_URL=https://localhost:9002 时，本地 OCC/ASM 实例应作为主要验证目标。如果 OAuth 或 ASM 数据配置错误，请在扩大范围之前先在本地进行诊断。

本地 SAP 注意事项 一些 SAP 2211 本地堆栈包含 messagecentercsocc，其后置的 Oauth2UserFilter 可能会再次用已认证的代理覆盖 /users/{customerId} 的代操作上下文。如果 asmagent 购物车调用退化为 EmployeeModel -> CustomerModel 类型转换错误，请修补该过滤器，以便在当前 OCC 用户与 OAuth 主体不同时，保留已匹配的客户。

质量门禁

• Ruff 用于代码检查和导入规范

• Mypy 用于 app/ 目录下的实用静态类型检查

• Pytest + coverage.xml 以便 SonarQube 可以使用与 CI 中相同的本地证据

本地 SonarQube 分析可以通过以下方式发布：

uv run pytest -q
sonar-scanner

sonar-project.properties 已签入，因此本地和 CI 扫描使用相同的项目键/源布局。

文档

• 工作流 — 实用工具调用序列

• 架构 Mermaid — 系统图源文件

• 请求 Mermaid — 泳道图源文件

• MCP 清单和工具注册：app/server.py

• 贡献指南：AGENTS.md

未来改进

• 仅在项目后续需要多进程或水平扩展的会话持久性时，添加可选的外部后端存储

支持的 OCC / ASM 覆盖范围

当前的服务器涵盖了上述流程所需的端点，包括基础站点、目录、商店、产品、购物车、购物车条目、结账地址/送货操作、订单提交以及 ASM 客户搜索 / 客户 360 / 绑定购物车式操作。