SAP Business One MCP Server Sample

• SAP Business One MCP Server Sample

  • Einführung

  • Architekturübersicht

  • Verfügbare MCP-Tools

    • Zentrale Discovery- und Ausführungstools

      • Progressive 3-Schritt-Discovery

    • Tools zur Unternehmensauswahl

    • Workflow-Hilfstools

    • MCP-Ressourcen

  • Voraussetzungen

  • Installation

  • Konfiguration

    • Direkter Modus (nur Entwicklung)

    • OAuth-Modus (Produktion, Standardmodus)

    • HTTPS / Transport

  • Starten des Servers

  • Verbinden eines KI-Clients

    • Cline (VS Code)

    • GitHub Copilot (VS Code)

    • Goose (Desktop)

    • MCP Inspector (Browser)

  • MCP-Client-Integration

  • Menschliche Bestätigung (MCP-Elicitation)

  • Klassifizierung personenbezogener Daten

    • Wie Felder klassifiziert werden

    • Wo die Klassifizierung erscheint

    • Schutzmaßnahmen zur Laufzeit

    • Schwärzungsverhalten bei Leseergebnissen

  • UDO/UDT/UDF-Unterstützung

    • UDO-Namensgebung

    • Discovery-Verzögerung

  • Multi-Tenant-Unterstützung

  • Anwendungsbeispiele

    • Natürlichsprachliche Abfragen

    • Workflow-Beispiele

      • Einfacher CRUD-Workflow

      • Order-to-Cash-Workflow (Schritt für Schritt)

    • Business-Intelligence-Abfragen

    • Datenmanipulation

  • Testen des Servers

    • Unit-Tests

    • Integrationstests

    • Umfassende Qualitätsprüfung

  • Protokollierung

    • Anwendungsprotokolle

    • Auditprotokolle

  • Sicherheitsaspekte

    • Authentifizierung

    • Autorisierung

    • Produktionskonfiguration

  • Fehlerbehebung

    • Server- oder Verbindungsprobleme

    • Authentifizierung und Unternehmenskontext

    • Entitäts-, Feld- oder Schreibprobleme

    • Debug-Optionen aktivieren

  • Konfigurationsreferenz

  • Einschränkungen

Einführung

Ab SAP Business One 10.0 FP2608 wird ein Beispiel für SAP Business One MCP Server bereitgestellt, das zeigt, wie OData-Dienste des SAP B1 Service Layer als dynamische Tools für KI-Agenten verfügbar gemacht werden können, die das Model Context Protocol (MCP) unterstützen.

Der Beispiel-Server ist bewusst minimal und leicht verständlich gehalten, zeigt dabei aber dennoch die zentralen Muster und Fähigkeiten eines MCP-Servers. Statt hunderter einzelner CRUD-Tools (einer pro Entität × Operation) zu registrieren, verwendet der Server eine progressive Discovery-Architektur, die hunderte potenzielle Tools auf einige wenige intelligente, wiederverwendbare Tools reduziert.

Dieses Design gibt KI-Assistenten die Möglichkeit:

• Entdecken relevanter B1-Entitäten durch eine leichtgewichtige semantische Suche

• Verstehen vollständiger Entitätsschemas – einschließlich Eigenschaften, Typen und Fähigkeiten

• Ausführen authentifizierter CRUD-Operationen mit automatischer OData-Abfrage-Generierung

Natürlich sprachliche Anfragen wie „Zeig mir die zehn wichtigsten Kunden nach Saldo“ oder „Erstelle eine Einkaufsbestellung für den Lieferanten V00001“ werden automatisch in korrekte Service-Layer-API-Aufrufe übersetzt.

Dieses Projekt wird nur als Referenz- und Lernbeispiel bereitgestellt. Es ist nicht unbedingt ein produktionsreifes Produkt. SAP-B1-Partner und -Entwickler sind aufgefordert, die Architektur zu studieren, den Code anzupassen, die eingebauten Fähigkeiten zu bewerten und eigene MCP-Server-Implementierungen zu entwickeln, die auf ihre spezifischen geschäftlichen Anforderungen und Einsatzumgebungen zugeschnitten sind.

Versionsanforderung: Dieser MCP-Server benötigt SAP Business One 10.0 FP2608 oder höher. Er nutzt Service-Layer-APIs, die in FP2608 eingeführt wurden, und funktioniert mit älteren Versionen nicht korrekt.

MCP-Protokollversion: Dieses Beispiel implementiert die MCP-Protokollversion 2025-11-25, die neueste Version der Model Context Protocol-Spezifikation für SAP Business One 10.0 FP2608. MCP-Clients, die sich mit diesem Server verbinden, müssen ebenfalls die Protokollversion 2025-11-25 unterstützen. Da sich das MCP-Protokoll weiterentwickelt, wird dieses Beispiel aktualisiert, um mit neuen Spezifikationsversionen Schritt zu halten.

Related MCP server: SAP OData MCP Server

Architekturübersicht

Der MCP-Server sitzt zwischen einem KI-Agenten (Cline, GitHub Copilot, Sublime, Cursor usw.) und dem SAP B1 Service Layer. Der SAP Business One MCP Server implementiert eine moderne, mehrschichtige Architektur, die OData-Dienstverträge in KI-freundliche MCP-Tools umwandelt. Die Architektur ist um ein progressives Discovery-Muster herum organisiert, das Token-Effizienz mit möglichst vollständiger, integrierter Funktionsbreite in Einklang bringt – die Integrität benötigt eine geringe Trainings-Anzahl, die HallDC-Rate bleibt insgesamt niedrig.

Zeige die Diagramm:

In dieser Architektur interagiert der MCP-Client im KI-Agenten über eine sichere HTTP-Transportschicht, die das MCP-Protokoll implementiert, mit dem MCP-Server. Zur Authentifizierung verwendet der MCP-Server OAuth2 mit Keycloak. Der MCP-Client bzw. der KI-Agent registriert sich als OAuth-Client über Extension SSO Manager und erhält über den Standard-OAuth2-Flow ein Zugriffstoken. Mit diesem Token können Clients optional die Unternehmensliste (SLD) vom SLD abrufen, um den korrekten Unternehmenskontext in die Anfragen aufzunehmen. Der Server validiert jede eingehende Anfrage, indem er das Bearer-Token per Keycloak prüft, damit nur authentifizierte Clients auf die Server-Tools zugreifen können, und über den audience-Claim sicherstellt, dass das Token für den Server ausgestellt wurden.

Verfügbare MCP-Tools

Wichtig: Tools werden von KI-Systemen genutzt und stellen keine stabile API dar. Namen, Parameter und Verhalten der Tools können sich je nach Version ändern. Sie daher keine fest beschriebenen Abhängigkeiten von bestimmten Tool-Signaturen.

Zentrale Discovery- und Ausführungstools

Der Server verwendet 4 zentrale Discovery‑/Ausführungstools statt hunderter einzelner CRUD‑TopIs:

Progressive 3-Schritte-Erkundung

Der Server vermeidet eine Tool-Explosion, indem er alles in einen 3-Schritt-Ablauf komprimiert:

Step 1: b1_find_entities        → Lightweight semantic search; returns entity names and categories
Step 2: b1_get_entity_schema    → Full schema for a selected entity (properties, types, keys)
Step 3: b1_read / b1_write      → Execute the read or write operation with schema-informed parameters

• Token-Effizienz: Schritt 1 liefert ~90 % weniger Daten als vollständige Schemas

• Klare Trennung: Das LLM kann scannen und auswählen, bevor es eine vollständige Schemaabfrage anstößt

• Progressive Detaillierung: Komplexe Typen können in einem Schritt-2.2-Aufruf aufgerufen werden, ohne zunächst alles zu laden

Tools für die Unternehmensauswahl

Im OAuth-Modus wählen Sie ein Unternehmen aus, bevor Sie die Entitäts-Tools aufrufen:

Workflow-Hilfstools

Zwei Workflow-Hilfswerkzeuge vereinfachen typische B1-Geschäftsabläufe:

Erkennen von Workflow-Macher-Tools zur Laufzeit:

Show me what workflow tools are available in the B1 MCP server

Der KI-Agent ruft b1_find_entities mit category: 'workflow' auf und erhält die vollständigen Beschreibungen von b1_copy_document und b1_create_payment.

MCP-Ressourcen

Zwei Ressourcentypen liefern Kontextwissen ohne Tool-Aufrufe:

Vorteile: KI-Assistenten können sofort auf diese Ressourcen zugreifen, ohne Tool-Aufrufe – effizienter für Workflows!

Voraussetzungen

Installation

1. Laden Sie dieses Paket b1-mcp-server.zip aus der Online-Hilfe herunter, entpacken Sie es und navigieren Sie dann in den entpackten Projektordner.

2. Installieren Sie die Abhängigkeiten und kompilieren Sie das Projekt:

npm install
npm run build

Konfiguration

Alle Einstellungen werden über eine .env-Datei im Projektstamm gesteuert. Kopieren Sie .env.example als Ausgangspunkt:

cp .env.example .env

Eine vollständige Referenz aller verfügbaren Variablen finden Sie im Kapitel Konfigurationsreferenz.

Direkter Modus (nur Entwicklung)

Verwenden Sie diesen Modus, wenn SAP B1 Service Layer mit einem Benutzernamen und einem Passwort zugänglich ist. Geeignet für schnelles Prototyping in lokalen Entwicklungsumgebungen und nur für Tests.

Hinweis: Trotz der Verwendung eines Benutzernamens und eines Passworts in der .env-Datei handelt es sich nicht um HTTP-Basic-Authentication. Die Anmeldedaten werden vom MCP-Server verwendet, um über die Login-API (/b1s/v2/Login) ein Session-Token von SAP B1 Service Layer zu erhalten. Alle nachfolgenden Anfragen werden mit diesem Session-Token authentifiziert.

NODE_ENV=development
AUTHENTICATION_MODE=direct

# B1 Service Layer host (server appends /b1s/v2/ internally)
SERVICE_LAYER_ROOT_URL=https://servicelayer.b1.example.com:50000

B1_COMPANY_DB=yourCompanyDB
B1_USERNAME=yourUsernameHere
B1_PASSWORD=yourPasswordHere

# Accept self-signed certs for local development/testing only
AUTH_ALLOW_SELF_SIGNED=true

OAuth-Modus (Produktion, Standardmodus)

Verwenden Sie diesen Standardmodus, da die Service Layer immer von Keycloak vorgelagert ist. Eingehende Bearer-Tokens werden validiert, bevor irgendeine B1-Anfrage weitergeleitet wird.

# Default mode, validate incoming requests via OAuth 2.0 / OIDC (requires OAUTH_BASE_URL and OAUTH_CLIENT_ID)
AUTHENTICATION_MODE=oauth

SERVICE_LAYER_ROOT_URL=https://servicelayer.b1.example.com:50000
SLD_ROOT_URL=https://sld.b1.example.com:40000

OAUTH_BASE_URL=https://keycloak.b1.example.com/auth/realms/sapb1/
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret

HTTPS / Transport

Der Server verwendet standardmäßig HTTPS und für die lokale Entwicklung ein selbstsigniertes Zertifikat. Sie können bei Bedarf auch auf HTTP wechseln.

HTTPS (Standard):

HTTPS_ENABLED=true
HTTPS_KEY_PATH=./certs/server.key
HTTPS_CERT_PATH=./certs/server.crt
PORT=3000

# Optional:
# HTTPS_CA_PATH=./certs/ca.crt
# HTTPS_PASSPHRASE=your-cert-passphrase

HTTP:

Falls Sie für lokale Tests, um Browser-Sicherheitswarnungen zu vermeiden, eine bereits vorgelagerte HTTPS-Gateway bzw. eines Reverse-Proxys haben oder aus anderen Gründen HTTP statt HTTPS verwenden möchten, setzen Sie:

HTTPS_ENABLED=false
PORT=3000

Angekündigte öffentliche URL (MCP_BASE_URL):

Standardmäßig leitet der Server seine angekündigte URL aus den aktiven Listener-Einstellungen ab. Wenn der Server hinter einem Reverse Proxy läuft oder Clients für OAuth-Metadaten und MCP-Endpunkte eine bestimmte Basis-URL verwenden sollen, setzen Sie diese explizit:

MCP_BASE_URL=https://mcp.example.com

Lassen Sie diesen Wert bei lokaler Entwicklung nicht gesetzt – der Server wird die korrekte URL automatisch ableiten.

Starten des Servers

Starten Sie den Server:

npm start

Prüfen Sie, ob er läuft:

curl http://localhost:3000/health

Der Server bietet drei integrierte REST-Endpunkte:

OAuth-Hinweis: Im OAuth-Modus erfordert GET /mcp ein gültiges Bearer-Token im Authorization-Header.

GET /health – Beispielantwort:

{
  "status": "healthy",
  "timestamp": "2026-06-17T03:50:58.338Z",
  "version": "1.0.0",
  "checks": {
    "auditLogger": { "healthy": true },
    "personalFieldCache": { "healthy": true }
  }
}

GET /mcp – Beispielantwort:

{
  "name": "b1-mcp-server",
  "version": "1.0.0",
  "protocol": { "version": "2025-11-25", "transport": "streamable-http" },
  "capabilities": { "tools": {}, "resources": {}, "logging": {} },
  "features": [
    "Dynamic SAP Business One Service Layer OData service discovery",
    "CRUD operations for all discovered entities",
    "Natural language query support",
    "Session-based HTTP transport",
    "Real-time service metadata"
  ],
  "endpoints": { "health": "/health", "mcp": "/mcp", "docs": "/docs" },
  "activeSessions": 1
}

Verbinden eines KI-Clients

Der Server stellt den MCP-Endpunkt Streamable HTTP unter folgender Adresse bereit:

http(s)://<host>:<port>/mcp

Jeder MCP-kompatible KI-Client kann sich mit diesem Endpunkt verbinden. Die folgende Tabelle fasst die wichtigsten Funktionen der unterstützten Clients zusammen:

MCP-Elicitation dient der Bestätigung von Schreiboperationen und sensiblewürdigen Lesevorgängen durch Menschen. Falls Ihr Client dies nicht unterstützt, setzen Sie MCP_HUMAN_CONFIRMATION_ENABLED=false in .env; andernfalls werden diese Operationen abgelehnt. Details finden Sie unter Menschliche Bestätigung (MCP-Elicitation).

Cline (VS Code)

Anweisungen zur Einrichtung, LLM-Provider-Konfiguration, OAuth-/Keycloak-Setup sowie Testbeispiele für alle CRUD-Operationen und Workflow-Tools finden Sie unter docs/B1_CLINE_INTEGRATION_GUIDE.md.

GitHub Copilot (VS Code)

Anweisungen zur Einrichtung, den neuzeitigen OAuth-/Keycloak-Einstellungen, Konfiguration einer statischen Client-ID, den OAuth-Unternehmensauswahl-Flow und Testbeispiele für Elicitation finden Sie unter docs/B1_GITHUB_COPILOT_INTEGRATION_GUIDE.md.

Goose (Desktop)

Einrichtungsanleitung, Konfigurationsoptionen, OAuth-/Keycloak-Setup und Verwendungsbeispiele finden Sie unter docs/B1_GOOSE_INTEGRATION_GUIDE.md.

MCP Inspector (Browser)

Verwenden Sie den MCP Inspector, um Tools interaktiv zu durchsuchen und rohe MCP-Nachrichten zu prüfen. Eine ausführliche Nutzungsanleitung – einschließlich der Erhaltung eines Bearer-Tokens und der erforderlichen Header im OAuth-Modus – finden Sie unter docs/MCP_INSPECTOR.md.

MCP-Client-Integration

Falls Sie eine benutzerdefinierte MCP-Client-Anwendung entwickeln, die sich im OAuth-Modus mit dem Server verbindet, folgt die Integration einem Standard-PKCE-OAuth-2.0-Flow:

1. OAuth-Metadata über GET /mcp ermitteln (der Server gibt seine Autorisierungs- und Token-Endpunkte bekannt).

2. Eine PKCE-Autorisierungsanfrage starten und den Benutzer an Keycloak weiterleiten.

3. Den Autorisierungscode gegen Tokens (Access-Token + Refresh-Token) eintauschen.

4. Verfügbare Unternehmen mit b1_list_companies abrufen.

5. Den Benutzer ein Unternehmen auswählen lassen und b1_select_company aufrufen.

6. Access-Token und Unternehmens-ID in jede MCP-Anfrage einfügen:

   • Authorization: Bearer <access_token>

   • x-b1-companyID: <companySchemaName>

7. Das Token vor Ablauf aktualisieren; beifehlgeschlagener Aktualisierung den PKCE-Flow neu starten.

Ein vollständiges, funktionierendes Beispiel mit kommentiertem Code – einschließlich Client-Registrierung, OAuth-Flow, Unternehmensauswahl und erwarteter Ausgabe – finden Sie unter docs/SIMPLE_MCP_CLIENT.md.

Menschliche Bestätigung (MCP-Elicitation)

MCP Elicitation ist ein Mechanismus des Protokolls, der es einem MCP-Server erlaubt, einen Tool-Aufruf während der Ausführung anzuhalten und dem verbundenen Client eine zusätzliche Eingabe oder Bestätigung zu verlangen, bevor er fortfährt. Anders als ein einfacher Prompt ist Elicitation direkt in das MCP-Protokoll integriert: Der Server sendet eine strukturierte Anfrage an den Client, der Client zeigt sie dem Benutzer (normalerweise als Inline-Dialog oder Formular) an, und der Server wartet auf die Antwort, bevor er entscheidet, ob fortgefahren oder abgebrochen wird. So bleibt der Mensch bei sensiblen Vorgängen im Entscheidungsablauf, ohne dass der KI-Agent selbst einen Bestätigungsablauf improvisieren muss.

Wenn MCP_HUMAN_CONFIRMATION_ENABLED=true (dem Standardwert), hält der Server vor folgenden Aktionen:

• Schreiboperationen (create, update, delete) – verlangt eine ausdrückliche Benutzerfreigabe

• Sensible Lesevorgänge – verlangt eine Aufforderung, wenn die Abfrage Felder auswählt, die als personenbezogene Daten gelten (E-Mail, Telefon, Identifikationsnummern)

Clients, die Elicitation unterstützen (z. B. GitHub Copilot), zeigen einen Inline-Bestätigungsdialog an. Der Benutzer muss bestätigen, bevor der Server fortgeht; eine Ablehnung bricht den Vorgang ab, ohne Daten zu verändern.

Beispiel für eine Schreibbestätigungsaufforderung:

CONFIRM WRITE OPERATION | OPERATION: update | ENTITY: BusinessPartners |
TARGET: C00001 | FIELDS: Phone1=+1 555-1234 |
RISK: This action will modify SAP Business One data. |
ACTION: Set confirmed=true only if you intend to continue.

Clients ohne Elicitation-Unterstützung (z. B. Stimme v4.0.8):

Der Server lehnt sensible Lesevorgänge und Schreiboperationen ab, anstatt ohne Bestätigung fortzufahren. Um diese Sperre bei automatisierten Projekten zu umgehen, setzen Sie:

MCP_HUMAN_CONFIRMATION_ENABLED=false

Klassifizierung personenbezogener Daten

Der Server verwendet die SAP-Business-One-Metadaten von PersonalFieldsmSetups und das SAP Business One PersonalFieldsSetups-Metadatenmodell (aufgelöst per Tabelle über PersonalFieldsSetupsService_GetPersonalFieldsByTable), um sensible Felder zu klassifizieren und Schutzmaßnahmen bei Lese- und Schreibzugriffen anzuwenden.

Wie Felder auffällig werden

• Klassifizierungsquelle: Service-Layer-Tabellenbezogene Einträge für persönliche Felder, die von PersonalFieldsSetupsService_GetPersonalFieldsByTable zurückgegeben werden.

• Abgleichsregel: Eine Eigenschaft wird als personenbezogen markiert, wenn Tabellenname + Feldname mit einem Eintrag der PersonalFieldsSetups übereinstimmen.

• Geltungsbereich: Die Klassifizierung wird sowohl auf Entitätseigenschaften der oberen Ebene als auch bin komplex typisierte Eigenschaften angewendet.

• Verschachtelte Auflösung: Bei komplexen Eigenschaften wechselt der Tabellenkontext mithilfe der Kindtabellenzuordnung und wird für tiefer verschachtelte Ebenen rekursiv fortgesetzt.

Wo die Klassifizierung erscheint

• In der Schema-Ausgabe von Schritt 2 über b1_get_entity_schema werden personenbezogene Eigenschaften mit isPersonalField markiert.

• Dies umfasst Skalarfelder und Eigenschaften von strukturellen Typen in der Unten, wenn die Tabellenzuordnung sie als personenbezogen markiert.

Schutz zur Laufzeit

Wenn MCP_HUMAN_CONFIRMATION_ENABLED=true:

• Schreiboperationen (create, update, delete) erfordern eine ausdrückliche Bestätigung auf MCP-Elicitation.

• Sensible Lesevorgänge erfordern der Bestätigung, wenn selectString explizit personenbezogene Top-Level-Felder enthält.

Verfügt der Client nicht über MCP-Elicitation, werden diese geschützten Vorgänge blockiert.

Schwärzungsverhalten bei Leseergebnissen

Die Schwärzung von Leseergebnissen hängt davon ab, ob selectString eine inhaltliche Bedeutung ist:

• Kein selectString (oder leer/nur Whitespace): Auf die gesamte Antwort wird rekursiv einer Schwärzung auf personenbezogenen Feldern angewendet, sowohl in Top-Level- als auch in verschachtelten komplexen Daten.

• Aussagekräftiges selectString mit rein skalar-Auswahlen: Die ausgewählten Skalarfelder werden zurückgegeben.

• Aussagekräftiges selectString under anderem komplexen Eigenschaften: Ausgewählte Skalarfelder bleiben sichtbar, personenbezogen Felder innerhalb der ausgewählten komplexen Eigenschaften werden rekursiv geschwärzt.

Das bedeutet, dass ein ausgewähltes personenbezogenes Top-Level-Skalarfeld nach der Benutzerbestätigung sichtbar sein kann, während nested personenbezogene Felder innerhalb ausgewählter komplexer Eigenschaften weiterhin verborgen, also zu ausgegeben.

Weitere Details zur Konfiguration personenbezogener Daten finden Sie unter diesem Link: SAP Business One Help Portal – Schutz personenbezogener Daten.

UDO/UDT/UDF-Unterstützung

Der Server erkennt und stellt Benutzerdefinierte Objekte (UDO), Benutzerdefinierte Tabellen (UDT) und Benutzerdefinierte Felder (UDF) automatisch bereit, zusätzlich zu den Standard-SAP-Entities – keine weitere Konfiguration nötig.

• UDOs, die in SAP B1 registriert sind, erscheinen als abfrage- und beschreibbare Entitäten in b1_find_entities und sind unter ihren in TEXT geplanten Geschäftskategorien auffindbar.

• UDTs (custom tables with prefix @) werden als Bestand erster Klasse behandelt und unterstützen dieselben CRUD-Vorgänge wie die Standard-Entitäten.

• UDFs, die in standard- oder benutzerdefinierte Tabellen eingefügt wurden, werden automatisch in das von b1_get_entity_schema gelieferte Schema mit korrection Typen und Metadaten aufgenommen.

Dies bedeutet, dass jede in SAP B1 vorgenommene Anpassung – Partner-Erweiterungen, Lokalisierungs-Add-ons oder kundenspezifische Felder – KI-Agenten über denselben dreistufigen Discovery-Prozess sofort zur Verfügung steht, ganz ohne serverseitige Änderungen.

UDO-Benennung

UDO-Codes müssen den OData-Bezeichnungsregeln entsprechen, um vom Service Layer erkannt zu werden. Verwenden Sie nur Buchstaben, Ziffern und Unterstriche – keine Leerzeichen oder andere Sonderzeichen (z. B. MY_CUSTOM_OBJECT, nicht My Custom Object). UDOs mit nicht konformen Codes werden nicht erkannt.

Discovery-Verzögerung

UDOs und UDTs, die über den SAP-B1-Client, den Web Client oder Add-ons hinzugefügt oder geändert werden, werden nicht sofort im MCP-Server dargestellt. Der Server speichert die vom Service Layer abgerufenen OData-Metadaten für einen konfigurierbaren Zeitraum zwischen (Standard: 30 Minuten, gesteuert über METADATA_CACHE_TTL_MINUTES). Neue oder geänderte UDOs/UDTs werden erst sichtbar, wenn der Cache von selbst abläuft oder der MCP-Server neu gestartet wird. Verringern Sie während der Entwicklung benutzerdefinierter Objekte METADATA_CACHE_TTL_MINUTES auf einen kleineren Wert (z. B. 5), um Änderungen schneller zu übernehmen.

Multi-Mandanten-Unterstützung

Eine einzelne MCP-Serverinstanz kann ohne Konfigurationsänderungen mehrere SAP-Business-One-Unternehmen bedienen. Im OAuth-Modus wird der aktive Mandant bzw. das Unternehmen zur Laufzeit dynamisch über das System Landscape Directory (SLD) ausgewählt.

So funktioniert es:

1. Der MCP-Client ruft b1_list_companies auf, um alle im SLD registrierten Unternehmen samt Status abzurufen.

2. Der Benutzer (bzw. ein vom Benutzer geführter KI-Agent) wählt das Zielunternehmen aus, indem er b1_select_company mit dem gewünschten CompanySchemaName aufruft.

3. Alle folgenden Tool-Aufrufe (b1_find_entities, b1_read, b1_write usw.) werden für die Dauer der Sitzung an die Service-Layer-Datenbank des ausgewählten Unternehmens weitergeleitet.

4. Um das Unternehmen zu wechseln, wird b1_select_company erneut mit einem anderen Schema-Namen aufgerufen – ein Neustart des Servers ist nicht erforderlich.

Wichtige Eigenschaften:

• Sitzungsbezogen: Die Unternehmensauswahl ist an die MCP-Sitzung gebunden. Verschiedene KI-Client-Sitzungen können auf derselben Serverinstanz gleichzeitig mit verschiedenen Unternehmen arbeiten.

• SLD-gesteuert: Die Unternehmensliste stammt direkt aus dem SLD und spiegelt den aktuellen Stand der registrierten Unternehmen wider. Es muss keine statische Unternehmensliste in der Konfiguration gepflegt werden.

• Nur OAuth: Der Wechsel zwischen Mandanten (Unternehmen) erfordert den OAuth-Modus. Der Direktmodus unterstützt nur ein einziges Unternehmen (B1_COMPANY_DB ist in .env festgelegt).

Hinweis: Ist bereits ein gültiger x-b1-companyID-Header in der Anfrage vorhanden, verwendet der MCP-Server diesen direkt – ein Aufruf von b1_list_companies und b1_select_company ist dann nicht erforderlich. Der Zweck dieser Tools besteht lediglich darin, dem KI-Agenten oder dem Benutzer zu helfen, den richtigen Namen des Unternehmensschemas zu ermitteln und den Unternehmenskontext herzustellen, falls dieser noch nicht bekannt ist. Sobald das gewünschte Unternehmen bekannt ist, kann seine Unternehmens-ID (über CompanySchemaName aufgelöst) direkt im x-b1-companyID-Header jeder weiteren MCP-Anfrage übergeben werden.

Verwendungsbeispiele

Abfragen in natürlicher Sprache

Workflow-Beispiele

Für weitere Implementierungen von Geschäftsworkflows oder zum Hinzufügen neuer MCP-Tools siehe docs/DEVELOPER_GUIDE.md.

Grundlegender CRUD-Workflow

1. b1_find_entities → "BusinessPartners"
  ↓ Returns: List of matching entities

2. b1_get_entity_schema → "BusinessPartners"
  ↓ Returns: scalar properties plus structuralProperties[]

3. b1_get_entity_schema → "BusinessPartners", structuralPropertyName="ContactEmployees"
  ↓ Returns: sub-properties for that structural property when needed

4. b1_read or b1_write → execute the selected operation
   ✓ Executes operation with proper parameters

Order-to-Cash-Workflow (Schritt für Schritt)

1. b1_write → Create Sales Order
   ↓ Returns: DocEntry 123

2. b1_copy_document → Order → Delivery
   ↓ Returns: DocEntry 456 (automatic BaseType handling)

3. b1_copy_document → Delivery → Invoice
   ↓ Returns: DocEntry 789 (automatic BaseType handling)

4. b1_create_payment → Create Payment
   ✓ Validates and creates payment (automatic balance checking)

Business-Intelligence-Abfragen

User: "Show me top 10 customers by balance"
→ Tool: b1_read
→ Parameters:
  {
    "entityName": "BusinessPartners",
    "operation": "read",
    "filterString": "CardType eq 'cCustomer'",
    "orderbyString": "CurrentAccountBalance desc",
    "topNumber": 10
  }

User: "How many open sales orders are there?"
→ Tool: b1_read
→ Parameters:
  {
    "entityName": "Orders",
    "operation": "read",
    "filterString": "DocumentStatus eq 'bost_Open'",
    "selectString": "DocEntry"
  }

Datenmanipulation

User: "Update supplier V10000 to have phone number 123-456-7890"
→ Tool: b1_write
→ Parameters:
  {
    "entityName": "BusinessPartners",
    "operation": "update",
    "parameters": {
      "CardCode": "V10000",
      "Phone1": "123-456-7890"
    }
  }

Testen des Servers

Unit-Tests

npm test

Dies ist ein Alias für npm run test:unit. Die Unit-Tests befinden sich unter src/tests/unit/.

Integrationstests

Integrationstests setzen einen laufenden MCP-Server mit einem erreichbaren Service Layer und OAuth-Provider voraus. Außerdem muss der Scope b1_mcp:access in Keycloak konfiguriert sein – für Einrichtungsanweisungen siehe KEYCLOAK_SETUP.md. Konfigurieren Sie die Test-Client-Anmeldedaten in Ihrer .env-Datei und führen Sie dann Folgendes aus:

npm run test:integration

Wichtige Variablen für die Integrationstests:

Die Integrationstests befinden sich unter src/tests/integration/.

Hinweis: Falls nach einer Aktualisierung von Abhängigkeiten ein Test fehlschlägt, führen Sie zuerst npm run build aus – Kompilierungsfehler treten dort oft schon vor dem Test Runner zutage.

Vollständige Qualitätsprüfung

Führen Sie Lint, Build und Unit-Tests in dieser Reihenfolge aus:

npm run lint
npm run build
npm test
npm run test:integration

Protokollierung

Der Server erzeugt zwei getrennte Protokolldatenströme, die jeweils unabhängig konfigurierbar sind.

Anwendungsprotokolle

Anwendungsprotokolle umfassen die Anforderungenungsverarbeitung, den Tool-Dispatch, den Sitzungsslebenszyklus und Service-Layer-Aufrufe. Die Standard-Logstufe ist info. Aktivieren Sie während der Entwicklung die ausführliche Protokollierung (verbose), um zu verfolgen, was der Server tut:

APP_LOG_LEVEL=debug
APP_LOG_CONSOLE_ENABLED=true

Die Logs werden standardmäßig in eine rotierende Datei geschrieben (APP_LOG_FILE_ENABLED=true). Dateigröße und Aufbewahrungsdauer werden über APP_LOG_MAX_SIZE_BYTES (Standard: 10 MB) und APP_LOG_RETENTION_DAYS (Standard: 90 Tage) gesteuert.

Audit-Protokolle

Audit-Protokolle erfassen sicherheitsrelevante EreIGNIS: Schreibbestätigungen, Sitzungsstart und -ablauf sowie Authentifizierungsfehler. Sie werden standardmäßig in eine rotierende Datei geschrieben und sollten in der Produktion aktiviert bleiben.

Fügen Sie während der Entwicklung zusätzlich eine Ausgabe der Audit-Ereignisse auf der Konsole hinzu:

AUDIT_LOG_CONSOLE_ENABLED=true

Dateigröße und Aufbewahrungsdauer werden über AUDIT_LOG_MAX_SIZE_BYTES (Standard: 10 MB) und AUDIT_LOG_RETENTION_DAYS (Standard: 365 Tage) gesteuert.

Eine vollständige Liste der Protokollvariablen finden Sie unter docs/CONFIGURATION_REFERENCE.md.

Eine schrittweise Anleitung zur Keycloak-Konfiguration für den OAuth-Modus – einschließlich MCP-Server-Client-Registrierung, Client-Scope, Audience-Mapper und vertrauenswürdigen Hosts – finden Sie unter docs/KEYCLOAK_SETUP.md.

Sicherheitsaspekte

Hinweis: Dieses Projekt ist ein Beispielprojekt. Überprüfen und härten Sie vor der Bereitstellung in eine Produktionsumgebung alle Sicherheitseinstellungen gemäß den Sicherheitsstandards und Compliance-Anforderungen Ihrer Organisation.

Authentifizierung

Dieser MCP-Server agiert im OAuth-2.0-Framework als Ressourcen-Server (RS) und verwendet den standardmäßigen MCP-Authentifizierungsmechanismus. Jede Anfrage eines KI-Agenten muss ein gültiges Bearer-Zugriffstoken enthalten; der Server validiert dies es, bevor er die Anfrage verarbeitet.

Die Zugriffstokens werden vom Identity and Authentication Management-Dienst von SAP Business One berechtigt, indem der Benutzer gültige Anmeldedaten angibt. Dieser Dienst basiert auf Keycloak und kann so konfiguriert werden, dass er SAP IAS (Identity Authentication Service) oder andere Identitäts provider für die Benutzerauthentifizierung anbindet.

Autorisierung

Die Autorisierung wird auf zwei Ebenen erzwungen:

Ebene 1 – MCP-Server: prüft die scope- und aud-Claims (Zielgruppe/Audience) des Zugriffstokens, um festzustellen, ob der KI-Agent die angeforderten MCP-Tools aufrufen dürfen. Es werden nur Token akzeptiert, die den erforderlichen b1_mcp:access-Scope besitzen und an diesen Server adressiert sind.

Ebene 2 – SAP B1 Service Layer: delegiert die Datenzugriffsestung an den Service Layer, der die mit dem Token verknüpften Benutzerrollen und -berechtigung über das standardmäßige Zugriffs kontrollmodell von SAP Business One prüft. Administratoren können detaillierte Zugriffe spolicies pro Benutzer und Gruppe definieren. Gibt der Service Layer HTTP 403 (Forbidden) zurück, zeigt der MCP-Server den KI-Agenten einen Fehler an, der auf anzureichende Rechte hinweist, und liefert keinerlei Daten zurück.

Produktionskonfiguration

Überprüfen Sie die folgenden Einstellungen vor einer Bereitstellung in der Produktion.

Transport

• HTTPS_ENABLED – Standardwert ist true. Verwenden Sie in der Produktion grundsätzlich HTTPS. Nur hinter einem TLS-terminierenden Reverse-Proxy deaktivieren.

• AnTu true. Never deaktivieren Sie diese Option nicht in Breitbands; verwenden Sie eine gültige CA oder NODE_EXTRA_CA_CERTS`.

Tokenvalidierung

• TOKEN_VALIDATION_MODE – Verwenden Sie introspection oder introspection-with-jwt-fallback (Standard) in der Produktion. Vermeiden Sie den Modus jwt allein, es sei denn, die Tokens sind kurzlebig (< 5 Minuten), da gesperrte Tokens bis zum Ablauf gültig bleiben.

• VALIDATE_AUDIENCE – Standardwert ist true. Bei Deaktivierung können für andere Dienste ausgestellte Tokens authentifiziert werden. Nur deaktivieren, wenn der OAuth-Provider den aud-Claim ablegen.

• OAUTH_VERIFY_SCOPES / OAUTH_REQUIRED_SCOPES – Halten Sie die scope-Prüfung aktiviert und beschränken Sie sie auf den minimal erforderlichen zz (b1_mcp:access).

Netzwerk und Zugriffskontrolle

• MCP_ALLOWED_HOSTS – Listen Sie alle Hostnamen auf, über die der Server erreichbar ist. Anfragen mit nicht passendem Host-Header werden abgelehnt (Schutz gegen DNS-Rebinding).

• REQUEST_BODY_LIMIT – Klein halten (Standard 1mb), um Speicher begrenzt zu halten und das DoS-Risiko zu reduzieren.

• CORS_ALLOWED_ORIGINS – Vorlage leer (CORS deaktiviert), außer browserbasierte Clients benötigen sie. Achten Sie in der Produktion darauf, * zu vermeiden.

• MCP_RATE_LIMIT_WINDOW_MINUTES / MCP_RATE_LIMIT_MAX – Passen Sie diese Werte an den erwarteten Client-Durchsatz an.

Sitzungssicherheit und Schreiberwartungen

• SESSION_TIMEOUT_MINUTES – Leerlauf von Sitzungen werden beendet und auditietet. In der Produktion kurz halten (Standard 30 Min.)

• MCP_HUMAN_CONFIRMATION_ENABLED – Standardwert ist true. Erlaubt eine Bestätigung durch den Benutzer vor jedem Schreibvorgang. Nur bei vollautomatisierten, nicht-interaktiven Pipelines deaktivieren.

Auditprotokollierung

• AUDIT_LOG_FILE_ENABLED – Standardwert ist true. Audit-Protokolle erfassen alle Schreibbestätigungen und Sitzungsereignisse. In der Produktion aktiviert lassen und AUDIT_LOG_RETENTION_DAYS nach den Compliance-Anforderungen festlegen.

Fehlerbehebung

Server- oder Verbindungsprobleme

• Prüfen Sie, dass Node.js >= 22.22.3 (node --version) vorhanden ist und dass npm run build fehlerfrei durchläuft.

• Kontrollieren Sie, dass SERVICE_LAYER_ROOT_URL nur die Host-URL enthält – ohne /b1s/v2/-Pfad, (z. B. https://servicelayer.b1.example.com:50000).

• Stellen Sie sicher, dass der Server läuft: curl http://localhost:3000/health.

• Vergewissern Sie sich, dass die MCP-Endpoint-URL in der Client-Konfiguration zur Server-Adresse passt, und starten Sie VS Code neu, falls keine Tools erscheinen.

Authentifizierung und Unternehmenskontext

• Direktmodus: Prüfen Sie B1_COMPANY_DB, B1_USERNAME und B1_PASSWORD.

• OAuth-Modus: Prüfen Sie OAUTH_BASE_URL, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET und SLD_ROOT_URL. Verwendet der Service Layer ein selbstsigniertes Zertifikat, setzen Sie AUTH_ALLOW_SELF_SIGNED=true (nur für die Entwicklung).

• Prüfen Sie die vertrauenswürdigen Hosts in Keycloak, wenn VS Code-Clients mit Failed to verify remote host fehlschlagen – siehe KEYCLOAK_SETUP.md.

• Rufen Sie im OAuth-Modus vor jeder Entity-Tool-Anfrage zuerst b1_list_companies und dann b1_select_company auf. Ohne ein ausgewähltes Unternehmen liefern die Tools keine SAP-B1-Daten.

Probleme mit Ents Entity, Feld oder Schreibvorgängen

• Verwenden Sie b1_find_entities, um den korrekten Entitätsnamen zu bestätigen (Groß-/Kleinschreibung beachten), und b1_get_entity_schema, um die Eigenschaftsnamen zu überprüfen, bevor Sie Filter- oder Select-Zeichenfolgen erstellen.

• Werden Schreibvorgänge abgelehnt und ist MCP_HUMAN_CONFIRMATION_ENABLED=true, muss der Client die MCP-Elicitation unterstützen. Verwenden Sie GitHub Copilot, oder setzen Sie MCP_HUMAN_CONFIRMATION_ENABLED=false für automatisierte Pipelines.

Debug-Optionen aktivieren

Aktivieren Sie die ausführliche Protokollierung, um die Verarbeitung von Anfragen und Service-Layer-Aufrufe nachzuverfolgen:

APP_LOG_LEVEL=debug
APP_LOG_CONSOLE_ENABLED=true
AUDIT_LOG_CONSOLE_ENABLED=true

Konfigurationsreferenz

Die vollständige Referenz der Umgebungsvariablen, gruppiert nach Kategorie (Authentifizierung, HTTPS, OAuthC, Sitzung, Caching, Protokollierung), finden Sie unter docs/CONFIGURATION_REFERENCE.md.

Einschränkungen

• Der stdio-Transport wird nicht unterstützt. Es wird nur streamfähiges HTTP unterstützt.

• OData-Aktionen/Funktionen werden im aktuellen MCP-Server-Beispiel nicht unterstützt. Es sind nur Standard-CRUD-Operationen auf Entitäten verfügbar.

• Das Hochladen/Herunterladen von Anhängen/Bildern wird im aktuellen MCP-Server-Beispiel nicht unterstützt.

• OData-Batchoperationen werden im aktuellen MCP-Server-Beispiel nicht unterstützt. Jede Entitätsoperation muss einzeln ausgeführt werden.

• Erweiterte OData-Abfragen werden nicht vollständig unterstützt. Nur die grundlegenden $filter, $select, $top und $orderby sind in den MCP-Tools implementiert.