SAP OData MCP Server

Un servidor MCP para integrarse con servicios SAP OData, configurado mediante variables de entorno.

GitHub
12
Prueba este MCPPatrocinado

Documentación

SAP OData MCP Server

Un servidor de Model Context Protocol (MCP) para integrar sistemas SAP con asistentes de IA como Claude mediante APIs REST de OData. Este servidor proporciona herramientas para conectarse a servicios OData de SAP, consultar conjuntos de entidades, ejecutar operaciones CRUD y llamar funciones OData.

Características

  • Conectividad SAP OData: Conéctese a sistemas SAP mediante APIs REST de OData
  • Manejo inteligente de conexiones: Gestiona correctamente las estructuras de URL de SAP OData y las respuestas 404
  • Descubrimiento de servicios: Descubra automáticamente los servicios OData disponibles mediante el catálogo o pruebas de servicios comunes
  • Consultas de conjuntos de entidades: Consulte cualquier conjunto de entidades OData con filtrado, ordenación y paginación
  • Operaciones CRUD: Operaciones de Crear, Leer, Actualizar y Eliminar en entidades OData
  • Importaciones de funciones: Ejecute importaciones de funciones OData y funciones personalizadas
  • Manejo de tokens CSRF: Gestión automática de tokens CSRF para operaciones seguras
  • Arquitectura modular: Código TypeScript limpio y mantenible con separación de responsabilidades

Requisitos previos

  • Node.js 18+
  • Sistema SAP con servicios OData habilitados
  • Acceso de red a los endpoints OData de SAP
  • Credenciales de usuario SAP con las autorizaciones adecuadas

⚠️ Ventaja: ¡No se requiere instalación del SDK RFC de SAP! Utiliza APIs HTTP/REST estándar.

Instalación

Configuración rápida

  1. Cree el proyecto:
mkdir sap-odata-mcp-server
cd sap-odata-mcp-server
mkdir src

  1. Copie los archivos fuente de los artefactos a su directorio src/:

    • src/index.ts - Punto de entrada
    • src/server.ts - Configuración del servidor MCP
    • src/handlers.ts - Manejadores de solicitudes
    • src/odata-client.ts - Cliente SAP OData
    • src/tool-definitions.ts - Definiciones de herramientas
    • src/types.ts - Tipos de TypeScript

  2. Copie los archivos de configuración:

    • package.json - Dependencias y scripts
    • tsconfig.json - Configuración de TypeScript
    • .env.example - Plantilla de variables de entorno

  3. Instale las dependencias:

npm install
  1. Configure el entorno:
cp .env.example .env
# Edit .env with your SAP details
  1. Compile el proyecto:
npm run build

Configuración

Variables de entorno

Cree un archivo .env con los detalles de su sistema SAP:

# Required SAP OData Configuration
SAP_ODATA_BASE_URL=https://your-sap-host:8000/sap/opu/odata/sap/
SAP_USERNAME=your-sap-username
SAP_PASSWORD=your-sap-password

# Optional Configuration
SAP_CLIENT=100
SAP_TIMEOUT=30000
SAP_VALIDATE_SSL=false  # for development with self-signed certificates
SAP_ENABLE_CSRF=true

Integración con Claude Desktop

Agregue a su archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sap-odata": {
      "command": "node",
      "args": ["/full/path/to/your/sap-odata-mcp-server/dist/index.js"],
      "env": {
        "SAP_ODATA_BASE_URL": "https://your-sap-host:8000/sap/opu/odata/sap/",
        "SAP_USERNAME": "your-username",
        "SAP_PASSWORD": "your-password",
        "SAP_CLIENT": "100",
        "SAP_VALIDATE_SSL": "false"
      }
    }
  }
}

Herramientas disponibles

1. sap_connect

Conéctese al servicio OData de SAP.

Parámetros:

  • baseUrl (obligatorio): URL base del servicio OData de SAP
  • username (obligatorio): Nombre de usuario de SAP
  • password (obligatorio): Contraseña de SAP
  • client (opcional): Número de cliente de SAP
  • timeout (opcional): Tiempo de espera de la solicitud en milisegundos (predeterminado: 30000)
  • validateSSL (opcional): Validar certificados SSL (predeterminado: true)
  • enableCSRF (opcional): Habilitar manejo de tokens CSRF (predeterminado: true)

2. sap_get_services

Obtenga la lista de servicios OData disponibles con descubrimiento inteligente.

3. sap_get_service_metadata

Obtenga los metadatos de un servicio OData específico.

Parámetros:

  • serviceName (obligatorio): Nombre del servicio OData

4. sap_query_entity_set

Consulte un conjunto de entidades OData con filtrado, ordenación y paginación.

Parámetros:

  • serviceName (obligatorio): Nombre del servicio OData
  • entitySet (obligatorio): Nombre del conjunto de entidades
  • select (opcional): Matriz de campos a seleccionar
  • filter (opcional): Expresión de filtro OData
  • orderby (opcional): Expresión de ordenación OData
  • top (opcional): Número de registros a devolver
  • skip (opcional): Número de registros a omitir
  • expand (opcional): Propiedades de navegación a expandir

5. sap_get_entity

Obtenga una entidad específica por sus valores de clave.

Parámetros:

  • serviceName (obligatorio): Nombre del servicio OData
  • entitySet (obligatorio): Nombre del conjunto de entidades
  • keyValues (obligatorio): Objeto con pares clave-valor para las claves de la entidad

6. sap_create_entity

Cree una nueva entidad en un conjunto de entidades.

7. sap_update_entity

Actualice una entidad existente.

8. sap_delete_entity

Elimine una entidad.

9. sap_call_function

Llame a una importación de función OData.

10. sap_connection_status

Verifique el estado actual de la conexión OData de SAP.

11. sap_disconnect

Desconéctese del servicio OData de SAP.

Ejemplos de uso

Primeros pasos con Claude

Una vez configurado, puede interactuar con SAP usando lenguaje natural en Claude:

Conectarse a SAP:

Connect to SAP OData service at https://sap-host:8000/sap/opu/odata/sap/ using username DEVELOPER and password mypassword

Descubrir servicios disponibles:

Get list of available OData services

Obtener información del servicio:

Get metadata for service GWSAMPLE_BASIC

Consultar datos:

Query BusinessPartnerSet from GWSAMPLE_BASIC, select BusinessPartnerID and CompanyName, top 10

Filtrado avanzado:

Query SalesOrderSet from ZSD_SALES_SRV, filter by CreationDate ge datetime'2024-01-01T00:00:00', order by CreationDate desc, top 20

Obtener registros específicos:

Get entity from MaterialSet in ZMM_MATERIAL_SRV with key Material = '000000000000000001'

Crear nuevos registros:

Create entity in CustomerSet with data: {"CustomerNumber": "1000", "CustomerName": "Test Customer", "Country": "US"}

Ejemplos de consultas OData

Filtrado:

$filter=MaterialType eq 'FERT' and CreationDate ge datetime'2024-01-01T00:00:00'

Selección de campos:

$select=Material,MaterialDescription,MaterialType,BaseUnit

Ordenación:

$orderby=CreationDate desc,Material asc

Paginación:

$top=50&$skip=100

Expansión de propiedades de navegación:

$expand=MaterialPlantData,MaterialSalesData

Requisitos del sistema SAP

Componentes SAP requeridos

  • SAP NetWeaver 7.0 o superior
  • Componente SAP Gateway activado
  • Servicios OData habilitados y configurados

Autorizaciones SAP requeridas

El usuario de SAP necesita estos objetos de autorización:

  • S_SERVICE: Autorización de servicio para endpoints OData
  • S_ICF: Autorización de Internet Communication Framework
  • S_TCODE: Autorización de transacción para BAPIs (si se utilizan importaciones de funciones)

Activación de servicios OData

  1. Transacción SICF: Active los servicios ICF en /sap/opu/odata
  2. Transacción /IWFND/MAINT_SERVICE: Gestione y active los servicios OData
  3. Transacción /IWFND/GW_CLIENT: Pruebe las llamadas a servicios OData

Arquitectura

Diseño modular

src/
├── index.ts              # Entry point - starts the server
├── server.ts             # MCP server setup and request routing
├── handlers.ts           # Business logic for each tool
├── odata-client.ts       # SAP OData HTTP client
├── tool-definitions.ts   # MCP tool schemas
└── types.ts              # TypeScript type definitions

Características clave

  • Prueba de conexión inteligente: Maneja la estructura de URL de SAP donde las URL base devuelven 404
  • Descubrimiento de servicios: Múltiples métodos para encontrar servicios OData disponibles
  • Manejo de errores: Manejo integral de errores con mensajes útiles
  • Seguridad de tipos: Soporte completo de TypeScript con interfaces adecuadas
  • Protección CSRF: Gestión automática de tokens CSRF para operaciones de escritura

Solución de problemas

Problemas comunes

Conexión rechazada (error de red)

  • Verifique que el sistema SAP esté en ejecución y sea accesible
  • Compruebe el nombre de host/puerto en SAP_ODATA_BASE_URL
  • Verifique que la configuración del firewall permita tráfico HTTP/HTTPS

401 No autorizado

  • Verifique SAP_USERNAME y SAP_PASSWORD
  • Verifique que la cuenta de usuario no esté bloqueada
  • Asegúrese de que el usuario tenga la autorización S_SERVICE

403 Prohibido

  • Verifique que el usuario tenga las autorizaciones SAP requeridas
  • Verifique la autorización S_ICF para rutas OData
  • Contacte al administrador de SAP para revisión de permisos

404 No encontrado

  • Esto es normal para URL base de SAP OData sin nombres de servicio
  • Verifique que los servicios OData estén activados (transacción SICF)
  • Use el descubrimiento de servicios para encontrar servicios disponibles

Errores de certificado SSL

  • Establezca SAP_VALIDATE_SSL=false para desarrollo
  • Instale certificados adecuados para producción
  • Verifique la cadena de certificados y la expiración

Modo de depuración

Habilite el registro detallado:

DEBUG=axios npm start

Verificación del sistema SAP

  1. Pruebe la URL de OData en el navegador: Navegue a su URL de OData de SAP
  2. Verifique la activación del servicio: Transacción SICF → /sap/opu/odata
  3. Verifique los servicios de gateway: Transacción /IWFND/MAINT_SERVICE
  4. Pruebe con el cliente de gateway: Transacción /IWFND/GW_CLIENT

Mejores prácticas de seguridad

Implementación en producción

  • Use HTTPS para todas las conexiones OData de SAP
  • Almacene las credenciales de forma segura - nunca codifique contraseñas
  • Cree usuarios de servicio dedicados con los permisos mínimos requeridos
  • Habilite la protección CSRF para operaciones de escritura
  • Implemente la autorización adecuada en SAP para servicios OData
  • Supervise los registros de acceso y configure alertas
  • Auditorías de seguridad periódicas de los permisos de usuario

Seguridad de red

  • Use VPN o redes privadas para el acceso a SAP
  • Implemente restricciones de IP cuando sea posible
  • Habilite las funciones de seguridad de SAP Gateway
  • Use una gestión adecuada de certificados

Servicios OData comunes de SAP

Servicios SAP estándar

  • GWSAMPLE_BASIC - Servicio de muestra básico para pruebas
  • GWDEMO - Servicio de demostración integral
  • RMTSAMPLEFLIGHT - Demostración de reserva de vuelos

Servicios de negocio

  • API_MATERIAL_SRV - Gestión de materiales
  • API_BUSINESS_PARTNER - Gestión de socios comerciales
  • API_SALES_ORDER_SRV - Gestión de pedidos de venta
  • API_PURCHASEORDER_PROCESS_SRV - Procesamiento de pedidos de compra

Conjuntos de entidades por módulo

  • MM (Gestión de materiales): MaterialSet, MaterialPlantDataSet
  • SD (Ventas y distribución): SalesOrderSet, CustomerSet, PricingConditionSet
  • FI (Contabilidad financiera): GeneralLedgerEntrySet, AccountingDocumentSet
  • HR (Recursos humanos): EmployeeSet, OrganizationalUnitSet

Desarrollo

Scripts disponibles

# Build TypeScript
npm run build

# Start production server
npm start

# Development mode with auto-reload
npm run dev

# Code quality
npm run lint
npm run format

Agregar nuevas funciones

  1. Agregue la definición de la herramienta en tool-definitions.ts
  2. Implemente el manejador en handlers.ts
  3. Agregue la ruta en la declaración switch de server.ts
  4. Actualice los tipos en types.ts si es necesario
  5. Compile y pruebe

Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios con tipos TypeScript adecuados
  4. Pruebe con un sistema SAP real
  5. Envíe una solicitud de extracción (pull request)

Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles.