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