@nubiia/mcp-freematica 0.6.1

package/dist/schemas/pedidos-compras.d.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+/**
+ * Enum lógico del estado de un pedido de compra.
+ *
+ * Mapeo a FIQL sobre los campos `ALCC_PED_BLOQ` y `ALCC_PED_RECIB`:
+ *
+ * - `pendiente`  → `ALCC_PED_BLOQ=='';ALCC_PED_RECIB==''`
+ *   (ambos campos vacíos — pedido abierto, ni bloqueado ni recibido)
+ * - `bloqueado`  → `ALCC_PED_BLOQ!=''`
+ *   (campo ALCC_PED_BLOQ tiene algún valor centinela)
+ * - `recibido`   → `ALCC_PED_RECIB!=''`
+ *   (campo ALCC_PED_RECIB tiene algún valor centinela)
+ *
+ * ASUNCIÓN EMPÍRICA — convención nullable en Freemática FIQL:
+ * La API de Freemática no expone IS NULL nativo en FIQL. La convención
+ * observada en otras tablas del sistema (ver TD-118: ASI_BORR, CARCL_FECIMPAG)
+ * es representar el valor nulo/ausente como cadena vacía `''` en expresiones
+ * `==` / `!=`. Para ALCC_PED_BLOQ y ALCC_PED_RECIB:
+ *   - bloqueado=true  → `ALCC_PED_BLOQ!=''`  (campo tiene valor → bloqueado)
+ *   - recibido=true   → `ALCC_PED_RECIB!=''` (campo tiene valor → recibido)
+ *   - pendiente       → ambos campos vacíos
+ *
+ * Esta convención NO ha sido verificada contra la API real de Freemática.
+ * Si en pruebas funcionales el filtro no actúa correctamente, puede que el
+ * centinela sea el literal `null` (como en CARCL_FECIMPAG), un valor 'S'/'N'
+ * o un valor numérico '1'/'0'. Documentado para futura verificación empírica.
+ *
+ * TODO(TD-152): verificar contra API real cuando esté disponible.
+ */
+export declare const EstadoPedidoEnum: z.ZodEnum<["pendiente", "bloqueado", "recibido"]>;
+export type EstadoPedido = z.infer<typeof EstadoPedidoEnum>;
+/**
+ * Genera la expresión FIQL para el filtro de estado de pedido de compra.
+ *
+ * El estado se mapea a expresiones FIQL sobre `ALCC_PED_BLOQ` y `ALCC_PED_RECIB`.
+ * Ver `EstadoPedidoEnum` para la documentación completa de la convención.
+ *
+ * @param estado - Valor del enum de estado.
+ * @returns Expresión FIQL para incluir en `rquery` (sin `rquery=`).
+ */
+export declare function buildEstadoPedidoFiql(estado: EstadoPedido): string;
+/**
+ * Filtros tipados para `freematica_list_pedidos_compra`.
+ *
+ * El endpoint GET /pcmp/v2/pedidos tiene un diseño mixto:
+ * - 4 filtros como **query params nativos** (no FIQL): codEmpresa, desdeFecha, hastaFecha, codProveedor.
+ * - El resto de filtros via **rQuery** (FIQL) con campos ALCC_*.
+ *
+ * Mapeo completo:
+ * | Filtro lógico        | Destino             | Campo API              |
+ * |----------------------|---------------------|------------------------|
+ * | empresa (4c)         | query param nativo  | codEmpresa             |
+ * | codProveedor (10c)   | query param nativo  | codProveedor           |
+ * | fechaPedidoDesde     | query param nativo  | desdeFecha             |
+ * | fechaPedidoHasta     | query param nativo  | hastaFecha             |
+ * | numPedido            | FIQL rquery         | ALCC_NUMDOC            |
+ * | codDocumento (4c)    | FIQL rquery         | ALCC_CODDOC            |
+ * | delegacion (4c)      | FIQL rquery         | ALCC_DELEG             |
+ * | formaPago (3c)       | FIQL rquery         | ALCC_FPAGO             |
+ * | tipoIva (4c)         | FIQL rquery         | ALCC_TIPO_IVA          |
+ * | codCliente (10c)     | FIQL rquery         | ALCC_COD_CLIENTE       |
+ * | codInstalador        | FIQL rquery         | ALCC_COD_INSTALADOR    |
+ * | codMantenedor        | FIQL rquery         | ALCC_COD_MANTENEDOR    |
+ * | fechaEntregaDesde    | FIQL rquery         | ALCC_FCHENTREGA =ge=   |
+ * | fechaEntregaHasta    | FIQL rquery         | ALCC_FCHENTREGA =le=   |
+ * | referencia (40c)     | FIQL rquery         | ALCC_REFERENCIA        |
+ * | estado               | FIQL rquery compuesta| ALCC_PED_BLOQ + ALCC_PED_RECIB |
+ */
+export declare const ListPedidosCompraFiltersSchema: {
+    empresa: z.ZodOptional<z.ZodString>;
+    codProveedor: z.ZodOptional<z.ZodString>;
+    fechaPedidoDesde: z.ZodOptional<z.ZodString>;
+    fechaPedidoHasta: z.ZodOptional<z.ZodString>;
+    numPedido: z.ZodOptional<z.ZodNumber>;
+    codDocumento: z.ZodOptional<z.ZodString>;
+    delegacion: z.ZodOptional<z.ZodString>;
+    formaPago: z.ZodOptional<z.ZodString>;
+    tipoIva: z.ZodOptional<z.ZodString>;
+    codCliente: z.ZodOptional<z.ZodString>;
+    codInstalador: z.ZodOptional<z.ZodString>;
+    codMantenedor: z.ZodOptional<z.ZodString>;
+    fechaEntregaDesde: z.ZodOptional<z.ZodString>;
+    fechaEntregaHasta: z.ZodOptional<z.ZodString>;
+    referencia: z.ZodOptional<z.ZodString>;
+    estado: z.ZodOptional<z.ZodEnum<["pendiente", "bloqueado", "recibido"]>>;
+    page: z.ZodDefault<z.ZodNumber>;
+    items: z.ZodDefault<z.ZodNumber>;
+};
+/** Tipo inferido de los filtros de listado de pedidos de compra. */
+export type ListPedidosCompraFilters = {
+    [K in keyof typeof ListPedidosCompraFiltersSchema]?: z.infer<(typeof ListPedidosCompraFiltersSchema)[K]>;
+};

package/dist/schemas/pedidos-compras.js

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+import { PaginationSchema } from './pagination.js';
+/**
+ * Enum lógico del estado de un pedido de compra.
+ *
+ * Mapeo a FIQL sobre los campos `ALCC_PED_BLOQ` y `ALCC_PED_RECIB`:
+ *
+ * - `pendiente`  → `ALCC_PED_BLOQ=='';ALCC_PED_RECIB==''`
+ *   (ambos campos vacíos — pedido abierto, ni bloqueado ni recibido)
+ * - `bloqueado`  → `ALCC_PED_BLOQ!=''`
+ *   (campo ALCC_PED_BLOQ tiene algún valor centinela)
+ * - `recibido`   → `ALCC_PED_RECIB!=''`
+ *   (campo ALCC_PED_RECIB tiene algún valor centinela)
+ *
+ * ASUNCIÓN EMPÍRICA — convención nullable en Freemática FIQL:
+ * La API de Freemática no expone IS NULL nativo en FIQL. La convención
+ * observada en otras tablas del sistema (ver TD-118: ASI_BORR, CARCL_FECIMPAG)
+ * es representar el valor nulo/ausente como cadena vacía `''` en expresiones
+ * `==` / `!=`. Para ALCC_PED_BLOQ y ALCC_PED_RECIB:
+ *   - bloqueado=true  → `ALCC_PED_BLOQ!=''`  (campo tiene valor → bloqueado)
+ *   - recibido=true   → `ALCC_PED_RECIB!=''` (campo tiene valor → recibido)
+ *   - pendiente       → ambos campos vacíos
+ *
+ * Esta convención NO ha sido verificada contra la API real de Freemática.
+ * Si en pruebas funcionales el filtro no actúa correctamente, puede que el
+ * centinela sea el literal `null` (como en CARCL_FECIMPAG), un valor 'S'/'N'
+ * o un valor numérico '1'/'0'. Documentado para futura verificación empírica.
+ *
+ * TODO(TD-152): verificar contra API real cuando esté disponible.
+ */
+export const EstadoPedidoEnum = z.enum(['pendiente', 'bloqueado', 'recibido']);
+/**
+ * Genera la expresión FIQL para el filtro de estado de pedido de compra.
+ *
+ * El estado se mapea a expresiones FIQL sobre `ALCC_PED_BLOQ` y `ALCC_PED_RECIB`.
+ * Ver `EstadoPedidoEnum` para la documentación completa de la convención.
+ *
+ * @param estado - Valor del enum de estado.
+ * @returns Expresión FIQL para incluir en `rquery` (sin `rquery=`).
+ */
+export function buildEstadoPedidoFiql(estado) {
+    switch (estado) {
+        case 'pendiente':
+            return "ALCC_PED_BLOQ=='';ALCC_PED_RECIB==''";
+        case 'bloqueado':
+            return "ALCC_PED_BLOQ!=''";
+        case 'recibido':
+            return "ALCC_PED_RECIB!=''";
+    }
+}
+/**
+ * Filtros tipados para `freematica_list_pedidos_compra`.
+ *
+ * El endpoint GET /pcmp/v2/pedidos tiene un diseño mixto:
+ * - 4 filtros como **query params nativos** (no FIQL): codEmpresa, desdeFecha, hastaFecha, codProveedor.
+ * - El resto de filtros via **rQuery** (FIQL) con campos ALCC_*.
+ *
+ * Mapeo completo:
+ * | Filtro lógico        | Destino             | Campo API              |
+ * |----------------------|---------------------|------------------------|
+ * | empresa (4c)         | query param nativo  | codEmpresa             |
+ * | codProveedor (10c)   | query param nativo  | codProveedor           |
+ * | fechaPedidoDesde     | query param nativo  | desdeFecha             |
+ * | fechaPedidoHasta     | query param nativo  | hastaFecha             |
+ * | numPedido            | FIQL rquery         | ALCC_NUMDOC            |
+ * | codDocumento (4c)    | FIQL rquery         | ALCC_CODDOC            |
+ * | delegacion (4c)      | FIQL rquery         | ALCC_DELEG             |
+ * | formaPago (3c)       | FIQL rquery         | ALCC_FPAGO             |
+ * | tipoIva (4c)         | FIQL rquery         | ALCC_TIPO_IVA          |
+ * | codCliente (10c)     | FIQL rquery         | ALCC_COD_CLIENTE       |
+ * | codInstalador        | FIQL rquery         | ALCC_COD_INSTALADOR    |
+ * | codMantenedor        | FIQL rquery         | ALCC_COD_MANTENEDOR    |
+ * | fechaEntregaDesde    | FIQL rquery         | ALCC_FCHENTREGA =ge=   |
+ * | fechaEntregaHasta    | FIQL rquery         | ALCC_FCHENTREGA =le=   |
+ * | referencia (40c)     | FIQL rquery         | ALCC_REFERENCIA        |
+ * | estado               | FIQL rquery compuesta| ALCC_PED_BLOQ + ALCC_PED_RECIB |
+ */
+export const ListPedidosCompraFiltersSchema = {
+    ...PaginationSchema,
+    // -------------------------------------------------------------------------
+    // Filtros nativos (query params, NO FIQL)
+    // -------------------------------------------------------------------------
+    empresa: z
+        .string()
+        .length(4)
+        .optional()
+        .describe('Código de empresa Freemática, exactamente 4 caracteres. ' +
+        'Se envía como query param nativo `codEmpresa` (NO FIQL). Ej.: "1000".'),
+    codProveedor: z
+        .string()
+        .min(1)
+        .max(10)
+        .optional()
+        .describe('Código natural del proveedor, hasta 10 caracteres. ' +
+        'Se envía como query param nativo `codProveedor` (NO FIQL). Ej.: "P001".'),
+    fechaPedidoDesde: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Formato ISO YYYY-MM-DD')
+        .optional()
+        .describe('Fecha inicio del rango de búsqueda por fecha de pedido (ISO YYYY-MM-DD). ' +
+        'Se envía como query param nativo `desdeFecha` (NO FIQL). Ej.: "2025-01-01".'),
+    fechaPedidoHasta: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Formato ISO YYYY-MM-DD')
+        .optional()
+        .describe('Fecha fin del rango de búsqueda por fecha de pedido (ISO YYYY-MM-DD). ' +
+        'Se envía como query param nativo `hastaFecha` (NO FIQL). Ej.: "2025-12-31".'),
+    // -------------------------------------------------------------------------
+    // Filtros FIQL (via rquery con campos ALCC_*)
+    // -------------------------------------------------------------------------
+    numPedido: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Número de pedido (hasta 8 dígitos). ' +
+        'FIQL: ALCC_NUMDOC==N. Ej.: 12345678.'),
+    codDocumento: z
+        .string()
+        .length(4)
+        .optional()
+        .describe('Código de tipo de documento, exactamente 4 caracteres. ' +
+        'FIQL: ALCC_CODDOC==XXXX. Ej.: "PCMP".'),
+    delegacion: z
+        .string()
+        .length(4)
+        .optional()
+        .describe('Código de delegación, exactamente 4 caracteres. ' +
+        'FIQL: ALCC_DELEG==XXXX. Ej.: "MAD1".'),
+    formaPago: z
+        .string()
+        .length(3)
+        .optional()
+        .describe('Código de forma de pago, exactamente 3 caracteres. ' +
+        'FIQL: ALCC_FPAGO==XXX. Ej.: "TRF".'),
+    tipoIva: z
+        .string()
+        .length(4)
+        .optional()
+        .describe('Código de tipo de IVA, exactamente 4 caracteres. ' +
+        'FIQL: ALCC_TIPO_IVA==XXXX. Ej.: "GEN1".'),
+    codCliente: z
+        .string()
+        .min(1)
+        .max(10)
+        .optional()
+        .describe('Código natural del cliente asociado al pedido, hasta 10 caracteres. ' +
+        'FIQL: ALCC_COD_CLIENTE==X. Ej.: "0001000".'),
+    codInstalador: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Código del instalador asociado al pedido. ' +
+        'FIQL: ALCC_COD_INSTALADOR==X.'),
+    codMantenedor: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Código del mantenedor asociado al pedido. ' +
+        'FIQL: ALCC_COD_MANTENEDOR==X.'),
+    fechaEntregaDesde: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Formato ISO YYYY-MM-DD')
+        .optional()
+        .describe('Fecha inicio del rango de fecha de entrega del pedido (ISO YYYY-MM-DD). ' +
+        'FIQL: ALCC_FCHENTREGA=ge=YYYY-MM-DD. Ej.: "2025-01-01".'),
+    fechaEntregaHasta: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, 'Formato ISO YYYY-MM-DD')
+        .optional()
+        .describe('Fecha fin del rango de fecha de entrega del pedido (ISO YYYY-MM-DD). ' +
+        'FIQL: ALCC_FCHENTREGA=le=YYYY-MM-DD. Ej.: "2025-12-31".'),
+    referencia: z
+        .string()
+        .min(1)
+        .max(40)
+        .optional()
+        .describe('Referencia exacta del pedido (hasta 40 caracteres). ' +
+        'FIQL: ALCC_REFERENCIA==X (match exacto). Ej.: "REF-2025-001".'),
+    estado: EstadoPedidoEnum
+        .optional()
+        .describe('Estado del pedido de compra. Valores: ' +
+        '"pendiente" (ni bloqueado ni recibido → ALCC_PED_BLOQ==\'\';ALCC_PED_RECIB==\'\'), ' +
+        '"bloqueado" (ALCC_PED_BLOQ!= \'\'), ' +
+        '"recibido" (ALCC_PED_RECIB!=\'\'). ' +
+        'NOTA EMPÍRICA: convención de campo vacío como centinela de "sin valor" en Freemática FIQL; ' +
+        'verificar contra API real si el filtro no produce resultados esperados.'),
+};
+//# sourceMappingURL=pedidos-compras.js.map

package/dist/schemas/pedidos-compras.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pedidos-compras.js","sourceRoot":"","sources":["../../src/schemas/pedidos-compras.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;AAI/E;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAoB;IACxD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,WAAW;YACd,OAAO,sCAAsC,CAAC;QAChD,KAAK,WAAW;YACd,OAAO,mBAAmB,CAAC;QAC7B,KAAK,UAAU;YACb,OAAO,oBAAoB,CAAC;IAChC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,GAAG,gBAAgB;IAEnB,4EAA4E;IAC5E,0CAA0C;IAC1C,4EAA4E;IAE5E,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,MAAM,CAAC,CAAC,CAAC;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,0DAA0D;QAC1D,uEAAuE,CACxE;IAEH,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,EAAE;SACV,QAAQ,CACP,qDAAqD;QACrD,yEAAyE,CAC1E;IAEH,gBAAgB,EAAE,CAAC;SAChB,MAAM,EAAE;SACR,KAAK,CAAC,qBAAqB,EAAE,wBAAwB,CAAC;SACtD,QAAQ,EAAE;SACV,QAAQ,CACP,2EAA2E;QAC3E,6EAA6E,CAC9E;IAEH,gBAAgB,EAAE,CAAC;SAChB,MAAM,EAAE;SACR,KAAK,CAAC,qBAAqB,EAAE,wBAAwB,CAAC;SACtD,QAAQ,EAAE;SACV,QAAQ,CACP,wEAAwE;QACxE,6EAA6E,CAC9E;IAEH,4EAA4E;IAC5E,8CAA8C;IAC9C,4EAA4E;IAE5E,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CACP,sCAAsC;QACtC,sCAAsC,CACvC;IAEH,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,MAAM,CAAC,CAAC,CAAC;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,yDAAyD;QACzD,uCAAuC,CACxC;IAEH,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,MAAM,CAAC,CAAC,CAAC;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,kDAAkD;QAClD,sCAAsC,CACvC;IAEH,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,MAAM,CAAC,CAAC,CAAC;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,qDAAqD;QACrD,oCAAoC,CACrC;IAEH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,MAAM,CAAC,CAAC,CAAC;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,mDAAmD;QACnD,yCAAyC,CAC1C;IAEH,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,EAAE;SACV,QAAQ,CACP,sEAAsE;QACtE,4CAA4C,CAC7C;IAEH,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CACP,4CAA4C;QAC5C,+BAA+B,CAChC;IAEH,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CACP,4CAA4C;QAC5C,+BAA+B,CAChC;IAEH,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,KAAK,CAAC,qBAAqB,EAAE,wBAAwB,CAAC;SACtD,QAAQ,EAAE;SACV,QAAQ,CACP,0EAA0E;QAC1E,yDAAyD,CAC1D;IAEH,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,KAAK,CAAC,qBAAqB,EAAE,wBAAwB,CAAC;SACtD,QAAQ,EAAE;SACV,QAAQ,CACP,uEAAuE;QACvE,yDAAyD,CAC1D;IAEH,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,EAAE;SACV,QAAQ,CACP,sDAAsD;QACtD,+DAA+D,CAChE;IAEH,MAAM,EAAE,gBAAgB;SACrB,QAAQ,EAAE;SACV,QAAQ,CACP,wCAAwC;QACxC,qFAAqF;QACrF,sCAAsC;QACtC,qCAAqC;QACrC,6FAA6F;QAC7F,yEAAyE,CAC1E;CACJ,CAAC"}

package/dist/server-instructions.d.ts

@@ -0,0 +1 @@
+export declare const FREEMATICA_MCP_INSTRUCTIONS: string;

package/dist/server-instructions.js

@@ -0,0 +1,83 @@
+export const FREEMATICA_MCP_INSTRUCTIONS = `
+# Freemática MCP
+
+Este servidor expone operaciones del API REST de Freemática como tools MCP.
+
+## Tools disponibles (8)
+
+### Materiales (1)
+
+- **freematica_list_materiales_asignados_servicios** — Lista de material
+  asignado a servicios (sin parámetros). Devuelve { items, count, total }.
+
+### Datos maestros (1)
+
+- **freematica_get_master_data** — Devuelve un catálogo de datos maestros.
+  Parámetro \`catalog\` (enum): tipos-contrato, tipo-instalacion, clases-servicios,
+  tipos-casos, subtipos-casos, tipos-oportunidad-negocio, tipos-impuestos,
+  naturalezas-abono, paises, nacionalidades, provincias, poblaciones, empresas,
+  delegaciones, lineas-negocio, cargos-clientes, familias, subfamilias (18 catálogos).
+  Devuelve { catalog, items, count, total }.
+
+### Clientes (2)
+
+- **freematica_list_clientes(page=1, items=20)** — Lista paginada de clientes.
+- **freematica_get_cliente(id)** — Detalle de un cliente. \`id\` = \`idReg\` opaco.
+
+### Contactos clientes (1)
+
+- **freematica_list_contactos_clientes(page=1, items=20)** — Lista paginada.
+
+### Oportunidades de negocio (3)
+
+- **freematica_list_oportunidades_negocio(page=1, items=20)** — Lista paginada.
+- **freematica_get_oportunidad_negocio(id)** — Detalle. \`id\` = \`idReg\` opaco.
+- **freematica_get_oportunidad_negocio_datos_ampliados(id)** — Datos ampliados.
+  Puede devolver not_found si la oportunidad no tiene datos extra.
+
+## Paginación
+
+Todas las tools \`freematica_list_*\` aceptan dos parámetros opcionales:
+
+- **page** (int, ≥1, default 1): página a recuperar, 1-indexed.
+- **items** (int, 1..50, default 20): items por página.
+
+La respuesta siempre incluye \`total\` = total de elementos en el dataset,
+para que puedas paginar (\`page = total / items + 1\`).
+
+AVISO: NO uses \`page=0\` (este parámetro lo bloquea al mínimo 1). El API real
+trata \`page=0\` como "devuelve TODO el dataset" — puede ser muchos MB.
+
+## IDs opacos en endpoints de detalle
+
+Las tools \`freematica_get_*\` requieren un \`id\` que es el campo \`idReg\` de los
+items en los listados — un string opaco base64 como \`MV9fMTAwMA==\` o \`MDJfXzI=\`.
+
+NO uses códigos naturales como \`COD_CLI\` o \`ID_OPORTUNIDAD\` — el API devuelve
+not_found. Patrón típico:
+
+1. Llamar a \`freematica_list_clientes\` y localizar el cliente que buscas.
+2. Tomar su campo \`idReg\`.
+3. Pasarlo como \`id\` a \`freematica_get_cliente\`.
+
+## Resolución de códigos a nombres
+
+Muchas tools devuelven códigos como \`COD_TIPO_OPOR: "01"\` o \`COD_GRUPO_CLI: 1.0\`.
+Para mostrar nombres legibles, usa \`freematica_get_master_data\` con el catálogo
+correspondiente y haz el lookup.
+
+## Manejo de errores
+
+Las llamadas pueden fallar con uno de estos códigos:
+
+| Código | Significado | Acción del LLM |
+|---|---|---|
+| invalid_token | Credenciales caducadas o inválidas | Avisar al usuario; renovar en Nubiia. |
+| forbidden | Permisos insuficientes | Explicar; no reintentar. |
+| not_found | Recurso o endpoint inexistente | Comprobar el id; no reintentar (excepto datos-ampliados, que puede ser un caso normal). |
+| rate_limit_exceeded | Demasiadas peticiones | Esperar y reintentar una vez. |
+| server_error | Error 5xx del API | Reintentar una vez con backoff. |
+| network_error | Problemas de red | Reintentar una vez tras 2s. |
+| unexpected_error | Error no clasificado | Loggear y reintentar una vez. |
+`.trim();
+//# sourceMappingURL=server-instructions.js.map

package/dist/server-instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../src/server-instructions.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiF1C,CAAC,IAAI,EAAE,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { FreematicaClient } from './clients/freematica-client.js';
+export interface CreateFreematicaServerOptions {
+    client: FreematicaClient;
+}
+export declare function createFreematicaServer(opts: CreateFreematicaServerOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,41 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FREEMATICA_MCP_INSTRUCTIONS } from './server-instructions.js';
+import { registerAlbaranesTools } from './tools/albaranes.js';
+import { registerCalendariosTools } from './tools/calendarios.js';
+import { registerCarteraTools } from './tools/cartera.js';
+import { registerClientesTools } from './tools/clientes.js';
+import { registerContactosClientesTools } from './tools/contactos-clientes.js';
+import { registerContabilidadTools } from './tools/contabilidad.js';
+import { registerContratosTools } from './tools/contratos.js';
+import { registerFacturasComprasTools } from './tools/facturas-compras.js';
+import { registerFacturasElectronicasTools } from './tools/facturas-electronicas.js';
+import { registerFacturasVentasTools } from './tools/facturas-ventas.js';
+import { registerLocalizacionesTools } from './tools/localizaciones.js';
+import { registerMasterDataTools } from './tools/master-data.js';
+import { registerOportunidadesNegocioTools } from './tools/oportunidades-negocio.js';
+import { registerPedidosComprasTools } from './tools/pedidos-compras.js';
+import { registerPersonalTools } from './tools/personal.js';
+import { registerPrlTools } from './tools/prl.js';
+import { registerProveedoresTools } from './tools/proveedores.js';
+export function createFreematicaServer(opts) {
+    const server = new McpServer({ name: 'freematica-mcp', version: '0.6.0' }, { instructions: FREEMATICA_MCP_INSTRUCTIONS });
+    registerContratosTools(server, opts.client);
+    registerMasterDataTools(server, opts.client);
+    registerClientesTools(server, opts.client);
+    registerContactosClientesTools(server, opts.client);
+    registerOportunidadesNegocioTools(server, opts.client);
+    registerCarteraTools(server, opts.client);
+    registerFacturasVentasTools(server, opts.client);
+    registerFacturasComprasTools(server, opts.client);
+    registerPedidosComprasTools(server, opts.client);
+    registerProveedoresTools(server, opts.client);
+    registerLocalizacionesTools(server, opts.client);
+    registerContabilidadTools(server, opts.client);
+    registerPrlTools(server, opts.client);
+    registerPersonalTools(server, opts.client);
+    registerCalendariosTools(server, opts.client);
+    registerFacturasElectronicasTools(server, opts.client);
+    registerAlbaranesTools(server, opts.client);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,8BAA8B,EAAE,MAAM,+BAA+B,CAAC;AAC/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAC3E,OAAO,EAAE,iCAAiC,EAAE,MAAM,kCAAkC,CAAC;AACrF,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,iCAAiC,EAAE,MAAM,kCAAkC,CAAC;AACrF,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAMlE,MAAM,UAAU,sBAAsB,CAAC,IAAmC;IACxE,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,EAC5C,EAAE,YAAY,EAAE,2BAA2B,EAAE,CAC9C,CAAC;IAEF,sBAAsB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5C,uBAAuB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7C,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3C,8BAA8B,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACpD,iCAAiC,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACvD,oBAAoB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1C,2BAA2B,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACjD,4BAA4B,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAClD,2BAA2B,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACjD,wBAAwB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9C,2BAA2B,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACjD,yBAAyB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/C,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACtC,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3C,wBAAwB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9C,iCAAiC,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACvD,sBAAsB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAE5C,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tools/albaranes.d.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { FreematicaClient } from '../clients/freematica-client.js';
+/**
+ * Registra las tools de albaranes en el servidor MCP.
+ *
+ * Tools registradas:
+ * - `freematica_list_albaranes_ventas`: lista paginada de albaranes de ventas.
+ * - `freematica_get_albaran_venta`: detalle de un albarán de venta por idReg.
+ * - `freematica_list_albaranes_factura`: lista de vinculaciones albarán↔factura.
+ * - `freematica_get_albaran_factura`: detalle de una vinculación por idReg.
+ * - `freematica_list_resultados_facturacion`: resultados batch facturación vigilancia.
+ *
+ * @param server - Instancia del servidor MCP.
+ * @param client - Cliente Freemática autenticado.
+ */
+export declare function registerAlbaranesTools(server: McpServer, client: FreematicaClient): void;

package/dist/tools/albaranes.js

@@ -0,0 +1,202 @@
+import { z } from 'zod';
+import { FreematicaError } from '../clients/base-client.js';
+import { ListAlbaranesFacturaFiltersSchema, ListAlbaranesVentasFiltersSchema, ListResultadosFacturacionFiltersSchema, } from '../schemas/albaranes.js';
+import { error, ok, okList } from './helpers.js';
+// ---------------------------------------------------------------------------
+// Tool names
+// ---------------------------------------------------------------------------
+const LIST_ALBARANES_VENTAS_TOOL = 'freematica_list_albaranes_ventas';
+const GET_ALBARAN_VENTA_TOOL = 'freematica_get_albaran_venta';
+const LIST_ALBARANES_FACTURA_TOOL = 'freematica_list_albaranes_factura';
+const GET_ALBARAN_FACTURA_TOOL = 'freematica_get_albaran_factura';
+const LIST_RESULTADOS_FACTURACION_TOOL = 'freematica_list_resultados_facturacion';
+// ---------------------------------------------------------------------------
+// Descriptions
+// ---------------------------------------------------------------------------
+const LIST_ALBARANES_VENTAS_DESCRIPTION = [
+    'Devuelve la lista paginada de albaranes de ventas de Freemática.',
+    '',
+    'Cada item contiene campos con prefijo ALVC_* (cabecera) y ALVL_* (líneas).',
+    'Campos destacados: ALVC_CODEMP (empresa), ALVC_DELEG (delegación),',
+    'ALVC_CODCLI (cliente), ALVC_CODDOC (código documento), ALVC_NUMDOC (número),',
+    'ALVC_FCHDOC (fecha), ALVC_SERIEFRA (serie factura), ALVC_IND_NOFAC (no facturar),',
+    'ALVC_FPAGO (forma pago), más `idReg` opaco para el endpoint singular.',
+    '',
+    'Los filtros principales (empresa, delegacion, codCliente, codDocumento, fechaDesde,',
+    'fechaHasta) se envían como query params NATIVOS del endpoint (no FIQL).',
+    'El campo `empresa` es requerido por el endpoint de Freemática.',
+    '',
+    'Paginación 1-indexed.',
+].join('\n');
+const GET_ALBARAN_VENTA_DESCRIPTION = [
+    'Devuelve el detalle completo de un albarán de venta.',
+    '',
+    'El parámetro `id` DEBE ser el campo `idReg` (string opaco base64) que aparece en',
+    'los items de freematica_list_albaranes_ventas. NO usar ALVC_NUMDOC ni otro código natural.',
+].join('\n');
+const LIST_ALBARANES_FACTURA_DESCRIPTION = [
+    'Devuelve la lista paginada de vinculaciones albarán↔factura de Freemática.',
+    '',
+    'Cada item contiene campos con prefijo FVCA_*: FVCA_CODEMP (empresa),',
+    'FVCA_SERIEFRA (serie factura), FVCA_NUMFRA (número factura), FVCA_CODCLI (cliente),',
+    'FVCA_NUMALB (número albarán), FVCA_FCHALB (fecha albarán), FVCA_FCHFAC (fecha factura),',
+    'FVCA_NUMPED (número pedido), FVCA_CODDOC (código documento), más `idReg` opaco.',
+    '',
+    'El filtro `idReg` es un query param nativo. Los filtros empresa, serie, numFactura',
+    'y codCliente se envían como FIQL en el parámetro rQuery.',
+    '',
+    'Casos de uso principales:',
+    '  - Buscar qué facturas incluyen un albarán determinado (filtrar por FVCA_NUMALB vía rQuery)',
+    '  - Listar todos los albaranes vinculados a una factura (filtrar por numFactura + serie)',
+    '',
+    'Paginación 1-indexed.',
+].join('\n');
+const GET_ALBARAN_FACTURA_DESCRIPTION = [
+    'Devuelve el detalle completo de un registro de vinculación albarán↔factura.',
+    '',
+    'El parámetro `id` DEBE ser el campo `idReg` (string opaco base64) que aparece en',
+    'los items de freematica_list_albaranes_factura. NO usar FVCA_NUMFRA ni otro código natural.',
+].join('\n');
+const LIST_RESULTADOS_FACTURACION_DESCRIPTION = [
+    'Devuelve los resultados del proceso batch de facturación automática de vigilancia.',
+    '',
+    'Cada item contiene campos con prefijo FACT_*: FACT_EMP (empresa), FACT_DELEG (delegación),',
+    'FACT_CAL (año calendario), FACT_MES (mes), FACT_CTRT (contrato), FACT_SERV (servicio),',
+    'FACT_TIPFAC (tipo facturación), FACT_COD_CLI (cliente), FACT_TRASP (estado traspaso),',
+    'FACT_NUMDOC (documento generado), FACT_IMP_BASE (importe base), FACT_IMPF (importe final),',
+    'y múltiples campos de horas (FACT_HHD, FACT_HHF, FACT_HHG, FACT_HHN, etc.).',
+    '',
+    'Todos los filtros se envían como FIQL en el parámetro rquery.',
+    '',
+    'Paginación 1-indexed. El param `order` es nativo del endpoint.',
+].join('\n');
+// ---------------------------------------------------------------------------
+// Register function
+// ---------------------------------------------------------------------------
+/**
+ * Registra las tools de albaranes en el servidor MCP.
+ *
+ * Tools registradas:
+ * - `freematica_list_albaranes_ventas`: lista paginada de albaranes de ventas.
+ * - `freematica_get_albaran_venta`: detalle de un albarán de venta por idReg.
+ * - `freematica_list_albaranes_factura`: lista de vinculaciones albarán↔factura.
+ * - `freematica_get_albaran_factura`: detalle de una vinculación por idReg.
+ * - `freematica_list_resultados_facturacion`: resultados batch facturación vigilancia.
+ *
+ * @param server - Instancia del servidor MCP.
+ * @param client - Cliente Freemática autenticado.
+ */
+export function registerAlbaranesTools(server, client) {
+    // -------------------------------------------------------------------------
+    // freematica_list_albaranes_ventas
+    // -------------------------------------------------------------------------
+    server.tool(LIST_ALBARANES_VENTAS_TOOL, LIST_ALBARANES_VENTAS_DESCRIPTION, ListAlbaranesVentasFiltersSchema, { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async ({ page, items, empresa, delegacion, codCliente, codDocumento, fechaDesde, fechaHasta, order, }) => {
+        try {
+            const result = await client.listAlbaranesVentas({
+                page,
+                items,
+                empresa,
+                delegacion,
+                codCliente,
+                codDocumento,
+                fechaDesde,
+                fechaHasta,
+                order,
+            });
+            return okList({ items: result.items, total: result.total, page, itemsPerPage: items });
+        }
+        catch (err) {
+            if (err instanceof FreematicaError)
+                return error(err);
+            return error(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+    // -------------------------------------------------------------------------
+    // freematica_get_albaran_venta
+    // -------------------------------------------------------------------------
+    server.tool(GET_ALBARAN_VENTA_TOOL, GET_ALBARAN_VENTA_DESCRIPTION, {
+        id: z
+            .string()
+            .min(1)
+            .describe('idReg opaco del albarán de venta (campo "idReg" en los items de freematica_list_albaranes_ventas).'),
+    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async ({ id }) => {
+        try {
+            const albaran = await client.getAlbaranVenta(id);
+            return ok(albaran);
+        }
+        catch (err) {
+            if (err instanceof FreematicaError)
+                return error(err);
+            return error(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+    // -------------------------------------------------------------------------
+    // freematica_list_albaranes_factura
+    // -------------------------------------------------------------------------
+    server.tool(LIST_ALBARANES_FACTURA_TOOL, LIST_ALBARANES_FACTURA_DESCRIPTION, ListAlbaranesFacturaFiltersSchema, { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async ({ page, items, idReg, empresa, serie, numFactura, codCliente, }) => {
+        try {
+            const result = await client.listAlbaranesFactura({
+                page,
+                items,
+                idReg,
+                empresa,
+                serie,
+                numFactura,
+                codCliente,
+            });
+            return okList({ items: result.items, total: result.total, page, itemsPerPage: items });
+        }
+        catch (err) {
+            if (err instanceof FreematicaError)
+                return error(err);
+            return error(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+    // -------------------------------------------------------------------------
+    // freematica_get_albaran_factura
+    // -------------------------------------------------------------------------
+    server.tool(GET_ALBARAN_FACTURA_TOOL, GET_ALBARAN_FACTURA_DESCRIPTION, {
+        id: z
+            .string()
+            .min(1)
+            .describe('idReg opaco del registro albarán-factura (campo "idReg" en los items de freematica_list_albaranes_factura).'),
+    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async ({ id }) => {
+        try {
+            const albaran = await client.getAlbaranFactura(id);
+            return ok(albaran);
+        }
+        catch (err) {
+            if (err instanceof FreematicaError)
+                return error(err);
+            return error(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+    // -------------------------------------------------------------------------
+    // freematica_list_resultados_facturacion
+    // -------------------------------------------------------------------------
+    server.tool(LIST_RESULTADOS_FACTURACION_TOOL, LIST_RESULTADOS_FACTURACION_DESCRIPTION, ListResultadosFacturacionFiltersSchema, { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async ({ page, items, empresa, delegacion, codCliente, calendario, mes, contrato, servicio, tipoFac, traspasado, order, }) => {
+        try {
+            const result = await client.listResultadosFacturacion({
+                page,
+                items,
+                empresa,
+                delegacion,
+                codCliente,
+                calendario,
+                mes,
+                contrato,
+                servicio,
+                tipoFac,
+                traspasado,
+                order,
+            });
+            return okList({ items: result.items, total: result.total, page, itemsPerPage: items });
+        }
+        catch (err) {
+            if (err instanceof FreematicaError)
+                return error(err);
+            return error(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+}
+//# sourceMappingURL=albaranes.js.map