# hac-mcp

[![npm version](https://img.shields.io/npm/v/hac-mcp.svg)](https://www.npmjs.com/package/hac-mcp)
[![npm downloads](https://img.shields.io/npm/dm/hac-mcp.svg)](https://www.npmjs.com/package/hac-mcp)
[![License](https://img.shields.io/badge/License-MIT--Commons--Clause-yellow.svg)](https://github.com/yunusemregul/hac-mcp/blob/master/LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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"*

![Web UI showing environment list and live activity log](docs/screenshots/web-ui-overview.jpeg)

## 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

| 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 |
| `job_status` | Poll a background job started with `async: true` |

## Content from files, results to files

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

| Tool | Inline | From disk |
|------|--------|-----------|
| `impex_import` | `script` (or `impexContent`) | `scriptPath`, or `scriptPaths` for an ordered list |
| `groovy_execute` | `script` | `scriptPath` |
| `flexible_search` | `query` | `queryPath` |
| `media_write` | `content` | `contentPath` |

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:

```jsonc
{ "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:

```jsonc
{ "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:

```jsonc
{ "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`:

```jsonc
{ "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:

```jsonc
{ "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)

```bash
npx hac-mcp
```

### Global install

```bash
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](https://pm2.keymetrics.io/)):

```bash
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**.

![Add Environment form with live connection test](https://github.com/yunusemregul/hac-mcp/blob/master/docs/screenshots/add-environment-form.jpeg)

### 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:

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

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

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

## Using with Claude Code

Claude Code can continue using the legacy SSE endpoint:

```bash
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:

```json
{
  "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:

```bash
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.