hac-mcp

A Model Context Protocol (MCP) server that provides AI assistants (like Claude) with programmatic access to SAP Commerce Cloud's Hybris Administration Console (HAC). It enables automated FlexibleSearch queries, ImpEx imports, Groovy script execution, and system administration tasks across multiple environments.

It authenticates with HAC using your existing credentials, no backend changes or additional setup required. Permitted operations are configured per environment, so the AI can only do what you explicitly allow.

What You Can Do

• "Inspect the PromotionRule with code SUMMER25 in staging and recreate it in my local environment"
• "My ImpEx is failing on staging, check the actual values in production and fill in the correct ones"
• "Find all orders stuck in WAIT status for more than 3 days in production and give me a summary"
• "Write a Groovy script to do ... and run it on local first, if it works I will approve it for staging"
• "This code is not working as expected, can you check its edge cases using Groovy with real data on staging?"
• "I want to test this CronJob on staging, it has a media field that accepts a CSV in txt format with source-product and target-product columns. Create multiple test medias, write them, run the job for each case, and validate the results with FlexibleSearch"

Features

• Multi-environment support: configure and switch between local, staging, and production HAC instances
• Fine-grained permissions: control which operations are allowed per environment
• Web UI: browser-based management console for adding/editing environments and monitoring activity
• Real-time logging: live HAC request and MCP tool execution logs via SSE
• Script run logs on disk: every Groovy, ImpEx and FlexSearch run is written to logs/<kind>/<date>/ with its script and result. Retention (default 30 days) and result truncation (default 20,000 chars) are configurable in the Web UI Settings modal
• Type search: trigram-based fuzzy search for SAP Commerce type names with per-environment caching
• FlexSearch error recovery: when a query fails due to an unknown field or type, valid field names are fetched and returned alongside the error so the AI can correct and retry without manual intervention
• ImpEx validation and enrichment: scripts are pre-validated for missing mandatory fields before import runs, and any post-import attribute errors are resolved to valid field lists on the fly so the AI can fix and retry the script itself

Tools

| Tool | Description | |------|-------------| | list_environments | List all configured HAC environments | | flexible_search | Execute FlexibleSearch queries | | search_type | Fuzzy search for type names | | get_type_info | Retrieve type metadata, attributes, and relationships | | resolve_pk | Resolve opaque PKs to type code and unique field values | | impex_import | Execute ImpEx import scripts | | groovy_execute | Execute Groovy scripts | | read_property | Search HAC configuration properties by key/value | | media_read | Read text/plain media content | | media_write | Create or overwrite media models | | list_cronjobs | List CronJobs with optional filtering | | run_cronjob | Execute a CronJob synchronously and wait for completion | | backoffice_config_raw | Read RAW Backoffice cockpit-config <context> blocks (any component), filter by type/component/module; no merge | | backoffice_config_resolve | Resolve the MERGED editor-area for a type (walks supertype chain, applies merge/replace/remove), tags each node with its module@type contributor |

Installation

Via npx (recommended)

npx hac-mcp

Global install

npm install -g hac-mcp
hac-mcp

The server starts on http://localhost:18432 by default.

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

Environment configuration is stored in ~/.hac-mcp/environments.json.

Auto-start on system boot (optional, recommended)

To keep the server running across restarts, use the startup subcommand (requires PM2):

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

This registers the server with PM2 and runs pm2 startup, which prints a one-time command to run (may require sudo on macOS/Linux) to hook PM2 into your OS boot sequence.

Configuration

Via Web UI

Open http://localhost:18432/ in your browser, click + Add Environment, fill in the details (connection is tested automatically as you type), then click Save.

Environment options

| Field | Type | Default | Description | |-------|------|---------|-------------| | name | string | | Display name | | description | string | | Optional notes | | url | string | | HAC base URL (e.g. https://host:9002/) | | username | string | | HAC login username | | password | string | | HAC login password | | dbType | string | MSSQL | Database dialect: MSSQL or MySQL | | allowFlexSearch | boolean | true | Allow FlexibleSearch queries | | allowImpexImport | boolean | false | Allow ImpEx imports | | allowGroovyExecution | boolean | false | Allow Groovy script execution | | allowGroovyCommitMode | boolean | false | Allow Groovy scripts to commit changes | | allowReadProperty | boolean | true | Allow reading platform config properties |

Tip for production: Disable allowImpexImport, allowGroovyCommitMode, or both to prevent accidental data modifications.

Using with Codex

Codex uses the Streamable HTTP endpoint:

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

Or add it directly to ~/.codex/config.toml:

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

Using with Claude Code

Claude Code can continue using the legacy SSE endpoint:

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

Other MCP clients

For clients that support Streamable HTTP, use:

Add the following to your MCP client configuration:

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

Project Structure

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

Release Notes

v1.0.8 - Fixed npx hac-mcp crashing on startup with ERR_MODULE_NOT_FOUND for tools/upload_to_vps.js in v1.0.6 and v1.0.7 (the tool files were missing from the published package). upload_to_vps and delete_from_vps are now opt-in: they are only registered when both HAC_MEDIA_HOST_URL and HAC_MEDIA_HOST_TOKEN are set.

v1.0.7 - Script run logs on disk are now managed: configurable retention (default 30 days) prunes old logs/<kind>/<date>/ folders on startup and daily, and result bodies are truncated (default 20,000 chars) before being written. The Settings modal exposes both, shows the log directory and its current size, and the activity log panel notes that runs are also saved to disk. Failed CSRF token extraction now reports it as a HAC connectivity problem (VPN down or IP not whitelisted) instead of a bare parse error.

v1.0.6 - Web UI shows the running server version next to the "HAC MCP" title and setup modal. Fixed the server previously reporting a hardcoded 1.0.0 version instead of reading package.json (was actually 1.0.5).

Security Notes

• Credentials are stored in plaintext in ~/.hac-mcp/environments.json. Avoid exposing this file.
• SSL certificate verification is disabled for HAC connections: be aware of this in untrusted networks.
• Restrict write permissions (allowImpexImport, allowGroovyCommitMode) on production environments.