# ordis-mcp-server

Servidor MCP de **solo lectura** para la API contable de Ordis SpA. Expone cada
endpoint de `https://ordis.cl/api/v1` como una tool tipada, para consultar la
contabilidad de forma nativa desde Claude (Claude Code / Claude Desktop) sin
adivinar rutas.

El servidor **no guarda el token**: lo lee de la variable de entorno
`ORDIS_API_KEY` y actúa solo como cliente HTTP. Autentica únicamente por header
`Authorization: Bearer`.

## Requisitos

- Node.js 18 o superior (usa `fetch` nativo).
- Un **token de la API de Ordis** (`ordis_sk_...`). Se genera en el portal:
  **ordis.cl → Acceso API a tus datos (`/portal/api-keys`) → Crear llave**.
  Se muestra una sola vez — guárdala como variable de entorno, nunca en un
  archivo versionado.

## Instalar y compilar

```bash
npm install
npm run build
```

Genera `dist/index.js` (el ejecutable del servidor).

## Probar en local (MCP Inspector)

```bash
ORDIS_API_KEY="ordis_sk_..." npx @modelcontextprotocol/inspector node dist/index.js
```

Abre la UI del Inspector, lista las 11 tools y prueba una llamada (ej.
`ordis_get_kpis` con `periodo: "2026-07"`).

## Conectar a Claude

### Opción 1 — Claude Code (CLI)

```bash
claude mcp add ordis \
  --env ORDIS_API_KEY=ordis_sk_TU_TOKEN \
  -- node /ruta/absoluta/ordis-mcp-server/dist/index.js
```

### Opción 2 — Config JSON (Claude Desktop / Claude Code)

En el archivo de config de MCP:

```json
{
  "mcpServers": {
    "ordis": {
      "command": "node",
      "args": ["/ruta/absoluta/ordis-mcp-server/dist/index.js"],
      "env": {
        "ORDIS_API_KEY": "ordis_sk_TU_TOKEN"
      }
    }
  }
}
```

> Usa la ruta **absoluta** a `dist/index.js`. Reinicia el cliente para que
> detecte el servidor.

## Variables de entorno

| Variable | Requerida | Descripción |
|---|---|---|
| `ORDIS_API_KEY` | Sí | Token de solo lectura (`ordis_sk_...`). |
| `ORDIS_API_BASE_URL` | No | Sobrescribe el base URL. Default: `https://ordis.cl/api/v1`. |

## Tools disponibles (11, todas solo lectura)

| Tool | Endpoint | Parámetros |
|---|---|---|
| `ordis_get_empresa` | `/me` | — |
| `ordis_list_facturas` | `/facturas` | `periodo?`, `tipo?`, `page?` |
| `ordis_get_f29` | `/f29` | `periodo?` |
| `ordis_get_f22` | `/f22` | `anio?` |
| `ordis_get_flujo_caja` | `/flujo-caja` | `anio?` |
| `ordis_get_kpis` | `/kpis` | `periodo?` |
| `ordis_list_liquidaciones` | `/liquidaciones` | `periodo?` |
| `ordis_list_trabajadores` | `/trabajadores` | `estado?` |
| `ordis_list_deudas` | `/deudas` | `estado?` |
| `ordis_list_movimientos_banco` | `/movimientos-banco` | `periodo?`, `page?` |
| `ordis_list_boletas_honorarios` | `/boletas-honorarios` | `periodo?`, `estado?`, `page?` |

- `periodo` valida el formato `YYYY-MM` en el cliente (falla rápido sin gastar
  una llamada de red).
- `anio` valida el rango 2020–2027.
- `page` debe ser ≥ 1.
- Enums validados en el cliente (mismos valores que la API): `tipo` =
  `emitida | recibida` · `estado` de boletas = `vigente | anulada | rechazada`
  · `estado` de deudas = `activo | pagado | cancelado` · `estado` de
  trabajadores = `activo | licencia | vacaciones | desvinculado`.
- En los endpoints con tope de filas (`deudas`, `trabajadores`), si la
  respuesta trae `meta.has_more: true` hay más datos que los devueltos.

## Estructura

```
ordis-mcp-server/
├── package.json
├── tsconfig.json
├── README.md
└── src/
    ├── index.ts       # arranque + transporte stdio
    ├── client.ts      # cliente HTTP: auth por header, timeout, errores accionables
    ├── tools.ts       # registro de las 11 tools
    ├── schemas.ts     # campos Zod reutilizables (periodo, anio, page, estado)
    └── constants.ts   # base URL, timeout, límite de caracteres
```

## Nota sobre versiones del SDK

Este servidor usa el SDK **v1** (`@modelcontextprotocol/sdk`), que es la línea
compatible y probada con la config stdio actual de Claude Code / Desktop.

Existe una línea **v2** (`@modelcontextprotocol/server`, spec 2026-07-28) con
paquetes renombrados y `zod/v4`. Cuando v2 se estabilice en los hosts, la
migración es acotada: cambiar los imports, pasar `inputSchema` como `z.object({...})`
en vez de shape plano, y actualizar el transporte. La lógica de negocio
(`client.ts`, mapeo de params) no cambia.

## Seguridad

- Solo lectura: no hay tools que escriban, borren ni muten datos (la API de
  Ordis tampoco tiene endpoints de escritura).
- El token vive solo en la variable de entorno; nunca se loguea ni se persiste.
- En stdio, `stdout` es el canal del protocolo MCP: todos los logs van a `stderr`.
- Puedes revocar el token cuando quieras desde `ordis.cl/portal/api-keys`; el
  corte es inmediato. Rota el token si sospechas que se expuso.
- **Al reportar un issue en este repositorio, no pegues respuestas de la API**
  (contienen datos de tu empresa). Describe el error y el endpoint; con eso
  alcanza.