SAP B1 ServiceLayer MCP Server

Servidor MCP (Model Context Protocol) para conectar asistentes de IA (opencode, Claude, etc.) al ServiceLayer de SAP Business One 10.0, en red local. Ejecutable con npx desde este repositorio de GitHub, sin instalar nada en el PC.

Características

• Solo lectura por defecto: con SAP_B1_READONLY=true (default) solo se registran tools de consulta (GET). Los tools de escritura (POST/PATCH/DELETE) no existen en el servidor y no pueden llamarse.

• Descubrimiento total: sap_list_entities, sap_get_entity_schema y sap_list_actions consultan GET /$metadata (descargado una sola vez por proceso y cacheado) y exponen las ~140 entidades CRUD (incluidas tablas de usuario @ y UDOs) y los cientos de métodos de servicio del ServiceLayer.

• Modo escritura opcional: con SAP_B1_READONLY=false se habilitan sap_create, sap_update, sap_delete para entidades del ServiceLayer y sap_call_action para métodos de servicio (pueden tener efectos colaterales).

• Ejecución vía npx github:: sin instalación manual.

• Sesión gestionada: login implícito con CompanyDB/usuario/contraseña, cookies B1SESSION + ROUTEID mantenidas en memoria (soporta ServiceLayer multi-nodo), re-login automático ante 401 y logout garantizado al cerrarse el proceso (además del tool sap_logout).

• TLS autofirmado: soporte para certificados autofirmados del ServiceLayer (típico en entornos locales) mediante SAP_B1_VERIFY_TLS=false.

• Sin telemetría ni llamadas externas: el cliente HTTP apunta exclusivamente a la URL configurada (SAP_B1_SERVER_URL).

• Límites de seguridad: top acotado a 200 registros por consulta.

Related MCP server: BTP MCP Server

Tools

Lectura (siempre disponibles)

Escritura (solo si SAP_B1_READONLY=false)

Requisitos

• Node.js 18+

• SAP Business One 10.0 con ServiceLayer habilitado (ruta típica https://<host>:50000/b1s/v1)

• opencode (o cualquier cliente MCP)

Configuración (variables de entorno)

Uso con opencode

En opencode.json del proyecto:

{
  "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
    }
  }
}

Reiniciar opencode después de guardar la configuración.

Seguridad

• Credenciales y cookies de sesión nunca se registran en logs.

• El proceso solo se comunica con SAP_B1_SERVER_URL.

• En modo READONLY=true los tools de escritura no se registran: es imposible crear/actualizar/eliminar registros, por diseño.

• Configuración validada al arrancar: faltan SAP_B1_SERVER_URL, SAP_B1_DATABASE, SAP_B1_USERNAME o SAP_B1_PASSWORD → el proceso aborta con mensaje claro.

• Nombres de entidad validados (^[A-Za-z][A-Za-z0-9_]*$): no se pueden inyectar rutas (ej: BusinessPartners/...).

• Valores de clave y filtros escapados en OData (comillas simples duplicadas): un id o ItemCode con ' no rompe la URL ni el $filter.

• La contraseña queda en texto plano en la configuración del cliente MCP. Considerar un secret manager si se comparte el repositorio.

• npx github: no tiene versionado semver: cada ejecución toma la última versión del branch main. Tras actualizar el repo, usar npm cache clean --force para forzar la recarga.

Estructura

Arquitectura hexagonal pragmática (ESM, sin framework): el dominio y los casos de uso no conocen el transporte MCP ni el HTTP; la infraestructura implementa el puerto ServiceLayerPort (DIP) y los tools MCP son controladores delgados.

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

Adaptación al esquema real (verificado contra ServiceLayer 10.0 v1)

El servidor se adapta dinámicamente al $metadata de cada instancia, sin nada hardcodeado. Hechos verificados en una instancia real (v1, OData v3):

• Entity sets comparten EntityType: Orders/Invoices/DeliveryNotes → SAPB1.Document. sap_get_entity_schema resuelve el tipo real automáticamente.

• Líneas de documento: en v1 son complex collections (DocumentLines, DocumentInstallments) que vienen inline en la respuesta; $expand solo aplica a navigationProperties (el esquema las lista, ej: BusinessPartner, Currency).

• Campos financieros: en v1 BusinessPartners no tiene Balance; usa CurrentAccountBalance, OpenOrdersBalance, OpenDeliveryNotesBalance. Las facturas no tienen BalanceDue: el saldo abierto es DocTotal − PaidToDate.

• Sin ItemStock ni /sql_query en v1 antiguos: sap_get_stock avisa con entidades de stock reales descubiertas; sap_sql_query devuelve error claro.

• Function imports v3 con IsBindable="true" se listan como bound (no invocables standalone) para no contaminar sap_list_actions.

Receta: reporte de antigüedad de saldos (30/60/90)

Sin SQL, solo con sap_query (funciona en cualquier v1/v2):

1. Facturas abiertas (paginar con skip en lotes ≤200 si hay muchas):

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

2. Por cada factura: saldo = DocTotal − PaidToDate; días = hoy − DocDueDate.

3. Agrupar por rangos 0-30 / 31-60 / 61-90 / 90+ y por cliente (o por ControlAccount para la vista por cuenta contable).

4. Totales por cliente/cuenta: sap_get_business_partners con CurrentAccountBalance (saldo actual) y CreditLimit.

Con sap_sql_query (v2) el mismo reporte es una sola query sobre OINV/OINV3/OFRJ/OCRD.

Desarrollo

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)

Todo el código JS está verificado con TypeScript estricto vía JSDoc (checkJs + strict + noUncheckedIndexedAccess): tsconfig.json sin build step, el servidor se ejecuta directo con node.

Verificación manual (JSON-RPC por 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