# SAP Commerce MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

An MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server that
exposes SAP Commerce (Hybris) HAC consoles — FlexibleSearch, Groovy
scripting, ImpEx, and type system browsing — to MCP-capable coding agents:
**Claude Code**, **Cursor**, **GitHub Copilot** (VS Code), **opencode**, and
any other MCP client. Point it at one or more SAP Commerce instances and let
your agent query data, run scripts, import data, and inspect the type system
directly from the console — without ever putting a password in front of the
LLM.

## Contents

- [Features](#features)
- [Installation](#installation)
- [Quickstart](#quickstart)
- [Tools reference](#tools-reference)
- [Per-agent configuration](#per-agent-configuration)
- [Security](#security)
- [CI / headless usage](#ci--headless-usage)
- [Migrating existing configs](#migrating-existing-configs)
- [Config file reference](#config-file-reference)
- [Multiple environments](#multiple-environments)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

## Features

- **Multi-environment**: configure any number of HAC servers (local, dev,
  staging, prod, ...) and switch between them mid-conversation, or target a
  specific one per tool call without switching.
- **Multi-agent setup wizard**: one interactive wizard configures **Claude
  Code**, **Cursor**, **GitHub Copilot (VS Code)**, and **opencode** —
  detecting which agents are already in use in your project and writing (or
  merging into) each one's native MCP config file.
- **Credentials never touch the LLM**: adding a server or changing a
  password always routes through the CLI wizard, never through chat —
  `add_server`/`update_server` tool descriptions instruct the agent to run
  the wizard rather than ask you for a password inline.
- **OS-keychain-backed credential storage**: passwords are stored in macOS
  Keychain, Windows Credential Manager, or the Linux Secret Service by
  default, with automatic fallback to an environment variable or (as a last
  resort) a plaintext file field — see [Security](#security).
- **One-command migration**: re-run the wizard on an older plaintext config
  and it offers to move every stored password into the OS keychain and
  strip it from the file.
- **FlexibleSearch, Groovy, ImpEx, and type-system browsing**, each callable
  against a named server without disturbing the active one.

## Installation

```bash
npm install -g @nirajlonkar/sap-commerce-mcp-server
```

This installs two CLI commands globally: `sap-commerce-mcp-setup` (the setup
wizard) and `sap-commerce-mcp-server` (the MCP server binary itself, which
your coding agent launches for you — you won't normally run this by hand).

## Quickstart

Run the setup wizard from inside the project you want to configure:

```bash
sap-commerce-mcp-setup
```

The wizard will:

1. Ask for (or find) your config file — defaults to
   `sapcc-mcp-servers.json` in the current directory. If it finds an existing
   config with plaintext passwords, it offers to migrate them to the OS
   keychain (see [Migrating existing configs](#migrating-existing-configs)).
2. Ask for the server details: name, HAC base URL, username, whether to make
   it the default server, and the password (entered with input masked, not
   echoed to the terminal).
3. Store the password in the OS keychain if one is available, falling back
   to a plaintext `password` field in the config file with a loud warning if
   not.
4. Walk up from your current directory looking for project markers
   (`.claude`, `.cursor`, `.vscode`, `.mcp.json`, `opencode.json`, `.git`) to
   find your project root. If it finds more than one candidate, it asks you
   to pick one; if it finds none, it asks you to type a path.
5. Detect which coding agents are in use in that project and let you pick
   which ones to configure (detected agents are pre-selected). It can
   configure **Claude Code**, **Cursor**, **GitHub Copilot (VS Code)**, and
   **opencode** — writing (or merging into) each agent's MCP config file.
   For any agent you skip, it prints the config snippet so you can add it
   by hand.

Re-running the wizard is safe: it merges into existing agent config files
rather than overwriting them, and offers to update or add servers to your
config file. **Restart your coding agent** after the wizard writes its
config — MCP clients read their config file at startup and won't pick up
changes to a running session.

## Tools reference

| Tool | Purpose |
|---|---|
| `list_servers` | List all configured HAC servers and show which one is active. |
| `switch_server` | Switch the active server (accepts partial/case-insensitive names). |
| `add_server` | Returns instructions to run the CLI wizard — never accepts a password through chat. |
| `remove_server` | Remove a configured server (not the active one, not the last one). |
| `update_server` | Update a server's URL or username; password changes are routed to the CLI wizard. |
| `test_connection` | Test connectivity and authentication against a server. |
| `execute_flexiblesearch` | Run a read-oriented FlexibleSearch query, optionally against a non-active server. |
| `execute_groovy` | Run a Groovy script in the HAC scripting console. Can modify data if `commit=true`. |
| `execute_impex` | Run an ImpEx script via the HAC import console. Modifies data in the target system. |
| `browse_type_system` | Look up a Hybris composed type and its attributes, or list all types. |

## Per-agent configuration

Each agent adapter points its MCP client at
`node <path-to-global-install>/src/index.js` with `SAPCC_CONFIG_FILE` set to
your servers config file. Below are the exact file paths and JSON shapes the
wizard writes (and what to copy by hand if you configure an agent
manually).

### Claude Code

File: `.mcp.json` (project root)

```json
{
  "mcpServers": {
    "sap-commerce": {
      "command": "node",
      "args": ["/absolute/path/to/src/index.js"],
      "env": {
        "SAPCC_CONFIG_FILE": "/absolute/path/to/sapcc-mcp-servers.json"
      }
    }
  }
}
```

### Cursor

File: `.cursor/mcp.json`

```json
{
  "mcpServers": {
    "sap-commerce": {
      "command": "node",
      "args": ["/absolute/path/to/src/index.js"],
      "env": {
        "SAPCC_CONFIG_FILE": "/absolute/path/to/sapcc-mcp-servers.json"
      }
    }
  }
}
```

### GitHub Copilot (VS Code)

File: `.vscode/mcp.json`

```json
{
  "servers": {
    "sap-commerce": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/src/index.js"],
      "env": {
        "SAPCC_CONFIG_FILE": "/absolute/path/to/sapcc-mcp-servers.json"
      }
    }
  }
}
```

### opencode

File: `opencode.json` (project root)

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sap-commerce": {
      "type": "local",
      "command": ["node", "/absolute/path/to/src/index.js"],
      "environment": {
        "SAPCC_CONFIG_FILE": "/absolute/path/to/sapcc-mcp-servers.json"
      },
      "enabled": true
    }
  }
}
```

Notes:
- The wizard merges these entries into existing files rather than
  overwriting them (an existing `mcpServers`/`servers`/`mcp` object is
  preserved, and only the `sap-commerce` key is added or replaced).
- If an existing config file is present but not valid JSON, it's copied to
  `<file>.bak-<timestamp>` before being rewritten, so nothing is silently
  lost.
- Restart the agent after writing/editing its config so it picks up the new
  server.

## Security

This server is designed so that **HAC credentials never pass through LLM
context** and are never stored in plaintext by default. Specifics:

- **Credentials only ever enter via the CLI wizard.** The `add_server` and
  `update_server` MCP tools never accept a password argument — their tool
  descriptions explicitly instruct the calling agent to run
  `sap-commerce-mcp-setup` instead. This means a prompt-injected or
  malicious instruction inside HAC data cannot trick the agent into
  exfiltrating or setting a credential through chat.
- **OS-keychain-backed storage, with graceful fallback.** Passwords are
  resolved in this order, per server, the first time the config is loaded:
  1. **OS keychain** (macOS Keychain, Windows Credential Manager, Linux
     Secret Service via [`@napi-rs/keyring`](https://github.com/napi-rs/keyring-rs)),
     under service name `sap-commerce-mcp` and account name equal to the
     server's `name`. This is the default when the setup wizard stores a
     password and a keychain is available.
  2. **Environment variable** `SAPCC_PASSWORD_<NAME>`, where `<NAME>` is the
     server's `name` upper-cased with every non-`[A-Z0-9]` character
     replaced by `_`. For example, a server named `dev-eu` resolves to
     `SAPCC_PASSWORD_DEV_EU`.
  3. **Plaintext `password` field** in the config file — used only as a
     last resort. This is discouraged: a warning is printed to stderr every
     time a server's password is resolved from the file, telling you to
     re-run the setup wizard to migrate it to the keychain.

  If none of the three tiers produce a password for a server, the server
  fails to start with an error listing all three options.

  `@napi-rs/keyring` is an **optionalDependency** with a native binding. On
  platforms where it fails to install (or isn't supported), the server
  still runs — it just skips straight to the environment variable and
  plaintext tiers.
- **Config file permissions.** On non-Windows systems, the setup wizard
  writes the servers config file with `600` permissions (owner read/write
  only), and the server warns on stderr at startup if it finds the file
  with looser permissions. Windows relies on the user account's own ACLs —
  there's no equivalent file-mode enforcement to check.
- **Password input is masked, never echoed.** The wizard reads the password
  character-by-character in raw terminal mode and never writes it to shell
  history, a log, or stdout.
- **Known tradeoff: self-signed TLS certificates are always accepted**
  (`rejectUnauthorized: false` in `src/hac-client.js`), with no option to
  turn this off. This is deliberate — HAC on local/dev instances almost
  always runs behind a self-signed cert — but it means the server does not
  verify the identity of the HAC endpoint it connects to. Only point this
  server at HAC URLs you trust and reach over a network path you trust
  (e.g. localhost, a VPN, or a private network); avoid pointing it at a HAC
  endpoint reachable over an untrusted or public network.
- **No telemetry.** The server makes no network calls other than to the
  HAC endpoints you configure.

## CI / headless usage

For CI or any environment where there's no OS keychain and no interactive
terminal:

1. Keep the `password` field out of your servers config file entirely (omit
   it — it's optional).
2. Set `SAPCC_PASSWORD_<NAME>` in the environment for each server, using the
   same uppercase/underscore normalization described above (e.g. a server
   named `dev-eu` needs `SAPCC_PASSWORD_DEV_EU`).
3. Set `SAPCC_CONFIG_FILE` to point at the servers config file if it's not
   in the default location.

This avoids ever writing a credential to disk in the CI environment.

## Migrating existing configs

If you have an older config file with plaintext `password` fields, re-run
the setup wizard:

```bash
sap-commerce-mcp-setup
```

When it finds servers with a plaintext `password` field and an OS keychain
is available, it asks:

```
Move N stored password(s) into the OS keychain and remove them from the file? (y/n)
```

Answering yes moves each password into the keychain (service
`sap-commerce-mcp`, account = server name) and deletes the `password` field
from the file. Any password that fails to migrate (e.g. keychain write
error) is left in place in the file, and the wizard tells you which ones.

## Config file reference

The servers config file (default location:
`~/.sapcc-mcp/servers.json`, or `%APPDATA%\sapcc-mcp\servers.json` on
Windows; override with `SAPCC_CONFIG_FILE`) has this shape:

```json
{
  "defaultServer": "local",
  "servers": [
    {
      "name": "local",
      "url": "https://localhost:9002/hac",
      "user": "admin"
    }
  ]
}
```

`password` is optional per server — see [Security](#security) for how it's
supplied. On non-Windows systems, the server warns on stderr if the config
file's permissions aren't `600` (owner read/write only); the setup wizard
sets this automatically when it writes the file.

**Note on the default path above vs. the wizard's suggested path:** the
setup wizard (`sap-commerce-mcp-setup`) suggests `sapcc-mcp-servers.json` in
your current directory as its default save location — a different default
from the server's own built-in lookup path described above. These two
defaults are independent and normally never interact: every agent config
snippet the wizard writes (see
[Per-agent configuration](#per-agent-configuration)) sets `SAPCC_CONFIG_FILE`
explicitly to wherever the wizard actually saved the file, so the server
always knows exactly where to look and its own default path is never
consulted. That built-in default only matters if you run
`sap-commerce-mcp-server` (or `node src/index.js`) directly *without*
`SAPCC_CONFIG_FILE` set — e.g. a manual or CI invocation (see
[CI / headless usage](#ci--headless-usage)) — in which case you must either
set `SAPCC_CONFIG_FILE` or place your config file at that exact default
path.

## Multiple environments

Add as many servers as you like — run `sap-commerce-mcp-setup` again with a
new server name to add another environment (dev, staging, prod, ...) to the
same config file. Once configured, use `list_servers` to see them all,
`switch_server <name>` to change which one subsequent calls target, or pass
`server: "<name>"` to any `execute_*`/`browse_type_system` call to target a
specific environment without switching.

## Troubleshooting

- **"Config file not found" at server startup**: either set
  `SAPCC_CONFIG_FILE` to your config file's path, or run
  `sap-commerce-mcp-setup` to create one at the default location.
- **"No password found for server ..."**: none of the three credential
  tiers produced a password — see [Security](#security) for the resolution
  order, and re-run the wizard to store one.
- **Agent doesn't see the new server after running the wizard**: MCP
  clients (Claude Code, Cursor, Copilot, opencode) all read their MCP
  config at startup only. Restart the agent/session.
- **SSL certificate errors**: the server already accepts self-signed
  certificates (see [Security](#security)); a certificate error usually
  means the HAC URL, port, or `/hac` path in your config is wrong, or the
  target isn't reachable from where the server runs.

## Contributing

Issues and pull requests are welcome. Run the test suite with:

```bash
npm test
```

## License

[MIT](LICENSE) © Niraj Lonkar