JinDaGe - hybris-mcp MCP Details

article

README

🚀 Hybris MCP 服务器

Hybris MCP 服务器是用于 SAP Commerce Cloud（Hybris）集成的 MCP（模型上下文协议）服务器。该服务器允许像 Claude 这样的 AI 助手与你的 Hybris 实例进行交互。

✨ 主要特性

产品管理：搜索产品、获取产品详情、浏览产品类别
订单管理：查看订单及订单详情
灵活搜索：直接执行 FlexibleSearch 查询
Groovy 脚本：通过脚本控制台运行 Groovy 脚本
ImpEx：使用 ImpEx 格式导入和导出数据
定时任务：列出并触发定时任务
缓存管理：清除 Hybris 缓存
目录同步：触发目录同步
健康检查：监控系统健康状况

📦 安装指南

git clone <repository-url>
cd hybris-mcp
npm install
npm run build

📚 详细文档

配置

通过环境变量进行配置： | 变量 | 是否必需 | 描述 | 默认值 | |------|----------|-------------|---------| | HYBRIS_BASE_URL | 是 | 你的 Hybris 实例的基础 URL | - | | HYBRIS_USERNAME | 是 | 管理员用户名（需要 HAC 访问权限） | - | | HYBRIS_PASSWORD | 是 | 管理员密码 | - | | HYBRIS_BASE_SITE_ID | 否 | OCC 基础站点 ID | electronics | | HYBRIS_CATALOG_ID | 否 | 产品目录 ID | electronicsProductCatalog | | HYBRIS_CATALOG_VERSION | 否 | 目录版本 | Online | | HYBRIS_HAC_PATH | 否 | HAC 路径前缀 | /hac |

常见配置

标准 Hybris（本地主机）：

HYBRIS_BASE_URL=https://localhost:9002
HYBRIS_USERNAME=admin
HYBRIS_PASSWORD=nimda

SAP Commerce Cloud（CCv2）：

HYBRIS_BASE_URL=https://backoffice.your-environment.model-t.cc.commerce.ondemand.com
HYBRIS_USERNAME=admin
HYBRIS_PASSWORD=your-password
HYBRIS_HAC_PATH=/hac

自定义站点配置：

HYBRIS_BASE_URL=https://localhost:9002
HYBRIS_USERNAME=admin
HYBRIS_PASSWORD=nimda
HYBRIS_BASE_SITE_ID=yoursite
HYBRIS_CATALOG_ID=yourProductCatalog
HYBRIS_CATALOG_VERSION=Online

使用方法

与 Claude Code 配合使用

使用 CLI 添加 MCP 服务器：

claude mcp add hybris \
  -e HYBRIS_BASE_URL=https://localhost:9002 \
  -e HYBRIS_USERNAME=admin \
  -e HYBRIS_PASSWORD=nimda \
  -- node /path/to/hybris-mcp/dist/index.js

或者手动添加到你的 Claude Code MCP 设置（~/.claude.json 或项目配置）：

{
  "mcpServers": {
    "hybris": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/hybris-mcp/dist/index.js"],
      "env": {
        "HYBRIS_BASE_URL": "https://localhost:9002",
        "HYBRIS_USERNAME": "admin",
        "HYBRIS_PASSWORD": "nimda"
      }
    }
  }
}

与 Claude Desktop 配合使用

添加到你的 Claude Desktop 配置（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "hybris": {
      "command": "node",
      "args": ["/path/to/hybris-mcp/dist/index.js"],
      "env": {
        "HYBRIS_BASE_URL": "https://localhost:9002",
        "HYBRIS_USERNAME": "admin",
        "HYBRIS_PASSWORD": "nimda"
      }
    }
  }
}

可用工具

产品与目录（OCC API）

| 工具 | 描述 | |------|-------------| | search_products | 在目录中搜索产品 | | get_product | 通过代码获取详细的产品信息 | | get_categories | 列出目录中的所有类别 | | get_category | 通过代码获取类别详情 |

订单（OCC API）

| 工具 | 描述 | |------|-------------| | get_orders | 获取用户的订单 | | get_order | 获取特定订单的详情 |

管理（HAC）

| 工具 | 描述 | |------|-------------| | flexible_search | 执行 FlexibleSearch 查询 | | execute_groovy | 运行 Groovy 脚本 | | import_impex | 导入 ImpEx 数据 | | export_impex | 将数据导出为 ImpEx 格式 | | get_cronjobs | 列出定时任务及其状态 | | trigger_cronjob | 触发定时任务运行 | | clear_cache | 清除 Hybris 缓存 | | get_system_info | 获取系统信息 | | trigger_catalog_sync | 同步目录版本 | | health_check | 检查系统健康状况 |

示例提示

搜索产品

Search for "camera" products in Hybris

灵活搜索

Run a FlexibleSearch query: SELECT {pk}, {code}, {name[en]} FROM {Product} WHERE {code} LIKE '%camera%'

执行 Groovy 脚本

Execute this Groovy script to count products:
import de.hybris.platform.core.Registry
def ctx = Registry.getApplicationContext()
def flexibleSearchService = ctx.getBean("flexibleSearchService")
def query = "SELECT COUNT(*) FROM {Product}"
def result = flexibleSearchService.search(query)
println "Total products: ${result.result[0]}"

导入 ImpEx

Import this ImpEx to create a product:
INSERT_UPDATE Product; code[unique=true]; name[lang=en]; catalogVersion(catalog(id),version)
; testProduct001 ; Test Product ; electronicsProductCatalog:Online

触发目录同步

Sync the electronics catalog from Staged to Online

安全注意事项

安全存储凭证 - 切勿将其提交到版本控制中
使用环境变量或安全的密钥管理
服务器的管理工具需要 HAC 管理员权限
如果只需要 OCC API 访问权限，可以考虑使用只读凭证

开发

# 开发模式下的监听模式
npm run dev

# 构建
npm run build

# 直接运行
HYBRIS_BASE_URL=https://localhost:9002 \
HYBRIS_USERNAME=admin \
HYBRIS_PASSWORD=nimda \
npm start

故障排除

连接问题

验证你的 Hybris 实例是否正在运行且可访问
检查 HAC 是否启用并可在配置的路径下访问
确保凭证具有 HAC 管理员访问权限

SSL 证书错误

对于使用自签名证书的本地开发：

NODE_TLS_REJECT_UNAUTHORIZED=0 node dist/index.js

CSRF 令牌错误

服务器会自动处理 CSRF 令牌。如果你遇到 CSRF 错误：

手动检查 HAC 登录是否正常
验证 HAC 路径是否正确
尝试重启 MCP 服务器以获取新的会话

📄 许可证

MIT

hybris-mcp