JouleOps @ NorthWind Manufacturing

SAP Joule、SAP HANA Cloud、Python FastAPI、Model Context Protocol (MCP) を使用したエージェント型 AI エンタープライズアシスタント。

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 スキルと MCP ベースのツール公開を組み合わせており、同じバックエンド機能をガバナンスが適用された統合パスを通じて利用できます。

問題提起

このプロジェクトは、NorthWind Manufacturing における一般的な運用タスクに対処します:

• プラントにおける材料在庫と安全在庫を確認する。

• 地域と日付範囲を指定してオープン販売注文を取得する。

• 顧客エクスポージャーと延滞請求書を確認する。

• 延滞請求書を要約し、債権回収の意思決定を支援する。

• 運用上のアクションが必要な場合に保守チケットを作成する。

複数のシステムを手動で照会する代わりに、ユーザーは SAP Joule を通じてこれらの要件を自然言語で表現できます。

主な機能

運用データ

• 材料とプラントによる材料詳細。

• 地域と日付範囲によるオープン販売注文。

• 顧客サマリー。

• 延滞請求書サマリー。

ビジネスアクション

• 保守チケットの作成。

• チケット作成前の材料/プラント組み合わせの検証。

• ビジネスアクションの監査記録の書き込み。

MCP

• FastMCP を使用したカスタム Python MCP サーバー。

• ストリーミング可能な HTTP トランスポート。

• MCP Inspector による MCP ツールの検出と実行。

• バックエンドビジネスロジックの再利用。

ガードレール

• 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 エージェント インテントルーティング、プランニング、ツール選択 Joule スキル REST ベースのアクション MCP サーバー MCP ツールの公開 FastAPI バックエンドのアクション/API レイヤー サービス ビジネスロジックと 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 エージェント型 AI 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. チケット ID を作成します。

4. チケットを HANA に挿入します。

5. 監査記録を挿入します。

6. トランザクションをコミットします。

7. 作成されたチケットを返します。

データベース

このアプリケーションは、SAP HANA Cloud の NORTHWIND スキーマを使用します。

テーブル

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

MATERIALS

材料 ID、説明、カテゴリ、単価、在庫数量、安全在庫、プラントコードを保存します。

SALES_ORDERS

注文 ID、顧客 ID、材料 ID、数量、ステータス、作成日、地域を保存します。

CUSTOMERS

顧客 ID、名前、地域、与信限度額、未収金額を保存します。

INVOICES

請求書 ID、顧客 ID、金額、支払期日、ステータス、延滞日数を保存します。

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 ドキュメントは、SAP Build で REST アクションを登録する際に使用できます。

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/server.py で定義されている ASGI/アプリケーションエントリポイントを使用して MCP サーバーを実行します。

app として公開される ASGI アプリケーションの場合、コマンドは次のとおりです:

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. ツール を開きます。

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 は、Joule Studio アクション用の BTP 宛先を通じて公開されます。

宛先には次のものを含める必要があります:

sap-joule-studio-action = true

MCP 宛先

MCP サーバーは、Joule Studio の MCP 検出用に設定された HTTP 宛先を通じて公開されます。

宛先には次のものを含める必要があります:

sap-joule-studio-mcp-server = true

ローカルデモンストレーションでは、ngrok などのトンネルを使用してローカルサービスを公開できます。

HANA 自体を Joule に直接公開してはなりません。

セキュリティとガードレール

LLM への HANA 認証情報の非公開

HANA の認証情報を保持するのは FastAPI/MCP のみです。

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 ツールは 3 つのパラメータすべてを公開する必要があります。

SAP Build アクションが 404 Not Found を返す

SAP Build アクションのエンドポイントは、FastAPI ルートと完全に一致している必要があります。

例:

GET /customers/{customer_id}/overdue-invoices

次のように設定してはなりません:

/invoices/{customer_id}/overdue-summary

現在の FastAPI OpenAPI 仕様を使用します:

http://127.0.0.1:8000/openapi.json

無効な OpenAPI ファイル

古い仕様ではなく、現在の FastAPI アプリケーションによって生成された OpenAPI ドキュメントを使用します。

再現性チェックリスト

バックエンド

• Python 環境が作成されている。

• 依存関係がインストールされている。

• .env が設定されている。

• FastAPI が正常に起動する。

• Swagger UI が読み込まれる。

• OpenAPI 仕様が読み込まれる。

• すべてのコア REST 操作が機能する。

HANA

• HANA Cloud インスタンスが利用可能である。

• NORTHWIND スキーマが存在する。

• 必要なテーブルが存在する。

• シードデータがロードされている。

• チケット作成が永続化される。

• 監査記録が作成される。

MCP

• MCP サーバーが起動する。

• ストリーミング可能な HTTP エンドポイントに到達できる。

• MCP Inspector が接続する。

• ツールが検出される。

• すべての必須パラメータが公開されている。

• 読み取りツールが有効な結果を返す。

• 書き込みツールが監査記録を作成する。

Joule / SAP Build

• JouleOps エージェントが設定されている。

• REST アクションが登録されている。

• MCP サーバーが接続されている。

• BTP 宛先が設定されている。

• 必要な宛先プロパティが設定されている。

• 代表的なプロンプトに対して正しいツールが選択される。

• 不足しているパラメータが正しく処理される。

• RBAC の動作が検証されている。

• ソースの透明性が検証されている。

デモ

• 在庫 + チケットのシナリオをテスト済み。

• オープン販売注文のシナリオをテスト済み。

• 顧客/請求書のシナリオをテスト済み。

• MCPのシナリオをテスト済み。

• エスカレーション/RBACのシナリオをテスト済み。

• ツールトレースを取得済み。

• HANAの結果を検証済み。

今後の改善点

考えられる拡張は以下のとおりです：

• SAP BTP Cloud FoundryまたはKymaにFastAPIとMCPをデプロイする。

• GitHub Actionsを使用したCI/CDを追加する。

• 包括的な自動テストを追加する。

• 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