JouleOps @ NorthWind Manufacturing

Корпоративный ИИ-ассистент с агентным поведением на базе SAP Joule, SAP HANA Cloud, Python FastAPI и Model Context Protocol (MCP).

JouleOps — это сценарный корпоративный ассистент для NorthWind Manufacturing. Он предоставляет управляемый интерфейс на естественном языке для получения операционных данных из SAP HANA Cloud и выполнения контролируемых бизнес-действий через сервисы Python FastAPI и собственный MCP-сервер.

Оглавление

• Обзор проекта

• Описание проблемы

• Ключевые возможности

• Архитектура

• Технологический стек

• Структура проекта

• Бизнес-возможности

• База данных

• REST API

• MCP-сервер

• Конфигурация окружения

• Локальная настройка

• Запуск проекта

• Тестирование

• Интеграция с SAP BTP и Joule

• Безопасность и ограничения

• Демонстрационные сценарии

• Устранение неполадок

• Контрольный список воспроизводимости

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

• Лицензия

Related MCP server: SAP OData to MCP Server

Обзор проекта

NorthWind Manufacturing хранит свои операционные данные в SAP HANA Cloud. JouleOps предоставляет единый агентный интерфейс для типовых операций на заводе, в продажах и финансах.

Предполагаемый сквозной сценарий:

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

Проект сочетает REST-навыки Joule (Joule Skills) с MCP-инструментами, чтобы одни и те же серверные возможности можно было использовать через управляемые интеграционные пути.

Описание проблемы

Проект решает типовые операционные задачи в NorthWind Manufacturing:

• Проверять остатки материалов и страховой запас на заводе.

• Получать открытые заказы на продажу по региону и диапазону дат.

• Просматривать сумму задолженности клиента и просроченные счета.

• Формировать сводку по просроченным счетам и поддерживать решения по взысканию задолженности.

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

Вместо ручных запросов в несколько систем пользователи могут формулировать эти требования на естественном языке через SAP Joule.

Ключевые возможности

Операционные данные

• Сведения о материалах по материалу и заводу.

• Открытые заказы на продажу по региону и диапазону дат.

• Сводки по клиентам.

• Сводки по просроченным счетам.

Бизнес-действия

• Создание заявок на техническое обслуживание.

• Проверка комбинаций материал/завод перед созданием заявок.

• Запись аудиторских записей для бизнес-действий.

MCP

• Собственный Python MCP-сервер на базе FastMCP.

• Транспорт Streamable HTTP.

• Обнаружение и выполнение MCP-инструментов через MCP Inspector.

• Повторное использование серверной бизнес-логики.

Защитные механизмы

• Учётные данные HANA остаются в серверной части.

• Валидация Pydantic.

• Параметризованный SQL.

• Аудит действий.

• Операции записи с учётом ролей.

• Без угадывания отсутствующих обязательных бизнес-параметров.

Архитектура

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

Ответственность

Компонент Ответственность

SAP Joule Взаимодействие на естественном языке Joule Studio Agent Маршрутизация намерений, планирование и выбор инструментов Joule Skills Действия на основе REST MCP Server Предоставление инструментов MCP FastAPI Серверный уровень действий/API Services Бизнес-логика и запросы к HANA HANA Cloud Хранение данных AUDIT_LOG Аудит операций записи

Технологический стек

Технология Назначение

Python 3.11+ Серверная часть и MCP FastAPI REST API Pydantic Валидация и схемы Uvicorn ASGI-сервер hdbcli Подключение к SAP HANA SAP HANA Cloud База данных FastMCP / mcp MCP-сервер SAP Joule / Joule Studio Агентный ИИ SAP Build Нативная интеграция SAP MCP Inspector Тестирование MCP Git / GitHub Контроль версий

Структура проекта

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

Приложение разделяет HTTP-маршрутизацию, подключение к базе данных, бизнес-сервисы, модели данных и интеграцию MCP.

Бизнес-возможности

1. Сведения о материале

GET /materials/{material_id}/{plant_code}

Пример:

GET /materials/MAT-1023/PLT-PUN

Возвращает информацию о материале для конкретного завода.

2. Открытые заказы на продажу

GET /sales-orders/open

Обязательные параметры:

region
date_from
date_to

Сервис получает открытые заказы и группирует возвращённые заказы по клиентам.

3. Сводка по клиенту

GET /customers/{customer_id}/summary

Пример:

GET /customers/C-501/summary

Объединяет информацию о клиенте и счетах для анализа суммы задолженности клиента.

4. Сводка по просроченным счетам

GET /customers/{customer_id}/overdue-invoices

Пример:

GET /customers/C-501/overdue-invoices

Предоставляет информацию о просроченных счетах, используемую агентом для рекомендаций по взысканию задолженности.

5. Создание заявки на техническое обслуживание

POST /tickets

Сервис:

1. Проверяет запрос.

2. Проверяет наличие материала на указанном заводе.

3. Создаёт идентификатор заявки.

4. Вставляет заявку в HANA.

5. Вставляет аудиторскую запись.

6. Подтверждает транзакцию.

7. Возвращает созданную заявку.

База данных

Приложение использует схему NORTHWIND в SAP HANA Cloud.

Таблицы

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

MATERIALS

Хранит идентификатор материала, описание, категорию, цену за единицу, количество на складе, страховой запас и код завода.

SALES_ORDERS

Хранит идентификатор заказа, идентификатор клиента, идентификатор материала, количество, статус, дату создания и регион.

CUSTOMERS

Хранит идентификатор клиента, имя, регион, кредитный лимит и сумму задолженности.

INVOICES

Хранит идентификатор счёта, идентификатор клиента, сумму, срок оплаты, статус и количество дней просрочки.

TICKETS

Хранит заявки на техническое обслуживание, созданные через JouleOps.

AUDIT_LOG

Хранит метку времени, роль пользователя, имя инструмента, маскированные параметры и результат для аудируемых операций.

Скрипты базы данных

sql/01_schema.sql

Создаёт объекты базы данных.

sql/02_seed.sql

Загружает синтетические данные NorthWind.

sql/generate_seed.py

Генерирует начальные данные при необходимости.

REST API

Запустите API из корня проекта:

uvicorn app.main:app --reload

Локальный адрес по умолчанию:

http://127.0.0.1:8000

Swagger UI:

http://127.0.0.1:8000/docs

Спецификация OpenAPI:

http://127.0.0.1:8000/openapi.json

Сгенерированный документ OpenAPI можно использовать при регистрации REST-действий в SAP Build.

MCP-сервер

Проект предоставляет выбранные серверные возможности через собственный FastMCP-сервер.

Локальная конечная точка MCP:

http://127.0.0.1:8001/mcp

Транспорт:

Streamable HTTP

MCP-сервер предоставляет инструменты для таких операций, как:

get_customer_summary_tool
get_material_details
get_open_sales_orders_tool
summarize_overdue_invoices
create_maintenance_ticket

Сигнатура MCP-инструмента должна соответствовать базовой бизнес-операции. Например, для открытых заказов на продажу требуется:

region
date_from
date_to

а не один customer_id.

Конфигурация окружения

Создайте файл .env в корне проекта:

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

Не коммитьте .env.

Рекомендуемые записи в .gitignore:

.env
.venv/
__pycache__/
*.pyc

Учётные данные HANA должны оставаться на стороне сервера и никогда не должны включаться в промпты Joule, описания MCP, контекст LLM или ответы API.

Локальная настройка

1. Клонируйте репозиторий

git clone <repository-url>
cd jouleops

2. Создайте виртуальное окружение

py -m venv .venv

Активируйте его:

.\.venv\Scripts\Activate.ps1

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

pip install -r requirements.txt

4. Настройте HANA

Создайте .env и укажите информацию для подключения к SAP HANA Cloud.

5. Создайте базу данных

Выполните:

sql/01_schema.sql

для целевой схемы HANA Cloud.

6. Загрузите начальные данные

Выполните:

sql/02_seed.sql

или сгенерируйте нужные данные с помощью:

sql/generate_seed.py

Запуск проекта

FastAPI

uvicorn app.main:app --reload

Проверьте:

http://127.0.0.1:8000/docs

MCP-сервер

Запустите MCP-сервер, используя точку входа ASGI/приложения, определённую в mcp/server.py.

Для ASGI-приложения, доступного как app, команда будет:

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

Итоговая команда должна соответствовать объекту, экспортируемому mcp/server.py проекта.

Тестирование

REST API

Используйте Swagger UI:

http://127.0.0.1:8000/docs

Рекомендуемые проверки:

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

Для операции с заявкой проверьте оба пункта:

NORTHWIND.TICKETS
NORTHWIND.AUDIT_LOG

после успешной записи.

MCP Inspector

Используйте MCP Inspector для просмотра и выполнения MCP-сервера.

Настройте:

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

После подключения:

1. Откройте Tools.

2. Выберите инструмент JouleOps.

3. Введите все обязательные параметры.

4. Выполните инструмент.

5. Проверьте JSON-ответ.

6. При необходимости проверьте данные в HANA.

7. Для операций записи проверьте AUDIT_LOG.

Интеграция с SAP BTP и Joule

Предполагаемый корпоративный сценарий:

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

Назначение действия FastAPI

REST API предоставляется через BTP Destination для действий Joule Studio.

Назначение должно содержать:

sap-joule-studio-action = true

Назначение MCP

MCP-сервер предоставляется через HTTP-назначение, настроенное для обнаружения MCP в Joule Studio.

Назначение должно содержать:

sap-joule-studio-mcp-server = true

Для локальных демонстраций туннель, например ngrok, может открыть доступ к локальному сервису.

Сама HANA никогда не должна быть напрямую доступна Joule.

Безопасность и ограничения

Учётные данные HANA не передаются LLM

Только FastAPI/MCP хранят учётные данные HANA.

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

Параметризованный SQL

Запросы используют привязку параметров:

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

а не конкатенацию строк.

Аудит действий

Операции записи должны записывать:

user role
tool name
masked parameters
outcome
timestamp

в NORTHWIND.AUDIT_LOG.

Проверка входных данных

Модели FastAPI/Pydantic проверяют структурированные входные данные до выполнения бизнес-логики.

Доступ на основе ролей

Предполагаемые роли:

PLANT_SUPERVISOR
SALES_MANAGER
FINANCE
VIEWER

Пользователь с ролью VIEWER не должен иметь возможность создавать заявки на техническое обслуживание.

Без угадывания

Если обязательный параметр отсутствует, агент должен запросить недостающую информацию вместо того, чтобы угадывать или отправлять null-значения в операцию записи.

Демонстрационные сценарии

Сценарий 1 --- Проверка остатков + автоматическая заявка

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

Ожидаемый ход выполнения:

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

Сценарий 2 --- Открытые заказы на продажу

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

Ожидаемый инструмент:

get_open_sales_orders

Ожидаемые параметры:

region
date_from
date_to

Сценарий 3 --- Задолженность клиента

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

Ожидаемые инструменты:

get_customer_summary
summarize_overdue_invoices

Сценарий 4 --- Демонстрация архитектуры MCP

Give me an inventory snapshot for the Chennai plant.

Этот сценарий предназначен для демонстрации эквивалентной бизнес-возможности через MCP-инструмент.

Сценарий 5 --- Эскалация / отсутствующие параметры

Create a ticket.

Агент должен запросить необходимую информацию вместо того, чтобы угадывать.

Для роли VIEWER операция записи должна быть отклонена.

Устранение неполадок

500 Internal Server Error

Проверьте:

1. Значения в .env.

2. Хост и порт HANA.

3. Сетевую доступность HANA Cloud.

4. Имена схемы и таблиц.

5. Параметры SQL.

6. Журналы Uvicorn.

Таблица HANA не найдена

Проверьте схему и таблицы:

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

Проект ожидает таблицы NorthWind в:

NORTHWIND

MCP Inspector не может подключиться

Проверьте:

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

Ожидаемая конечная точка:

http://127.0.0.1:8001/mcp

MCP-инструмент сообщает об отсутствующих аргументах

Проверьте, что сигнатура MCP-обёртки соответствует функции сервиса.

Например:

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

MCP-инструмент должен предоставлять все три параметра.

SAP Build Action возвращает 404 Not Found

Конечная точка SAP Build Action должна точно соответствовать маршруту FastAPI.

Например:

GET /customers/{customer_id}/overdue-invoices

не должна быть настроена как:

/invoices/{customer_id}/overdue-summary

Используйте текущую спецификацию OpenAPI FastAPI:

http://127.0.0.1:8000/openapi.json

Неверный файл OpenAPI

Используйте документ OpenAPI, сгенерированный текущим приложением FastAPI, а не устаревшую спецификацию.

Контрольный список воспроизводимости

Серверная часть

• Создано Python-окружение.

• Установлены зависимости.

• Настроен .env.

• FastAPI успешно запускается.

• Swagger UI загружается.

• Спецификация OpenAPI загружается.

• Все основные REST-операции работают.

HANA

• Доступен экземпляр HANA Cloud.

• Существует схема NORTHWIND.

• Существуют необходимые таблицы.

• Загружены начальные данные.

• Создание заявок сохраняется.

• Создаются аудиторские записи.

MCP

• MCP-сервер запускается.

• Конечная точка Streamable HTTP доступна.

• MCP Inspector подключается.

• Инструменты обнаруживаются.

• Все обязательные параметры предоставлены.

• Инструменты чтения возвращают корректные результаты.

• Инструменты записи создают аудиторские записи.

Joule / SAP Build

• Агент JouleOps настроен.

• REST-действия зарегистрированы.

• MCP-сервер подключён.

• Настроены BTP Destinations.

• Настроены обязательные свойства назначения.

• Для репрезентативных промптов выбраны корректные инструменты.

• Отсутствующие параметры обрабатываются корректно.

• Поведение RBAC проверено.

• Прозрачность источника проверена.

Демонстрация

• Сценарий «склад + тикет» протестирован.

• Сценарий открытого заказа на продажу протестирован.

• Сценарий «клиент/счёт» протестирован.

• Сценарий MCP протестирован.

• Сценарий эскалации/RBAC протестирован.

• Трассировки инструментов записаны.

• Результаты HANA проверены.

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

Возможные расширения включают:

• Развернуть FastAPI и MCP в SAP BTP Cloud Foundry или Kyma.

• Добавить CI/CD с использованием GitHub Actions.

• Добавить комплексные автоматизированные тесты.

• Создать панель аудита Fiori/SAPUI5.

• Добавить возможности HANA Vector Engine.

• Добавить семантический поиск по историческим тикетам.

• Добавить привязку документов для политик кредитования/взыскания.

• Добавить мультиагентную оркестрацию.

• Добавить двуязычное взаимодействие.

• Добавить аутентификацию и авторизацию производственного уровня.

• Добавить структурированную наблюдаемость и мониторинг производительности.

Лицензия

Этот проект был разработан как учебная/выпускная реализация, демонстрирующая интеграцию SAP Joule, SAP HANA Cloud, Python FastAPI и Model Context Protocol.

Если в репозиторий не добавлена отдельная лицензия, проект следует рассматривать как учебную работу, специфичную для данного проекта.

Благодарности

Создано с использованием:

• SAP Joule / Joule Studio

• SAP Build

• SAP HANA Cloud

• Python

• FastAPI

• Pydantic

• FastMCP / Model Context Protocol

• MCP Inspector

• Git / GitHub