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 Skills와 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 Skills 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 내부 서버 오류

확인 사항:

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 작업이 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 결과 검증 완료.

향후 개선 사항

잠재적 확장 사항은 다음과 같습니다:

• FastAPI 및 MCP를 SAP BTP Cloud Foundry 또는 Kyma에 배포.

• 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