SAP Commerce MCP 서버

Quality Gate Status Coverage SonarCloud Python License

이 프로젝트는 ASM 직원 워크플로우에 중점을 둔 SAP Commerce Cloud용 MCP 서버를 제공합니다. 고객 검색, 고객 가장(impersonation), 장바구니 바인딩 또는 관리, 그리고 작업 지향적 MCP 도구를 통한 OCC 기반 커머스 작업 완료 기능을 수행합니다.

이 저장소는 이제 **로컬 우선(local-first)**으로 처리됩니다. 예상되는 기본 대상은 https://localhost:9002이며, SAP_BASE_URL이 실제 호스트를 제어합니다. 원격 테넌트도 여전히 사용할 수 있지만, 문서, 테스트 및 검증 흐름은 로컬 SAP Commerce 런타임을 진실의 원천(truth-first)으로 삼아야 합니다.

현재 이 서버가 수행하는 작업

ASM 우선 고객 작업: 고객 검색, 고객 가장, 고객을 대신하여 작업 수행
세션 인식 장바구니 관리: 수동으로 장바구니를 조작할 필요 없이 장바구니 생성, 검사, 업데이트, 제거 및 비우기
결제 흐름: 배송 주소, 배송 방식, 게스트 이메일 및 주문 생성
제품 및 검색 도구: 제품 검색, 세부 정보 가져오기, 재고 검사, 기본 사이트/매장/카탈로그/카테고리 탐색
두 가지 도구 계층: 에이전트 친화적인 상위 수준 도구와 하위 수준 OCC/ASM 래퍼
세션 지향: get_session_status를 통해 에이전트가 현재 장바구니/사용자/기본 사이트 컨텍스트를 파악하도록 지원
FastMCP 전송: 로컬 또는 원격 MCP 클라이언트를 위한 stdio 및 SSE 전송

요청 흐름

1. 아키텍처 개요

Architecture overview

출처: docs/diagrams/architecture.mmd

2. 요청 스윔레인 예시

이는 "에이전트가 고객을 가장한 후, 고객을 대신하여 쇼핑을 계속하는" 일반적인 경로입니다.

Example request swimlane

출처: docs/diagrams/example-request.mmd

MCP 도구

상위 수준 도구

이 도구들은 ASM 직원 워크플로우를 위한 주요 계약입니다.

검색 및 제품

search_products — 키워드 제품 검색
get_product — 단일 제품 세부 정보 가져오기
get_session_status — 현재 세션 상태 검사

고객 / ASM

search_customer — 고객을 빠르게 찾기
impersonate_customer — 고객으로 가장 시작
end_impersonation — 익명 모드로 복귀

장바구니 및 결제

add_to_cart — 제품 하나 추가
get_cart — 현재 장바구니 읽기
update_cart_entry — 항목 수량 변경
remove_from_cart — 항목 하나 삭제
clear_cart — 장바구니 비우기
set_delivery_address — 배송 주소 연결
set_delivery_mode — 배송 방식 선택
get_delivery_modes — 배송 옵션 나열
set_guest_email — 게스트 결제 이메일 설정
place_order — 주문 제출

하위 수준 도구

이 도구들은 정확한 제어를 위해 더 좁은 범위의 OCC / ASM 기본 요소를 노출합니다.

basesites.list — 사용 가능한 기본 사이트 나열
catalogs.list — 사이트의 카탈로그 나열
catalogs.get — 카탈로그 하나 가져오기
catalogVersions.get — 카탈로그 버전 하나 가져오기
categories.products — 카테고리별 제품 탐색
stores.list — 사이트의 매장 나열
stores.get — 기본 매장 하나 가져오기
products.get — OCC 제품 하나 가져오기
products.stock — 재고 데이터 검사
products.stockCount — 재고 위치 계산
asm.customer360 — 고객 360 조각 가져오기
asm.customers.create — 고객 생성
asm.customers.search — ASM 고객 검색 실행
asm.customers.suggest — 고객 제안 가져오기
carts.list — 장바구니 나열
carts.create — 장바구니 생성 또는 복원
carts.get — 장바구니 하나 가져오기
carts.delete — 장바구니 하나 삭제
cartEntries.list — 장바구니 항목 나열
cartEntries.add — 항목 하나 추가
cartEntries.get — 항목 하나 가져오기
cartEntries.update — 항목 페이로드 교체
cartEntries.patch — 항목 부분 업데이트
cartEntries.delete — 항목 하나 삭제

구성

종속성 설치:
```
uv sync
```
환경 템플릿 복사:
```
cp .env.example .env
```
로컬 SAP Commerce 인스턴스의 경우 다음을 설정합니다:
```
SAP_BASE_URL=https://localhost:9002
```
SAP 배포 환경이 다른 경우 다음 경로 조각을 유지하거나 조정하십시오:
- OCC_API_PATH=/occ/v2
- OAUTH_PATH=/authorizationserver/oauth/token
- ASM_PATH=/assistedservicewebservices
로컬 테넌트 또는 검증 대상 원격 테넌트에 대한 OAuth 자격 증명을 구성합니다. 기본 로컬 샘플 데이터 설정의 경우, 예상되는 기본값은 다음과 같습니다:
```
OAUTH_CLIENT_ID=mobile_android
OAUTH_CLIENT_SECRET=secret
OAUTH_USERNAME=asmagent
OAUTH_PASSWORD=nimda
OAUTH_SCOPE=basic
```

실행

Stdio:
```
python -m app.server
```
SSE:
```
fastmcp serve app/server.py --sse :8080
```

테스트

전체 검증 제품군:

uv run ruff check app tests
uv run mypy app
uv run pytest -q

스모크 체크:

uv run pytest tests/integration/test_smoke.py -q

라이브 검색 흐름:

uv run pytest tests/integration/test_integration_live.py -s

참고 라이브 테스트는 실제 SAP Commerce 런타임에 대해 현재 계약을 검증하기 위한 것입니다. SAP_BASE_URL=https://localhost:9002일 때, 로컬 OCC/ASM 인스턴스가 주요 증명 대상이어야 합니다. OAuth 또는 ASM 데이터가 잘못 구성된 경우, 범위를 넓히기 전에 로컬에서 진단하십시오.

로컬 SAP 주의사항 일부 SAP 2211 로컬 스택에는 messagecentercsocc가 포함되어 있으며, 이 필터의 후반부 Oauth2UserFilter는 인증된 에이전트의 /users/{customerId} 대리 컨텍스트를 다시 덮어쓸 수 있습니다. asmagent 장바구니 호출이 EmployeeModel -> CustomerModel 캐스트 오류로 회귀하는 경우, 현재 OCC 사용자가 OAuth 주체와 다를 때 이미 일치된 고객을 유지하도록 해당 필터를 패치하십시오.

품질 게이트

린팅 및 가져오기 위생을 위한 Ruff
app/ 전반에 걸친 실용적인 정적 유형 게이트를 위한 Mypy
SonarQube가 CI에서 사용되는 것과 동일한 로컬 증거를 소비할 수 있도록 하는 Pytest + coverage.xml

로컬 SonarQube 분석은 다음을 통해 게시할 수 있습니다:

uv run pytest -q
sonar-scanner

sonar-project.properties가 체크인되어 있으므로 로컬 및 CI 스캔은 동일한 프로젝트 키/소스 레이아웃을 사용합니다.

문서

워크플로우 — 실용적인 도구 호출 시퀀스
아키텍처 Mermaid — 시스템 다이어그램 소스
요청 Mermaid — 스윔레인 다이어그램 소스
MCP 매니페스트 및 도구 등록: app/server.py
기여 가이드: AGENTS.md

향후 개선 사항

프로젝트가 나중에 다중 프로세스 또는 수평적으로 확장된 세션 지속성이 필요한 경우에만 선택적 외부 백업 저장소 추가

지원되는 OCC / ASM 범위

현재 서버는 기본 사이트, 카탈로그, 매장, 제품, 장바구니, 장바구니 항목, 결제 주소/배송 작업, 주문 생성 및 ASM 고객 검색 / 고객 360 / 장바구니 바인딩 스타일 작업을 포함하여 위 흐름에 필요한 엔드포인트를 다룹니다.

SAP Commerce MCP Server