sap-b1-hana-mcp

Servidor MCP (Model Context Protocol) para consultar SAP B1 HANA mediante SQL directo sobre el driver oficial de SAP (@sap/hana-client).

Sin instalación: se ejecuta con npx directamente desde este repositorio de GitHub. Solo necesitas definir variables de entorno.

Uso

1. Requisitos

• Node.js 20+ (solo en la máquina que ejecuta el agente; no se instala nada del MCP).

2. Registro en opencode (u otro cliente MCP)

Añade este bloque a tu configuración de opencode (por ejemplo ~/.config/opencode/opencode.json):

{
  "mcp": {
    "sap-b1-hana": {
      "type": "local",
      "command": ["npx", "-y", "github:leonardows1/sap-b1-hana-mcp"],
"environment": {
        "HANA_HOST": "192.168.1.100",
        "HANA_PORT": "30015",
        "HANA_USER": "USUARIO_HANA",
        "HANA_PASSWORD": "TU_CONTRASEÑA",
        "HANA_DATABASE": "MI_TENANT",
        "HANA_SCHEMA": "MI_EMPRESA",
        "HANA_READONLY": "true"
      },
      "enabled": true
    }
  }
}

Nota: la primera ejecución de npx descarga e instala el paquete y puede tardar más de 5 segundos. Si el cliente MCP reporta timeout al iniciar, aumenta "timeout": 60000 en el bloque.

3. Variables de entorno

Variable	Obligatoria	Descripción	Ejemplo
HANA_HOST	Sí	Host del servidor HANA	192.168.1.100
HANA_PORT	No (default 30015)	Puerto HANA (tenant)	30013
HANA_USER	Sí	Usuario de HANA	USUARIO_HANA
HANA_PASSWORD	Sí	Contraseña	...
HANA_DATABASE	No	Tenant de HANA (MDC)	MI_TENANT
HANA_SCHEMA	No	Esquema (company database de SAP B1)	MI_EMPRESA
HANA_READONLY	No (default true)	true = solo consultas de lectura; false = permite INSERT/UPDATE/DELETE/DDL	true
HANA_SSL	No (default false)	true = conexión cifrada (sin validación de certificado)	false

Herramientas MCP

Tool	Descripción
execute_query	Ejecuta SQL y devuelve filas en JSON (columns, rows, rowCount, truncated).
check_connection	Verifica la conexión: base de datos, versión y esquema actual.
list_schemas	Lista esquemas de la instancia (filtro opcional por patrón).
list_tables	Lista tablas de un esquema (filtro opcional por patrón).
get_table_schema	Estructura de una tabla: columnas, tipos, longitud, escala, nulabilidad.

Importante sobre SQL y SAP B1

Las tablas y columnas de SAP B1 usan mayúsculas y minúsculas mezcladas y distinguen mayúsculas: los nombres de columna deben escribirse entre comillas dobles:

SELECT "ItemCode", "ItemName", "OnHand" FROM OITM WHERE "OnHand" > 0 ORDER BY "OnHand" DESC

Sin comillas, HANA convierte a mayúsculas y la consulta falla con invalid column name.

Modo solo lectura

Con HANA_READONLY=true (por defecto) el servidor rechaza cualquier sentencia que no sea SELECT, WITH, EXPLAIN, SHOW o DESCRIBE. Para habilitar escrituras usa HANA_READONLY=false — bajo tu responsabilidad.

Desarrollo

npm install
npm run build      # compila TypeScript a dist/
npm test           # tests unitarios (vitest)

La carpeta dist/ se compila y se versiona: es lo que ejecuta npx github:... sin necesidad de build en la máquina del usuario.

Arquitectura

Capas con inyección de dependencias manual y principios SOLID:

src/
├── index.ts              Composition root: DI, host MCP (stdio)
├── configuration/        HanaOptions + validación de variables de entorno
├── domain/               Modelos: QueryResult, SchemaInfo, TableInfo, ColumnInfo, StatementKind
├── application/          Abstracciones de servicios + ISqlGuard (Strategy) + clasificador SQL
├── infrastructure/       Única capa que toca @sap/hana-client: factory de conexión,
│                         servicios de consulta/esquema, mapeo de datos (Buffer→base64, Date→ISO)
└── mcp/                  Adaptadores delgados: registro de tools MCP

Licencias

• Este proyecto: MIT.
• Driver @sap/hana-client: SAP Developer License Agreement (se distribuye como dependencia npm, no se versiona en este repositorio). Ver node_modules/@sap/hana-client/developer-license-3_2.txt.