SAP Commerce MCP Server

This project exposes an MCP server for SAP Commerce Cloud focused on ASM employee workflows: search a customer, impersonate them, bind or manage a cart, and complete OCC-backed commerce actions through task-oriented MCP tools.

The repo is now treated as local-first: the expected default target is https://localhost:9002, with SAP_BASE_URL controlling the actual host. Remote tenants can still be used, but the docs, tests, and validation flow should make the local SAP Commerce runtime truth-first.

What this server does now

• ASM-first customer actions: search a customer, impersonate a customer, and continue acting on their behalf

• Session-aware cart management: create, inspect, update, remove, and clear carts without manual cart juggling

• Checkout flow: delivery address, delivery mode, guest email, and order placement

• Product and discovery tools: search products, fetch details, inspect stock, browse base sites/stores/catalogs/categories

• Two tool layers: high-level agent-friendly tools plus low-level OCC/ASM wrappers

• Session orientation: get_session_status helps agents understand the current cart/user/base-site context

• FastMCP transport: stdio and SSE transports for local or remote MCP clients

How a request flows

1. Architecture at a glance

Source: docs/diagrams/architecture.mmd

2. Example request swimlane

This is the typical “agent impersonates a customer, then keeps shopping on their behalf” path.

Source: docs/diagrams/example-request.mmd

MCP tools

High-level tools

These are the main contract for ASM employee workflows.

Discovery and products

• search_products — keyword product discovery

• get_product — fetch one product detail

• get_session_status — inspect current session state

Customer / ASM

• search_customer — find a customer quickly

• impersonate_customer — start acting as customer

• end_impersonation — return to anonymous mode

Cart and checkout

• add_to_cart — add one product

• get_cart — read current cart

• update_cart_entry — change entry quantity

• remove_from_cart — delete one entry

• clear_cart — empty the cart

• set_delivery_address — attach shipping address

• set_delivery_mode — choose shipping method

• get_delivery_modes — list shipping options

• set_guest_email — set guest checkout email

• place_order — submit the order

Low-level tools

These expose narrower OCC / ASM primitives for exact control.

• basesites.list — list available base sites

• catalogs.list — list catalogs for a site

• catalogs.get — fetch one catalog

• catalogVersions.get — fetch one catalog version

• categories.products — browse products by category

• stores.list — list stores for a site

• stores.get — fetch one base store

• products.get — fetch one OCC product

• products.stock — inspect stock data

• products.stockCount — count stock locations

• asm.customer360 — fetch customer 360 fragments

• asm.customers.create — create a customer

• asm.customers.search — run ASM customer search

• asm.customers.suggest — get customer suggestions

• carts.list — list carts

• carts.create — create or restore cart

• carts.get — fetch one cart

• carts.delete — delete one cart

• cartEntries.list — list cart entries

• cartEntries.add — add one entry

• cartEntries.get — fetch one entry

• cartEntries.update — replace entry payload

• cartEntries.patch — partially update entry

• cartEntries.delete — delete one entry

Configuration

1. Install dependencies:

   uv sync

2. Copy the environment template:

   cp .env.example .env

3. For the local SAP Commerce instance, set:

   SAP_BASE_URL=https://localhost:9002

4. Keep or adjust these path fragments if your SAP deployment differs:

   • OCC_API_PATH=/occ/v2

   • OAUTH_PATH=/authorizationserver/oauth/token

   • ASM_PATH=/assistedservicewebservices

5. Configure OAuth credentials for the local tenant or remote tenant you are validating against. For the stock local sample-data setup, these are the expected defaults:

   OAUTH_CLIENT_ID=mobile_android
   OAUTH_CLIENT_SECRET=secret
   OAUTH_USERNAME=asmagent
   OAUTH_PASSWORD=nimda
   OAUTH_SCOPE=basic

Running

• Stdio:

  python -m app.server

• SSE:

  fastmcp serve app/server.py --sse :8080

Testing

• Full verification suite:

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

• Smoke checks:

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

• Live discovery flow:

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

Note Live tests are intended to validate the current contract against a real SAP Commerce runtime. When SAP_BASE_URL=https://localhost:9002, the local OCC/ASM instance should be the primary proof target. If OAuth or ASM data is misconfigured, diagnose it locally before broadening scope.

Local SAP caveat Some SAP 2211 local stacks include messagecentercsocc, whose late Oauth2UserFilter can overwrite the /users/{customerId} on-behalf context with the authenticated agent again. If asmagent cart calls regress to EmployeeModel -> CustomerModel cast errors, patch that filter so it preserves the already-matched customer when the current OCC user differs from the OAuth principal.

Quality gates

• Ruff for linting and import hygiene

• Mypy for a practical static type gate across app/

• Pytest + coverage.xml so SonarQube can consume the same local evidence used in CI

Local SonarQube analysis can be published with:

uv run pytest -q
sonar-scanner

sonar-project.properties is checked in so local and CI scans use the same project key/source layout.

Documentation

• Workflows — practical tool-call sequences

• Architecture Mermaid — source for the system diagram

• Request Mermaid — source for the swimlane diagram

• MCP manifest and tool registration: app/server.py

• Contribution guide: AGENTS.md

Future improvements

• add an optional external backing store only if the project later needs multi-process or horizontally scaled session persistence

Supported OCC / ASM coverage

The current server covers the endpoints needed for the flows above, including base sites, catalogs, stores, products, carts, cart entries, checkout address/delivery operations, order placement, and ASM customer search / customer 360 / bind-cart style operations.