SAP OData到MCP服务器的BTP🚀
🎯 项目目标
将您的SAP S/4HANA或ECC系统转换为 对话式人工智能界面 通过将所有OData服务作为动态MCP工具公开。这使您能够与ERP数据进行自然语言交互：
- “给我看看10家银行” → 自动查询$top=10的银行实体
- “将ID为1的银行更新为街道号5” → 对银行实体执行PATCH操作
- “创建一个名为John Doe的新客户” → 向客户实体执行POST
- “列出本周的所有采购订单” → 对PurchaseOrder实体的日期范围应用$filter
🏗️ 架构概述-三级渐进式发现
graph TB
A[AI Agent/LLM] --> B[MCP Client]
B --> C[SAP MCP Server]
C --> D[SAP BTP Destination]
D --> E[SAP System]
C --> F[Level 1: Lightweight Discovery]
F --> G[Minimal Service/Entity List]
C --> H[Level 2: Full Metadata]
H --> I[Complete Entity Schemas]
C --> J[Level 3: CRUD Execution]
J --> K[Authenticated Operations]
style A fill:#e1f5fe
style C fill:#f3e5f5
style E fill:#e8f5e8
style F fill:#fff3e0
style H fill:#e8eaf6
style J fill:#e0f2f1核心组件：
- 🔍 第1级-发现：轻量级搜索返回最小的服务/实体列表（令牌优化）
- 📋 级别2-元数据：所选实体的完整架构详细信息按需提供
- ⚡ 第3级-执行：使用级别2的元数据进行身份验证的CRUD操作
- 🔌 MCP协议层：完全符合MCP 2025-06-18规范
- 🌐 HTTP传输：用于web应用程序的基于会话的流式HTTP
- 🔐 BTP集成：通过SAP BTP目标服务实现无缝身份验证
三级方法的好处：
- 代币高效：级别1返回的数据比完整模式少90%
- 渐进式细节：仅在需要时获取完整架构
- 更好的LLM体验：响应更小，工作流程更清晰
- 减少上下文：从200多种工具减少到仅3种
✨ 主要特点
🎨 OData的自然语言
- 智能查询翻译：将自然语言转换为适当的OData查询
- 上下文感知操作：了解实体关系和约束
- 参数推断：自动将用户意图映射到工具参数
🔄 动态CRUD操作
- 读取操作：具有过滤、排序和分页功能的实体集
- 创建操作：创建新实体并进行验证
- 更新操作：部分和全部实体更新
- 删除操作：安全实体删除并确认
🚀 生产就绪
- 会话管理：自动创建和清理会话
- 错误处理：通过用户友好的消息进行全面的错误处理
- 日志记录：调试和监控的详细日志记录
- 安全：DNS重新绑定保护、CORS、头盔安全
📊 实时元数据
- 服务目录：实时发现可用服务
- 实体架构：从OData元数据生成动态架构
- 能力检测：自动检测每个实体的CRUD功能
🏛️ 系统架构
┌─────────────────────┐ ┌───────────────────────────┐ ┌─────────────────────┐
│ │ │ │ │ │
│ 🤖 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系统
- SAP BTP帐户，提供目标和连接服务
- 用于定制的TypeScript知识
🚀 用法示例
自然语言查询
MCP服务器会自动将这些自然语言命令转换为相应的工具调用：
| 自然语言 | 生成的工具调用 | OData 查询 |
|---|---|---|
| “给我看看10家银行” | r-BankService-Bank | GET /BankSet?$top=10 |
| “在德国寻找银行” | r-BankService-Bank | GET /BankSet?$filter=Country eq 'DE' |
| “将123银行名称更新为ABC公司” | u-BankService-Bank | PATCH /BankSet('123') |
| “创建新客户John Doe” | c-CustomerService-Customer | POST /CustomerSet |
| “删除订单456” | d-OrderService-Order | DELETE /OrderSet('456') |
📋 可用工具-三级架构
服务器暴露 3个渐进式发现工具 而不是数百个单独的CRUD工具：
级别1：发现sap数据
目的：轻量级搜索服务和实体
退货：最小数据（serviceId、serviceName、entityName、entityCount）
用法:
// Search for customer entities
discover-sap-data({ query: "customer" })
// Get all available services
discover-sap-data({ query: "" })
// Search in specific category
discover-sap-data({ query: "sales", category: "sales" })后备方案：如果未找到匹配项，则返回所有具有实体列表的服务
______________________________________________________________________
级别2：获取实体元数据
目的：获取特定实体的完整架构
退货：具有属性、类型、键和功能的完整架构
用法:
// Get full schema for Customer entity
get-entity-metadata({
serviceId: "API_BUSINESS_PARTNER",
entityName: "Customer"
})输出：所有属性、类型、可空标志、maxLength、键、功能
______________________________________________________________________
第三级：执行sap操作
目的：执行经过身份验证的CRUD操作
运营：读取、读取单个、创建、更新、删除
用法:
// Read customers
execute-sap-operation({
serviceId: "API_BUSINESS_PARTNER",
entityName: "Customer",
operation: "read",
filterString: "CustomerName eq 'ACME'"
})
// Update customer
execute-sap-operation({
serviceId: "API_BUSINESS_PARTNER",
entityName: "Customer",
operation: "update",
parameters: { CustomerID: "123", CustomerName: "New Name" }
})______________________________________________________________________
工作流示例
1. discover-sap-data → "customer"
↓ Returns: List of customer-related entities
2. get-entity-metadata → "API_BUSINESS_PARTNER", "Customer"
↓ Returns: Full schema with all properties
3. execute-sap-operation → read/create/update/delete
✓ Executes operation with proper parameters协议版本: 2025-06-18
支持的功能:
- ✅ 工具 随着
listChanged通知 - ✅ 资源 随着
listChanged通知 - ✅ 日志记录 带液位控制
- ✅ 会话管理 用于HTTP传输
- ✅ 错误处理 带有正确的错误代码
运输支持
- ✅ 可流式传输的HTTP （推荐）
- ✅ 工作室 用于命令行使用
- ✅ 基于会话 具有自动清理功能
- ✅ DNS重新绑定保护
🔒 安全和身份验证
SAP BTP集成
- 使用BTP目标服务进行S/4HANA或ECC身份验证
- 支持主体传播和OAuth2
- 自动令牌刷新和会话管理
- BTP中的安全凭据存储
HTTP安全
- Helmet.js安全标头
- 具有可配置源的CORS保护
- DNS重新绑定攻击防御
- 请求速率限制（可配置）
会话安全
- 自动会话过期（默认24小时）
- 安全会话ID生成
- 服务器重启时的会话清理
- 内存泄漏预防
📚 API 参考
健康检查
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工具。
⚡ 快速开始
- 有关本地开发和测试，请参阅 LOCAL_RUN.md
- 有关部署到SAP BTP的信息，请参阅 部署.md