# SAP MCP Server – lokale Variante

Dieser MCP-Server stellt ausgewählte SAP-OData-Services für MCP-Clients bereit. Die lokale Variante läuft ausschließlich auf `127.0.0.1`, verbindet sich direkt über HTTPS mit SAP und benötigt keine BTP-Dienste oder zusätzliche MCP-Anmeldung. SAP-Anmeldung und SAP-Berechtigungen gelten weiterhin.

## Lokaler Schnellstart

### 1. Voraussetzungen

- Git, npm und **Node.js 22 ab Version 22.23.4** (`>=22.23.4 <23`) mit `--use-system-ca`.
- Netzwerk- beziehungsweise VPN-Zugriff auf das SAP-System.
- SAP-Benutzer und Passwort mit Berechtigungen für die benötigten OData-Services. Ein ausschließlich browserbasierter SSO-Zugang wird durch diesen Schnellstart nicht automatisch unterstützt.

Die folgenden Befehle gelten für Windows, Linux und macOS.

### 2. Repository klonen und einrichten

```sh
git clone https://github.com/Josia-WIAG/SAP_MCP_Server_local.git
cd SAP_MCP_Server_local
npm ci
npm run setup:local
```

`setup:local` legt `.env` aus [config/local.env.example](config/local.env.example) an. Eine bereits vorhandene `.env` wird **nicht überschrieben**. Die ursprüngliche `.env.example` ist für die BTP-Konfiguration gedacht und wird hier nicht benötigt.

### 3. Vier SAP-Angaben eintragen

Die erzeugte `.env` im Editor öffnen und diese Werte anpassen:

```dotenv
SAP_URL=https://your-sap-host:44300
SAP_CLIENT=100
SAP_USER=your-sap-user
SAP_PASSWORD="your-password"
```

Den Mandanten immer dreistellig angeben, beispielsweise `100` oder `010`. Das Passwort in Anführungszeichen setzen, insbesondere bei `#` oder Leerzeichen. Die echte `.env` ist durch `.gitignore` ausgeschlossen und gehört nicht ins Repository.

### 4. Konfiguration prüfen und Server starten

```sh
npm run check:local
npm run start:local
```

- `check:local` prüft die lokale Konfiguration, startet aber keinen Server und testet weder VPN noch SAP-Anmeldung.
- `start:local` kompiliert die Anwendung und startet sie mit dem Zertifikatsvertrauen des Betriebssystems. Der Server läuft im Terminal und kann mit **Strg+C** beendet werden.
- Beim Start werden die V2- und V4-Servicekataloge gelesen und die konfigurierten Filter angewendet. Service-Metadaten werden erst bei Bedarf geladen. Vor der ersten Abfrage den Abschluss der Discovery abwarten.

### 5. MCP-Client verbinden

Im MCP-Client einen Server mit folgenden Angaben eintragen:

| Einstellung | Wert |
|---|---|
| Transport | Streamable HTTP |
| URL | `http://127.0.0.1:3000/mcp` |
| Zusätzliche MCP-Anmeldung | Im lokalen Modus nicht erforderlich |

Der Client muss auf demselben Rechner laufen. Bei einem anderen `PORT` in `.env` die URL entsprechend anpassen. Eine erste Leseanfrage kann beispielsweise die verfügbaren Services über `search-sap-services` suchen und anschließend deren Entitäten über `discover-service-entities` untersuchen.

Der lokale Server bietet auch Schreibwerkzeuge an, soweit Service und SAP-Berechtigungen diese erlauben. Er ist nicht auf Lesezugriffe beschränkt.

### Weitere lokale Einstellungen

- Die Vorlage enthält die BAS-Filter und die ausgewählten Kunden-/Finanzservices mit einem Limit von **200 Services**. Welche davon verfügbar sind, hängt vom SAP-System ab.
- Eine bestehende Konfiguration mit `destinations` als JSON wird weiterhin unterstützt.
- Bei zusätzlichen Unternehmenszertifikaten `NODE_EXTRA_CA_CERTS` in `.env` auf eine lokale PEM-Datei setzen; die TLS-Prüfung bleibt aktiv.
- Optional kann für **S4W/100** die in der Vorlage kommentierte V2/V4-Lesepräferenz aktiviert werden. Diese Bestätigung gilt nicht automatisch für andere Systeme.

Details und weitere Hinweise stehen in [README.local.md](README.local.md).

## Hintergrund und ursprüngliches BTP-Projekt

Die folgenden Abschnitte dokumentieren das ursprüngliche BTP-Projekt. Sie sind **keine Voraussetzung für den lokalen Schnellstart**. Die lokale Variante mit Anmeldungsausnahme und Loopback-Bindung darf nicht unverändert nach BTP deployed werden; dafür ist der getrennte BTP-Stand vorgesehen.

This repository is an enterprise-ready MCP (Model Context Protocol) server that bridges SAP OData services with AI capabilities. Based on the original project **[btp-sap-odata-to-mcp-server](https://github.com/lemaiwo/btp-sap-odata-to-mcp-server)** by @lemaiwo, this optimized version features enhanced security, simplified configuration, modular authentication, and comprehensive Cloud Foundry integration.

## ✨ Key Features

### 🔐 Enhanced Security Architecture
- **Modular Authentication System**: Factory pattern supporting IAS, OAuth2, JWT, Basic Auth, and API Keys
- **Secure Session Management**: Thread-safe session bridging with proper locking mechanisms
- **Role-Based Access Control**: Granular permissions with XSUAA integration
- **Principal Propagation**: Maintains user context throughout the request lifecycle
- **Security Best Practices**: No sensitive data logging, secure error handling, JWT validation

### 🎯 Simplified OData Discovery
- **Pattern-Based Filtering**: Simple include/exclude patterns for service discovery
- **Business Domain Mode**: Pre-configured domains (sales, finance, HR, etc.)
- **Whitelist Mode**: Explicit service control for production environments
- **Smart Defaults**: Automatic exclusion of test/debug services

### 🧠 AI-Powered Capabilities
- **Smart Query Router**: Natural language to OData conversion
- **Hierarchical Tool Architecture**: 17+ tools organized in logical layers
- **Intelligent Workflow Orchestration**: Automatic tool chaining and optimization
- **Real-time Analytics**: KPI monitoring and trend analysis

### 🎨 Interactive UI Tools Suite
- **`ui-form-generator`**: Dynamic SAP Fiori forms with validation
- **`ui-data-grid`**: Interactive tables with sorting and filtering
- **`ui-dashboard-composer`**: Real-time KPI dashboards
- **`ui-workflow-builder`**: Visual workflow creation
- **`ui-report-builder`**: Analytical reports with drill-down

### ☁️ Cloud-Native Features
- **Cloud Foundry Optimized**: Native integration with CF services
- **Structured Logging**: SAP Cloud Logging with fallback support
- **Health Monitoring**: Comprehensive health check endpoints
- **Performance Metrics**: Built-in performance tracking
- **Graceful Shutdown**: Proper resource cleanup

## 🚀 BTP-Installation (ursprüngliches Projekt)

### Prerequisites

-   Access to an SAP BTP, Cloud Foundry environment.
-   Required BTP services: XSUAA, Identity, Connectivity, Destination.
-   Node.js >= 18.

### 1. Installation

```bash
# Use a checkout of the separately prepared BTP variant.
# Do not deploy the local working tree described above.
npm install
```

### 2. Configuration

Configure the application using environment variables. See the [Configuration Guide](./docs/CONFIGURATION.md) for detailed documentation.

```bash
cp .env.example .env
# Edit .env with your configuration
```

#### Quick Configuration Example

```bash
# Authentication
SAP_IAS_URL=https://your-tenant.accounts.ondemand.com
SAP_IAS_CLIENT_ID=your-client-id
SAP_IAS_CLIENT_SECRET=your-secret

# OData Discovery (Simplified)
ODATA_DISCOVERY_MODE=pattern
ODATA_INCLUDE_PATTERNS=*API*,Z*
ODATA_EXCLUDE_PATTERNS=*_TEST*,*_TEMP*
ODATA_MAX_SERVICES=50

# Destinations
SAP_DESTINATION_NAME=SAP_S4HANA
```

### 3. Build and Deploy

```bash
# Build the TypeScript source code for BTP
npm run build:btp

# Deploy to SAP BTP, Cloud Foundry
npm run deploy:btp
```

## 📚 Documentation

Complete documentation is available with structured navigation for all aspects of the project.

### 🏠 **[Documentation Hub](./docs/README.md)**
Main navigation center with use-case-based guidance and complete file index.

### 🚀 Quick Links

| Category | Document | Description |
|----------|----------|-------------|
| **Getting Started** | [Configuration Guide](./docs/CONFIGURATION.md) | Environment setup, OData discovery, CF deployment |
| **Architecture** | [Architecture Overview](./docs/ARCHITECTURE.md) | System design, security model, tool hierarchy |
| **🎨 Modern Diagrams** | [Modern Architecture Diagrams](./docs/MODERN-ARCHITECTURE-DIAGRAMS.md) | **NEW!** Interactive visual architecture |
| **Usage** | [User Guide](./docs/USER_GUIDE.md) | Authentication, tool usage, workflow examples |
| **Reference** | [Tool Reference](./docs/TOOL_REFERENCE.md) | Complete tool documentation with parameters |
| **Deployment** | [Deployment Guide](./docs/DEPLOYMENT.md) | SAP BTP and local development setup |
| **Development** | [Testing Guide](./docs/guides/TESTING.md) | Test suite and development guidelines |
| **Changes** | [Changelog](./docs/CHANGELOG.md) | Version history and feature updates |

### 📖 **Navigation Flow**
```
README.md → docs/README.md → All Documentation
     ↓           ↓
Quick Start → Structured Navigation → Complete Coverage
```