JouleOps @ NorthWind Manufacturing

Asistente empresarial de IA agéntico con SAP Joule, SAP HANA Cloud, Python FastAPI y Model Context Protocol (MCP).

JouleOps es un asistente empresarial basado en escenarios para NorthWind Manufacturing. Proporciona una interfaz gobernada de lenguaje natural para recuperar datos operativos de SAP HANA Cloud y realizar acciones empresariales controladas a través de servicios Python FastAPI y un servidor MCP personalizado.

Índice

• Resumen del proyecto

• Planteamiento del problema

• Características principales

• Arquitectura

• Pila tecnológica

• Estructura del proyecto

• Capacidades empresariales

• Base de datos

• API REST

• Servidor MCP

• Configuración del entorno

• Configuración local

• Ejecución del proyecto

• Pruebas

• Integración con SAP BTP y Joule

• Seguridad y salvaguardas

• Escenarios de demostración

• Solución de problemas

• Lista de verificación de reproducibilidad

• Mejoras futuras

• Licencia

Related MCP server: SAP OData to MCP Server

Resumen del proyecto

NorthWind Manufacturing almacena sus datos operativos en SAP HANA Cloud. JouleOps proporciona una única interfaz agéntica para operaciones comunes de planta, ventas y finanzas.

El flujo integral previsto es:

User
  ↓
SAP Joule / Joule Studio Agent
  ↓
Joule Skill OR MCP Tool
  ↓
Python FastAPI / MCP Server
  ↓
SAP HANA Cloud
  ↓
JSON Result
  ↓
Joule Agent
  ↓
Grounded Response

El proyecto combina Joule Skills basados en REST con la exposición de herramientas basadas en MCP, de modo que las mismas capacidades de backend puedan consumirse a través de rutas de integración gobernadas.

Planteamiento del problema

El proyecto aborda tareas operativas comunes en NorthWind Manufacturing:

• Consultar el stock de material y el stock de seguridad en una planta.

• Recuperar pedidos de venta abiertos para una región y un rango de fechas.

• Revisar la exposición de clientes y las facturas vencidas.

• Resumir las facturas vencidas y respaldar las decisiones de cobro.

• Crear tickets de mantenimiento cuando se requiere una acción operativa.

En lugar de consultar manualmente varios sistemas, los usuarios pueden expresar estos requisitos en lenguaje natural a través de SAP Joule.

Características principales

Datos operativos

• Detalles de material por material y planta.

• Pedidos de venta abiertos por región y rango de fechas.

• Resúmenes de clientes.

• Resúmenes de facturas vencidas.

Acción empresarial

• Crear tickets de mantenimiento.

• Verificar las combinaciones de material/planta antes de crear tickets.

• Escribir registros de auditoría para las acciones empresariales.

MCP

• Servidor MCP de Python personalizado con FastMCP.

• Transporte HTTP transmisible (streamable).

• Descubrimiento y ejecución de herramientas MCP mediante MCP Inspector.

• Reutilización de la lógica empresarial del backend.

Salvaguardas

• Las credenciales de HANA permanecen en el backend.

• Validación con Pydantic.

• SQL parametrizado.

• Registro de auditoría.

• Operaciones de escritura conscientes del rol.

• Sin suposiciones de parámetros empresariales obligatorios faltantes.

Arquitectura

                    ┌──────────────────────┐
                    │      User / Joule    │
                    └──────────┬───────────┘
                               │
                               ▼
                    ┌──────────────────────┐
                    │  SAP Joule Studio    │
                    │       Agent          │
                    └──────────┬───────────┘
                               │
                    ┌──────────┴───────────┐
                    │                      │
                    ▼                      ▼
             ┌──────────────┐      ┌──────────────┐
             │ Joule Skill  │      │ MCP Server   │
             │ REST Action  │      │  FastMCP     │
             └──────┬───────┘      └──────┬───────┘
                    │                     │
                    └──────────┬──────────┘
                               ▼
                    ┌──────────────────────┐
                    │ Python Backend       │
                    │ FastAPI + Services   │
                    └──────────┬───────────┘
                               │
                               ▼
                    ┌──────────────────────┐
                    │   SAP HANA Cloud     │
                    │      NORTHWIND       │
                    └──────────────────────┘

Responsabilidades

Componente Responsabilidad

SAP Joule Interacción en lenguaje natural Joule Studio Agent Enrutamiento de intenciones, planificación y selección de herramientas Joule Skills Acciones basadas en REST MCP Server Exposición de herramientas MCP FastAPI Capa de acciones/API de backend Services Lógica empresarial y consultas a HANA HANA Cloud Persistencia de datos AUDIT_LOG Auditoría de operaciones de escritura

Pila tecnológica

Tecnología Propósito

Python 3.11+ Backend y MCP FastAPI API REST Pydantic Validación y esquemas Uvicorn Servidor ASGI hdbcli Conectividad con SAP HANA SAP HANA Cloud Base de datos FastMCP / mcp Servidor MCP SAP Joule / Joule Studio IA agéntica SAP Build Integración nativa de SAP MCP Inspector Pruebas de MCP Git / GitHub Control de versiones

Estructura del proyecto

jouleops/
│
├── app/
│   ├── api/
│   │   └── routes.py
│   │
│   ├── db/
│   │   └── db.py
│   │
│   ├── models/
│   │   └── models.py
│   │
│   ├── services/
│   │   ├── customers.py
│   │   ├── invoices.py
│   │   ├── materials.py
│   │   ├── sales_orders.py
│   │   └── tickets.py
│   │
│   └── main.py
│
├── mcp/
│   └── server.py
│
├── sql/
│   ├── 01_schema.sql
│   ├── 02_seed.sql
│   └── generate_seed.py
│
├── tests/
│
├── .env
├── .gitignore
├── requirements.txt
└── README.md

La aplicación separa el enrutamiento HTTP, la conectividad de base de datos, los servicios empresariales, los modelos de datos y la integración MCP.

Capacidades empresariales

1. Detalles de material

GET /materials/{material_id}/{plant_code}

Ejemplo:

GET /materials/MAT-1023/PLT-PUN

Recupera información de material para una planta específica.

2. Pedidos de venta abiertos

GET /sales-orders/open

Parámetros obligatorios:

region
date_from
date_to

El servicio recupera los pedidos abiertos y agrupa los pedidos devueltos por cliente.

3. Resumen de cliente

GET /customers/{customer_id}/summary

Ejemplo:

GET /customers/C-501/summary

Combina la información de cliente y facturas para el análisis de exposición de clientes.

4. Resumen de facturas vencidas

GET /customers/{customer_id}/overdue-invoices

Ejemplo:

GET /customers/C-501/overdue-invoices

Proporciona información de facturas vencidas utilizada por el agente para recomendaciones de cobro.

5. Crear ticket de mantenimiento

POST /tickets

El servicio:

1. Valida la solicitud.

2. Verifica que el material exista en la planta solicitada.

3. Crea un ID de ticket.

4. Inserta el ticket en HANA.

5. Inserta un registro de auditoría.

6. Confirma la transacción.

7. Devuelve el ticket creado.

Base de datos

La aplicación utiliza el esquema NORTHWIND en SAP HANA Cloud.

Tablas

NORTHWIND.MATERIALS
NORTHWIND.SALES_ORDERS
NORTHWIND.CUSTOMERS
NORTHWIND.INVOICES
NORTHWIND.TICKETS
NORTHWIND.AUDIT_LOG

MATERIALS

Almacena ID de material, descripción, categoría, precio unitario, cantidad de stock, stock de seguridad y código de planta.

SALES_ORDERS

Almacena ID de pedido, ID de cliente, ID de material, cantidad, estado, fecha de creación y región.

CUSTOMERS

Almacena ID de cliente, nombre, región, límite de crédito y saldo pendiente.

INVOICES

Almacena ID de factura, ID de cliente, importe, fecha de vencimiento, estado y días de retraso.

TICKETS

Almacena los tickets de mantenimiento creados a través de JouleOps.

AUDIT_LOG

Almacena marca de tiempo, rol de usuario, nombre de herramienta, parámetros enmascarados y resultado de las operaciones auditadas.

Scripts de base de datos

sql/01_schema.sql

Crea los objetos de base de datos.

sql/02_seed.sql

Carga datos sintéticos de NorthWind.

sql/generate_seed.py

Genera datos semilla cuando es necesario.

API REST

Inicie la API desde la raíz del proyecto:

uvicorn app.main:app --reload

Dirección local predeterminada:

http://127.0.0.1:8000

Swagger UI:

http://127.0.0.1:8000/docs

Especificación OpenAPI:

http://127.0.0.1:8000/openapi.json

El documento OpenAPI generado puede utilizarse al registrar las acciones REST en SAP Build.

Servidor MCP

El proyecto expone capacidades seleccionadas del backend a través de un servidor FastMCP personalizado.

Punto de conexión MCP local:

http://127.0.0.1:8001/mcp

Transporte:

Streamable HTTP

El servidor MCP expone herramientas para operaciones como:

get_customer_summary_tool
get_material_details
get_open_sales_orders_tool
summarize_overdue_invoices
create_maintenance_ticket

La firma de la herramienta MCP debe coincidir con la operación empresarial subyacente. Por ejemplo, los pedidos de venta abiertos requieren:

region
date_from
date_to

en lugar de un único customer_id.

Configuración del entorno

Cree un archivo .env en la raíz del proyecto:

HANA_HOST=your-hana-host
HANA_PORT=443
HANA_USER=your-hana-user
HANA_PASSWORD=your-hana-password

No confirme .env.

Entradas recomendadas para .gitignore:

.env
.venv/
__pycache__/
*.pyc

Las credenciales de HANA deben permanecer en el lado del servidor y nunca deben incluirse en los prompts de Joule, las descripciones de MCP, el contexto del LLM ni las respuestas de la API.

Configuración local

1. Clonar el repositorio

git clone <repository-url>
cd jouleops

2. Crear un entorno virtual

py -m venv .venv

Actívelo:

.\.venv\Scripts\Activate.ps1

3. Instalar dependencias

pip install -r requirements.txt

4. Configurar HANA

Cree .env y proporcione la información de conexión de SAP HANA Cloud.

5. Crear la base de datos

Ejecute:

sql/01_schema.sql

contra el esquema de HANA Cloud de destino.

6. Cargar datos semilla

Ejecute:

sql/02_seed.sql

o genere los datos necesarios con:

sql/generate_seed.py

Ejecución del proyecto

FastAPI

uvicorn app.main:app --reload

Verifique:

http://127.0.0.1:8000/docs

Servidor MCP

Ejecute el servidor MCP utilizando el punto de entrada ASGI/aplicación definido en mcp/server.py.

Para una aplicación ASGI expuesta como app, el comando es:

uvicorn mcp.server:app --host 127.0.0.1 --port 8001

El comando final debe coincidir con el objeto exportado por el mcp/server.py del proyecto.

Pruebas

API REST

Utilice Swagger UI:

http://127.0.0.1:8000/docs

Comprobaciones recomendadas:

GET  /materials/MAT-1023/PLT-PUN
GET  /customers/C-501/summary
GET  /customers/C-501/overdue-invoices
GET  /sales-orders/open
POST /tickets

Para la operación de ticket, verifique ambos:

NORTHWIND.TICKETS
NORTHWIND.AUDIT_LOG

después de una escritura correcta.

MCP Inspector

Utilice MCP Inspector para inspeccionar y ejecutar el servidor MCP.

Configure:

Server ID: jouleops-mcp
Transport: Streamable HTTP
URL: http://127.0.0.1:8001/mcp

Después de conectarse:

1. Abra Tools.

2. Seleccione una herramienta de JouleOps.

3. Introduzca todos los parámetros obligatorios.

4. Ejecute la herramienta.

5. Verifique la respuesta JSON.

6. Verifique los datos de HANA cuando corresponda.

7. Para operaciones de escritura, verifique AUDIT_LOG.

Integración con SAP BTP y Joule

El flujo empresarial previsto es:

SAP Joule
   ↓
Joule Studio Agent
   ↓
BTP Destination
   ↓
FastAPI / MCP
   ↓
SAP HANA Cloud

Destino de acción FastAPI

La API REST se expone a través de un BTP Destination para las acciones de Joule Studio.

El destino debe contener:

sap-joule-studio-action = true

Destino MCP

El servidor MCP se expone a través de un destino HTTP configurado para el descubrimiento MCP de Joule Studio.

El destino debe contener:

sap-joule-studio-mcp-server = true

Para demostraciones locales, un túnel como ngrok puede exponer el servicio local.

HANA nunca debe exponerse directamente a Joule.

Seguridad y salvaguardas

Sin credenciales de HANA para el LLM

Solo FastAPI/MCP posee las credenciales de HANA.

Joule
  ↓
Tool parameters
  ↓
FastAPI / MCP
  ↓
HANA credentials
  ↓
SAP HANA Cloud

SQL parametrizado

Las consultas utilizan enlace de parámetros:

cursor.execute(
    """
    SELECT ...
    WHERE MATERIAL_ID = ?
      AND PLANT_CODE = ?
    """,
    (material_id, plant_code),
)

en lugar de concatenación de cadenas.

Registro de auditoría

Las operaciones de escritura deben registrar:

user role
tool name
masked parameters
outcome
timestamp

en NORTHWIND.AUDIT_LOG.

Validación de entrada

Los modelos de FastAPI/Pydantic validan las entradas estructuradas antes de que se ejecute la lógica empresarial.

Acceso basado en roles

Los roles previstos son:

PLANT_SUPERVISOR
SALES_MANAGER
FINANCE
VIEWER

Un VIEWER no debe tener permitido crear tickets de mantenimiento.

Sin suposiciones

Si falta un parámetro obligatorio, el agente debe solicitar la información faltante en lugar de adivinar o enviar valores nulos a una operación de escritura.

Escenarios de demostración

Escenario 1 --- Verificación de stock + ticket automático

Is steel coil MAT-1023 below safety stock in Pune?
If yes, raise a HIGH-priority ticket for the Mechanical team.

Flujo esperado:

get_material_details
        ↓
Compare stock with safety stock
        ↓
create_ticket
        ↓
AUDIT_LOG
        ↓
Confirmation

Escenario 2 --- Pedidos de venta abiertos

Show me last week's open sales orders for the South region,
grouped by customer, with totals.

Herramienta esperada:

get_open_sales_orders

Parámetros esperados:

region
date_from
date_to

Escenario 3 --- Exposición de clientes

Summarize C-501's overdue invoices and tell me what to do next.

Herramientas esperadas:

get_customer_summary
summarize_overdue_invoices

Escenario 4 --- Demostración de la arquitectura MCP

Give me an inventory snapshot for the Chennai plant.

Este escenario está pensado para demostrar una capacidad empresarial equivalente a través de una herramienta MCP.

Escenario 5 --- Escalada / parámetros faltantes

Create a ticket.

El agente debe solicitar la información obligatoria en lugar de adivinar.

Para un VIEWER, la operación de escritura debe rechazarse.

Solución de problemas

500 Internal Server Error

Compruebe:

1. Los valores de .env.

2. El host y el puerto de HANA.

3. La accesibilidad de red de HANA Cloud.

4. Los nombres de esquema/tablas.

5. Los parámetros SQL.

6. Los registros de Uvicorn.

Tabla de HANA no encontrada

Verifique el esquema y las tablas:

SELECT SCHEMA_NAME, TABLE_NAME
FROM SYS.TABLES
ORDER BY SCHEMA_NAME, TABLE_NAME;

El proyecto espera las tablas de NorthWind en:

NORTHWIND

MCP Inspector no puede conectarse

Verifique:

MCP server is running
Port = 8001
Path = /mcp
Transport = Streamable HTTP

Punto de conexión esperado:

http://127.0.0.1:8001/mcp

La herramienta MCP informa de argumentos faltantes

Compruebe que la firma del envoltorio MCP coincida con la función del servicio.

Por ejemplo:

def get_open_sales_orders(
    region: str,
    date_from: date,
    date_to: date,
):
    ...

La herramienta MCP debe exponer los tres parámetros.

La acción de SAP Build devuelve 404 Not Found

El punto de conexión de la acción de SAP Build debe coincidir exactamente con la ruta de FastAPI.

Por ejemplo:

GET /customers/{customer_id}/overdue-invoices

no debe configurarse como:

/invoices/{customer_id}/overdue-summary

Utilice la especificación OpenAPI actual de FastAPI:

http://127.0.0.1:8000/openapi.json

Archivo OpenAPI no válido

Utilice el documento OpenAPI generado por la aplicación FastAPI actual en lugar de una especificación desactualizada.

Lista de verificación de reproducibilidad

Backend

• Entorno de Python creado.

• Dependencias instaladas.

• .env configurado.

• FastAPI se inicia correctamente.

• Swagger UI se carga.

• La especificación OpenAPI se carga.

• Todas las operaciones REST principales funcionan.

HANA

• Instancia de HANA Cloud disponible.

• El esquema NORTHWIND existe.

• Las tablas necesarias existen.

• Datos semilla cargados.

• La creación de tickets persiste.

• Se crean registros de auditoría.

MCP

• El servidor MCP se inicia.

• El punto de conexión HTTP transmisible es accesible.

• MCP Inspector se conecta.

• Las herramientas se descubren.

• Todos los parámetros obligatorios están expuestos.

• Las herramientas de lectura devuelven resultados válidos.

• Las herramientas de escritura crean registros de auditoría.

Joule / SAP Build

• Agente de JouleOps configurado.

• Acciones REST registradas.

• Servidor MCP conectado.

• BTP Destinations configurados.

• Propiedades de destino obligatorias configuradas.

• Herramientas correctas seleccionadas para prompts representativos.

• Parámetros faltantes gestionados correctamente.

• Comportamiento de RBAC verificado.

• Transparencia de fuentes verificada.

Demo

• Escenario de stock + ticket probado.

• Escenario de pedido de venta abierto probado.

• Escenario de cliente/factura probado.

• Escenario MCP probado.

• Escenario de escalado/RBAC probado.

• Trazas de herramientas capturadas.

• Resultados de HANA verificados.

Mejoras futuras

Las posibles extensiones incluyen:

• Desplegar FastAPI y MCP en SAP BTP Cloud Foundry o Kyma.

• Añadir CI/CD usando GitHub Actions.

• Añadir pruebas automatizadas exhaustivas.

• Crear un panel de auditoría Fiori/SAPUI5.

• Añadir capacidades de HANA Vector Engine.

• Añadir búsqueda semántica sobre tickets históricos.

• Añadir anclaje documental para políticas de crédito/cobro.

• Añadir orquestación multiagente.

• Añadir interacción bilingüe.

• Añadir autenticación y autorización de nivel de producción.

• Añadir observabilidad estructurada y monitorización del rendimiento.

Licencia

Este proyecto fue desarrollado como una implementación educativa/proyecto final que demuestra la integración de SAP Joule, SAP HANA Cloud, Python FastAPI y Model Context Protocol.

A menos que se añada una licencia separada al repositorio, el proyecto debe tratarse como trabajo educativo específico del proyecto.

Agradecimientos

Construido con:

• SAP Joule / Joule Studio

• SAP Build

• SAP HANA Cloud

• Python

• FastAPI

• Pydantic

• FastMCP / Model Context Protocol

• MCP Inspector

• Git / GitHub