hac-mcp

Un servidor de Model Context Protocol (MCP) que proporciona a los asistentes de IA (como Claude) acceso programático a la Hybris Administration Console (HAC) de SAP Commerce Cloud. Permite consultas FlexibleSearch automatizadas, importaciones ImpEx, ejecución de scripts Groovy y tareas de administración del sistema en múltiples entornos.

Se autentica con HAC usando tus credenciales existentes, sin necesidad de cambios en el backend ni configuración adicional. Las operaciones permitidas se configuran por entorno, de modo que la IA solo puede hacer lo que tú autorizas explícitamente.

Lo que puedes hacer

• "Inspecciona la PromotionRule con código SUMMER25 en staging y recréala en mi entorno local"

• "Mi ImpEx está fallando en staging, comprueba los valores reales en producción y rellena los correctos"

• "Encuentra todos los pedidos atascados en estado WAIT durante más de 3 días en producción y dame un resumen"

• "Escribe un script Groovy para hacer ... y ejecútalo primero en local; si funciona, lo aprobaré para staging"

• "Este código no funciona como se esperaba, ¿puedes comprobar sus casos límite usando Groovy con datos reales en staging?"

• "Quiero probar este CronJob en staging; tiene un campo de media que acepta un CSV en formato txt con columnas source-product y target-product. Crea varios media de prueba, escríbelos, ejecuta el job para cada caso y valida los resultados con FlexibleSearch"

Related MCP server: Hybris MCP Server

Características

• Soporte multi-entorno: configura y cambia entre instancias HAC locales, de staging y de producción

• Permisos granulares: controla qué operaciones están permitidas por entorno

• Interfaz web: consola de gestión basada en navegador para añadir/editar entornos y monitorizar la actividad

• Registro en tiempo real: registros en vivo de solicitudes HAC y ejecución de herramientas MCP vía SSE

• Registros de ejecución en disco: cada ejecución de Groovy, ImpEx y FlexSearch se escribe en logs/<kind>/<date>/ con su script y resultado. La retención (por defecto 30 días) y el truncamiento de resultados (por defecto 20.000 caracteres) son configurables en el modal de Ajustes de la interfaz web

• Búsqueda de tipos: búsqueda difusa basada en trigramas para nombres de tipos de SAP Commerce con caché por entorno

• Recuperación de errores de FlexibleSearch: cuando una consulta falla debido a un campo o tipo desconocido, se obtienen los nombres de campo válidos y se devuelven junto con el error para que la IA pueda corregir y reintentar sin intervención manual

• Validación y enriquecimiento de ImpEx: los scripts se prevalidan para detectar campos obligatorios faltantes antes de ejecutar la importación, y cualquier error de atributos posterior a la importación se resuelve en listas de campos válidos sobre la marcha para que la IA pueda corregir y reintentar el script por sí misma

Herramientas

Instalación

Vía npx (recomendado)

npx hac-mcp

Instalación global

npm install -g hac-mcp
hac-mcp

El servidor se inicia en http://localhost:18432 por defecto.

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

La configuración de entornos se almacena en ~/.hac-mcp/environments.json.

Inicio automático al arrancar el sistema (opcional, recomendado)

Para mantener el servidor en ejecución entre reinicios, usa el subcomando startup (requiere PM2):

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

Esto registra el servidor con PM2 y ejecuta pm2 startup, que imprime un comando de una sola vez para ejecutar (puede requerir sudo en macOS/Linux) para conectar PM2 a la secuencia de arranque de tu sistema operativo.

Configuración

Vía interfaz web

Abre http://localhost:18432/ en tu navegador, haz clic en + Añadir Entorno, completa los detalles (la conexión se prueba automáticamente mientras escribes) y luego haz clic en Guardar.

Opciones de entorno

Consejo para producción: Desactiva allowImpexImport, allowGroovyCommitMode o ambos para evitar modificaciones accidentales de datos.

Uso con Codex

Codex usa el endpoint HTTP Streamable:

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

O añádelo directamente a ~/.codex/config.toml:

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

Uso con Claude Code

Claude Code puede seguir usando el endpoint SSE heredado:

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

Otros clientes MCP

Para clientes que soporten HTTP Streamable, usa:

Añade lo siguiente a la configuración de tu cliente MCP:

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

Estructura del proyecto

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

Notas de la versión

v1.0.7 - Los registros de ejecución de scripts en disco ahora se gestionan: la retención configurable (por defecto 30 días) elimina las carpetas antiguas logs/<kind>/<date>/ al inicio y diariamente, y los cuerpos de resultados se truncan (por defecto 20.000 caracteres) antes de escribirse. El modal de Ajustes expone ambos, muestra el directorio de registros y su tamaño actual, y el panel de registro de actividad indica que las ejecuciones también se guardan en disco. La extracción fallida del token CSRF ahora se informa como un problema de conectividad con HAC (VPN caída o IP no incluida en la lista blanca) en lugar de un error de análisis simple.

v1.0.6 - La interfaz web muestra la versión del servidor en ejecución junto al título "HAC MCP" y el modal de configuración. Se corrigió que el servidor informara una versión fija 1.0.0 en lugar de leer package.json (en realidad era 1.0.5).

Notas de seguridad

• Las credenciales se almacenan en texto plano en ~/.hac-mcp/environments.json. Evita exponer este archivo.

• La verificación de certificados SSL está deshabilitada para las conexiones HAC: ten esto en cuenta en redes no confiables.

• Restringe los permisos de escritura (allowImpexImport, allowGroovyCommitMode) en entornos de producción.