SAP Business One MCP Server Sample

Wait, I accidentally inserted "The entire final output should be the translation." Need ensure not to include artifacts from earlier "thinking". I need to provide clean final output. Let's produce final accurately with all content, but I need to avoid marginnal errors. Let's rewrite cleanly.

I will now output final translated text only. No extra. But I need to ensure original "Architecture Overview" translated correctly. Let's finalize carefully.

Potential issues: "El servidor MCP se sitúa entre un agente de IA (Cline, GitHub Copilot, Cursor, etc.) y SAP B1 Service Layer." Correct.

"Implementa una arquitectura moderna en capas que transforma los contratos de servicio OData en herramientas MCP adaptadas a la IA. La arquitectura se organiza en torno a un patrón de descubrimiento progresivo que equilibra la eficiencia en el uso de tokens con una exposición global de las capacidades."

Need "token" as token in AI; keep.

"Utilizando este token, los clientes pueden obtener opcionalmente la lista de empresas del SLD para incluir el contexto de la empresa correcta en las solicitudes."

Ah, "using this token" should be "Con este token".

Now final.

Let's check the English source again carefully for any missed heading or paragraph. It includes "Progressive 3-Step Discovery" in TOC only, not body. Fine.

Need perhaps "SAR B1 Service Layer" in first paragraph.

Let's ensure final no code fences.

Let's write the entire final response# SAP Business One MCP Server Sample

• SAP Business One MCP Server Sample

  • Introducción

  • Resumen de la arquitectura

  • Herramientas MCP disponibles

    • Herramientas principales de descubrimiento y ejecución

      • Descubrimiento progresivo en 3 pasos

    • Herramientas de selección de empresa

    • Herramientas auxiliares de flujo de trabajo

    • Recursos MCP

  • Requisitos previos

  • Instalación

  • Configuración

    • Modo directo (solo desarrollo)

    • Modo OAuth (producción, modo predeterminado)

    • HTTPS / Transporte

  • Ejecución del servidor

  • Conexión de un cliente de IA

    • Cline (VS Code)

    • GitHub Copilot (VS Code)

    • Goose (Escritorio)

    • MCP Inspector (Navegador)

  • Integración del cliente MCP

  • Confirmación humana (MCP Elicitation)

  • Clasificación de datos personales

    • Cómo se clasifican los campos

    • Dónde aparece la clasificación

    • Protecciones en tiempo de ejecución

    • Comportamiento de redacción de los resultados de lectura

  • Soporte de UDO/UDT/UDF

    • Nomenclatura de UDO

    • Retraso en el descubrimiento

  • Soporte multiinquilino

  • Ejemplos de uso

    • Consultas en lenguaje natural

    • Ejemplos de flujos de trabajo

      • Flujo de trabajo CRUD básico

      • Flujo de trabajo de pedido a cobro (paso a paso)

    • Consultas de inteligencia de negocio

    • Manipulación de datos

  • Pruebas del servidor

    • Pruebas unitarias

    • Pruebas de integración

    • Control de calidad completo

  • Registro de eventos (Logging)

    • Registros de la aplicación

    • Registros de auditoría

  • Consideraciones de seguridad

    • Autenticación

    • Autorización

    • Configuración de producción

  • Solución de problemas

    • Problemas del servidor o de conexión

    • Autenticación y contexto de empresa

    • Problemas con entidades, campos o escrituras

    • Habilitar opciones de depuración

  • Referencia de configuración

  • Limitación

Introducción

A partir de la versión SAP Business One 10.0 de FP2608, se presenta un ejemplo para SAP Business One MCP Server para demostrar cómo se pueden exponer los servicios OData travésSAP B1 Service Layer comme herramientas dinámicas para agentes de IA que soporta el Model Context Protocol (MCP).

El servidor de ejemplo está diseñado para ser mínimo y fácil de entender, al mismo tiempo que muestra los patrones y las capacidades centrales de un servidor MCP. Estos servidores ofrecen una solución para el registro de cientos de herramientas CRUD individuals (una por entidad × operación), utilizando una arquitectura de descubrimiento progresivo that reduces cientos of possible herramientas into several inteligentes and reusable tools.

Este diseño is obligatory to AI assistants:

• Discover relevantes entidades B1 a trough lightweight semantic search

• Understand complete entidad schemas including properties, types, y capacidades

• Execute operaciones CRUD validaded con generation automática de consultas OData

Las solicitudes en lenguaje natural, zoals "Muéstrame los 10 principales clientes por saldo" o "Create un pedido de compra para el proveedor V00001", se traducen automática en llamadas API dans Service Layer correctas.

Este projecto se provides as sample ref. = Reference y aprendizable only. No necesariamente is a product ready for production. SAP B1 partners y developers recommended to study the architecture, adapt code, evaluate capabilities built-in and build their own MCP server implementations tailored to their specific business needs and deployment.

Version Requirement: This MCP server requires SAP Business One 10.0 FP2608 or higher. It relies on APIs introduced in Service Layer on FP2608, and will not correct with older versions.

Protocol Version MCP: This sample implements MCP protocol 2025-11-25, which is latest version of Model Context Proto spec for SAP B1 10.0 FP2608. MCP clients that connect to this server should also support version 2025-11-25. As the MCP protocol continues to evolve, this sample will be updated to stay up to date with new spec.

Related MCP server: SAP OData MCP Server

Architecture Overview

The MCP server is between an AI agent (Cline, GitHub Copilot, Cursor, etc.) and SAP B1 Service Layer. SAP Business1 MCP Server implements layered architecture that turns OData contracts into tools MCP oriented. The architecture is based on progressive discovery pattern balances tokens and capacities.

In this architecture, the MCP client in agent interacts with MCP server via safe HTTP transport implementing protocol MCP. For authentication, server uses OAuth2.centration with Keycloak. Client MCP or AI agent reports as OAuth client through Extension SSO Manager and obtains a tokens through standard OAuth2 flow. Using these token, clients may opt to obtain company list from the "SLD" and include correct company context. Server validates each request against the token token with Keycloak, checking that only authenticated clients can access the to tools, and verifies audience to ensure belongs to server.

Tools MCP Available

Warning: Tools are used by AI models and they do not represent a stable API. Names, parameters and behavior may change. Do not hard dependence on specific signatures.

Main Discovery and Execution Tools

The server uses 4 main tools of découvrir / execut and not hundreds of individual tools.

Descubrimiento progresivo en 3 pasos

El servidor evita la proliferación de herramientas al condensar todo en un flujo de 3 pasos:

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

• Eficiencia de tokens: el paso 1 devuelve ~90 % menos de datos que los esquemas completos

• Separación clara: el LLM puede escanear y seleccionar antes de comprometerse a recuperar un esquema completo

• Detalle progresivo: se puede profundizar en los tipos complejos mediante una llamada del paso 2.2 sin recuperarlo todo de antemano

Herramientas de selección de empresa

En el modo OAuth, seleccione una empresa antes de llamar a las herramientas de entidades:

Herramientas auxiliares de flujo de trabajo

Dos herramientas auxiliares de flujo de trabajo simplifican los flujos de trabajo comerciales habituales en B1:

Descubrimiento de herramientas de flujo de trabajo en tiempo de ejecución:

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

El agente de IA llama a b1_find_entities con category: 'workflow' y recibe las descripciones completas de b1_copy_document y b1_create_payment.

Recursos MCP

Dos tipos de recursos proporcionan conocimiento contextual sin llamadas a herramientas.

Ventajas: los asistentes de IA pueden acceder a estos recursos al instante sin llamadas a herramientas: ¡más eficiente para los flujos de trabajo!

Requisitos previos

Instalación

1. Descargue este paquete b1-mcp-server.zip de la ayuda en línea, descomprímalo y navegue hasta la carpeta del proyecto descomprimido.

2. Instale las dependencias y compile:

npm install
npm run build

Configuración

Todos los ajustes se controlan mediante un archivo .env en la raíz del proyecto. Copie .env.example como punto de partida:

cp .env.example .env

Para obtener una referencia completa de todas las variables disponibles, consulte el capítulo Referencia de configuración.

Modo directo (solo desarrollo)

Utilice este modo cuando la SAP B1 Service Layer sea accesible con un nombre de usuario y una contraseña. Adecuado únicamente para prototipos rápidos en el entorno de desarrollo local y para pruebas.

Nota: A pesar de usar un nombre de usuario y una contraseña en el archivo .env, esto no es autenticación básica HTTP. Las credenciales las utiliza el servidor MCP para obtener un token de sesión de la SAP B1 Service Layer a través de su API de inicio de sesión (/b1s/v2/Login), y todas las solicitudes posteriores se autentican con ese token de sesión.

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

Modo OAuth (producción, modo predeterminado)

Utilice este modo predeterminado, ya que la Service Layer siempre está protegida por Keycloak. Los tokens de portador entrantes se validan contra el proveedor OAuth antes de reenviar cualquier solicitud B1.

# 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 / transporte

El servidor usa HTTPS de forma predeterminada y utiliza un certificado autofirmado para el desarrollo local. También puede cambiar a HTTP si lo prefiere.

HTTPS (predeterminado):

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:

Si desea HTTP en lugar de HTTPS por pruebas locales, para evitar problemas de advertencias de seguridad del navegador u otras razones (p. ej., ya dispone de una puerta de enlace HTTPS o un proxy inverso frontal), establezca:

HTTPS_ENABLED=false
PORT=3000

URL pública anunciada (MCP_BASE_URL):

De forma predeterminada, el servidor deriva su URL anunciada de la configuración del listener activo. Si el servidor está detrás de un proxy inverso o necesita que los clientes usen una URL base específica para los metadatos OAuth y los endpoints MCP, establézcala explícitamente:

MCP_BASE_URL=https://mcp.example.com

Déjela sin establecer para el desarrollo local: el servidor inferirá la URL correcta automáticamente.

Ejecución del servidor

Inicie el servidor:

npm start

Verifique que se está ejecutando:

curl http://localhost:3000/health

El servidor expone tres endpoints REST integrados:

Nota de OAuth: En modo OAuth, GET /mcp requiere un token de portador válido en el encabezado Authorization.

GET /health — respuesta de ejemplo:

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

GET /mcp — respuesta de ejemplo:

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

Conexión de un cliente de IA

El servidor expone un endpoint MCP Streamable HTTP en:

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

Cualquier cliente de IA compatible con MCP puede conectarse a este endpoint. La tabla siguiente resume las capacidades clave de los clientes compatibles:

La elicitación MCP se utiliza para la confirmación humana de operaciones de escritura y lecturas sensibles. Si su cliente no la admite, establezca MCP_HUMAN_CONFIRMATION_ENABLED=false en .env o esas operaciones se rechazarán. Consulte Confirmación humana (elicitación MCP) para obtener más detalles.

Cline (VS Code)

Para obtener instrucciones de configuración, configuración del proveedor de LLM, configuración de OAuth / Keycloak y ejemplos de prueba que cubren todas las operaciones CRUD y las herramientas de flujo de trabajo, consulte docs/B1_CLINE_INTEGRATION_GUIDE.md.

GitHub Copilot (VS Code)

Para obtener instrucciones de configuración, configuración de OAuth / Keycloak, configuración del ID de cliente estático, flujo de selección de empresa OAuth y ejemplos de prueba de elicitación, consulte docs/B1_GITHUB_COPILOT_INTEGRATION_GUIDE.md.

Goose (Desktop)

Para obtener instrucciones de configuración, opciones de configuración, configuración de OAuth / Keycloak y ejemplos de uso, consulte docs/B1_GOOSE_INTEGRATION_GUIDE.md.

MCP Inspector (navegador)

Utilice el MCP Inspector para explorar herramientas de forma interactiva e inspeccionar mensajes MCP sin procesar. Para obtener instrucciones de uso completas (incluido cómo obtener un token de portador y establecer los encabezados necesarios en modo OAuth), consulte docs/MCP_INSPECTOR.md.

Integración de cliente MCP

Si está creando una aplicación cliente MCP personalizada que se conecta al servidor en modo OAuth, la integración sigue un flujo estándar PKCE OAuth 2.0:

1. Descubra los metadatos OAuth desde GET /mcp (el servidor anuncia sus endpoints de autorización y token).

2. Inicie una solicitud de autorización PKCE y redirija al usuario a Keycloak.

3. Intercambie el código de autorización por tokens (token de acceso + token de actualización).

4. Obtenga las empresas disponibles mediante b1_list_companies.

5. Permita que el usuario seleccione una empresa y llame a b1_select_company.

6. Incluya el token de acceso y el ID de empresa en cada solicitud MCP:

   • Authorization: Bearer <access_token>

   • x-b1-companyID: <companySchemaName>

7. Actualice el token antes de que expire; reinicie el flujo PKCE si falla la actualización.

Para ver un ejemplo funcional completo con código anotado (incluidos el registro del cliente, el flujo OAuth, la selección de empresa y la salida esperada), consulte docs/SIMPLE_MCP_CLIENT.md.

Confirmación humana (elicitación MCP)

La elicitación MCP es un mecanismo a nivel de protocolo que permite a un servidor MCP pausar una llamada de herramienta a mitad de ejecución y solicitar al cliente conectado información adicional o confirmación antes de continuar. A diferencia de una simple indicación, la elicitación está integrada en el protocolo MCP: el servidor envía una solicitud estructurada al cliente, el cliente la presenta al usuario (normalmente como un diálogo o formulario en línea) y el servidor espera la respuesta antes de decidir si continúa o aborta. Esto mantiene al humano en el circuito para operaciones sensibles sin requerir que el agente de IA improvise su propio flujo de confirmación.

Cuando MCP_HUMAN_CONFIRMATION_ENABLED=true (el valor predeterminado), el servidor se pausa antes de:

• Operaciones de escritura (create, update, delete): solicita la aprobación explícita del usuario

• Lecturas sensibles: solicita confirmación cuando la consulta selecciona campos clasificados como datos personales (correo electrónico, teléfono, números de identidad)

Los clientes que admiten la elicitación (como GitHub Copilot) muestran un diálogo de confirmación en línea. El usuario debe aprobar antes de que el servidor continúe; rechazar cancela la operación sin modificar ningún dato.

Ejemplo de solicitud de confirmación de escritura:

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.

Clientes sin soporte de elicitación (p. ej., Cline v4.0.8):

El servidor rechazará las lecturas sensibles y las operaciones de escritura en lugar de continuar sin confirmación. Para omitir esto en canalizaciones automatizadas o de desarrollo, establezca:

MCP_HUMAN_CONFIRMATION_ENABLED=false

Clasificación de datos personales

El servidor utiliza los metadatos PersonalFieldsSetups de SAP Business One (resueltos por tabla mediante PersonalFieldsSetupsService_GetPersonalFieldsByTable) para clasificar los campos sensibles y aplicar salvaguardas durante las lecturas y escrituras.

Cómo se clasifican los campos

• Fuente de clasificación: entradas de campos personales con ámbito de tabla de la Service Layer devueltas por PersonalFieldsSetupsService_GetPersonalFieldsByTable.

• Regla de coincidencia: una propiedad se marca como personal cuando el nombre de la tabla + el nombre del campo coinciden con una fila de PersonalFieldsSetups.

• Alcance: la clasificación se aplica tanto a las propiedades de entidad de nivel superior como a las propiedades de tipo complejo anidadas.

• Resolución anidada: para propiedades complejas, el contexto de la tabla cambia mediante la asignación de tablas secundarias y continúa de forma recursiva para anidamientos más profundos.

Dónde aparece la clasificación

• En la salida del esquema del paso 2 mediante b1_get_entity_schema, las propiedades personales se marcan con isPersonalField.

• Esto incluye campos escalares y propiedades de tipo estructural anidadas cuando la asignación de tablas las marca como personales.

Protecciones en tiempo de ejecución

Cuando MCP_HUMAN_CONFIRMATION_ENABLED=true:

• Las operaciones de escritura (create, update, delete) requieren confirmación explícita de elicitación MCP.

• Las lecturas sensibles requieren confirmación cuando selectString incluye explícitamente campos personales de nivel superior.

Si el cliente no admite la elicitación MCP, estas operaciones protegidas se bloquean.

Comportamiento de redacción en los resultados de lectura

La redacción de lecturas depende de si selectString es significativo:

• Sin selectString (o en blanco/solo espacios): se aplica redacción de respuesta completa de forma recursiva a los campos personales tanto en los datos complejos de nivel superior como anidados.

• selectString significativo con solo selecciones escalares: los campos escalares seleccionados se devuelven según lo solicitado.

• selectString significativo que incluye propiedades complejas: los campos escalares seleccionados permanecen visibles y los campos personales dentro de las propiedades complejas seleccionadas se redactan de forma recursiva.

Esto significa que un campo personal escalar de nivel superior seleccionado puede ser visible después de la confirmación del usuario, mientras que los campos personales anidados dentro de las propiedades complejas seleccionadas siguen redactados.

Para obtener más detalles sobre la configuración de datos personales, consulte este enlace: Portal de ayuda de SAP Business One: protección de datos personales.

Soporte de UDO/UDT/UDF

El servidor descubre y expone automáticamente objetos definidos por el usuario (UDO), tablas definidas por el usuario (UDT) y campos definidos por el usuario (UDF) junto con las entidades estándar de SAP B1; no se requiere configuración adicional.

• Los UDO registrados en SAP B1 aparecen como entidades consultables y escribibles en b1_find_entities, localizables en su categoría empresarial asignada.

• Las UDT (tablas personalizadas con prefijo @) se presentan como entidades de primera clase y admiten las mismas operaciones CRUD que las entidades estándar.

• Los UDF añadidos a tablas estándar o personalizadas se incluyen automáticamente en el esquema devuelto por b1_get_entity_schema, con los tipos y metadatos correctos.

Esto significa que cualquier personalización realizada en SAP B1 (extensiones de socios, complementos de localización o campos específicos del cliente) está inmediatamente disponible para los agentes de IA a través del mismo flujo de descubrimiento de 3 pasos, sin necesidad de cambios en el servidor.

Nomenclatura de UDO

Los códigos UDO deben cumplir con las reglas de identificadores de OData para ser reconocidos por Service Layer. Use solo letras, dígitos y guiones bajos, sin espacios ni otros caracteres especiales (por ejemplo, use MY_CUSTOM_OBJECT, no My Custom Object). Los UDO con códigos no conformes no serán detectables.

Retraso en el descubrimiento

Los UDO y UDT agregados o modificados a través del cliente SAP B1, el cliente web o los complementos no se reflejan en el servidor MCP de inmediato. El servidor almacena en caché los metadatos de OData obtenidos de Service Layer durante un período configurable (predeterminado: 30 minutos, controlado por METADATA_CACHE_TTL_MINUTES). Los UDO/UDT nuevos o modificados solo serán detectables después de que la caché expire naturalmente, o cuando se reinicie el servidor MCP. Durante el desarrollo activo de objetos personalizados, reduzca METADATA_CACHE_TTL_MINUTES a un valor más pequeño (por ejemplo, 5) para detectar los cambios más rápido.

Soporte Multiinquilino

Una única instancia del servidor MCP puede atender a múltiples empresas de SAP Business One sin ningún cambio de configuración. En modo OAuth, el inquilino o empresa activo se selecciona dinámicamente en tiempo de ejecución utilizando el System Landscape Directory (SLD).

Cómo funciona:

1. El cliente MCP llama a b1_list_companies para recuperar todas las empresas disponibles registradas en el SLD, junto con su estado.

2. El usuario (o el agente de IA, guiado por el usuario) selecciona la empresa objetivo llamando a b1_select_company con el CompanySchemaName elegido.

3. Todas las llamadas de herramientas posteriores (b1_find_entities, b1_read, b1_write, etc.) se enrutan a la base de datos de Service Layer de la empresa seleccionada durante la duración de la sesión.

4. Para cambiar de empresa, llame a b1_select_company nuevamente con un nombre de esquema diferente; no se requiere reiniciar el servidor.

Características clave:

• Ámbito de sesión: La selección de empresa está vinculada a la sesión MCP. Diferentes sesiones de clientes de IA pueden operar contra diferentes empresas simultáneamente en la misma instancia del servidor.

• Impulsado por SLD: La lista de empresas se obtiene directamente del SLD y refleja el estado en vivo de las empresas registradas. No es necesario mantener una lista estática de empresas en la configuración.

• Solo OAuth: El cambio de empresa multiinquilino requiere el modo OAuth. El modo directo es de una sola empresa (B1_COMPANY_DB está fijo en .env).

Nota: Si ya hay un encabezado x-b1-companyID válido presente en la solicitud, el servidor MCP lo usa directamente; no es necesario llamar a b1_list_companies y b1_select_company. El propósito de esas herramientas es simplemente ayudar al agente de IA o al usuario a determinar el nombre de esquema de empresa correcto y establecer el contexto de la empresa cuando aún no se conoce. Una vez que se conoce la empresa deseada, su ID de empresa (resuelto desde el CompanySchemaName) se puede pasar directamente en el encabezado x-b1-companyID de cada solicitud MCP posterior.

Ejemplos de Uso

Consultas en Lenguaje Natural

Ejemplos de Flujos de Trabajo

Para implementar flujos de trabajo comerciales adicionales o agregar nuevas herramientas MCP, consulte docs/DEVELOPER_GUIDE.md.

Flujo de Trabajo CRUD Básico

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

Flujo de Trabajo de Pedido a Cobro (Paso a Paso)

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)

Consultas de Inteligencia de Negocios

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

Manipulación de Datos

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

Pruebas del Servidor

Pruebas Unitarias

npm test

Este es un alias para npm run test:unit. Las pruebas unitarias se encuentran en src/tests/unit/.

Pruebas de Integración

Las pruebas de integración requieren un servidor MCP en ejecución con un Service Layer y un proveedor OAuth accesibles. También requieren que el alcance b1_mcp:access esté configurado en Keycloak; consulte KEYCLOAK_SETUP.md para obtener instrucciones de configuración. Configure las credenciales del cliente de prueba en su .env y luego ejecute:

npm run test:integration

Variables clave para las pruebas de integración:

Las pruebas de integración se encuentran en src/tests/integration/.

Nota: Si una prueba falla después de actualizar las dependencias, ejecute npm run build primero; los errores de tiempo de compilación a menudo aparecen allí antes que en el ejecutor de pruebas.

Verificación de Calidad Completa

Ejecute lint, build y pruebas unitarias en secuencia:

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

Registro de Actividades

El servidor produce dos flujos de registro separados, cada uno configurable de forma independiente.

Registros de Aplicación

Los registros de aplicación cubren el manejo de solicitudes, el despacho de herramientas, el ciclo de vida de la sesión y las llamadas a Service Layer. El nivel predeterminado es info. Habilite el registro detallado durante el desarrollo para rastrear lo que está haciendo el servidor:

APP_LOG_LEVEL=debug
APP_LOG_CONSOLE_ENABLED=true

Los registros se escriben en un archivo rotativo por defecto (APP_LOG_FILE_ENABLED=true). El tamaño del archivo y la retención están controlados por APP_LOG_MAX_SIZE_BYTES (predeterminado 10 MB) y APP_LOG_RETENTION_DAYS (predeterminado 90 días).

Registros de Auditoría

Los registros de auditoría registran eventos relevantes para la seguridad: confirmaciones de escritura, inicio y expiración de sesiones, y fallos de autenticación. Se escriben en un archivo rotativo por defecto y deben permanecer habilitados en producción.

Para también transmitir eventos de auditoría a la consola durante el desarrollo:

AUDIT_LOG_CONSOLE_ENABLED=true

El tamaño del archivo y la retención están controlados por AUDIT_LOG_MAX_SIZE_BYTES (predeterminado 10 MB) y AUDIT_LOG_RETENTION_DAYS (predeterminado 365 días).

Para la lista completa de variables de registro, consulte docs/CONFIGURATION_REFERENCE.md.

Para la configuración paso a paso de Keycloak requerida para el modo OAuth, incluido el registro del cliente del servidor MCP, el alcance del cliente, el mapeador de audiencia y los hosts de confianza, consulte docs/KEYCLOAK_SETUP.md.

Consideraciones de Seguridad

Nota: Este proyecto es una muestra. Antes de implementarlo en un entorno de producción, revise y refuerce todas las configuraciones de seguridad de acuerdo con los estándares de seguridad y los requisitos de cumplimiento de su organización.

Autenticación

Este servidor MCP actúa como un Servidor de Recursos (RS) en el marco OAuth 2.0 y utiliza el mecanismo de autenticación MCP estándar. Cada solicitud de un agente de IA debe llevar un token de acceso de portador válido; el servidor valida el token antes de procesar cualquier solicitud.

Los tokens de acceso se obtienen del servicio de Identity and Authentication Management de SAP Business One proporcionando credenciales de usuario válidas. Este servicio se basa en Keycloak y se puede configurar para conectarse a SAP IAS (Identity Authentication Service) u otros proveedores de identidad para la autenticación de usuarios.

Autorización

La autorización se aplica en dos capas:

Capa 1 — Servidor MCP: verifica las reclamaciones scope y aud (audiencia) del token de acceso para determinar si el agente de IA tiene permitido invocar las herramientas MCP solicitadas. Solo se aceptan tokens que lleven el alcance requerido b1_mcp:access y estén dirigidos a este servidor.

Capa 2 — SAP B1 Service Layer: delega la decisión de acceso a datos a Service Layer, que evalúa los roles y permisos de usuario asociados con el token contra el modelo de control de acceso estándar de SAP Business One. Los administradores pueden definir políticas de acceso detalladas por usuario y grupo. Si Service Layer devuelve HTTP 403 (Prohibido), el servidor MCP muestra un error al agente de IA indicando privilegios insuficientes y no devuelve ningún dato.

Configuración de Producción

Revise estas configuraciones antes de cualquier implementación en producción.

Transporte

• HTTPS_ENABLED — predeterminado a true. Use siempre HTTPS en producción. Solo deshabilite detrás de un proxy inverso que termine TLS.

• AUTH_ALLOW_SELF_SIGNED — predeterminado a false. Nunca habilite en producción; use una CA válida o NODE_EXTRA_CA_CERTS.

Validación de tokens

• TOKEN_VALIDATION_MODE — use introspection o introspection-with-jwt-fallback (predeterminado) en producción. Evite el modo solo jwt a menos que los tokens tengan una vida corta (< 5 min), ya que los tokens revocados permanecen válidos hasta su expiración.

• VALIDATE_AUDIENCE — predeterminado a true. Deshabilitarlo permite que tokens emitidos para otros servicios se autentiquen; solo deshabilite si su proveedor OAuth no puede restringir la reclamación aud.

• OAUTH_VERIFY_SCOPES / OAUTH_REQUIRED_SCOPES — mantenga la verificación de alcances habilitada y restringida al alcance mínimo requerido (b1_mcp:access).

Red y control de acceso

• MCP_ALLOWED_HOSTS — liste todos los nombres de host a través de los cuales el servidor es accesible. Las solicitudes con un encabezado Host que no coincida se rechazan (protección contra rebinding de DNS).

• REQUEST_BODY_LIMIT — mantenga pequeño (predeterminado 1mb) para limitar la memoria y reducir el riesgo de DoS.

• CORS_ALLOWED_ORIGINS — déjelo sin establecer (CORS deshabilitado) a menos que los clientes basados en navegador lo requieran. Evite * en producción.

• MCP_RATE_LIMIT_WINDOW_MINUTES / MCP_RATE_LIMIT_MAX — ajuste para que coincida con el rendimiento esperado del cliente.

Seguridad de sesión y escritura

• SESSION_TIMEOUT_MINUTES — las sesiones inactivas se expiran y se auditan. Mantenga corto en producción (predeterminado: 30 min).

• MCP_HUMAN_CONFIRMATION_ENABLED — predeterminado a true. Requiera confirmación del usuario antes de cualquier escritura. Solo deshabilite en pipelines totalmente automatizados y no interactivos.

Registro de auditoría

• AUDIT_LOG_FILE_ENABLED — predeterminado a true. Los registros de auditoría registran todas las confirmaciones de escritura y eventos de sesión. Mantenga habilitado en producción y establezca AUDIT_LOG_RETENTION_DAYS para cumplir con sus requisitos de cumplimiento.

Solución de Problemas

Problemas de servidor o conexión

• Verifique Node.js >= 22.22.3 (node --version) y que npm run build se complete sin errores.

• Compruebe que SERVICE_LAYER_ROOT_URL sea solo el host, sin la ruta /b1s/v2/ (por ejemplo, https://servicelayer.b1.example.com:50000).

• Confirme que el servidor esté en ejecución: curl http://localhost:3000/health.

• Verifique que la URL del punto final MCP en la configuración del cliente coincida con la dirección del servidor y reinicie VS Code si las herramientas no aparecen.

Autenticación y contexto de empresa

• Modo directo: verifique B1_COMPANY_DB, B1_USERNAME y B1_PASSWORD.

• Modo OAuth: verifique OAUTH_BASE_URL, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET y SLD_ROOT_URL. Si Service Layer usa un certificado autofirmado, establezca AUTH_ALLOW_SELF_SIGNED=true (solo desarrollo).

• Compruebe los hosts de confianza de Keycloak si los clientes de VS Code fallan con Failed to verify remote host — consulte docs/KEYCLOAK_SETUP.md.

• En modo OAuth, siempre llame a b1_list_companies y luego a b1_select_company antes de cualquier llamada de herramienta de entidad. Sin una empresa seleccionada, las herramientas no devolverán datos de SAP B1.

Problemas de entidad, campo o escritura

• Utilice b1_find_entities para confirmar el nombre correcto de la entidad (distingue entre mayúsculas y minúsculas) y b1_get_entity_schema para verificar los nombres de las propiedades antes de construir las cadenas de filtro o selección.

• Si se rechazan las operaciones de escritura y MCP_HUMAN_CONFIRMATION_ENABLED=true, el cliente debe admitir MCP Elicitation. Utilice GitHub Copilot o establezca MCP_HUMAN_CONFIRMATION_ENABLED=false para pipelines automatizados.

Habilitar opciones de depuración

Habilite el registro detallado para rastrear el manejo de solicitudes y las llamadas al Service Layer:

APP_LOG_LEVEL=debug
APP_LOG_CONSOLE_ENABLED=true
AUDIT_LOG_CONSOLE_ENABLED=true

Referencia de configuración

Para ver la lista completa de variables de entorno agrupadas por categoría (autenticación, HTTPS, OAuth, sesión, caché, registro), consulte docs/CONFIGURATION_REFERENCE.md.

Limitación

• El transporte stdio no es compatible. Solo se admite HTTP de streaming.

• Las acciones/funciones de OData no son compatibles en la muestra actual del servidor MCP. Solo están disponibles las operaciones CRUD estándar sobre las entidades.

• La carga/descarga de archivos adjuntos e imágenes no es compatible en la muestra actual del servidor MCP.

• Las operaciones por lotes de OData no son compatibles en la muestra actual del servidor MCP. Cada operación con una entidad debe realizarse individualmente.

• Las consultas avanzadas de OData no son totalmente compatibles. Solo se implementan las básicas $filter, $select, $top y $orderby en las herramientas MCP.