# 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`):

```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**:

```sql
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

```bash
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`.