SAP OData to MCP Server for BTP🚀

🎯 Project Goal

Transform your SAP S/4HANA or ECC system into a conversational AI interface by exposing all OData services as dynamic MCP tools. This enables natural language interactions with your ERP data:

"Show me 10 banks" → Automatically queries the Bank entity with $top=10
"Update bank with ID 1 to have street number 5" → Executes PATCH operation on Bank entity
"Create a new customer with name John Doe" → Performs POST to Customer entity
"List all purchase orders from this week" → Applies $filter for date range on PurchaseOrder entity

🏗️ Architecture Overview

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

Core Components:

🔍 Service Discovery Engine: Automatically discovers all available OData services from SAP
⚙️ Dynamic Tool Generator: Creates MCP tools for CRUD operations on each discovered entity
🔌 MCP Protocol Layer: Full compliance with MCP 2025-06-18 specification
🌐 HTTP Transport: Session-based Streamable HTTP for web applications
🔐 BTP Integration: Seamless authentication via SAP BTP Destination service

✨ Key Features

🎨 Natural Language to OData

Smart Query Translation: Converts natural language to proper OData queries
Context-Aware Operations: Understands entity relationships and constraints
Parameter Inference: Automatically maps user intent to tool parameters

🔄 Dynamic CRUD Operations

Read Operations: Entity sets with filtering, sorting, pagination
Create Operations: New entity creation with validation
Update Operations: Partial and full entity updates
Delete Operations: Safe entity deletion with confirmation

🚀 Production-Ready

Session Management: Automatic session creation and cleanup
Error Handling: Comprehensive error handling with user-friendly messages
Logging: Detailed logging for debugging and monitoring
Security: DNS rebinding protection, CORS, Helmet security

📊 Real-Time Metadata

Service Catalog: Live discovery of available services
Entity Schemas: Dynamic schema generation from OData metadata
Capability Detection: Automatic detection of CRUD capabilities per entity

🏛️ System Architecture

┌─────────────────────┐    ┌───────────────────────────┐    ┌─────────────────────┐
│                     │    │                           │    │                     │
│   🤖 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        │                          
                           │                           │                          
                           └───────────────────────────┘

🎯 Use Cases

📈 Business Intelligence Queries

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

📝 Data Maintenance

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

📊 Analytical Insights

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

🔧 System Administration

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

🛠️ Installation & Setup

Prerequisites

Node.js 18.x or higher
SAP S/4HANA or ECC system with OData services enabled
SAP BTP account with Destination and Connectivity services
TypeScript knowledge for customization

🚀 Usage Examples

Natural Language Queries

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')`

📋 Available Tools

Tool Naming Convention

{operationAbbreviation}-{serviceId}-{entityName}

Where operationAbbreviation is:

r: read (query entities or get single entity)
c: create (create new entity)
u: update (update existing entity)
d: delete (delete entity)

Examples:

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

CRUD Operations

Protocol Version: 2025-06-18

Supported Capabilities:

✅ Tools with listChanged notifications
✅ Resources with listChanged notifications
✅ Logging with level control
✅ Session Management for HTTP transport
✅ Error Handling with proper error codes

Protocol Version

2025-06-18

Supported Capabilities

✅ Tools with listChanged notifications
✅ Resources with listChanged notifications
✅ Logging with level control
✅ Session Management for HTTP transport
✅ Error Handling with proper error codes

Transport Support

✅ Streamable HTTP (recommended)
✅ Stdio for command line usage
✅ Session-based with automatic cleanup
✅ DNS Rebinding Protection

🔒 Security & Authentication

SAP BTP Integration

Uses BTP Destination service for S/4HANA or ECC authentication
Supports Principal Propagation and OAuth2
Automatic token refresh and session management
Secure credential storage in BTP

HTTP Security

Helmet.js security headers
CORS protection with configurable origins
DNS rebinding attack prevention
Request rate limiting (configurable)

Session Security

Automatic session expiration (24h default)
Secure session ID generation
Session cleanup on server restart
Memory leak prevention

📚 API Reference

Health Check

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

Server Info

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
}

Documentation

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

🎬 Demo

See the MCP server in action:

⚡ Quick Start

For local development and testing, see LOCAL_RUN.md
For deployment to SAP BTP, see DEPLOYMENT.md

oisee/btp-sap-odata-to-mcp-server