hac-mcp

一个 Model Context Protocol (MCP) 服务器，为 AI 助手（如 Claude）提供对 SAP Commerce Cloud 的 Hybris 管理控制台（HAC） 的程序化访问。它支持跨多个环境自动执行 FlexibleSearch 查询、ImpEx 导入、Groovy 脚本执行和系统管理任务。

它使用您现有的凭据与 HAC 进行身份验证，无需后端更改或额外设置。允许的操作按环境进行配置，因此 AI 只能执行您明确允许的操作。

您可以做什么

• "检查暂存环境中代码为 SUMMER25 的 PromotionRule，并在我的本地环境中重新创建它"

• "我的 ImpEx 在暂存环境中失败了，请检查生产环境中的实际值并填入正确的值"

• "查找生产环境中所有处于 WAIT 状态超过 3 天的订单，并给我一份摘要"

• "编写一个 Groovy 脚本执行……并先在本地运行，如果有效，我会批准它在暂存环境中运行"

• "这段代码没有按预期工作，你能用 Groovy 在暂存环境中用真实数据检查它的边界情况吗？"

• "我想在暂存环境中测试这个 CronJob，它有一个媒体字段，接受包含 source-product 和 target-product 列的 CSV 格式的 txt 文件。创建多个测试媒体，写入它们，为每种情况运行该作业，并使用 FlexibleSearch 验证结果"

Related MCP server: Hybris MCP Server

功能

• 多环境支持：配置并在本地、暂存和生产 HAC 实例之间切换

• 细粒度权限：控制每个环境允许执行哪些操作

• Web UI：基于浏览器的管理控制台，用于添加/编辑环境和监控活动

• 实时日志：通过 SSE 实时查看 HAC 请求和 MCP 工具执行日志

• 脚本运行日志写入磁盘：每次 Groovy、ImpEx 和 FlexSearch 运行都会连同脚本和结果写入 logs/<kind>/<date>/。保留期限（默认 30 天）和结果截断（默认 20,000 字符）可在 Web UI 设置弹窗中配置

• 类型搜索：基于三元组（trigram）的模糊搜索，用于查找 SAP Commerce 类型名称，并支持按环境缓存

• FlexSearch 错误恢复：当查询因未知字段或类型而失败时，会获取有效字段名称并与错误一起返回，以便 AI 无需人工干预即可自行纠正并重试

• ImpEx 验证和增强：在导入运行前对脚本进行缺失必填字段的预验证，并且导入后的任何属性错误都会即时解析为有效字段列表，以便 AI 自行修复并重试脚本

工具

安装

通过 npx（推荐）

npx hac-mcp

全局安装

npm install -g hac-mcp
hac-mcp

服务器默认在 http://localhost:18432 上启动。

Options:
  -p, --port    Port to listen on (default: 18432)
  -v, --version Print version
  -h, --help    Show help

环境配置存储在 ~/.hac-mcp/environments.json 中。

系统启动时自动启动（可选，推荐）

为了在重启后保持服务器运行，请使用 startup 子命令（需要 PM2）：

npx hac-mcp startup
npx hac-mcp startup --port 4000  # with custom port

这会将服务器注册到 PM2 并运行 pm2 startup，它会打印一条需要执行的一次性命令（在 macOS/Linux 上可能需要 sudo），以将 PM2 挂接到操作系统的启动序列中。

配置

通过 Web UI

在浏览器中打开 http://localhost:18432/，点击 + 添加环境，填写详细信息（连接会在您输入时自动测试），然后点击 保存。

环境选项

生产环境提示： 禁用 allowImpexImport、allowGroovyCommitMode 或两者，以防止意外的数据修改。

与 Codex 一起使用

Codex 使用 Streamable HTTP 端点：

codex mcp add hac-mcp --url http://localhost:18432/mcp

或者直接将其添加到 ~/.codex/config.toml：

[mcp_servers.hac-mcp]
url = "http://localhost:18432/mcp"

与 Claude Code 一起使用

Claude Code 可以继续使用旧版 SSE 端点：

claude mcp add --transport sse hac-mcp http://localhost:18432/mcp/sse

其他 MCP 客户端

对于支持 Streamable HTTP 的客户端，请使用：

将以下内容添加到您的 MCP 客户端配置中：

{
  "mcpServers": {
    "hac-mcp": {
      "url": "http://localhost:18432/mcp"
    }
  }
}

项目结构

hac-mcp/
├── server.js           # Express app, MCP SSE endpoint, REST API
├── hac.js              # HAC client (login, FlexSearch, ImpEx, Groovy, etc.)
├── storage.js          # Environment config persistence
├── type-index.js       # Trigram fuzzy type search with caching
├── tools/
│   ├── index.js        # Tool registry
│   ├── context.js      # Shared runtime state (sessions, logging)
│   ├── fileLog.js      # On-disk script run logs (retention, truncation)
│   ├── zodLoose.js     # Loose Zod validators (string -> number/bool)
│   └── *.js            # One file per MCP tool
└── static/
    ├── index.html      # Management console UI
    ├── app.js          # UI logic
    └── style.css       # Styles

发布说明

v1.0.7 - 磁盘上的脚本运行日志现在得到管理：可配置的保留期限（默认 30 天）会在启动时和每天清理旧的 logs/<kind>/<date>/ 文件夹，并且结果正文在写入前会被截断（默认 20,000 字符）。设置弹窗同时公开了这两项，显示日志目录及其当前大小，活动日志面板也会注明运行结果同时保存到磁盘。CSRF 令牌提取失败现在会报告为 HAC 连接问题（VPN 断开或 IP 未列入白名单），而不是单纯的解析错误。

v1.0.6 - Web UI 在"HAC MCP"标题和设置弹窗旁边显示正在运行的服务器版本。修复了服务器之前报告硬编码的 1.0.0 版本而不是读取 package.json 的问题（实际为 1.0.5）。

安全说明

• 凭据以明文形式存储在 ~/.hac-mcp/environments.json 中。请避免暴露此文件。

• HAC 连接已禁用 SSL 证书验证：请注意在不受信任的网络中使用此功能的风险。

• 在生产环境中限制写权限（allowImpexImport、allowGroovyCommitMode）。