hac-mcp

Ein Model Context Protocol (MCP)-Server, der KI-Assistenten (wie Claude) programmatischen Zugriff auf die Hybris Administration Console (HAC) von SAP Commerce Cloud bietet. Er ermöglicht automatisierte FlexibleSearch-Abfragen, ImpEx-Importe, die Ausführung von Groovy-Skripten und Systemverwaltungsaufgaben über mehrere Umgebungen hinweg.

Er authentifiziert sich bei HAC mit Ihren vorhandenen Anmeldedaten – keine Backend-Änderungen oder zusätzliche Einrichtung erforderlich. Erlaubte Operationen werden pro Umgebung konfiguriert, sodass die KI nur das tun kann, was Sie ausdrücklich erlauben.

Was Sie tun können

• „Untersuche die PromotionRule mit dem Code SUMMER25 im Staging und erstelle sie in meiner lokalen Umgebung neu“

• „Mein ImpEx schlägt im Staging fehl, prüfe die tatsächlichen Werte in der Produktion und fülle die richtigen ein“

• „Finde alle Bestellungen, die seit mehr als 3 Tagen im Status WAIT festhängen, in der Produktion und gib mir eine Zusammenfassung“

• „Schreibe ein Groovy-Skript, um ... zu tun, und führe es zuerst lokal aus. Wenn es funktioniert, werde ich es für das Staging freigeben“

• „Dieser Code funktioniert nicht wie erwartet. Kannst du seine Randfälle mit Groovy und echten Daten im Staging überprüfen?“

• „Ich möchte diesen CronJob im Staging testen. Er hat ein Medienfeld, das eine CSV im txt-Format mit den Spalten source-product und target-product akzeptiert. Erstelle mehrere Testmedien, schreibe sie, führe den Job für jeden Fall aus und validiere die Ergebnisse mit FlexibleSearch“

Related MCP server: Hybris MCP Server

Funktionen

• Unterstützung mehrerer Umgebungen: Konfigurieren und Wechseln zwischen lokalen, Staging- und Produktions-HAC-Instanzen

• Feingranulare Berechtigungen: Steuern Sie, welche Operationen pro Umgebung erlaubt sind

• Web-UI: Browserbasierte Verwaltungskonsole zum Hinzufügen/Bearbeiten von Umgebungen und zur Überwachung der Aktivität

• Echtzeit-Protokollierung: Live-Protokolle von HAC-Anfragen und MCP-Tool-Ausführungen über SSE

• Skript-Ausführungsprotokolle auf der Festplatte: Jede Groovy-, ImpEx- und FlexSearch-Ausführung wird mit Skript und Ergebnis in logs/<kind>/<date>/ geschrieben. Aufbewahrungsdauer (Standard 30 Tage) und Ergebnis-Kürzung (Standard 20.000 Zeichen) sind im Web-UI-Einstellungsdialog konfigurierbar.

• Typsuche: Trigramm-basierte Fuzzy-Suche nach SAP-Commerce-Typnamen mit Caching pro Umgebung

• FlexSearch-Fehlerbehebung: Wenn eine Abfrage aufgrund eines unbekannten Felds oder Typs fehlschlägt, werden gültige Feldnamen abgerufen und zusammen mit dem Fehler zurückgegeben, damit die KI den Fehler korrigieren und ohne manuellen Eingriff erneut versuchen kann.

• ImpEx-Validierung und -Anreicherung: Skripte werden vor dem Import auf fehlende Pflichtfelder validiert, und etwaige Attributfehler nach dem Import werden spontan in gültige Feldlisten aufgelöst, damit die KI das Skript selbst korrigieren und erneut versuchen kann.

Tools

Installation

Über npx (empfohlen)

npx hac-mcp

Globale Installation

npm install -g hac-mcp
hac-mcp

Der Server startet standardmäßig auf http://localhost:18432.

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

Die Umgebungskonfiguration wird in ~/.hac-mcp/environments.json gespeichert.

Automatischer Start beim Systemstart (optional, empfohlen)

Um den Server über Neustarts hinweg laufen zu lassen, verwenden Sie den Unterbefehl startup (erfordert PM2):

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

Dies registriert den Server bei PM2 und führt pm2 startup aus, das einen einmaligen Befehl ausgibt, den Sie ausführen müssen (auf macOS/Linux möglicherweise mit sudo), um PM2 in die Boot-Sequenz Ihres Betriebssystems einzubinden.

Konfiguration

Über die Web-UI

Öffnen Sie http://localhost:18432/ in Ihrem Browser, klicken Sie auf + Umgebung hinzufügen, füllen Sie die Details aus (die Verbindung wird automatisch während der Eingabe getestet) und klicken Sie dann auf Speichern.

Umgebungsoptionen

Tipp für die Produktion: Deaktivieren Sie allowImpexImport, allowGroovyCommitMode oder beide, um versehentliche Datenänderungen zu verhindern.

Verwendung mit Codex

Codex verwendet den Streamable-HTTP-Endpunkt:

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

Oder fügen Sie es direkt zu ~/.codex/config.toml hinzu:

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

Verwendung mit Claude Code

Claude Code kann weiterhin den alten SSE-Endpunkt verwenden:

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

Andere MCP-Clients

Für Clients, die Streamable HTTP unterstützen, verwenden Sie:

Fügen Sie Folgendes zu Ihrer MCP-Client-Konfiguration hinzu:

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

Projektstruktur

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

Versionshinweise

v1.0.7 – Skript-Ausführungsprotokolle auf der Festplatte werden jetzt verwaltet: Eine konfigurierbare Aufbewahrungsdauer (Standard 30 Tage) bereinigt alte logs/<kind>/<date>/-Ordner beim Start und täglich, und Ergebnisinhalte werden vor dem Schreiben gekürzt (Standard 20.000 Zeichen). Der Einstellungsdialog legt beides offen, zeigt das Protokollverzeichnis und dessen aktuelle Größe, und das Aktivitätsprotokoll weist darauf hin, dass Ausführungen auch auf der Festplatte gespeichert werden. Fehlgeschlagene CSRF-Token-Extraktion wird nun als HAC-Konnektivitätsproblem (VPN ausgefallen oder IP nicht whitelisted) gemeldet, statt als bloßer Parse-Fehler.

v1.0.6 – Die Web-UI zeigt die laufende Serverversion neben dem Titel „HAC MCP“ und im Setup-Dialog. Behoben, dass der Server zuvor eine fest codierte Version 1.0.0 meldete, anstatt package.json zu lesen (tatsächlich war es 1.0.5).

Sicherheitshinweise

• Anmeldedaten werden im Klartext in ~/.hac-mcp/environments.json gespeichert. Vermeiden Sie, diese Datei offenzulegen.

• Die SSL-Zertifikatsprüfung ist für HAC-Verbindungen deaktiviert: Seien Sie sich dessen in nicht vertrauenswürdigen Netzwerken bewusst.

• Beschränken Sie Schreibberechtigungen (allowImpexImport, allowGroovyCommitMode) in Produktionsumgebungen.