JouleOps @ NorthWind Manufacturing

Agentischer KI-Unternehmensassistent mit SAP Joule, SAP HANA Cloud, Python FastAPI und Model Context Protocol (MCP).

JouleOps ist ein szenariobasierter Unternehmensassistent für NorthWind Manufacturing. Er bietet eine kontrollierte Schnittstelle in natürlicher Sprache zum Abrufen operativer Daten aus SAP HANA Cloud und zur Durchführung kontrollierter Geschäftsaktionen über Python-FastAPI-Dienste und einen benutzerdefinierten MCP-Server.

Inhaltsverzeichnis

• Projektübersicht

• Problemstellung

• Hauptfunktionen

• Architektur

• Technologie-Stack

• Projektstruktur

• Geschäftsfähigkeiten

• Datenbank

• REST-API

• MCP-Server

• Umgebungskonfiguration

• Lokale Einrichtung

• Projekt ausführen

• Testen

• SAP-BTP- und Joule-Integration

• Sicherheit und Schutzmaßnahmen

• Demo-Szenarien

• Fehlerbehebung

• Reproduzierbarkeits-Checkliste

• Zukünftige Verbesserungen

• Lizenz

Related MCP server: SAP OData to MCP Server

Projektübersicht

NorthWind Manufacturing speichert seine operativen Daten in SAP HANA Cloud. JouleOps bietet eine einheitliche agentische Schnittstelle für gängige Werks-, Vertriebs- und Finanzoperationen.

Der vorgesehene End-to-End-Ablauf ist:

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

Das Projekt kombiniert REST-basierte Joule-Skills mit MCP-basierter Tool-Bereitstellung, sodass dieselben Backend-Fähigkeiten über kontrollierte Integrationspfade genutzt werden können.

Problemstellung

Das Projekt adressiert gängige operative Aufgaben bei NorthWind Manufacturing:

• Materialbestand und Sicherheitsbestand an einem Werk prüfen.

• Offene Kundenaufträge für eine Region und einen Datumsbereich abrufen.

• Kundenexposition und überfällige Rechnungen prüfen.

• Überfällige Rechnungen zusammenfassen und Inkassoentscheidungen unterstützen.

• Wartungstickets erstellen, wenn operative Maßnahmen erforderlich sind.

Anstatt mehrere Systeme manuell abzufragen, können Benutzer diese Anforderungen in natürlicher Sprache über SAP Joule ausdrücken.

Hauptfunktionen

Operative Daten

• Materialdetails nach Material und Werk.

• Offene Kundenaufträge nach Region und Datumsbereich.

• Kundenübersichten.

• Zusammenfassungen überfälliger Rechnungen.

Geschäftsaktionen

• Wartungstickets erstellen.

• Material-/Werk-Kombinationen vor der Ticket-Erstellung verifizieren.

• Audit-Datensätze für Geschäftsaktionen schreiben.

MCP

• Benutzerdefinierter Python-MCP-Server mit FastMCP.

• Streamable-HTTP-Transport.

• MCP-Tool-Erkennung und -Ausführung über MCP Inspector.

• Wiederverwendung der Backend-Geschäftslogik.

Schutzmaßnahmen

• HANA-Anmeldedaten bleiben im Backend.

• Pydantic-Validierung.

• Parametrisierte SQL-Abfragen.

• Audit-Protokollierung.

• Rollenbewusste Schreiboperationen.

• Kein Raten fehlender erforderlicher Geschäftsparameter.

Architektur

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

Verantwortlichkeiten

Komponente Verantwortlichkeit

SAP Joule Interaktion in natürlicher Sprache Joule Studio Agent Intent-Routing, Planung und Tool-Auswahl Joule Skills REST-basierte Aktionen MCP-Server MCP-Tool-Bereitstellung FastAPI Backend-Aktions-/API-Ebene Services Geschäftslogik und HANA-Abfragen HANA Cloud Datenpersistenz AUDIT_LOG Auditierung von Schreiboperationen

Technologie-Stack

Technologie Zweck

Python 3.11+ Backend und MCP FastAPI REST-API Pydantic Validierung und Schemas Uvicorn ASGI-Server hdbcli SAP-HANA-Konnektivität SAP HANA Cloud Datenbank FastMCP / mcp MCP-Server SAP Joule / Joule Studio Agentische KI SAP Build SAP-native Integration MCP Inspector MCP-Tests Git / GitHub Versionskontrolle

Projektstruktur

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

Die Anwendung trennt HTTP-Routing, Datenbankkonnektivität, Geschäftsdienste, Datenmodelle und MCP-Integration.

Geschäftsfähigkeiten

1. Materialdetails

GET /materials/{material_id}/{plant_code}

Beispiel:

GET /materials/MAT-1023/PLT-PUN

Ruft Materialinformationen für ein bestimmtes Werk ab.

2. Offene Kundenaufträge

GET /sales-orders/open

Erforderliche Parameter:

region
date_from
date_to

Der Dienst ruft offene Aufträge ab und gruppiert die zurückgegebenen Aufträge nach Kunde.

3. Kundenübersicht

GET /customers/{customer_id}/summary

Beispiel:

GET /customers/C-501/summary

Kombiniert Kunden- und Rechnungsinformationen für die Analyse der Kundenexposition.

4. Zusammenfassung überfälliger Rechnungen

GET /customers/{customer_id}/overdue-invoices

Beispiel:

GET /customers/C-501/overdue-invoices

Liefert Informationen zu überfälligen Rechnungen, die der Agent für Inkassoempfehlungen verwendet.

5. Wartungsticket erstellen

POST /tickets

Der Dienst:

1. Validiert die Anfrage.

2. Verifiziert, dass das Material am angeforderten Werk existiert.

3. Erstellt eine Ticket-ID.

4. Fügt das Ticket in HANA ein.

5. Fügt einen Audit-Datensatz ein.

6. Committet die Transaktion.

7. Gibt das erstellte Ticket zurück.

Datenbank

Die Anwendung verwendet das Schema NORTHWIND in SAP HANA Cloud.

Tabellen

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

MATERIALS

Speichert Material-ID, Beschreibung, Kategorie, Stückpreis, Lagerbestand, Sicherheitsbestand und Werkscode.

SALES_ORDERS

Speichert Auftrags-ID, Kunden-ID, Material-ID, Menge, Status, Erstellungsdatum und Region.

CUSTOMERS

Speichert Kunden-ID, Name, Region, Kreditlimit und offenen Betrag.

INVOICES

Speichert Rechnungs-ID, Kunden-ID, Betrag, Fälligkeitsdatum, Status und Tage überfällig.

TICKETS

Speichert Wartungstickets, die über JouleOps erstellt wurden.

AUDIT_LOG

Speichert Zeitstempel, Benutzerrolle, Tool-Name, maskierte Parameter und Ergebnis für auditierte Operationen.

Datenbankskripte

sql/01_schema.sql

Erstellt die Datenbankobjekte.

sql/02_seed.sql

Lädt synthetische NorthWind-Daten.

sql/generate_seed.py

Generiert Seed-Daten bei Bedarf.

REST-API

API vom Projektstammverzeichnis starten:

uvicorn app.main:app --reload

Standardmäßige lokale Adresse:

http://127.0.0.1:8000

Swagger-UI:

http://127.0.0.1:8000/docs

OpenAPI-Spezifikation:

http://127.0.0.1:8000/openapi.json

Das generierte OpenAPI-Dokument kann bei der Registrierung der REST-Aktionen in SAP Build verwendet werden.

MCP-Server

Das Projekt stellt ausgewählte Backend-Fähigkeiten über einen benutzerdefinierten FastMCP-Server bereit.

Lokaler MCP-Endpunkt:

http://127.0.0.1:8001/mcp

Transport:

Streamable HTTP

Der MCP-Server stellt Tools für Operationen wie folgende bereit:

get_customer_summary_tool
get_material_details
get_open_sales_orders_tool
summarize_overdue_invoices
create_maintenance_ticket

Die MCP-Tool-Signatur muss mit der zugrunde liegenden Geschäftsoperation übereinstimmen. Beispielsweise erfordern offene Kundenaufträge:

region
date_from
date_to

anstatt einer einzelnen customer_id.

Umgebungskonfiguration

Erstellen Sie eine .env-Datei im Projektstammverzeichnis:

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

Committen Sie .env nicht.

Empfohlene .gitignore-Einträge:

.env
.venv/
__pycache__/
*.pyc

HANA-Anmeldedaten müssen serverseitig bleiben und dürfen niemals in Joule-Prompts, MCP-Beschreibungen, LLM-Kontext oder API-Antworten enthalten sein.

Lokale Einrichtung

1. Repository klonen

git clone <repository-url>
cd jouleops

2. Virtuelle Umgebung erstellen

py -m venv .venv

Aktivieren:

.\.venv\Scripts\Activate.ps1

3. Abhängigkeiten installieren

pip install -r requirements.txt

4. HANA konfigurieren

Erstellen Sie .env und geben Sie die Verbindungsinformationen für SAP HANA Cloud an.

5. Datenbank erstellen

Führen Sie Folgendes aus:

sql/01_schema.sql

gegen das Ziel-HANA-Cloud-Schema.

6. Seed-Daten laden

Führen Sie Folgendes aus:

sql/02_seed.sql

oder generieren Sie die erforderlichen Daten mit:

sql/generate_seed.py

Projekt ausführen

FastAPI

uvicorn app.main:app --reload

Überprüfen:

http://127.0.0.1:8000/docs

MCP-Server

Führen Sie den MCP-Server über den in mcp/server.py definierten ASGI-/Anwendungs-Einstiegspunkt aus.

Für eine als app bereitgestellte ASGI-Anwendung lautet der Befehl:

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

Der endgültige Befehl sollte dem vom Projekt mcp/server.py exportierten Objekt entsprechen.

Testen

REST-API

Swagger-UI verwenden:

http://127.0.0.1:8000/docs

Empfohlene Prüfungen:

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

Für die Ticket-Operation verifizieren Sie beides:

NORTHWIND.TICKETS
NORTHWIND.AUDIT_LOG

nach einem erfolgreichen Schreibvorgang.

MCP Inspector

Verwenden Sie MCP Inspector, um den MCP-Server zu inspizieren und auszuführen.

Konfigurieren:

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

Nach dem Verbinden:

1. Tools öffnen.

2. Ein JouleOps-Tool auswählen.

3. Alle erforderlichen Parameter eingeben.

4. Das Tool ausführen.

5. Die JSON-Antwort verifizieren.

6. HANA-Daten bei Bedarf verifizieren.

7. Für Schreiboperationen AUDIT_LOG verifizieren.

SAP-BTP- und Joule-Integration

Der vorgesehene Unternehmensablauf ist:

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

FastAPI-Aktionsziel

Die REST-API wird über ein BTP-Ziel für Joule-Studio-Aktionen bereitgestellt.

Das Ziel sollte Folgendes enthalten:

sap-joule-studio-action = true

MCP-Ziel

Der MCP-Server wird über ein HTTP-Ziel bereitgestellt, das für die MCP-Erkennung in Joule Studio konfiguriert ist.

Das Ziel sollte Folgendes enthalten:

sap-joule-studio-mcp-server = true

Für lokale Demonstrationen kann ein Tunnel wie ngrok den lokalen Dienst bereitstellen.

HANA selbst sollte niemals direkt für Joule bereitgestellt werden.

Sicherheit und Schutzmaßnahmen

Keine HANA-Anmeldedaten an das LLM

Nur FastAPI/MCP hält HANA-Anmeldedaten.

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

Parametrisierte SQL-Abfragen

Abfragen verwenden Parameterbindung:

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

anstatt String-Konkatenation.

Audit-Protokollierung

Schreiboperationen sollten Folgendes aufzeichnen:

user role
tool name
masked parameters
outcome
timestamp

in NORTHWIND.AUDIT_LOG.

Eingabevalidierung

FastAPI-/Pydantic-Modelle validieren strukturierte Eingaben, bevor die Geschäftslogik ausgeführt wird.

Rollenbasierter Zugriff

Die vorgesehenen Rollen sind:

PLANT_SUPERVISOR
SALES_MANAGER
FINANCE
VIEWER

Ein VIEWER darf keine Wartungstickets erstellen.

Kein Raten

Wenn ein erforderlicher Parameter fehlt, sollte der Agent die fehlenden Informationen anfordern, anstatt zu raten oder Null-Werte an eine Schreiboperation zu senden.

Demo-Szenarien

Szenario 1 --- Bestandsprüfung + automatisches Ticket

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

Erwarteter Ablauf:

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

Szenario 2 --- Offene Kundenaufträge

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

Erwartetes Tool:

get_open_sales_orders

Erwartete Parameter:

region
date_from
date_to

Szenario 3 --- Kundenexposition

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

Erwartete Tools:

get_customer_summary
summarize_overdue_invoices

Szenario 4 --- MCP-Architektur-Demonstration

Give me an inventory snapshot for the Chennai plant.

Dieses Szenario soll eine gleichwertige Geschäftsfähigkeit über ein MCP-Tool demonstrieren.

Szenario 5 --- Eskalation / fehlende Parameter

Create a ticket.

Der Agent sollte die erforderlichen Informationen anfordern, anstatt zu raten.

Für einen VIEWER muss die Schreiboperation abgelehnt werden.

Fehlerbehebung

500 Internal Server Error

Prüfen:

1. .env-Werte.

2. HANA-Host und -Port.

3. Netzwerkerreichbarkeit von HANA Cloud.

4. Schema-/Tabellennamen.

5. SQL-Parameter.

6. Uvicorn-Protokolle.

HANA-Tabelle nicht gefunden

Verifizieren Sie das Schema und die Tabellen:

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

Das Projekt erwartet die NorthWind-Tabellen unter:

NORTHWIND

MCP Inspector kann keine Verbindung herstellen

Verifizieren:

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

Erwarteter Endpunkt:

http://127.0.0.1:8001/mcp

MCP-Tool meldet fehlende Argumente

Prüfen Sie, ob die MCP-Wrapper-Signatur mit der Servicefunktion übereinstimmt.

Zum Beispiel:

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

Das MCP-Tool muss alle drei Parameter bereitstellen.

SAP-Build-Aktion gibt 404 Not Found zurück

Der SAP-Build-Aktionsendpunkt muss exakt mit der FastAPI-Route übereinstimmen.

Zum Beispiel:

GET /customers/{customer_id}/overdue-invoices

darf nicht als Folgendes konfiguriert werden:

/invoices/{customer_id}/overdue-summary

Verwenden Sie die aktuelle FastAPI-OpenAPI-Spezifikation:

http://127.0.0.1:8000/openapi.json

Ungültige OpenAPI-Datei

Verwenden Sie das von der aktuellen FastAPI-Anwendung generierte OpenAPI-Dokument anstelle einer veralteten Spezifikation.

Reproduzierbarkeits-Checkliste

Backend

• Python-Umgebung erstellt.

• Abhängigkeiten installiert.

• .env konfiguriert.

• FastAPI startet erfolgreich.

• Swagger-UI lädt.

• OpenAPI-Spezifikation lädt.

• Alle Kern-REST-Operationen funktionieren.

HANA

• HANA-Cloud-Instanz verfügbar.

• NORTHWIND-Schema vorhanden.

• Erforderliche Tabellen vorhanden.

• Seed-Daten geladen.

• Ticket-Erstellung wird persistiert.

• Audit-Datensätze werden erstellt.

MCP

• MCP-Server startet.

• Streamable-HTTP-Endpunkt ist erreichbar.

• MCP Inspector verbindet sich.

• Tools werden erkannt.

• Alle erforderlichen Parameter werden bereitgestellt.

• Lesetools liefern gültige Ergebnisse.

• Schreibwerkzeuge erstellen Audit-Datensätze.

Joule / SAP Build

• JouleOps-Agent konfiguriert.

• REST-Aktionen registriert.

• MCP-Server verbunden.

• BTP-Ziele konfiguriert.

• Erforderliche Zieleigenschaften konfiguriert.

• Korrekte Tools für repräsentative Prompts ausgewählt.

• Fehlende Parameter korrekt behandelt.

• RBAC-Verhalten verifiziert.

• Quelltransparenz verifiziert.

Demo

• Bestands- und Ticket-Szenario getestet.

• Szenario für offene Verkaufsaufträge getestet.

• Kunden-/Rechnungsszenario getestet.

• MCP-Szenario getestet.

• Eskalations-/RBAC-Szenario getestet.

• Tool-Traces erfasst.

• HANA-Ergebnisse verifiziert.

Zukünftige Verbesserungen

Mögliche Erweiterungen umfassen:

• FastAPI und MCP auf SAP BTP Cloud Foundry oder Kyma bereitstellen.

• CI/CD mit GitHub Actions hinzufügen.

• Umfassende automatisierte Tests hinzufügen.

• Ein Fiori/SAPUI5-Audit-Dashboard erstellen.

• HANA Vector Engine-Funktionen hinzufügen.

• Semantische Suche über historische Tickets hinzufügen.

• Dokumenten-Grounding für Kredit-/Inkassorichtlinien hinzufügen.

• Multi-Agent-Orchestrierung hinzufügen.

• Zweisprachige Interaktion hinzufügen.

• Produktionsreife Authentifizierung und Autorisierung hinzufügen.

• Strukturierte Beobachtbarkeit und Leistungsüberwachung hinzufügen.

Lizenz

Dieses Projekt wurde als Bildungs-/Abschlussprojekt entwickelt, das die Integration von SAP Joule, SAP HANA Cloud, Python FastAPI und Model Context Protocol demonstriert.

Sofern dem Repository keine separate Lizenz hinzugefügt wird, sollte das Projekt als projektspezifische Bildungsarbeit behandelt werden.

Danksagungen

Erstellt mit:

• SAP Joule / Joule Studio

• SAP Build

• SAP HANA Cloud

• Python

• FastAPI

• Pydantic

• FastMCP / Model Context Protocol

• MCP Inspector

• Git / GitHub