Btp Sap Odata To MCP Server

🚀 SAP OData to MCP Server for BTP

Transform your SAP S/4HANA or ECC system into a conversational AI interface by exposing all OData services as dynamic MCP tools. This allows you to interact with your ERP data using natural language, offering a more intuitive and efficient way to access and manipulate information.

🚀 Quick Start

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

✨ 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.

🏗️ 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.

🏛️ 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

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

Basic Usage

The MCP server automatically translates these natural language commands to the appropriate tool calls:

📋 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

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.

📚 Documentation

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:

⚙️ Environment Variable: Disable ReadEntity Tool Registration

⚠️ Important Note

To disable registration of the ReadEntity tool for all entities in all services, set the following in your .env file:

DISABLE_READ_ENTITY_TOOL=true

This will prevent registration of the ReadEntity tool for all entities and services.