SAP Commerce MCP Server

SAP Commerce MCP 服务

此 Model Context Protocol（MCP）服务集成了 SAP Commerce Cloud 的 OCC API，可通过 Claude 使用自然语言与产品数据交互。

功能

• 产品搜索：使用自然语言查询搜索产品
• 高级搜索：按类别、价格范围等筛选产品
• 产品详情：获取特定产品的详细信息
• 库存可用性：查看产品库存水平和可用性
• 类别：浏览和按类别搜索产品
• 促销：获取有效促销信息
• 评价：查看产品评价和评分
• 产品推荐：获取个性化产品推荐
• 购物车管理：支持完整的购物车操作
• 运行状况监控：实时跟踪服务运行状况
• 性能分析：分析历史性能并提供洞察

可用工具

1. search-products：支持分页的基础产品搜索

   • 参数：
     • query：搜索查询字符串
     • currentPage：（可选）页码
     • pageSize：（可选）每页结果数

2. search-products-advanced：带筛选条件的高级产品搜索

   • 参数：
     • query：（可选）搜索查询字符串
     • categoryCode：（可选）类别代码筛选条件
     • minPrice：（可选）最低价格筛选条件
     • maxPrice：（可选）最高价格筛选条件
     • sort：（可选）排序顺序
     • currentPage：（可选）页码
     • pageSize：（可选）每页结果数

3. get-product-details：获取产品详细信息

   • 参数：
     • productCode：产品代码/SKU

4. check-product-availability：查看产品库存水平

   • 参数：
     • productCode：产品代码/SKU
     • location：（可选）仓库/门店位置代码

5. get-categories：浏览产品类别

   • 参数：
     • categoryId：（可选）特定类别 ID

6. get-products-by-category：获取某个类别中的产品

   • 参数：
     • categoryId：类别 ID
     • currentPage：（可选）页码
     • pageSize：（可选）每页结果数
     • sort：（可选）排序顺序

7. get-promotions：获取促销信息

   • 参数：
     • promotionId：（可选）特定促销 ID

8. get-product-reviews：获取产品评价

   • 参数：
     • productCode：产品代码/SKU

9. get-product-suggestions：获取产品推荐

   • 参数：
     • productCode：参考产品代码/SKU
     • maxResults：（可选）推荐数量上限

10. create-cart：创建新的购物车

    • 参数：无

11. get-cart：获取购物车详情

    • 参数：
      • cartId：要获取的购物车 ID

12. add-to-cart：将产品添加到购物车

    • 参数：
      • cartId：购物车 ID
      • productCode：产品代码/SKU
      • quantity：（可选）添加数量（默认值：1）

13. update-cart-entry：更新购物车中的产品数量

    • 参数：
      • cartId：购物车 ID
      • entryNumber：购物车中的条目编号
      • quantity：新数量

14. remove-from-cart：从购物车中移除产品

    • 参数：
      • cartId：购物车 ID
      • entryNumber：要移除的条目编号

15. get-order-status：查看订单状态

    • 参数：
      • orderId：订单 ID

16. get-order-history：查看订单历史记录

    • 参数：
      • userId：用户 ID

17. check-service-health：获取当前服务运行状况

    • 参数：无

18. analyze-performance：获取历史性能洞察

    • 参数：无

配置

可使用环境变量配置此服务：

# SAP Commerce Cloud Configuration
SAP_COMMERCE_URL=https://your-commerce-url/occ/v2
SAP_COMMERCE_SITE=your-site-name
SAP_COMMERCE_TIMEOUT=10000
SAP_COMMERCE_VALIDATE_SSL=false

# OAuth2 Authentication (optional)
SAP_COMMERCE_CLIENT_ID=your-client-id
SAP_COMMERCE_CLIENT_SECRET=your-client-secret

# Logging Configuration
LOG_LEVEL=info # debug, info, warn, or error

设置

1. 安装依赖项：

   npm install
   

2. 构建项目：

   npm run build
   

3. 启动服务：

   npm start
   

Claude 集成示例查询

• “搜索所有与 ‘hacendado’ 相关的商品”
• “查找价格低于 $500 的电子产品”
• “获取代码为 ‘ABC123’ 的商品详情”
• “查询商品 ‘XYZ789’ 的库存情况”
• “显示 ‘electronics’ 类别中的所有商品”
• “目前有哪些促销活动正在进行？”
• “显示商品 ‘ABC123’ 的评价”
• “推荐与 ‘ABC123’ 类似的商品”
• “创建一个新的购物车”
• “将商品 ‘ABC123’ 的 2 件加入我的购物车”
• “将我的购物车中第 1 件商品的数量更新为 3”
• “从我的购物车中移除第 2 件商品”
• “显示我的购物车详情”
• “订单 ‘ORD123456’ 的状态是什么？”
• “显示我的订单历史记录”
• “检查服务当前的健康状态”
• “分析过去 12 小时的性能”
• “显示性能洞察”
• “获取今天的缓存命中率”

开发

项目通过 .vscode/mcp.json 集成了 VS Code，便于调试和开发。请务必使用你的 SAP Commerce 实例详情更新配置。

在开发模式下运行

开发时，你可以使用：

npm run dev

这会以监视模式启动 TypeScript，并在代码更改时重新编译。

性能监控

实时健康检查

服务包含实时健康监控，并提供以下指标：

• API 延迟
• 错误率
• 缓存命中率
• 服务状态（健康／降级／不健康）

历史分析

性能数据会被存储和分析，内容包括：

• 24 小时历史趋势
• P95 延迟跟踪
• 错误率模式
• 缓存效率指标
• 自动生成的性能洞察

日志

日志存储在 logs 目录中，并会自动轮换：

• 错误日志：logs/error-YYYY-MM-DD.log
• 合并日志：logs/combined-YYYY-MM-DD.log
• 健康指标：logs/health-YYYY-MM-DD.log

日志每天自动轮换，并保留 30 天。

错误处理

服务针对常见的 SAP Commerce API 问题提供了全面的错误处理：

• 无效的商品代码
• 网络连接问题
• 身份验证错误
• API 速率限制
• 无效的类别或促销活动 ID
• 价格范围验证
• 排序参数验证
• 购物车操作失败

身份验证

服务支持 OAuth2 客户端凭据流，可用于向 SAP Commerce 发送经过身份验证的请求。在环境变量中配置客户端 ID 和密钥，即可启用经过身份验证的请求。

令牌管理

• 自动处理令牌刷新
• 令牌过期缓冲时间（5 分钟）
• 身份验证失败时优雅回退

缓存

服务实现了智能缓存，具备以下功能：

• 商品数据的 TTL 为 5 分钟
• 自动缓存失效
• 缓存命中率监控
• 用于内存管理的清除策略

购物车会话管理

服务为匿名用户维护购物车会话，并具备以下功能：

• 自动创建购物车
• 持久跟踪购物车 ID
• 购物车条目管理
• 购物车总额计算
• 商品可用性验证

安全说明

• 开发时可使用 SAP_COMMERCE_VALIDATE_SSL=false 禁用 SSL 证书验证
• 在生产环境中，请确保正确配置 SSL 证书和身份验证
• 将敏感凭据（客户端 ID／密钥）存储在环境变量中，切勿写入代码
• 建议对生产部署进行定期安全审计
• 购物车 ID 应视为敏感信息

性能优化

服务包含多项性能优化功能：

• 自动重试请求，并采用指数退避策略
• 缓存频繁访问的数据
• 请求批处理和节流
• 性能监控和告警
• 历史性能分析
• 自动生成性能洞察和建议