Skip to content
Back to search

btp-sap-odata-to-mcp-server

BTP CloudFoundry Node.js MCP server for SAP OData services integration

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lemaiwo--btp-sap-odata-to-mcp-server/badge.svg)](/listings/lemaiwo--btp-sap-odata-to-mcp-server)

HTML

<a href="/listings/lemaiwo--btp-sap-odata-to-mcp-server"><img src="/api/listings/lemaiwo--btp-sap-odata-to-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 327 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # SAP OData to MCP Server for BTP🚀
  2. ## 🎯 **Project Goal**
  3. 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:
  4. - **"Show me 10 banks"** → Automatically queries the Bank entity with $top=10
  5. - **"Update bank with ID 1 to have street number 5"** → Executes PATCH operation on Bank entity
  6. - **"Create a new customer with name John Doe"** → Performs POST to Customer entity
  7. - **"List all purchase orders from this week"** → Applies $filter for date range on PurchaseOrder entity
  8. ## 🏗️ **Architecture Overview - 3-Level Progressive Discovery**
  9. ```mermaid
  10. graph TB
  11. A[AI Agent/LLM] --> B[MCP Client]
  12. B --> C[SAP MCP Server]
  13. C --> D[SAP BTP Destination]
  14. D --> E[SAP System]
  15. C --> F[Level 1: Lightweight Discovery]
  16. F --> G[Minimal Service/Entity List]
  17. C --> H[Level 2: Full Metadata]
  18. H --> I[Complete Entity Schemas]
  19. C --> J[Level 3: CRUD Execution]
  20. J --> K[Authenticated Operations]
  21. style A fill:#e1f5fe
  22. style C fill:#f3e5f5
  23. style E fill:#e8f5e8
  24. style F fill:#fff3e0
  25. style H fill:#e8eaf6
  26. style J fill:#e0f2f1
  27. ```
  28. ### **Core Components:**
  29. 1. **🔍 Level 1 - Discovery**: Lightweight search returning minimal service/entity lists (token-optimized)
  30. 2. **📋 Level 2 - Metadata**: Full schema details on-demand for selected entities
  31. 3. **⚡ Level 3 - Execution**: Authenticated CRUD operations using metadata from Level 2
  32. 4. **🔌 MCP Protocol Layer**: Full compliance with MCP 2025-06-18 specification
  33. 5. **🌐 HTTP Transport**: Session-based Streamable HTTP for web applications
  34. 6. **🔐 BTP Integration**: Seamless authentication via SAP BTP Destination service
  35. ### **3-Level Approach Benefits:**
  36. - **Token Efficient**: Level 1 returns 90% less data than full schemas
  37. - **Progressive Detail**: Fetch full schemas only when needed
  38. - **Better LLM Experience**: Smaller responses, clearer workflow
  39. - **Reduced Context**: From 200+ tools down to just 3
  40. ## ✨ **Key Features**
  41. ### **🎨 Natural Language to OData**
  42. - **Smart Query Translation**: Converts natural language to proper OData queries
  43. - **Context-Aware Operations**: Understands entity relationships and constraints
  44. - **Parameter Inference**: Automatically maps user intent to tool parameters
  45. ### **🔄 Dynamic CRUD Operations**
  46. - **Read Operations**: Entity sets with filtering, sorting, pagination
  47. - **Create Operations**: New entity creation with validation
  48. - **Update Operations**: Partial and full entity updates
  49. - **Delete Operations**: Safe entity deletion with confirmation
  50. ### **🚀 Production-Ready**
  51. - **Session Management**: Automatic session creation and cleanup
  52. - **Error Handling**: Comprehensive error handling with user-friendly messages
  53. - **Logging**: Detailed logging for debugging and monitoring
  54. - **Security**: DNS rebinding protection, CORS, Helmet security
  55. ### **📊 Real-Time Metadata**
  56. - **Service Catalog**: Live discovery of available services
  57. - **Entity Schemas**: Dynamic schema generation from OData metadata
  58. - **Capability Detection**: Automatic detection of CRUD capabilities per entity
  59. ## 🏛️ **System Architecture**
  60. ```
  61. ┌─────────────────────┐ ┌───────────────────────────┐ ┌─────────────────────┐
  62. │ │ │ │ │ │
  63. │ 🤖 AI Agent │ │ 🖥️ SAP MCP Server │ │ 🏢 SAP │
  64. │ - Claude │◄──►│ - Service Discovery │◄──►│ - OData Services │
  65. │ - GPT-4 │ │ - CRUD Tool Registry │ │ - Business Logic │
  66. │ - Local LLMs │ │ - Session Management │ │ - Master Data │
  67. │ │ │ - BTP Authentication │ │ │
  68. └─────────────────────┘ └───────────────────────────┘ └─────────────────────┘
  69. │
  70. ▼
  71. ┌───────────────────────────┐
  72. │ │
  73. │ ☁️ SAP BTP Platform │
  74. │ - Destination Service │
  75. │ - Connectivity Service │
  76. │ - XSUAA Security │
  77. │ │
  78. └───────────────────────────┘
  79. ```
  80. ## 🎯 **Use Cases**
  81. ### **📈 Business Intelligence Queries**
  82. ```
  83. User: "Show me top 10 customers by revenue this quarter"
  84. → Tool: r-CustomerService-Customer
  85. → Parameters: $filter, $orderby, $top
  86. ```
  87. ### **📝 Data Maintenance**
  88. ```
  89. User: "Update supplier ABC123 to have status 'Active'"
  90. → Tool: u-SupplierService-Supplier
  91. → Parameters: SupplierId="ABC123", Status="Active"
  92. ```
  93. ### **📊 Analytical Insights**
  94. ```
  95. User: "How many open purchase orders are there?"
  96. → Tool: r-PurchaseOrderService-PurchaseOrder
  97. → Parameters: $filter=Status eq 'Open'&$count=true
  98. ```
  99. ### **🔧 System Administration**
  100. ```
  101. User: "List all inactive users in the system"
  102. → Tool: r-UserService-User
  103. → Parameters: $filter=Status eq 'Inactive'
  104. ```
  105. ## 🛠️ **Installation & Setup**
  106. ### **Prerequisites**
  107. - Node.js 18.x or higher
  108. - SAP S/4HANA or ECC system with OData services enabled
  109. - SAP BTP account with Destination and Connectivity services
  110. - TypeScript knowledge for customization
  111. ## 🚀 **Usage Examples**
  112. ### **Natural Language Queries**
  113. The MCP server automatically translates these natural language commands to the appropriate tool calls:
  114. | **Natural Language** | **Generated Tool Call** | **OData Query** |
  115. |---------------------|------------------------|-----------------|
  116. | "Show me 10 banks" | `r-BankService-Bank` | `GET /BankSet?$top=10` |
  117. | "Find banks in Germany" | `r-BankService-Bank` | `GET /BankSet?$filter=Country eq 'DE'` |
  118. | "Update bank 123 name to ABC Corp" | `u-BankService-Bank` | `PATCH /BankSet('123')` |
  119. | "Create a new customer John Doe" | `c-CustomerService-Customer` | `POST /CustomerSet` |
  120. | "Delete order 456" | `d-OrderService-Order` | `DELETE /OrderSet('456')` |
  121. ## 📋 **Available Tools - 3-Level Architecture**
  122. The server exposes **3 progressive discovery tools** instead of hundreds of individual CRUD tools:
  123. ### **Level 1: discover-sap-data**
  124. **Purpose**: Lightweight search for services and entities
  125. **Returns**: Minimal data (serviceId, serviceName, entityName, entityCount)
  126. **Usage**:
  127. ```javascript
  128. // Search for customer entities
  129. discover-sap-data({ query: "customer" })
  130. // Get all available services
  131. discover-sap-data({ query: "" })
  132. // Search in specific category
  133. discover-sap-data({ query: "sales", category: "sales" })
  134. ```
  135. **Fallback**: If no matches found, returns ALL services with entity lists
  136. ---
  137. ### **Level 2: get-entity-metadata**
  138. **Purpose**: Get complete schema for a specific entity
  139. **Returns**: Full schema with properties, types, keys, capabilities
  140. **Usage**:
  141. ```javascript
  142. // Get full schema for Customer entity
  143. get-entity-metadata({
  144. serviceId: "API_BUSINESS_PARTNER",
  145. entityName: "Customer"
  146. })
  147. ```
  148. **Output**: All properties, types, nullable flags, maxLength, keys, capabilities
  149. ---
  150. ### **Level 3: execute-sap-operation**
  151. **Purpose**: Perform authenticated CRUD operations
  152. **Operations**: read, read-single, create, update, delete
  153. **Usage**:
  154. ```javascript
  155. // Read customers
  156. execute-sap-operation({
  157. serviceId: "API_BUSINESS_PARTNER",
  158. entityName: "Customer",
  159. operation: "read",
  160. filterString: "CustomerName eq 'ACME'"
  161. })
  162. // Update customer
  163. execute-sap-operation({
  164. serviceId: "API_BUSINESS_PARTNER",
  165. entityName: "Customer",
  166. operation: "update",
  167. parameters: { CustomerID: "123", CustomerName: "New Name" }
  168. })
  169. ```
  170. ---
  171. ### **Workflow Example**
  172. ```
  173. 1. discover-sap-data → "customer"
  174. ↓ Returns: List of customer-related entities
  175. 2. get-entity-metadata → "API_BUSINESS_PARTNER", "Customer"
  176. ↓ Returns: Full schema with all properties
  177. 3. execute-sap-operation → read/create/update/delete
  178. ✓ Executes operation with proper parameters
  179. ```
  180. ### **Protocol Version**: 2025-06-18
  181. ### **Supported Capabilities**:
  182. - ✅ **Tools** with `listChanged` notifications
  183. - ✅ **Resources** with `listChanged` notifications
  184. - ✅ **Logging** with level control
  185. - ✅ **Session Management** for HTTP transport
  186. - ✅ **Error Handling** with proper error codes
  187. ### **Transport Support**
  188. - ✅ **Streamable HTTP** (recommended)
  189. - ✅ **Stdio** for command line usage
  190. - ✅ **Session-based** with automatic cleanup
  191. - ✅ **DNS Rebinding Protection**
  192. ## 🔒 **Security & Authentication**
  193. ### **SAP BTP Integration**
  194. - Uses BTP Destination service for S/4HANA or ECC authentication
  195. - Supports Principal Propagation and OAuth2
  196. - Automatic token refresh and session management
  197. - Secure credential storage in BTP
  198. ### **HTTP Security**
  199. - Helmet.js security headers
  200. - CORS protection with configurable origins
  201. - DNS rebinding attack prevention
  202. - Request rate limiting (configurable)
  203. ### **Session Security**
  204. - Automatic session expiration (24h default)
  205. - Secure session ID generation
  206. - Session cleanup on server restart
  207. - Memory leak prevention
  208. ## 📚 **API Reference**
  209. ### **Health Check**
  210. ```http
  211. GET /health
  212. {
  213. "status": "healthy",
  214. "activeSessions": 3,
  215. "discoveredServices": 25,
  216. "version": "2.0.0"
  217. }
  218. ```
  219. ### **Server Info**
  220. ```http
  221. GET /mcp
  222. {
  223. "name": "btp-sap-odata-to-mcp-server",
  224. "protocol": { "version": "2025-06-18" },
  225. "capabilities": { "tools": {}, "resources": {} },
  226. "features": ["Dynamic service discovery", "CRUD operations"],
  227. "activeSessions": 3
  228. }
  229. ```
  230. ### **Documentation**
  231. ```http
  232. GET /docs
  233. {
  234. "title": "SAP MCP Server API",
  235. "endpoints": {...},
  236. "mcpCapabilities": {...},
  237. "usage": {...}
  238. }
  239. ```
  240. ## 🎬 Demo
  241. See the MCP server in action:
  242. ![MCP Demo](docs/img/MCP%20Demo.gif)
  243. ## ⚙️ Environment Variable: Disable ReadEntity Tool Registration
  244. To disable registration of the ReadEntity tool for all entities in all services, set the following in your `.env` file:
  245. ```env
  246. DISABLE_READ_ENTITY_TOOL=true
  247. ```
  248. This will prevent registration of the ReadEntity tool for all entities and services.
  249. ## ⚡ Quick Start
  250. - For local development and testing, see [LOCAL_RUN.md](./docs/LOCAL_RUN.md)
  251. - For deployment to SAP BTP, see [DEPLOYMENT.md](./docs/DEPLOYMENT.md)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.