Btp Sap Odata To MCP Server

🚀 SAP OData to MCP Server for BTP

このプロジェクトは、すべてのODataサービスを動的なMCPツールとして公開することで、SAP S/4HANAまたはECCシステムを会話型AIインターフェースに変換します。これにより、ERPデータとの自然言語対話が可能になります。

• "Show me 10 banks" → 自動的に$top=10で銀行エンティティをクエリします。
• "Update bank with ID 1 to have street number 5" → 銀行エンティティに対してPATCH操作を実行します。
• "Create a new customer with name John Doe" → 顧客エンティティに対してPOSTを実行します。
• "List all purchase orders from this week" → 注文エンティティに対して日付範囲の$filterを適用します。

🚀 クイックスタート

• ローカル開発とテストについては、LOCAL_RUN.mdを参照してください。
• SAP BTPへのデプロイについては、DEPLOYMENT.mdを参照してください。

✨ 主な機能

🎨 自然言語からODataへの変換

• スマートクエリ翻訳：自然言語を適切なODataクエリに変換します。
• コンテキスト認識操作：エンティティの関係と制約を理解します。
• パラメータ推論：ユーザーの意図を自動的にツールのパラメータにマッピングします。

🔄 動的CRUD操作

• 読み取り操作：フィルタリング、ソート、ページネーション付きのエンティティセット。
• 作成操作：検証付きの新しいエンティティの作成。
• 更新操作：部分的および完全なエンティティの更新。
• 削除操作：確認付きの安全なエンティティの削除。

🚀 本番環境対応

• セッション管理：自動的なセッションの作成とクリーンアップ。
• エラーハンドリング：ユーザーフレンドリーなメッセージ付きの包括的なエラーハンドリング。
• ロギング：デバッグと監視用の詳細なロギング。
• セキュリティ：DNSリバインディング保護、CORS、Helmetセキュリティ。

📊 リアルタイムメタデータ

• サービスカタログ：利用可能なサービスのライブディスカバリー。
• エンティティスキーマ：ODataメタデータからの動的なスキーマ生成。
• 機能検出：エンティティごとのCRUD機能の自動検出。

🏗️ アーキテクチャの概要

graph TB
    A[AI Agent/LLM] --> B[MCP Client]
    B --> C[SAP MCP Server]
    C --> D[SAP BTP Destination]
    D --> E[SAP SAP System]
    
    C --> F[Dynamic Service Discovery]
    F --> G[OData Catalog API]
    C --> H[CRUD Tool Generation]
    H --> I[Entity Metadata Parser]
    
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style E fill:#e8f5e8

主要コンポーネント:

1. 🔍 サービスディスカバリーエンジン：SAPから利用可能なすべてのODataサービスを自動的に検出します。
2. ⚙️ 動的ツール生成器：検出された各エンティティに対するCRUD操作のMCPツールを作成します。
3. 🔌 MCPプロトコル層：MCP 2025-06-18仕様に完全に準拠しています。
4. 🌐 HTTPトランスポート：ウェブアプリケーション用のセッションベースのストリーム可能なHTTP。
5. 🔐 BTP統合：SAP BTP Destinationサービスを介したシームレスな認証。

🏛️ システムアーキテクチャ

┌─────────────────────┐    ┌───────────────────────────┐    ┌─────────────────────┐
│                     │    │                           │    │                     │
│   🤖 AI Agent       │    │   🖥️  SAP MCP Server     │    │   🏢 SAP            │
│   - Claude          │◄──►│   - Service Discovery     │◄──►│   - OData Services  │
│   - GPT-4           │    │   - CRUD Tool Registry    │    │   - Business Logic  │
│   - Local LLMs      │    │   - Session Management    │    │   - Master Data     │
│                     │    │   - BTP Authentication    │    │                     │
└─────────────────────┘    └───────────────────────────┘    └─────────────────────┘
                                           │                                       
                                           ▼                                       
                           ┌───────────────────────────┐                          
                           │                           │                          
                           │   ☁️  SAP BTP Platform    │                          
                           │   - Destination Service   │                          
                           │   - Connectivity Service  │                          
                           │   - XSUAA Security        │                          
                           │                           │                          
                           └───────────────────────────┘                          

🎯 ユースケース

📈 ビジネスインテリジェンスクエリ

User: "Show me top 10 customers by revenue this quarter"
→ Tool: r-CustomerService-Customer
→ Parameters: $filter, $orderby, $top

📝 データメンテナンス

User: "Update supplier ABC123 to have status 'Active'"
→ Tool: u-SupplierService-Supplier
→ Parameters: SupplierId="ABC123", Status="Active"

📊 分析的洞察

User: "How many open purchase orders are there?"
→ Tool: r-PurchaseOrderService-PurchaseOrder
→ Parameters: $filter=Status eq 'Open'&$count=true

🔧 システム管理

User: "List all inactive users in the system"
→ Tool: r-UserService-User
→ Parameters: $filter=Status eq 'Inactive'

📦 インストール

前提条件

• Node.js 18.x以上
• ODataサービスが有効になっているSAP S/4HANAまたはECCシステム
• DestinationおよびConnectivityサービスを持つSAP BTPアカウント
• カスタマイズ用のTypeScriptの知識

💻 使用例

基本的な使用法

# 自然言語クエリ
The MCP server automatically translates these natural language commands to the appropriate tool calls:

| **Natural Language** | **Generated Tool Call** | **OData Query** |
|---------------------|------------------------|-----------------|
| "Show me 10 banks" | `r-BankService-Bank` | `GET /BankSet?$top=10` |
| "Find banks in Germany" | `r-BankService-Bank` | `GET /BankSet?$filter=Country eq 'DE'` |
| "Update bank 123 name to ABC Corp" | `u-BankService-Bank` | `PATCH /BankSet('123')` |
| "Create a new customer John Doe" | `c-CustomerService-Customer` | `POST /CustomerSet` |
| "Delete order 456" | `d-OrderService-Order` | `DELETE /OrderSet('456')` |

📋 利用可能なツール

ツールの命名規則

{operationAbbreviation}-{serviceId}-{entityName}

ここで、operationAbbreviationは以下の通りです。

• r: 読み取り（エンティティをクエリまたは単一のエンティティを取得）
• c: 作成（新しいエンティティを作成）
• u: 更新（既存のエンティティを更新）
• d: 削除（エンティティを削除）

例:

• r-API_BUSINESS_PARTNER-BusinessPartner
• c-API_CUSTOMER_MATERIAL_SRV-CustomerMaterial
• u-API_SALES_ORDER_SRV-SalesOrder
• d-API_SALES_ORDER_SRV-SalesOrder

CRUD操作

プロトコルバージョン: 2025-06-18

サポートされる機能:

• ✅ listChanged通知付きのツール
• ✅ listChanged通知付きのリソース
• ✅ レベル制御付きのロギング
• ✅ HTTPトランスポート用のセッション管理
• ✅ 適切なエラーコード付きのエラーハンドリング

トランスポートサポート

• ✅ ストリーム可能なHTTP（推奨）
• ✅ コマンドラインでの使用用のStdio
• ✅ 自動クリーンアップ付きのセッションベース
• ✅ DNSリバインディング保護

🔒 セキュリティと認証

SAP BTP統合

• S/4HANAまたはECCの認証にBTP Destinationサービスを使用します。
• プリンシパル伝播とOAuth2をサポートしています。
• 自動トークン更新とセッション管理。
• BTP内の安全な資格情報の保存。

HTTPセキュリティ

• Helmet.jsセキュリティヘッダー。
• 設定可能なオリジンを持つCORS保護。
• DNSリバインディング攻撃の防止。
• 設定可能なリクエストレート制限。

セッションセキュリティ

• 自動セッション期限切れ（デフォルト24時間）。
• 安全なセッションIDの生成。
• サーバー再起動時のセッションクリーンアップ。
• メモリリークの防止。

📚 ドキュメント

ヘルスチェック

GET /health
{
  "status": "healthy",
  "activeSessions": 3,
  "discoveredServices": 25,
  "version": "2.0.0"
}

サーバー情報

GET /mcp
{
  "name": "btp-sap-odata-to-mcp-server",
  "protocol": { "version": "2025-06-18" },
  "capabilities": { "tools": {}, "resources": {} },
  "features": ["Dynamic service discovery", "CRUD operations"],
  "activeSessions": 3
}

ドキュメント

GET /docs
{
  "title": "SAP MCP Server API",
  "endpoints": {...},
  "mcpCapabilities": {...},
  "usage": {...}
}

🎬 デモ

MCPサーバーの動作を見るには、以下を参照してください。

⚙️ 環境変数: ReadEntityツールの登録を無効にする

すべてのサービスのすべてのエンティティに対するReadEntityツールの登録を無効にするには、.envファイルに以下を設定します。

DISABLE_READ_ENTITY_TOOL=true

これにより、すべてのエンティティとサービスに対するReadEntityツールの登録が防止されます。