@nubiia/mcp-freematica 0.6.4 → 0.8.0

package/README.md

@@ -59,6 +59,37 @@ MCP server que expone operaciones del API REST de Freemática (ERP: facturación
 | `freematica_list_albaranes_factura`                  | `GET /pven/v2/albaranes-facturas`                            | Lista paginada de vinculaciones albarán↔factura (idReg nativo + FIQL)                              |
 | `freematica_get_albaran_factura`                     | `GET /pven/v2/albaranes-facturas/{idReg}`                    | Detalle de una vinculación albarán-factura                                                         |
 | `freematica_list_resultados_facturacion`             | `GET /pvss/v1/facturacion-resultados`                        | Resultados del proceso batch de facturación automática de vigilancia (FIQL)                        |
+| `freematica_list_contratos`                          | `GET /pvss/v1/contratos`                                     | Lista paginada de cabeceras de contratos (solo filtros nativos: el API ignora FIQL aquí)           |
+| `freematica_get_contrato`                            | `GET /pvss/v1/contratos` (scan)                              | Busca un contrato por empresa + código natural (paginación interna + filtrado en cliente)          |
+| `freematica_list_servicios_contrato`                 | `GET /pvss/v1/contratos/{idReg}/servicios`                   | Servicios de un contrato                                                                           |
+| `freematica_get_servicio_contrato`                   | `GET /pvss/v2/contratos-servicios/{idReg}`                   | Detalle de un servicio de contrato                                                                 |
+| `freematica_list_contratos_opcionales`               | `GET /ppre/v2/contratos/opcionales`                          | Lista paginada de opcionales de contratos                                                          |
+| `freematica_get_contrato_opcionales`                 | `GET /ppre/v2/contratos/opcionales/{idReg}`                  | Detalle de un registro de opcionales                                                               |
+| `freematica_list_localizaciones_envio_clientes`      | `GET /pgrl/v2/localizaciones-envio-clientes`                 | Localizaciones de envío de clientes                                                                |
+| `freematica_list_localizaciones_factura_clientes`    | `GET /pgrl/v2/localizaciones-factura-clientes`               | Localizaciones de factura de clientes                                                              |
+
+### Tools de escritura (requieren `FREEMATICA_ENABLE_WRITES=true`)
+
+Por defecto el servidor es de **solo lectura**. Con `FREEMATICA_ENABLE_WRITES=true` se registran además estas tools de creación y actualización. **No existe ninguna tool de borrado.** Todas las escrituras dejan log de auditoría (operación + endpoint + campos a nivel info; body completo a nivel debug).
+
+| Tool                                           | Endpoint Freemática                                             | Descripción                                                      |
+| ---------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `freematica_create_contrato`                   | `POST /pvss/v2/contratos`                                       | Alta de cabecera de contrato                                     |
+| `freematica_update_contrato`                   | `PUT /pvss/v2/contratos/{idReg}`                                | Actualización de cabecera de contrato                            |
+| `freematica_create_servicio_contrato`          | `POST /pvss/v2/contratos/{idReg}/servicios`                     | Alta de servicio (identificación derivada del idReg)             |
+| `freematica_update_servicio_fechas`            | `PUT /pvss/v2/contratos/{id}/servicio/{id}`                     | Fechas inicio/fin del servicio (mecanismo de baja)               |
+| `freematica_create_servicio_historico_precios` | `POST /pvss/v2/contratos/{id}/servicios-historico-precios/{id}` | Alta de revisión de precios del servicio                         |
+| `freematica_update_servicio_historico_precios` | `PUT /pvss/v2/contratos/{id}/servicios-historico-precios/{id}`  | Actualización de revisión de precios                             |
+| `freematica_create_servicio_facturacion_txt`   | `POST /pvss/v2/contratos/{id}/servicios-facturacion-txt/{id}`   | Alta de línea de texto de facturación                            |
+| `freematica_update_servicio_facturacion`       | `PUT /pvss/v2/contratos/{id}/servicios-facturacion/{id}`        | Datos de facturación del servicio (precios hora, forma de pago…) |
+| `freematica_create_contrato_opcionales`        | `POST /ppre/v2/contratos/opcionales`                            | Alta de opcionales de contrato                                   |
+| `freematica_update_contrato_opcionales`        | `PUT /ppre/v2/contratos/opcionales/{idReg}`                     | Actualización de opcionales de contrato                          |
+| `freematica_create_cliente`                    | `POST /pgrl/v2/clientes`                                        | Alta de cliente (idReg derivado de grupo+código)                 |
+| `freematica_update_cliente`                    | `PUT /pgrl/v2/clientes/{idReg}`                                 | Actualización parcial de cliente (fetch+merge)                   |
+| `freematica_create_contacto_cliente`           | `POST /pgrl/v2/contactos-clientes`                              | Alta de contacto de cliente                                      |
+| `freematica_update_contacto_cliente`           | `PUT /pgrl/v2/contactos-clientes/{idReg}`                       | Actualización parcial de contacto (fetch+merge)                  |
+| `freematica_create_localizacion_cliente`       | `POST /pgrl/v2/localizaciones-{tipo}-clientes`                  | Alta de localización (tipo: cobro/envio/factura/servicio)        |
+| `freematica_update_localizacion_cliente`       | `PUT /pgrl/v2/localizaciones-{tipo}-clientes/{idReg}`           | Actualización parcial de localización (fetch+merge)              |
 
 ## Filtros tipados (FIQL interno)
 
@@ -234,18 +265,19 @@ El servidor lee toda su configuración de **variables de entorno** al arrancar.
 
 Variables de entorno opcionales para tuning de comportamiento en producción:
 
-| Variable                                | Default                                              | Descripción                                                                                                                                     |
-| --------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `FREEMATICA_BASE_URL`                   | `https://api-p01.clientservicepanel.com/restsat/api` | Base URL del API de Freemática. Cambiar solo si Freemática cambia el host o se usa un entorno alternativo.                                      |
-| `FREEMATICA_TIMEOUT_MS`                 | `30000`                                              | Timeout por petición en milisegundos. Si el upstream no responde en este tiempo, el request se cancela con `network_error`.                     |
-| `FREEMATICA_MAX_RETRIES`                | `3`                                                  | Número máximo de reintentos para errores 5xx y errores de red. Los errores 4xx nunca se reintentan.                                             |
-| `FREEMATICA_CIRCUIT_BREAKER_THRESHOLD`  | `5`                                                  | Número de operaciones lógicas fallidas consecutivas (post-retry-exhaustion) necesarias para abrir el circuit breaker.                           |
-| `FREEMATICA_CIRCUIT_BREAKER_TIMEOUT_MS` | `30000`                                              | Tiempo en ms que el circuit breaker permanece abierto antes de pasar a half-open.                                                               |
-| `FREEMATICA_MAX_RESPONSE_SIZE_MB`       | `10`                                                 | Tamaño máximo de respuesta aceptada del upstream en MB. Respuestas mayores se truncan con aviso en el campo `truncated`.                        |
-| `MCP_TRANSPORT`                         | `stdio`                                              | Transporte: `stdio` (para Claude Desktop/Code) o `http` (para Nubiia). Equivale al flag `--transport=`.                                         |
-| `MCP_PORT`                              | `3000`                                               | Puerto TCP donde el servidor MCP expone `/mcp` y `/health`. Ignorado en modo stdio.                                                             |
-| `MCP_ALLOWED_ORIGINS`                   | `*`                                                  | CORS: lista de orígenes permitidos separados por coma, o `*` para todos. En producción restringir al dominio de Nubiia. Ignorado en modo stdio. |
-| `LOG_LEVEL`                             | `info`                                               | Nivel de log para pino: `fatal`, `error`, `warn`, `info`, `debug`, `trace`. En producción usar `info`. En desarrollo usar `debug`.              |
+| Variable                                | Default                                              | Descripción                                                                                                                                                |
+| --------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FREEMATICA_BASE_URL`                   | `https://api-p01.clientservicepanel.com/restsat/api` | Base URL del API de Freemática. Cambiar solo si Freemática cambia el host o se usa un entorno alternativo.                                                 |
+| `FREEMATICA_TIMEOUT_MS`                 | `30000`                                              | Timeout por petición en milisegundos. Si el upstream no responde en este tiempo, el request se cancela con `network_error`.                                |
+| `FREEMATICA_MAX_RETRIES`                | `3`                                                  | Número máximo de reintentos para errores 5xx y errores de red. Los errores 4xx nunca se reintentan.                                                        |
+| `FREEMATICA_CIRCUIT_BREAKER_THRESHOLD`  | `5`                                                  | Número de operaciones lógicas fallidas consecutivas (post-retry-exhaustion) necesarias para abrir el circuit breaker.                                      |
+| `FREEMATICA_CIRCUIT_BREAKER_TIMEOUT_MS` | `30000`                                              | Tiempo en ms que el circuit breaker permanece abierto antes de pasar a half-open.                                                                          |
+| `FREEMATICA_MAX_RESPONSE_SIZE_MB`       | `10`                                                 | Tamaño máximo de respuesta aceptada del upstream en MB. Respuestas mayores se truncan con aviso en el campo `truncated`.                                   |
+| `FREEMATICA_ENABLE_WRITES`              | `false`                                              | Registra las tools de escritura (`freematica_create_*` / `freematica_update_*`). Sin ella el servidor es de solo lectura. Valores: `true`/`false`/`1`/`0`. |
+| `MCP_TRANSPORT`                         | `stdio`                                              | Transporte: `stdio` (para Claude Desktop/Code) o `http` (para Nubiia). Equivale al flag `--transport=`.                                                    |
+| `MCP_PORT`                              | `3000`                                               | Puerto TCP donde el servidor MCP expone `/mcp` y `/health`. Ignorado en modo stdio.                                                                        |
+| `MCP_ALLOWED_ORIGINS`                   | `*`                                                  | CORS: lista de orígenes permitidos separados por coma, o `*` para todos. En producción restringir al dominio de Nubiia. Ignorado en modo stdio.            |
+| `LOG_LEVEL`                             | `info`                                               | Nivel de log para pino: `fatal`, `error`, `warn`, `info`, `debug`, `trace`. En producción usar `info`. En desarrollo usar `debug`.                         |
 
 ### De dónde salen las credenciales `x-auth-*`
 

package/dist/clients/freematica-client.d.ts

@@ -3,11 +3,12 @@ import { type MasterDataCatalog } from '../schemas/master-data.js';
 import { type ListCarteraFilters } from '../schemas/cartera.js';
 import type { ListFacturasCabeceraFilters, ListFacturaLineasFilters, ListFacturaIvaFilters, ListFacturaVencimientosFilters } from '../schemas/facturas-ventas.js';
 import { type ListPedidosCompraFilters } from '../schemas/pedidos-compras.js';
+import { type LocalizacionTipo } from '../schemas/localizaciones.js';
 import type { Cliente } from '../types/clientes.js';
 import type { ContactoCliente } from '../types/contactos-clientes.js';
 import type { MasterDataItem } from '../types/master-data.js';
 import type { OportunidadNegocio } from '../types/oportunidades-negocio.js';
-import type { VoContratosServMatAsignado } from '../types/contratos.js';
+import type { VoContrato, VoContratoServicio, VoContratosOpcionales, VoContratosServMatAsignado, VoServiciosFac, VoServiciosFacTxt, VoServiciosHistPr } from '../types/contratos.js';
 export interface ListResult<T> {
     items: T[];
     total: number;
@@ -601,6 +602,268 @@ export declare class FreematicaClient extends BaseClient {
         traspasado?: string;
         order?: string;
     }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de cabeceras de contratos.
+     *
+     * Endpoint: GET /pvss/v1/contratos
+     *
+     * IMPORTANTE: este endpoint IGNORA silenciosamente el query param `rQuery`
+     * (verificado empíricamente contra el API real el 2026-07-02: con un filtro
+     * FIQL válido devuelve el dataset completo sin error). Por eso solo se
+     * exponen los filtros nativos `codEmpresa` y `codDelegacion`; cualquier otro
+     * filtrado debe hacerse en cliente (ver `getContrato`).
+     *
+     * @param opts - Paginación + filtros nativos empresa/delegación + order.
+     * @returns Lista paginada de cabeceras de contrato (campos CTRT_*).
+     */
+    listContratos(opts?: ListOptions & {
+        empresa?: string;
+        delegacion?: string;
+        order?: string;
+    }): Promise<ListResult<VoContrato>>;
+    /**
+     * Busca una cabecera de contrato por sus códigos naturales.
+     *
+     * No existe un endpoint GET singular para contratos pvss y el listado ignora
+     * `rQuery`, así que se pagina el listado (items=200, máximo permitido por el
+     * API) filtrando en cliente por CTRT_COD hasta encontrar la coincidencia.
+     *
+     * @param opts - Códigos naturales del contrato.
+     * @returns Cabecera del contrato.
+     * @throws FreematicaError('not_found') si no existe.
+     */
+    getContrato(opts: {
+        empresa: string;
+        delegacion?: string;
+        codContrato: string;
+    }): Promise<VoContrato>;
+    /**
+     * Lista paginada de servicios de un contrato.
+     *
+     * Endpoint: GET /pvss/v1/contratos/{idContrato}/servicios
+     *
+     * @param idContrato - idReg opaco del contrato (Base64 "EMP__DELEG__COD").
+     * @param opts - Paginación + order.
+     * @returns Lista paginada de servicios (campos CTRTS_*).
+     */
+    listServiciosContrato(idContrato: string, opts?: ListOptions & {
+        order?: string;
+    }): Promise<ListResult<VoContratoServicio>>;
+    /**
+     * Detalle de un servicio de contrato por `idReg` opaco.
+     *
+     * Endpoint: GET /pvss/v2/contratos-servicios/{idreg}
+     *
+     * @param idReg - idReg opaco del servicio (Base64 "EMP__DELEG__CTRT__COD").
+     * @returns Servicio completo.
+     */
+    getServicioContrato(idReg: string): Promise<VoContratoServicio>;
+    /**
+     * Lista paginada de opcionales de contratos.
+     *
+     * Endpoint: GET /ppre/v2/contratos/opcionales
+     *
+     * @param opts - Paginación + order.
+     * @returns Lista paginada de opcionales (campos CON2_*).
+     */
+    listContratosOpcionales(opts?: ListOptions & {
+        order?: string;
+    }): Promise<ListResult<VoContratosOpcionales>>;
+    /**
+     * Detalle de un registro de opcionales de contrato por `idReg` opaco.
+     *
+     * Endpoint: GET /ppre/v2/contratos/opcionales/{idReg}
+     */
+    getContratoOpcionales(idReg: string): Promise<VoContratosOpcionales>;
+    /**
+     * Alta de cabecera de contrato.
+     *
+     * Endpoint: POST /pvss/v2/contratos — body VoContratos.
+     * Campos requeridos por el API: CTRT_DELEG, CTRT_DES, CTRT_FECHA, CTRT_COD_CLI.
+     *
+     * @param body - Campos CTRT_* del contrato.
+     * @returns El contrato creado (VoContratos).
+     */
+    createContrato(body: VoContrato): Promise<VoContrato>;
+    /**
+     * Actualización de cabecera de contrato.
+     *
+     * Endpoint: PUT /pvss/v2/contratos/{idReg} — body VoContratos.
+     *
+     * @param idReg - idReg opaco del contrato.
+     * @param body - Campos CTRT_* a actualizar.
+     * @returns Respuesta del API.
+     */
+    updateContrato(idReg: string, body: VoContrato): Promise<VoContrato>;
+    /**
+     * Alta de un servicio en un contrato.
+     *
+     * Endpoint: POST /pvss/v2/contratos/{idReg}/servicios — body VoServicios.
+     * Campos requeridos por el API: CTRTS_EMP, CTRTS_DELEG, CTRTS_CTRT (los
+     * mismos valores codificados en el idReg del contrato).
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param body - Campos CTRTS_* del servicio.
+     * @returns El servicio creado (VoServicios).
+     */
+    createServicioContrato(idContrato: string, body: VoContratoServicio): Promise<VoContratoServicio>;
+    /**
+     * Actualiza fechas de inicio y fin de un servicio.
+     *
+     * Endpoint: PUT /pvss/v2/contratos/{idContrato}/servicio/{idServicio}.
+     * Según el spec, este endpoint solo actualiza fecha inicio y fecha fin.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos CTRTS_* (fechas) a actualizar.
+     * @returns Respuesta del API.
+     */
+    updateServicioFechas(idContrato: string, idServicio: string, body: VoContratoServicio): Promise<VoContratoServicio>;
+    /**
+     * Actualiza los datos de facturación de un servicio.
+     *
+     * Endpoint: PUT /pvss/v2/contratos/{idContrato}/servicios-facturacion/{idServicio}.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos CTRTF_* a actualizar.
+     * @returns Respuesta del API.
+     */
+    updateServicioFacturacion(idContrato: string, idServicio: string, body: VoServiciosFac): Promise<VoServiciosFac>;
+    /**
+     * Alta de un texto de facturación de un servicio.
+     *
+     * Endpoint: POST /pvss/v2/contratos/{idContrato}/servicios-facturacion-txt/{idServicio}.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos CTRTFL_* del texto.
+     * @returns Respuesta del API.
+     */
+    createServicioFacturacionTxt(idContrato: string, idServicio: string, body: VoServiciosFacTxt): Promise<VoServiciosFacTxt>;
+    /**
+     * Alta de un registro de histórico de precios de un servicio.
+     *
+     * Endpoint: POST /pvss/v2/contratos/{idContrato}/servicios-historico-precios/{idServicio}.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos SERVHPR_* del histórico.
+     * @returns Respuesta del API (VoServiciosHistPr).
+     */
+    createServicioHistoricoPrecios(idContrato: string, idServicio: string, body: VoServiciosHistPr): Promise<VoServiciosHistPr>;
+    /**
+     * Actualiza un registro de histórico de precios de un servicio.
+     *
+     * Endpoint: PUT /pvss/v2/contratos/{idContrato}/servicios-historico-precios/{idServicio}.
+     *
+     * @param idContrato - idReg opaco del contrato.
+     * @param idServicio - idReg opaco del servicio.
+     * @param body - Campos SERVHPR_* a actualizar.
+     * @returns Respuesta del API.
+     */
+    updateServicioHistoricoPrecios(idContrato: string, idServicio: string, body: VoServiciosHistPr): Promise<VoServiciosHistPr>;
+    /**
+     * Alta de un registro de opcionales de contrato.
+     *
+     * Endpoint: POST /ppre/v2/contratos/opcionales — body VoContratosOpcionales.
+     * Campos requeridos por el API: CON2_CODEMP, CON2_DELEG, CON2_TIPOCONT,
+     * CON2_NUMCONT, CON2_FCHCONT.
+     *
+     * @param body - Campos CON2_* del registro.
+     * @returns El registro creado.
+     */
+    createContratoOpcionales(body: VoContratosOpcionales): Promise<VoContratosOpcionales>;
+    /**
+     * Actualiza un registro de opcionales de contrato.
+     *
+     * Endpoint: PUT /ppre/v2/contratos/opcionales/{idReg}.
+     *
+     * @param idReg - idReg opaco del registro de opcionales.
+     * @param body - Campos CON2_* a actualizar.
+     * @returns Respuesta del API.
+     */
+    updateContratoOpcionales(idReg: string, body: VoContratosOpcionales): Promise<VoContratosOpcionales>;
+    /**
+     * Log de auditoría de operaciones de escritura.
+     *
+     * Nivel info: operación + endpoint + claves del body (sin valores).
+     * Nivel debug: body completo, para poder reconstruir la operación.
+     */
+    private logWrite;
+    /**
+     * Alta de cliente.
+     *
+     * Endpoint: POST /pgrl/v2/clientes — body VoClientes.
+     * Requeridos por el API: idReg, COD_GRUPO_CLI, COD_CLI, NOMBRE_CLI, NIF,
+     * TIPO_IMPTO, COD_DIVISA, TIPO_FACT.
+     */
+    createCliente(body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Actualización de cliente.
+     *
+     * Endpoint: PUT /pgrl/v2/clientes/{idReg} — body VoClientes completo
+     * (el caller hace fetch+merge antes de llamar).
+     */
+    updateCliente(idReg: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Detalle de un contacto de cliente por `idReg` opaco.
+     *
+     * Endpoint: GET /pgrl/v1/contactos-clientes/{idreg}
+     * (v2 solo expone el listado; el singular es v1 pero devuelve las mismas
+     * columnas CC_*). Se usa en el fetch+merge del update.
+     */
+    getContactoCliente(idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Alta de contacto de cliente.
+     *
+     * Endpoint: POST /pgrl/v2/contactos-clientes — body VoContactosClientes.
+     * Requeridos por el API: CC_GRUPO_CLI, CC_CLI.
+     */
+    createContactoCliente(body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Actualización de contacto de cliente.
+     *
+     * Endpoint: PUT /pgrl/v2/contactos-clientes/{idReg}.
+     */
+    updateContactoCliente(idReg: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Detalle de una localización de cliente por tipo e `idReg` opaco.
+     *
+     * Usa el GET singular v2 del tipo (v1 para factura, que no tiene v2; las
+     * columnas son las mismas). Se emplea en el fetch+merge de los updates.
+     */
+    getLocalizacionCliente(tipo: LocalizacionTipo, idReg: string): Promise<Record<string, unknown>>;
+    /**
+     * Lista paginada de localizaciones de envío de clientes.
+     *
+     * Endpoint: GET /pgrl/v2/localizaciones-envio-clientes
+     */
+    listLocalizacionesEnvioClientes(opts?: ListOptions & {
+        codCliente?: string;
+        grupoCliente?: string;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Lista paginada de localizaciones de factura de clientes.
+     *
+     * Endpoint: GET /pgrl/v2/localizaciones-factura-clientes
+     */
+    listLocalizacionesFacturaClientes(opts?: ListOptions & {
+        codCliente?: string;
+        grupoCliente?: string;
+    }): Promise<ListResult<Record<string, unknown>>>;
+    /**
+     * Alta de localización de cliente (cobro, envío, factura o servicio).
+     *
+     * Endpoint: POST /pgrl/v2/localizaciones-{tipo}-clientes — body Vo del tipo.
+     */
+    createLocalizacionCliente(tipo: LocalizacionTipo, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Actualización de localización de cliente (cobro, envío, factura o servicio).
+     *
+     * Endpoint: PUT /pgrl/v2/localizaciones-{tipo}-clientes/{idReg}.
+     */
+    updateLocalizacionCliente(tipo: LocalizacionTipo, idReg: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
     private listResource;
     /**
      * Helper genérico para endpoints de lista que soportan paginación + filtros FIQL