hac-mcp

Model Context Protocol (MCP) サーバーであり、AIアシスタント（Claudeなど）に SAP Commerce Cloud の Hybris Administration Console (HAC) へのプログラムによるアクセスを提供します。複数の環境にわたって、FlexibleSearch クエリ、ImpEx インポート、Groovy スクリプト実行、システム管理タスクを自動化できます。

既存の認証情報を使用して HAC と認証するため、バックエンドの変更や追加設定は不要です。許可される操作は環境ごとに設定されるため、AI は明示的に許可した操作のみ実行できます。

できること

• "ステージング環境のコード SUMMER25 の PromotionRule を調べて、ローカル環境に再作成して"

• "ステージングで ImpEx が失敗しているので、本番の実際の値を確認して正しい値を入力して"

• "本番で3日以上 WAIT ステータスのままの注文をすべて見つけて、サマリーを提供して"

• "…を行う 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 の設定モーダルで設定可能

• 型検索: SAP Commerce の型名に対する trigram ベースのあいまい検索（環境ごとにキャッシュ）

• 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 が実行されます。これにより、OS の起動シーケンスに PM2 をフックするための一度だけのコマンドが表示されます（macOS/Linux では sudo が必要な場合があります）。

設定

Web UI を使用

ブラウザで http://localhost:18432/ を開き、+ Add Environment をクリックして、詳細を入力（入力中に接続が自動テストされます）し、Save をクリックします。

環境オプション

本番環境のヒント: 誤ったデータ変更を防ぐために、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」タイトルとセットアップモーダルの横に表示されるようになりました。サーバーが package.json を読み取らずにハードコードされた 1.0.0 バージョンを報告していた問題を修正（実際は 1.0.5 でした）。

セキュリティに関する注意

• 認証情報は ~/.hac-mcp/environments.json に平文で保存されます。このファイルを公開しないでください。

• HAC 接続では SSL 証明書の検証が無効になっています。信頼できないネットワークでは注意してください。

• 本番環境では書き込み権限（allowImpexImport、allowGroovyCommitMode）を制限してください。