SAP Commerce MCP Server

Этот проект предоставляет MCP-сервер для SAP Commerce Cloud, ориентированный на рабочие процессы сотрудников ASM: поиск клиента, олицетворение (impersonation), привязка или управление корзиной, а также выполнение коммерческих действий через OCC с помощью инструментов MCP, ориентированных на задачи.

Репозиторий теперь рассматривается как local-first (локальный приоритет): ожидаемой целью по умолчанию является https://localhost:9002, при этом SAP_BASE_URL управляет фактическим хостом. Удаленные арендаторы (tenants) по-прежнему могут использоваться, но документация, тесты и процесс проверки должны рассматривать локальную среду выполнения SAP Commerce как основной источник истины.

Что делает этот сервер сейчас

• Действия с клиентами в стиле ASM: поиск клиента, олицетворение клиента и продолжение действий от его имени

• Управление корзиной с учетом сессии: создание, просмотр, обновление, удаление и очистка корзин без ручного управления ими

• Процесс оформления заказа: адрес доставки, способ доставки, email гостя и размещение заказа

• Инструменты для работы с продуктами и поиска: поиск продуктов, получение сведений, проверка наличия на складе, просмотр базовых сайтов/магазинов/каталогов/категорий

• Два уровня инструментов: высокоуровневые инструменты для агентов и низкоуровневые обертки OCC/ASM

• Ориентация на сессию: get_session_status помогает агентам понять текущий контекст корзины/пользователя/базового сайта

• Транспорт FastMCP: транспорты stdio и SSE для локальных или удаленных MCP-клиентов

Как проходит запрос

1. Обзор архитектуры

Источник: docs/diagrams/architecture.mmd

2. Пример дорожки запроса (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 — установить 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 — удаление одной позиции

Конфигурация

1. Установите зависимости:

   uv sync

2. Скопируйте шаблон окружения:

   cp .env.example .env

3. Для локального экземпляра SAP Commerce установите:

   SAP_BASE_URL=https://localhost:9002

4. Сохраните или настройте эти фрагменты путей, если ваше развертывание SAP отличается:

   • OCC_API_PATH=/occ/v2

   • OAUTH_PATH=/authorizationserver/oauth/token

   • ASM_PATH=/assistedservicewebservices

5. Настройте учетные данные 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 для линтинга и гигиены импортов

• Mypy для практического статического контроля типов в app/

• Pytest + coverage.xml, чтобы SonarQube мог использовать те же локальные данные, что и в CI

Локальный анализ SonarQube можно опубликовать с помощью:

uv run pytest -q
sonar-scanner

Файл sonar-project.properties добавлен в репозиторий, поэтому локальные сканирования и сканирования в CI используют один и тот же ключ проекта и структуру исходного кода.

Документация

• Рабочие процессы — практические последовательности вызовов инструментов

• Архитектура Mermaid — исходный код для системной диаграммы

• Запрос Mermaid — исходный код для диаграммы дорожек

• Манифест MCP и регистрация инструментов: app/server.py

• Руководство по внесению вклада: AGENTS.md

Будущие улучшения

• добавить опциональное внешнее хранилище только в том случае, если проекту позже потребуется многопроцессность или горизонтально масштабируемая сессия

Поддерживаемое покрытие OCC / ASM

Текущий сервер охватывает конечные точки, необходимые для вышеуказанных процессов, включая базовые сайты, каталоги, магазины, продукты, корзины, позиции корзины, операции с адресом/доставкой при оформлении заказа, размещение заказа и поиск клиентов ASM / 360 о клиенте / операции привязки корзины.