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"

Related MCP server: Hybris MCP Server

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

• Files in, files out: every tool that takes content also takes a file path (scriptPath, scriptPaths, queryPath, contentPath), and every tool takes outputPath to write its full result to disk instead of into the conversation

• No forced timeout: HAC requests wait as long as HAC needs by default; a caller that wants a deadline passes timeoutMs per call

• Async mode: impex_import and groovy_execute accept async: true, returning a job id immediately so work that outlives the client's idle timeout is not lost - poll it with job_status

Tools

Content from files, results to files

Tools that take content accept it inline or from a file, using one convention everywhere:

The rules are identical for all of them:

• give exactly one of inline or path - both or neither is rejected

• paths must be absolute; a relative path would resolve against the server's working directory, so it is rejected rather than silently read from the wrong place

• files are read as UTF-8 and used byte-exact: no trimming, no line-ending rewriting (ImpEx is whitespace sensitive)

• when content comes from a file, the confirmation error shows the resolved path, size, line count and the first 20 lines, so nothing is approved sight-unseen

In the other direction, every tool accepts outputPath (absolute). The full result is written there and the response shrinks to a confirmation plus the first lines. This applies in every state - success, failure and the in-progress snapshot of a job_status poll all overwrite the file, so it never holds a stale result. flexible_search additionally keeps path, which writes raw CSV rather than the formatted response.

Examples

impex_import - inline, then from an ordered list of files:

{ "environmentId": "abc123", "confirmed_by_user": true,
  "script": "INSERT_UPDATE Title;code[unique=true]\n;mr\n" }

// imported in order; after the first failure the rest are reported as skipped
{ "environmentId": "abc123", "confirmed_by_user": true,
  "scriptPaths": ["/data/impex/01-catalog.impex", "/data/impex/02-products.impex"],
  "outputPath": "/tmp/impex-errors.txt" }

The response is always a compact summary. Each file reports succeeded / failed / skipped with its duration, its processed and unresolved line counts, and its unresolved lines grouped by cause:

❌ **02-categories.impex** - failed · 4.2s
  processed 180 line(s), 65 unresolved
  UPDATE Category — no existing item found for update (65)
    code: 2051204@40, 2051205@41, 2051206@42, … 45 more

The type and the message are stated once per cause, and each failing item is listed as value@line - the line in your source file, recovered by matching the row back against it, since HAC reports neither the file nor a usable line number. The message appears once even though ImpEx repeats it per retry pass. outputPath receives every item with its full values.

groovy_execute - inline, then from a file with the output sent to disk:

{ "environmentId": "abc123", "confirmed_by_user": true,
  "script": "productService.getProductForCode('123').name" }

{ "environmentId": "abc123", "confirmed_by_user": true,
  "scriptPath": "/data/groovy/audit-orders.groovy",
  "outputPath": "/tmp/audit.txt" }

flexible_search - inline, then one reusable query file bound to different values:

{ "environmentId": "abc123", "query": "SELECT {pk},{uid} FROM {Employee}", "maxCount": 50 }

// /data/flex/by-code.flex contains: SELECT {pk},{name} FROM {Product} WHERE {code} = ?code
{ "environmentId": "abc123", "queryPath": "/data/flex/by-code.flex",
  "params": { "code": "SUMMER25" }, "path": "/tmp/products.csv" }

media_write:

{ "environmentId": "abc123", "confirmed_by_user": true,
  "mediaPk": "8796093054980", "content": "col1,col2\na,b\n" }

{ "environmentId": "abc123", "confirmed_by_user": true,
  "mediaPk": "8796093054980", "contentPath": "/data/import-rows.csv" }

Long-running imports and scripts

HAC requests have no client-side timeout by default - a call waits as long as HAC needs. Pass timeoutMs on an individual call to impose one.

That leaves the client's idle timeout (300 s in Claude Code), which can drop a call even though the server finished the work. Two mechanisms cover it:

• Progress notifications - while a client supplied a progress token, impex_import, groovy_execute and flexible_search ping it every 15 s so the call is not considered idle.

• Async mode - pass async: true to impex_import or groovy_execute. The call returns a job id immediately and the work continues on the server regardless of what the client does:

{ "environmentId": "abc123", "confirmed_by_user": true, "async": true,
  "scriptPaths": ["/data/impex/big-catalog.impex"] }
// → Job id: impex-mu70lpe0508c7f

{ "jobId": "impex-mu70lpe0508c7f" }   // job_status: running / succeeded / failed, plus the full result

job_status with no arguments lists recent jobs. Jobs are kept in memory for 24 hours and do not survive a server restart.

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

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; injects the shared *Path / outputPath params
│   ├── context.js      # Shared runtime state (sessions, logging, progress)
│   ├── fileIo.js       # Shared file input/output convention
│   ├── jobs.js         # In-memory registry for async: true jobs
│   ├── 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
└── test/
    ├── smoke.test.js   # Packs, installs and starts the package, lists tools over MCP
    └── file-io.test.js # File input/output convention and query parameter binding

Development

npm test packs the package exactly as it would be published, installs it into a temp directory, starts the server and lists its tools over MCP. It also fails if a published file is not committed to git. It runs in CI on every push and pull request, and before npm publish. To run it before every git push, enable the bundled hook once per clone:

git config core.hooksPath .githooks

Release Notes

v1.1.0 - Every tool that takes content now also takes a file path under one convention: impex_import gained scriptPath and scriptPaths (an ordered list, imported one after another, stopping at the first failure), groovy_execute gained scriptPath, flexible_search gained queryPath plus a params object for ?code style placeholders, and media_write gained contentPath. Exactly one of inline or path is allowed, paths must be absolute, files are read byte-exact, and the confirmation error shows the resolved path, size, line count and first 20 lines. In the other direction every tool now accepts outputPath. impex_import always answers with a compact summary and writes the full unresolved-line dump to outputPath. Long work no longer gets lost: HAC requests have no client-side timeout by default (pass timeoutMs for one), long calls send progress notifications, and impex_import / groovy_execute accept async: true to return a job id polled with the new job_status tool.

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.