Btp Sap Odata To MCP Server

🚀 SAP OData 轉 MCP 服務器（用於 BTP）

本項目旨在將所有 OData 服務作為動態 MCP 工具公開，從而將您的 SAP S/4HANA 或 ECC 系統轉變為對話式 AI 接口。這使得用戶能夠通過自然語言與 ERP 數據進行交互：

• “顯示 10 家銀行” → 自動使用 $top=10 查詢銀行實體
• “將 ID 為 1 的銀行的街道編號更新為 5” → 對銀行實體執行 PATCH 操作
• “創建一個名為 John Doe 的新客戶” → 向客戶實體執行 POST 請求
• “列出本週的所有采購訂單” → 對採購訂單實體應用日期範圍的 $filter 操作

🏗️ 架構概述

graph TB
    A[AI 代理/大語言模型] --> B[MCP 客戶端]
    B --> C[SAP MCP 服務器]
    C --> D[SAP BTP 目標]
    D --> E[SAP 系統]
    
    C --> F[動態服務發現]
    F --> G[OData 目錄 API]
    C --> H[CRUD 工具生成]
    H --> I[實體元數據解析器]
    
    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，適用於 Web 應用程序
5. 🔐 BTP 集成：通過 SAP BTP 目標服務實現無縫認證

✨ 關鍵特性

🎨 自然語言轉 OData

• 智能查詢翻譯：將自然語言轉換為合適的 OData 查詢
• 上下文感知操作：理解實體關係和約束
• 參數推斷：自動將用戶意圖映射到工具參數

🔄 動態 CRUD 操作

• 讀取操作：支持過濾、排序和分頁的實體集
• 創建操作：創建新實體並進行驗證
• 更新操作：部分和全量實體更新
• 刪除操作：安全刪除實體並進行確認

🚀 生產就緒

• 會話管理：自動創建和清理會話
• 錯誤處理：全面的錯誤處理，提供用戶友好的消息
• 日誌記錄：詳細的日誌記錄，用於調試和監控
• 安全：DNS 重綁定保護、CORS 和 Helmet 安全防護

📊 即時元數據

• 服務目錄：即時發現可用服務
• 實體架構：根據 OData 元數據動態生成架構
• 功能檢測：自動檢測每個實體的 CRUD 功能

🏛️ 系統架構

┌─────────────────────┐    ┌───────────────────────────┐    ┌─────────────────────┐
│                     │    │                           │    │                     │
│   🤖 AI 代理       │    │   🖥️  SAP MCP 服務器     │    │   🏢 SAP            │
│   - Claude          │◄──►│   - 服務發現            │◄──►│   - OData 服務      │
│   - GPT-4           │    │   - CRUD 工具註冊表      │    │   - 業務邏輯        │
│   - 本地大語言模型  │    │   - 會話管理            │    │   - 主數據          │
│                     │    │   - BTP 認證            │    │                     │
└─────────────────────┘    └───────────────────────────┘    └─────────────────────┘
                                           │                                       
                                           ▼                                       
                           ┌───────────────────────────┐                          
                           │                           │                          
                           │   ☁️  SAP BTP 平臺       │                          
                           │   - 目標服務            │                          
                           │   - 連接服務            │                          
                           │   - XSUAA 安全          │                          
                           │                           │                          
                           └───────────────────────────┘                          

🎯 使用案例

📈 商業智能查詢

用戶：“顯示本季度收入最高的 10 個客戶”
→ 工具：r-CustomerService-Customer
→ 參數：$filter, $orderby, $top

📝 數據維護

用戶：“將供應商 ABC123 的狀態更新為‘活躍’”
→ 工具：u-SupplierService-Supplier
→ 參數：SupplierId="ABC123", Status="Active"

📊 分析洞察

用戶：“有多少未結采購訂單？”
→ 工具：r-PurchaseOrderService-PurchaseOrder
→ 參數：$filter=Status eq 'Open'&$count=true

🔧 系統管理

用戶：“列出系統中的所有非活躍用戶”
→ 工具：r-UserService-User
→ 參數：$filter=Status eq 'Inactive'

🛠️ 安裝與設置

先決條件

• Node.js 18.x 或更高版本
• 啟用 OData 服務的 SAP S/4HANA 或 ECC 系統
• 具有目標和連接服務的 SAP BTP 賬戶
• 具備 TypeScript 知識以進行定製

🚀 使用示例

自然語言查詢

MCP 服務器會自動將這些自然語言命令轉換為相應的工具調用：

📋 可用工具

工具命名約定

{操作縮寫}-{服務 ID}-{實體名稱}

其中操作縮寫為：

• 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 集成

• 使用 BTP 目標服務進行 S/4HANA 或 ECC 認證
• 支持主體傳播和 OAuth2
• 自動刷新令牌和管理會話
• 在 BTP 中安全存儲憑證

HTTP 安全

• Helmet.js 安全頭
• 可配置源的 CORS 保護
• 防止 DNS 重綁定攻擊
• 可配置的請求速率限制

會話安全

• 自動會話過期（默認 24 小時）
• 安全的會話 ID 生成
• 服務器重啟時清理會話
• 防止內存洩漏

📚 API 參考

健康檢查

GET /health
{
  "狀態": "健康",
  "活躍會話數": 3,
  "發現的服務數": 25,
  "版本": "2.0.0"
}

服務器信息

GET /mcp
{
  "名稱": "btp-sap-odata-to-mcp-server",
  "協議": { "版本": "2025-06-18" },
  "功能": { "工具": {}, "資源": {} },
  "特性": ["動態服務發現", "CRUD 操作"],
  "活躍會話數": 3
}

文檔

GET /docs
{
  "標題": "SAP MCP 服務器 API",
  "端點": {...},
  "MCP 功能": {...},
  "用法": {...}
}

🎬 演示

查看 MCP 服務器的實際運行情況：

⚙️ 環境變量：禁用 ReadEntity 工具註冊

要禁用所有服務中所有實體的 ReadEntity 工具註冊，請在 .env 文件中設置以下內容：

DISABLE_READ_ENTITY_TOOL=true

這將阻止所有實體和服務的 ReadEntity 工具註冊。

⚡ 快速開始

• 對於本地開發和測試，請參閱 LOCAL_RUN.md
• 對於部署到 SAP BTP，請參閱 DEPLOYMENT.md