SAP Commerce MCP Server

An MCP (Model Context Protocol) 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
• Installation
• Quickstart
• Tools reference
• Per-agent configuration
• Security
• CI / headless usage
• Migrating existing configs
• Config file reference
• Multiple environments
• Troubleshooting
• Contributing
• 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.
• 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

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:

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).
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)

{
  "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

{
  "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

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

{
  "$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), 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:

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:

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

password is optional per server — see 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) 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) — 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 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); 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:

npm test

License

MIT © Niraj Lonkar