SAP B1 ServiceLayer MCP Server

MCP-Server (Model Context Protocol) zur Verbindung von KI-Assistenten (opencode, Claude usw.) mit dem ServiceLayer von SAP Business One 10.0 im lokalen Netzwerk. Ausführbar mit npx aus diesem GitHub-Repository, ohne Installation auf dem PC.

Funktionen

• Standardmäßig nur lesend: Mit SAP_B1_READONLY=true (Standard) werden nur Abfrage-Tools (GET) registriert. Die Schreib-Tools (POST/PATCH/DELETE) existieren nicht auf dem Server und können nicht aufgerufen werden.

• Vollständige Erkennung: sap_list_entities, sap_get_entity_schema und sap_list_actions fragen GET /$metadata ab (einmal pro Prozess heruntergeladen und gecacht) und legen die ~140 CRUD-Entitäten (einschließlich Benutzertabellen @ und UDOs) sowie die hunderte Service-Methoden des ServiceLayer offen.

• Optionaler Schreibmodus: Mit SAP_B1_READONLY=false werden sap_create, sap_update, sap_delete für ServiceLayer-Entitäten und sap_call_action für Service-Methoden aktiviert (können Nebenwirkungen haben).

• Ausführung über npx github:: ohne manuelle Installation.

• Verwaltete Sitzung: impliziter Login mit CompanyDB/Benutzer/Passwort, Cookies B1SESSION + ROUTEID werden im Speicher gehalten (unterstützt mehrknotigen ServiceLayer), automatischer Re-Login bei 401 und garantierter Logout beim Beenden des Prozesses (zusätzlich zum Tool sap_logout).

• Selbstsigniertes TLS: Unterstützung für selbstsignierte Zertifikate des ServiceLayer (typisch in lokalen Umgebungen) über SAP_B1_VERIFY_TLS=false.

• Keine Telemetrie oder externe Aufrufe: Der HTTP-Client zeigt ausschließlich auf die konfigurierte URL (SAP_B1_SERVER_URL).

• Sicherheitslimits: top auf 200 Datensätze pro Abfrage begrenzt.

Related MCP server: BTP MCP Server

Tools

Lesen (immer verfügbar)

Schreiben (nur wenn SAP_B1_READONLY=false)

Voraussetzungen

• Node.js 18+

• SAP Business One 10.0 mit aktiviertem ServiceLayer (typischer Pfad https://<host>:50000/b1s/v1)

• opencode (oder ein beliebiger MCP-Client)

Konfiguration (Umgebungsvariablen)

Verwendung mit opencode

In der opencode.json des Projekts:

{
  "mcp": {
    "sap-b1-servicelayer": {
      "type": "local",
      "command": ["npx", "-y", "github:leonardows1/sap-b1-servicelayer-mcp"],
      "environment": {
        "SAP_B1_SERVER_URL": "https://<host>:50000/b1s/v1",
        "SAP_B1_DATABASE": "<CompanyDB>",
        "SAP_B1_USERNAME": "<usuario>",
        "SAP_B1_PASSWORD": "<password>",
        "SAP_B1_SESSION_TIMEOUT": "30",
        "SAP_B1_VERIFY_TLS": "false",
        "SAP_B1_READONLY": "true"
      },
      "enabled": true
    }
  }
}

opencode nach dem Speichern der Konfiguration neu starten.

Sicherheit

• Anmeldedaten und Sitzungs-Cookies werden nie protokolliert.

• Der Prozess kommuniziert nur mit SAP_B1_SERVER_URL.

• Im Modus READONLY=true werden die Schreib-Tools nicht registriert: Es ist unmöglich, Datensätze zu erstellen/aktualisieren/löschen — by design.

• Konfiguration wird beim Start validiert: Fehlen SAP_B1_SERVER_URL, SAP_B1_DATABASE, SAP_B1_USERNAME oder SAP_B1_PASSWORD → der Prozess bricht mit klarer Meldung ab.

• Entitätsnamen werden validiert (^[A-Za-z][A-Za-z0-9_]*$): Es können keine Pfade injiziert werden (z. B. BusinessPartners/...).

• Schlüsselwerte und Filter werden in OData escaped (einfache Anführungszeichen verdoppelt): Eine id oder ein ItemCode mit ' bricht weder die URL noch den $filter.

• Das Passwort liegt im Klartext in der MCP-Client-Konfiguration. Bei geteiltem Repository einen Secret Manager in Betracht ziehen.

• npx github: hat kein Semver-Versioning: Jede Ausführung nimmt die neueste Version des main-Branches. Nach einem Repo-Update npm cache clean --force verwenden, um das Neuladen zu erzwingen.

Struktur

Pragmatische Hexagonalarchitektur (ESM, ohne Framework): Die Domäne und die Anwendungsfälle kennen weder den MCP-Transport noch HTTP; die Infrastruktur implementiert das Port ServiceLayerPort (DIP) und die MCP-Tools sind dünne Controller.

sap-b1-servicelayer-mcp/
├── package.json                  # Definición del paquete npm (bin: server.js)
├── server.js                     # Composition root: cablea dependencias y arranca stdio
├── src/
│   ├── config/
│   │   └── config.js             # Configuración desde env, validada e inmutable
│   ├── domain/
│   │   ├── errors.js             # Excepciones tipadas (Configuration/InvalidArgument/ServiceLayer)
│   │   ├── oData.js              # Helpers puros: query string, filtros, clamp de $top, validación de entidad
│   │   └── edmx.js               # Parseo puro de $metadata: entity sets, esquemas, function imports
│   ├── application/
│   │   ├── ports.js              # Puerto ServiceLayerPort (contrato, DIP)
│   │   ├── helpers.js            # ensureOk / ensureSuccess / unwrapValue
│   │   └── services/
│   │       ├── queryService.js   # Consulta GET genérica a entidades OData
│   │       ├── catalogService.js # Socios de negocio y artículos (compone QueryService)
│   │       ├── salesService.js   # Pedidos de venta y stock
│   │       ├── sessionService.js # Estado y cierre de sesión
│   │       ├── writeService.js   # create / update / delete
│   │       ├── metadataService.js # Descubrimiento: $metadata cacheado, entidades, esquemas y actions
│   │       └── sqlService.js     # SQL de solo lectura (SELECT/WITH) vía POST /sql_query
│   └── infrastructure/
│       ├── http/
│       │   ├── httpClient.js     # Cliente HTTP mínimo (http/https)
│       │   ├── cookies.js        # Manipulación pura de cookies de sesión
│       │   └── serviceLayerClient.js # Adaptador del puerto: login, 401, logout
│       └── mcp/
│           ├── result.js         # ok / err / serialize / handle (controladores delgados)
│           └── tools.js          # Registro de tools MCP
├── test/                         # node:test (sin dependencias externas)
│   ├── config.test.js
│   ├── oData.test.js
│   ├── edmx.test.js              # parseo EDMX v3/v4 (entity sets, esquemas, function imports)
│   ├── cookies.test.js
│   ├── client.test.js
│   ├── fakePort.js               # fake tipado del puerto ServiceLayerPort (compartido)
│   ├── services.test.js          # casos de uso con cliente fake (anti-inyección)
│   ├── metadataService.test.js   # descubrimiento y acciones con fake
│   ├── sqlService.test.js        # SQL solo-lectura (rechazos, Service Not Found)
│   └── tools.test.js             # integración MCP in-memory (registro y llamadas)
├── .gitignore
└── README.md

Anpassung an das reale Schema (verifiziert gegen ServiceLayer 10.0 v1)

Der Server passt sich dynamisch an das $metadata jeder Instanz an, ohne etwas hartkodiert zu haben. Verifizierte Fakten in einer realen Instanz (v1, OData v3):

• Entity-Sets teilen sich EntityType: Orders/Invoices/DeliveryNotes → SAPB1.Document. sap_get_entity_schema löst den tatsächlichen Typ automatisch auf.

• Belegpositionen: In v1 sind es Complex Collections (DocumentLines, DocumentInstallments), die inline in der Antwort enthalten sind; $expand gilt nur für navigationProperties (das Schema listet sie, z. B.: BusinessPartner, Currency).

• Finanzfelder: In v1 hat BusinessPartners kein Balance; verwende CurrentAccountBalance, OpenOrdersBalance, OpenDeliveryNotesBalance. Rechnungen haben kein BalanceDue: Der offene Saldo ist DocTotal − PaidToDate.

• Kein ItemStock und kein /sql_query in alten v1: sap_get_stock weist mit tatsächlich erkannten Bestandsentitäten darauf hin; sap_sql_query gibt eine klare Fehlermeldung zurück.

• Function Imports v3 mit IsBindable="true" werden als bound gelistet (nicht eigenständig aufrufbar), um sap_list_actions nicht zu verunreinigen.

Rezept: Saldenaltersbericht (30/60/90)

Ohne SQL, nur mit sap_query (funktioniert in jedem v1/v2):

1. Offene Rechnungen (bei vielen mit skip in Stapeln ≤200 paginieren):

   sap_query('Invoices',
     filter='PaidToDate lt DocTotal',
     select='CardCode,CardName,DocNum,DocDate,DocDueDate,DocTotal,PaidToDate,DocumentStatus,ControlAccount')

2. Für jede Rechnung: saldo = DocTotal − PaidToDate; Tage = heute − DocDueDate.

3. Gruppieren nach Bereichen 0-30 / 31-60 / 61-90 / 90+ und nach Kunde (oder nach ControlAccount für die Sicht nach Sachkonto).

4. Summen pro Kunde/Konto: sap_get_business_partners mit CurrentAccountBalance (aktueller Saldo) und CreditLimit.

Mit sap_sql_query (v2) ist derselbe Bericht eine einzige Abfrage über OINV/OINV3/OFRJ/OCRD.

Entwicklung

npm install     # dependencias
npm test        # tests (node:test)
npm run typecheck  # verificación de tipos estricta (tsc --noEmit sobre JSDoc)
npm start       # arranque local (requiere variables de entorno)

Der gesamte JS-Code ist mit striktem TypeScript über JSDoc verifiziert (checkJs + strict + noUncheckedIndexedAccess): tsconfig.json ohne Build-Schritt, der Server läuft direkt mit node.

Manuelle Verifikation (JSON-RPC über stdio)

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
  SAP_B1_SERVER_URL=... SAP_B1_DATABASE=... SAP_B1_USERNAME=... SAP_B1_PASSWORD=... \
  npx -y github:leonardows1/sap-b1-servicelayer-mcp