hac-mcp

Сервер Model Context Protocol (MCP), который предоставляет AI-ассистентам (например, Claude) программный доступ к Hybris Administration Console (HAC) платформы SAP Commerce Cloud. Он обеспечивает автоматизированные запросы FlexibleSearch, импорт ImpEx, выполнение скриптов Groovy и задачи системного администрирования в нескольких средах.

Он аутентифицируется в HAC с использованием ваших существующих учетных данных, не требуя изменений в бэкенде или дополнительной настройки. Разрешенные операции настраиваются для каждой среды, поэтому ИИ может делать только то, что вы явно разрешили.

Что вы можете делать

• «Проверить PromotionRule с кодом SUMMER25 в staging и воссоздать его в моей локальной среде»

• «Мой ImpEx падает на staging, проверь фактические значения в production и заполни правильные»

• «Найди все заказы, зависшие в статусе WAIT более 3 дней в production, и дай мне сводку»

• «Напиши Groovy-скрипт, чтобы сделать ..., и сначала запусти его на локальной среде; если он сработает, я одобрю его для staging»

• «Этот код работает не так, как ожидалось; можешь проверить его крайние случаи с помощью Groovy на реальных данных в staging?»

• «Я хочу протестировать этот CronJob на staging; у него есть медиа-поле, которое принимает CSV в формате txt с колонками source-product и target-product. Создай несколько тестовых медиа, запиши их, запусти задание для каждого случая и проверь результаты с помощью FlexibleSearch»

Related MCP server: Hybris MCP Server

Возможности

• Поддержка нескольких сред: настройка и переключение между локальными, staging и production экземплярами HAC.

• Гибкие разрешения: контроль того, какие операции разрешены для каждой среды.

• Веб-интерфейс: консоль управления на основе браузера для добавления/редактирования сред и мониторинга активности.

• Логирование в реальном времени: живые журналы запросов HAC и выполнения инструментов MCP через SSE.

• Журналы выполнения скриптов на диске: каждый запуск Groovy, ImpEx и FlexSearch записывается в logs/<kind>/<date>/ вместе со скриптом и результатом. Срок хранения (по умолчанию 30 дней) и усечение результата (по умолчанию 20 000 символов) настраиваются в модальном окне настроек веб-интерфейса.

• Поиск типов: нечеткий поиск на основе триграмм для имен типов SAP Commerce с кэшированием для каждой среды.

• Восстановление после ошибок FlexSearch: когда запрос не выполняется из-за неизвестного поля или типа, допустимые имена полей извлекаются и возвращаются вместе с ошибкой, чтобы ИИ мог исправить и повторить попытку без ручного вмешательства.

• Проверка и обогащение ImpEx: скрипты предварительно проверяются на отсутствие обязательных полей перед запуском импорта, а любые ошибки атрибутов после импорта разрешаются в списки допустимых полей на лету, чтобы ИИ мог исправить и повторить скрипт самостоятельно.

Инструменты

Установка

Через 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, который выводит одноразовую команду для выполнения (может потребоваться sudo на macOS/Linux), чтобы подключить PM2 к последовательности загрузки вашей ОС.

Конфигурация

Через веб-интерфейс

Откройте http://localhost:18432/ в браузере, нажмите + Add Environment, заполните детали (подключение проверяется автоматически по мере ввода), затем нажмите Save.

Параметры среды

Совет для production: Отключите 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 — Веб-интерфейс показывает текущую версию сервера рядом с заголовком «HAC MCP» и в модальном окне настройки. Исправлена проблема, из-за которой сервер ранее сообщал жестко заданную версию 1.0.0 вместо чтения package.json (на самом деле была 1.0.5).

Замечания по безопасности

• Учетные данные хранятся в открытом виде в ~/.hac-mcp/environments.json. Избегайте раскрытия этого файла.

• Проверка SSL-сертификатов отключена для подключений к HAC: учитывайте это в недоверенных сетях.

• Ограничьте права на запись (allowImpexImport, allowGroovyCommitMode) в производственных средах.