Servidor MCP de SAP Commerce

Este proyecto expone un servidor MCP para SAP Commerce Cloud centrado en flujos de trabajo de empleados de ASM: buscar un cliente, suplantar su identidad, vincular o gestionar un carrito y completar acciones de comercio respaldadas por OCC a través de herramientas MCP orientadas a tareas.

El repositorio ahora se trata como local-first: el destino predeterminado esperado es https://localhost:9002, con SAP_BASE_URL controlando el host real. Se pueden seguir utilizando inquilinos remotos, pero la documentación, las pruebas y el flujo de validación deben hacer que el tiempo de ejecución local de SAP Commerce sea la fuente de verdad.

Qué hace este servidor ahora

• Acciones de cliente centradas en ASM: buscar un cliente, suplantar a un cliente y seguir actuando en su nombre

• Gestión de carritos con conocimiento de sesión: crear, inspeccionar, actualizar, eliminar y vaciar carritos sin necesidad de gestionar manualmente los carritos

• Flujo de pago: dirección de entrega, modo de entrega, correo electrónico de invitado y realización de pedidos

• Herramientas de producto y descubrimiento: buscar productos, obtener detalles, inspeccionar stock, explorar sitios base/tiendas/catálogos/categorías

• Dos capas de herramientas: herramientas de alto nivel amigables para agentes más envoltorios de bajo nivel OCC/ASM

• Orientación a la sesión: get_session_status ayuda a los agentes a comprender el contexto actual del carrito/usuario/sitio base

• Transporte FastMCP: transportes stdio y SSE para clientes MCP locales o remotos

Cómo fluye una solicitud

1. Arquitectura de un vistazo

Fuente: docs/diagrams/architecture.mmd

2. Carril de ejemplo de solicitud

Este es el camino típico de "el agente suplanta a un cliente y luego sigue comprando en su nombre".

Fuente: docs/diagrams/example-request.mmd

Herramientas MCP

Herramientas de alto nivel

Estos son el contrato principal para los flujos de trabajo de los empleados de ASM.

Descubrimiento y productos

• search_products — descubrimiento de productos por palabras clave

• get_product — obtener el detalle de un producto

• get_session_status — inspeccionar el estado de la sesión actual

Cliente / ASM

• search_customer — encontrar un cliente rápidamente

• impersonate_customer — empezar a actuar como cliente

• end_impersonation — volver al modo anónimo

Carrito y pago

• add_to_cart — añadir un producto

• get_cart — leer el carrito actual

• update_cart_entry — cambiar la cantidad de una entrada

• remove_from_cart — eliminar una entrada

• clear_cart — vaciar el carrito

• set_delivery_address — adjuntar dirección de envío

• set_delivery_mode — elegir método de envío

• get_delivery_modes — listar opciones de envío

• set_guest_email — establecer correo electrónico de pago de invitado

• place_order — enviar el pedido

Herramientas de bajo nivel

Estas exponen primitivas de OCC / ASM más estrechas para un control exacto.

• basesites.list — listar sitios base disponibles

• catalogs.list — listar catálogos para un sitio

• catalogs.get — obtener un catálogo

• catalogVersions.get — obtener una versión de catálogo

• categories.products — explorar productos por categoría

• stores.list — listar tiendas para un sitio

• stores.get — obtener una tienda base

• products.get — obtener un producto OCC

• products.stock — inspeccionar datos de stock

• products.stockCount — contar ubicaciones de stock

• asm.customer360 — obtener fragmentos 360 del cliente

• asm.customers.create — crear un cliente

• asm.customers.search — ejecutar búsqueda de clientes ASM

• asm.customers.suggest — obtener sugerencias de clientes

• carts.list — listar carritos

• carts.create — crear o restaurar carrito

• carts.get — obtener un carrito

• carts.delete — eliminar un carrito

• cartEntries.list — listar entradas del carrito

• cartEntries.add — añadir una entrada

• cartEntries.get — obtener una entrada

• cartEntries.update — reemplazar carga útil de entrada

• cartEntries.patch — actualizar parcialmente la entrada

• cartEntries.delete — eliminar una entrada

Configuración

1. Instalar dependencias:

   uv sync

2. Copiar la plantilla de entorno:

   cp .env.example .env

3. Para la instancia local de SAP Commerce, establecer:

   SAP_BASE_URL=https://localhost:9002

4. Mantenga o ajuste estos fragmentos de ruta si su despliegue de SAP difiere:

   • OCC_API_PATH=/occ/v2

   • OAUTH_PATH=/authorizationserver/oauth/token

   • ASM_PATH=/assistedservicewebservices

5. Configure las credenciales de OAuth para el inquilino local o el inquilino remoto contra el que está validando. Para la configuración de datos de muestra locales estándar, estos son los valores predeterminados esperados:

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

Ejecución

• Stdio:

  python -m app.server

• SSE:

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

Pruebas

• Suite de verificación completa:

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

• Comprobaciones de humo:

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

• Flujo de descubrimiento en vivo:

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

Nota Las pruebas en vivo están destinadas a validar el contrato actual contra un tiempo de ejecución real de SAP Commerce. Cuando SAP_BASE_URL=https://localhost:9002, la instancia local de OCC/ASM debería ser el objetivo de prueba principal. Si los datos de OAuth o ASM están mal configurados, diagnostíquelos localmente antes de ampliar el alcance.

Advertencia sobre SAP local Algunas pilas locales de SAP 2211 incluyen messagecentercsocc, cuyo Oauth2UserFilter tardío puede sobrescribir el contexto en nombre de /users/{customerId} con el agente autenticado nuevamente. Si las llamadas al carrito de asmagent regresan a errores de conversión EmployeeModel -> CustomerModel, parche ese filtro para que conserve el cliente ya coincidente cuando el usuario actual de OCC difiera del principal de OAuth.

Puertas de calidad

• Ruff para linting e higiene de importaciones

• Mypy para una puerta de tipo estático práctica en app/

• Pytest + coverage.xml para que SonarQube pueda consumir la misma evidencia local utilizada en CI

El análisis local de SonarQube se puede publicar con:

uv run pytest -q
sonar-scanner

sonar-project.properties está registrado para que los escaneos locales y de CI utilicen la misma clave de proyecto/diseño de fuente.

Documentación

• Flujos de trabajo — secuencias prácticas de llamadas a herramientas

• Arquitectura Mermaid — fuente para el diagrama del sistema

• Solicitud Mermaid — fuente para el diagrama de carril

• Manifiesto MCP y registro de herramientas: app/server.py

• Guía de contribución: AGENTS.md

Mejoras futuras

• añadir un almacén de respaldo externo opcional solo si el proyecto necesita más adelante persistencia de sesión multiproceso o escalada horizontalmente

Cobertura de OCC / ASM soportada

El servidor actual cubre los puntos finales necesarios para los flujos anteriores, incluyendo sitios base, catálogos, tiendas, productos, carritos, entradas de carrito, operaciones de dirección/entrega de pago, realización de pedidos y operaciones de estilo búsqueda de clientes ASM / cliente 360 / vincular carrito.