hac-mcp

AI 어시스턴트(Claude 등)에게 SAP Commerce Cloud의 **Hybris Administration Console(HAC)**에 대한 프로그래밍 방식 액세스를 제공하는 Model Context Protocol (MCP) 서버입니다. 여러 환경에서 자동화된 FlexibleSearch 쿼리, ImpEx 가져오기, Groovy 스크립트 실행, 시스템 관리 작업을 지원합니다.

기존 자격 증명을 사용하여 HAC에 인증하므로 백엔드 변경이나 추가 설정이 필요 없습니다. 허용된 작업은 환경별로 구성되므로 AI는 명시적으로 허용한 작업만 수행할 수 있습니다.

할 수 있는 작업

• "스테이징 환경에서 코드가 SUMMER25인 PromotionRule을 조사하고 로컬 환경에 재생성해 줘"

• "내 ImpEx가 스테이징에서 실패하고 있어. 프로덕션의 실제 값을 확인해서 올바른 값으로 채워 줘"

• "프로덕션에서 3일 이상 WAIT 상태로 멈춰 있는 모든 주문을 찾아서 요약해 줘"

• "...을 수행하는 Groovy 스크립트를 작성해서 먼저 로컬에서 실행하고, 작동하면 스테이징용으로 승인하겠어"

• "이 코드가 예상대로 작동하지 않아. 스테이징에서 실제 데이터로 Groovy를 사용해 엣지 케이스를 확인해 줄 수 있어?"

• "이 CronJob을 스테이징에서 테스트하고 싶어. source-product와 target-product 열이 있는 CSV를 txt 형식으로 받는 미디어 필드가 있어. 여러 테스트 미디어를 만들고, 작성하고, 각 케이스에 대해 작업을 실행한 다음 FlexibleSearch로 결과를 검증해 줘"

Related MCP server: Hybris MCP Server

기능

• 다중 환경 지원: 로컬, 스테이징, 프로덕션 HAC 인스턴스 구성 및 전환

• 세분화된 권한: 환경별 허용 작업 제어

• 웹 UI: 환경 추가/편집 및 활동 모니터링을 위한 브라우저 기반 관리 콘솔

• 실시간 로깅: SSE를 통한 실시간 HAC 요청 및 MCP 도구 실행 로그

• 디스크의 스크립트 실행 로그: 모든 Groovy, ImpEx, FlexSearch 실행은 스크립트와 결과와 함께 logs/<kind>/<date>/에 기록됩니다. 보존 기간(기본 30일)과 결과 잘림(기본 20,000자)은 웹 UI 설정 모달에서 구성할 수 있습니다.

• 타입 검색: 환경별 캐싱을 지원하는 SAP Commerce 타입 이름에 대한 trigram 기반 퍼지 검색

• FlexSearch 오류 복구: 알 수 없는 필드나 타입으로 인해 쿼리가 실패하면 유효한 필드 이름을 가져와 오류와 함께 반환하므로 AI가 수동 개입 없이 수정하고 재시도할 수 있습니다.

• ImpEx 검증 및 보강: 가져오기 실행 전에 필수 필드 누락 여부를 사전 검증하며, 가져오기 후 속성 오류가 발생하면 유효한 필드 목록으로 즉시 해결하여 AI가 스크립트를 직접 수정하고 재시도할 수 있습니다.

도구

설치

npx 사용(권장)

npx hac-mcp

전역 설치

npm install -g hac-mcp
hac-mcp

서버는 기본적으로 http://localhost:18432에서 시작됩니다.

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

환경 구성은 ~/.hac-mcp/environments.json에 저장됩니다.

시스템 부팅 시 자동 시작(선택 사항, 권장)

재시작 후에도 서버가 계속 실행되도록 하려면 startup 하위 명령을 사용하세요(PM2 필요):

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

이 명령은 서버를 PM2에 등록하고 pm2 startup을 실행하여 OS 부팅 시퀀스에 PM2를 연결하는 일회성 명령을 출력합니다(macOS/Linux에서는 sudo가 필요할 수 있음).

구성

웹 UI 사용

브라우저에서 http://localhost:18432/을 열고 + 환경 추가를 클릭한 다음 세부 정보를 입력하고(입력하는 동안 연결이 자동으로 테스트됨) 저장을 클릭합니다.

환경 옵션

프로덕션 팁: 우발적인 데이터 수정을 방지하려면 allowImpexImport, allowGroovyCommitMode 또는 둘 다 비활성화하세요.

Codex와 함께 사용

Codex는 Streamable HTTP 엔드포인트를 사용합니다:

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

또는 ~/.codex/config.toml에 직접 추가:

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

Claude Code와 함께 사용

Claude Code는 기존 SSE 엔드포인트를 계속 사용할 수 있습니다:

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

기타 MCP 클라이언트

Streamable HTTP를 지원하는 클라이언트의 경우:

MCP 클라이언트 구성에 다음을 추가하세요:

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

프로젝트 구조

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

릴리스 노트

v1.0.7 - 디스크의 스크립트 실행 로그가 이제 관리됩니다: 구성 가능한 보존 기간(기본 30일)이 시작 시와 매일 오래된 logs/<kind>/<date>/ 폴더를 정리하며, 결과 본문은 작성 전에 잘립니다(기본 20,000자). 설정 모달에서 두 가지를 모두 노출하고 로그 디렉터리와 현재 크기를 표시하며, 활동 로그 패널은 실행이 디스크에도 저장됨을 알립니다. CSRF 토큰 추출 실패 시 이제 단순한 파싱 오류 대신 HAC 연결 문제(VPN 다운 또는 IP가 허용 목록에 없음)로 보고합니다.

v1.0.6 - 웹 UI가 "HAC MCP" 제목 및 설정 모달 옆에 실행 중인 서버 버전을 표시합니다. 서버가 package.json을 읽는 대신 하드코딩된 1.0.0 버전을 보고하던 문제를 수정했습니다(실제로는 1.0.5였음).

보안 참고 사항

• 자격 증명은 ~/.hac-mcp/environments.json에 일반 텍스트로 저장됩니다. 이 파일이 노출되지 않도록 주의하세요.

• HAC 연결에 대한 SSL 인증서 검증이 비활성화되어 있습니다: 신뢰할 수 없는 네트워크에서 이 점을 유의하세요.

• 프로덕션 환경에서는 쓰기 권한(allowImpexImport, allowGroovyCommitMode)을 제한하세요.