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:

1. 🔍 Service Discovery Engine: Automatically discovers all available OData services from SAP
2. ⚙️ Dynamic Tool Generator: Creates MCP tools for CRUD operations on each discovered entity
3. 🔌 MCP Protocol Layer: Full compliance with MCP 2025-06-18 specification
4. 🌐 HTTP Transport: Session-based Streamable HTTP for web applications
5. 🔐 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