@frihet/mcp-server 1.17.0 → 2.0.1

package/dist/tools/einvoice.js

@@ -28,7 +28,7 @@
  *   POST /v1/invoices/:id/ksef/submit      — Poland KSeF (stub — endpoint not yet exposed; returns unavailable)
  */
 import { z } from "zod/v4";
-import { withToolLogging, mutateContent, getContent, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, } from "./shared.js";
+import { withToolLogging, mutateContent, getContent, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, } from "./shared.js";
 /* ------------------------------------------------------------------ */
 /*  Honest "backend endpoint not yet available" result                  */
 /* ------------------------------------------------------------------ */
@@ -99,6 +99,20 @@ export const eInvoiceFormatSchema = z.enum([
     "peppol-bis-3",
     "facturae",
 ]);
+/** Export is narrower than dispatch/validation. The ERP public export API
+ * exposes Factur-X EN16931 only; accepting Extended/Basic/Minimum here and
+ * silently mapping them to EN16931 would produce the wrong fiscal profile. */
+export const eInvoiceExportFormatSchema = z.enum([
+    "xrechnung-cii",
+    "xrechnung-ubl",
+    "facturx-en16931",
+    "fatturapa",
+    "ubl",
+    "cii",
+    "peppol-bis-3",
+    "fa-2-ksef",
+    "facturae",
+]);
 /* ------------------------------------------------------------------ */
 /*  Output schemas                                                      */
 /* ------------------------------------------------------------------ */
@@ -410,19 +424,23 @@ export function registerEInvoiceTools(server, _client) {
     // -- einvoice_export --
     server.registerTool("einvoice_export", {
         title: "Export E-Invoice XML",
-        description: "Export an invoice as e-invoicing XML in a specific format. " +
+        description: "Export an invoice as inline e-invoicing XML in a specific format. " +
             "Supports Facturae (ES B2G), XRechnung-CII (DE), XRechnung-UBL (DE), " +
-            "Factur-X profiles (FR), FatturaPA (IT), PEPPOL-BIS-3 (EU network), UBL and CII (generic). " +
+            "Factur-X EN16931 (FR), FatturaPA (IT), PEPPOL-BIS-3 (EU network), FA-2-KSeF (PL), UBL and CII (generic). " +
+            "Factur-X Extended, Basic and Minimum are not exposed by this endpoint and are refused rather than collapsed to a different profile. " +
             "For Facturae, set signed=true to get XAdES-enveloped XML for FACe/AEAT submission. " +
-            "Returns a signed download URL valid for 24 hours. " +
+            "Returns the generated XML inline with its MIME type and filename. " +
             "\n\n" +
             "/ Exporta una factura como XML de facturacion electronica en el formato especificado. " +
             "Para Facturae con signed=true devuelve XML firmado XAdES para envio a FACe/AEAT.",
-        annotations: READ_ONLY_ANNOTATIONS,
+        // Conservative static classification: signed=true exercises a workspace
+        // signing certificate, so the tool cannot truthfully be advertised as a
+        // read-only operation even though unsigned generation is side-effect free.
+        annotations: UPDATE_ANNOTATIONS,
         inputSchema: {
             invoiceId: z.string().describe("Frihet invoice ID to export / ID de la factura a exportar"),
-            format: eInvoiceFormatSchema.describe("E-invoice format. Choose based on recipient country: " +
-                "ES B2G→facturae, DE→xrechnung-cii/ubl, FR→facturx-*, IT→fatturapa, EU PEPPOL→peppol-bis-3, " +
+            format: eInvoiceExportFormatSchema.describe("E-invoice format. Choose based on recipient country: " +
+                "ES B2G→facturae, DE→xrechnung-cii/ubl, FR→facturx-en16931, IT→fatturapa, PL→fa-2-ksef, EU PEPPOL→peppol-bis-3, " +
                 "generic→ubl or cii / Formato de factura electronica."),
             signed: z.boolean().optional().describe("If true, returns XAdES-enveloped signed XML (Facturae only). Requires workspace signing certificate configured. " +
                 "/ Si true, devuelve XML firmado XAdES (solo Facturae). Requiere certificado de firma configurado."),
@@ -439,7 +457,8 @@ export function registerEInvoiceTools(server, _client) {
                         `  Format: ${format}\n` +
                         `  Signed: ${signed ?? false}\n` +
                         `  Filename: ${result.filename}\n` +
-                        `  Download URL: ${result.xmlUrl}`),
+                        `  Content-Type: ${result.contentType}\n` +
+                        `  XML: returned inline (${result.xml.length} characters)`),
                 ],
                 structuredContent: result,
             };
@@ -460,7 +479,8 @@ export function registerEInvoiceTools(server, _client) {
     // -- face_submit --
     server.registerTool("face_submit", {
         title: "Submit to FACe (Spain B2G)",
-        description: "Submit a Facturae-formatted invoice to the Spanish FACe (Punto General de Entrada de Facturas Electrónicas) B2G portal. " +
+        description: "Requires confirm=true as a local client/agent interlock before submitting a Facturae invoice to Spain's FACe B2G portal. " +
+            "This flag is not server-verifiable human attestation and is never forwarded to the API. " +
             "The invoice must have a recipient with DIR3 administrative unit codes (órgano gestor, unidad tramitadora, oficina contable). " +
             "Returns a submission reference (registro) that can be used with face_status to poll the portal. " +
             "\n\n" +
@@ -477,9 +497,22 @@ export function registerEInvoiceTools(server, _client) {
             invoiceId: z.string().describe("Frihet invoice ID to submit / ID de la factura a enviar a FACe"),
             mode: z.enum(["mock", "sandbox", "production"]).optional().describe("Submission mode: mock (local sim), sandbox (FACe pre-prod), production (live). Default: production. " +
                 "/ Modo de envío: mock (simulación local), sandbox (pre-producción FACe), production (real). Por defecto: production."),
+            confirm: z.boolean().describe("Must be true to pass the local submission interlock in every mode, including mock and sandbox. " +
+                "This is not actor/resource/payload/expiry-bound attestation. / Debe ser true para superar el interlock local en todos los modos."),
         },
         outputSchema: faceSubmitOutput,
-    }, async ({ invoiceId, mode }) => withToolLogging("face_submit", async () => {
+    }, async ({ invoiceId, mode, confirm }) => withToolLogging("face_submit", async () => {
+        if (!confirm) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "Error: face_submit requires confirm=true before any FACe submission or simulation. " +
+                            "It is a local client/agent interlock, not server-verifiable human attestation. " +
+                            "/ Se requiere confirm=true antes de cualquier envío o simulación FACe.",
+                    }],
+                isError: true,
+            };
+        }
         const plannedEndpoint = `/v1/invoices/${invoiceId}/face/submit`;
         const resolvedMode = mode ?? "production";
         try {
@@ -562,7 +595,8 @@ export function registerEInvoiceTools(server, _client) {
     // -- ticketbai_submit --
     server.registerTool("ticketbai_submit", {
         title: "Submit TicketBAI (Basque Country)",
-        description: "Submit an invoice to the Basque Country TicketBAI e-invoicing system. " +
+        description: "Requires confirm=true as a local client/agent interlock before submitting an invoice to TicketBAI. " +
+            "This flag is not server-verifiable human attestation and is never forwarded to the API. " +
             "Territory is auto-detected from the workspace address (Bizkaia → BATUZ/LROE, Gipuzkoa → Gipuzkoa TicketBAI, Araba → Araba TicketBAI). " +
             "Returns the submission TicketBAI ID (TBAI identifier) and QR code URL for printing on the invoice. " +
             "\n\n" +
@@ -577,9 +611,22 @@ export function registerEInvoiceTools(server, _client) {
             invoiceId: z.string().describe("Frihet invoice ID to submit / ID de la factura a enviar"),
             sandbox: z.boolean().optional().describe("If true, submits to the hacienda test endpoint instead of production. Default: false. " +
                 "/ Si true, envía al entorno de pruebas de la hacienda. Por defecto: false."),
+            confirm: z.boolean().describe("Must be true to pass the local submission interlock in both sandbox and production. " +
+                "This is not actor/resource/payload/expiry-bound attestation. / Debe ser true para superar el interlock local."),
         },
         outputSchema: ticketbaiSubmitOutput,
-    }, async ({ invoiceId, sandbox }) => withToolLogging("ticketbai_submit", async () => {
+    }, async ({ invoiceId, sandbox, confirm }) => withToolLogging("ticketbai_submit", async () => {
+        if (!confirm) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "Error: ticketbai_submit requires confirm=true before any TicketBAI submission. " +
+                            "It is a local client/agent interlock, not server-verifiable human attestation. " +
+                            "/ Se requiere confirm=true antes de cualquier envío TicketBAI.",
+                    }],
+                isError: true,
+            };
+        }
         const plannedEndpoint = `/v1/invoices/${invoiceId}/ticketbai/submit`;
         const isSandbox = sandbox ?? false;
         try {

package/dist/tools/fiscal.d.ts

@@ -12,10 +12,9 @@
  *
  * NOTE: ticketbai_status is registered by einvoice.ts (canonical, more complete impl).
  *
- * REST surface: /v1/fiscal/* (documented: pending — backend ships separately)
- *
- * NOTE: ERP backend endpoints /v1/fiscal/* are planned. Tools are wired
- * and will surface 404 errors until the backend ships.
+ * REST surface: Frihet-ERP functions/src/publicApi.ts serves READ-ONLY
+ * GET /v1/fiscal/modelo/{303,130,390,347}. Modelo 180 has no route; its tool
+ * returns NOT_DEPLOYED without calling. Period params: src/fiscal-period.ts.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { IFrihetClient } from "../client-interface.js";

package/dist/tools/fiscal.js

@@ -12,14 +12,82 @@
  *
  * NOTE: ticketbai_status is registered by einvoice.ts (canonical, more complete impl).
  *
- * REST surface: /v1/fiscal/* (documented: pending — backend ships separately)
- *
- * NOTE: ERP backend endpoints /v1/fiscal/* are planned. Tools are wired
- * and will surface 404 errors until the backend ships.
+ * REST surface: Frihet-ERP functions/src/publicApi.ts serves READ-ONLY
+ * GET /v1/fiscal/modelo/{303,130,390,347}. Modelo 180 has no route; its tool
+ * returns NOT_DEPLOYED without calling. Period params: src/fiscal-period.ts.
  */
 import { z } from "zod/v4";
-import { withToolLogging, formatRecord, getContent, mutateContent, READ_ONLY_ANNOTATIONS, ERROR_CONTENT_ANNOTATIONS, fiscalModeloSummaryOutput, verifactuStatusOutput, } from "./shared.js";
-import { withBackendGuard, isBackendNotFound } from "./backend-availability.js";
+import { withToolLogging, confirmationRequiredError, formatRecord, getContent, mutateContent, READ_ONLY_ANNOTATIONS, ERROR_CONTENT_ANNOTATIONS, fiscalModeloSummaryOutput, verifactuStatusOutput, } from "./shared.js";
+import { withBackendGuard, isBackendNotFound, notDeployedError } from "./backend-availability.js";
+import { FISCAL_PERIOD_RULES } from "../fiscal-period.js";
+function fiscalPeriodError(toolName, structured, message) {
+    return {
+        content: [{ type: "text", text: `Error: ${message}`, annotations: ERROR_CONTENT_ANNOTATIONS }],
+        structuredContent: { ...structured, tool: toolName, message },
+        isError: true,
+    };
+}
+/**
+ * READ-ONLY modelo summary with a fail-closed period contract:
+ *   1. a supplied period must match the backend's own format, or no call is made;
+ *   2. the modelo the backend reports (`modeloCode`/`model`) must be the one
+ *      requested, or the figures are withheld (MODELO_MISMATCH);
+ *   3. the period the backend reports must be well-formed and, when one was
+ *      requested, identical to it — otherwise the figures belong to another
+ *      period and are withheld (PERIOD_MISMATCH), never shown under the
+ *      requested label.
+ */
+function invalidFiscalPeriod(toolName, modeloCode, period) {
+    const rule = FISCAL_PERIOD_RULES[modeloCode];
+    if (!rule) {
+        return notDeployedError(toolName, `/v1/fiscal/modelo/${modeloCode}`);
+    }
+    if (period === undefined || rule.pattern.test(period))
+        return undefined;
+    return fiscalPeriodError(toolName, { error: "invalid_period", code: "INVALID_PERIOD", modeloCode, requested: period, expectedFormat: rule.format }, `Invalid period for Modelo ${modeloCode}: use ${rule.format}. No request was sent. ` +
+        `/ Periodo no valido para el Modelo ${modeloCode}: usa ${rule.format}. No se ha enviado ninguna peticion.`);
+}
+async function fiscalModeloSummary(client, toolName, modeloCode, period, title) {
+    const rule = FISCAL_PERIOD_RULES[modeloCode];
+    if (!rule) {
+        return notDeployedError(toolName, `/v1/fiscal/modelo/${modeloCode}`);
+    }
+    const result = await client.getFiscalModeloSummary(modeloCode, period);
+    // The backend names the modelo in `modeloCode` and/or legacy `model`
+    // (Frihet-ERP publicApi.ts). Every key present must name the requested
+    // modelo, and at least one must be present; otherwise another modelo's
+    // figures would be shown under this one's label.
+    const returnedModelos = [result["modeloCode"], result["model"]].filter((v) => v !== undefined);
+    const modeloAgrees = returnedModelos.length > 0 && returnedModelos.every((v) => v === modeloCode);
+    if (!modeloAgrees) {
+        return fiscalPeriodError(toolName, {
+            error: "modelo_mismatch",
+            code: "MODELO_MISMATCH",
+            requestedModelo: modeloCode,
+            returnedModelo: returnedModelos.map((v) => (typeof v === "string" ? v : null)),
+        }, `Frihet returned a summary that is not identifiable as Modelo ${modeloCode}, so no figures are shown ` +
+            `(they would be mislabelled). Do NOT state any amount for this modelo; retry or contact support. ` +
+            `/ Frihet devolvio un resumen que no corresponde al Modelo ${modeloCode}; no se muestran cifras. ` +
+            `NO indiques ningun importe para este modelo.`);
+    }
+    const returned = typeof result["period"] === "string" ? result["period"] : null;
+    const year = result["year"];
+    const yearAgrees = year === undefined || (returned !== null && String(year) === returned);
+    const matches = returned !== null &&
+        rule.pattern.test(returned) &&
+        yearAgrees &&
+        (period === undefined || returned === period);
+    if (!matches) {
+        return fiscalPeriodError(toolName, { error: "period_mismatch", code: "PERIOD_MISMATCH", modeloCode, requested: period ?? null, returned }, `Frihet returned a Modelo ${modeloCode} summary whose period does not match the request, so no figures are shown ` +
+            `(they would be mislabelled). Do NOT state any amount for this period; retry or contact support. ` +
+            `/ Frihet devolvio un resumen del Modelo ${modeloCode} de un periodo distinto al solicitado; no se muestran cifras. ` +
+            `NO indiques ningun importe para este periodo.`);
+    }
+    return {
+        content: [getContent(formatRecord(title, result))],
+        structuredContent: result,
+    };
+}
 export function registerFiscalTools(server, client) {
     // -- get_modelo_303_summary --
     server.registerTool("get_modelo_303_summary", {
@@ -34,16 +102,11 @@ export function registerFiscalTools(server, client) {
             period: z
                 .string()
                 .optional()
-                .describe("Period in format YYYY-QN (e.g. '2026-Q1') or YYYY for annual / Periodo en formato YYYY-QN o YYYY"),
+                .describe("Quarter in format YYYY-QN (e.g. '2026-Q1'); defaults to the current quarter / Trimestre en formato YYYY-QN; por defecto el trimestre actual"),
         },
         outputSchema: fiscalModeloSummaryOutput,
-    }, async ({ period }) => withToolLogging("get_modelo_303_summary", () => withBackendGuard("get_modelo_303_summary", "/v1/fiscal/303", async () => {
-        const result = await client.getFiscalModeloSummary("303", period);
-        return {
-            content: [getContent(formatRecord("Modelo 303 Summary", result))],
-            structuredContent: result,
-        };
-    })));
+    }, async ({ period }) => withToolLogging("get_modelo_303_summary", async () => invalidFiscalPeriod("get_modelo_303_summary", "303", period) ??
+        withBackendGuard("get_modelo_303_summary", "/v1/fiscal/modelo/303", () => fiscalModeloSummary(client, "get_modelo_303_summary", "303", period, "Modelo 303 Summary"))));
     // -- get_modelo_130_summary --
     server.registerTool("get_modelo_130_summary", {
         title: "Get Modelo 130 Summary (IRPF Estimated Payment)",
@@ -57,16 +120,11 @@ export function registerFiscalTools(server, client) {
             period: z
                 .string()
                 .optional()
-                .describe("Period in format YYYY-QN (e.g. '2026-Q1') / Periodo en formato YYYY-QN"),
+                .describe("Quarter in format YYYY-QN (e.g. '2026-Q1'); defaults to the current quarter / Trimestre en formato YYYY-QN; por defecto el trimestre actual"),
         },
         outputSchema: fiscalModeloSummaryOutput,
-    }, async ({ period }) => withToolLogging("get_modelo_130_summary", () => withBackendGuard("get_modelo_130_summary", "/v1/fiscal/130", async () => {
-        const result = await client.getFiscalModeloSummary("130", period);
-        return {
-            content: [getContent(formatRecord("Modelo 130 Summary", result))],
-            structuredContent: result,
-        };
-    })));
+    }, async ({ period }) => withToolLogging("get_modelo_130_summary", async () => invalidFiscalPeriod("get_modelo_130_summary", "130", period) ??
+        withBackendGuard("get_modelo_130_summary", "/v1/fiscal/modelo/130", () => fiscalModeloSummary(client, "get_modelo_130_summary", "130", period, "Modelo 130 Summary"))));
     // -- get_modelo_390_summary --
     server.registerTool("get_modelo_390_summary", {
         title: "Get Modelo 390 Summary (IVA Annual Recap)",
@@ -83,21 +141,15 @@ export function registerFiscalTools(server, client) {
                 .describe("Year in format YYYY (e.g. '2025') / Ejercicio en formato YYYY"),
         },
         outputSchema: fiscalModeloSummaryOutput,
-    }, async ({ period }) => withToolLogging("get_modelo_390_summary", () => withBackendGuard("get_modelo_390_summary", "/v1/fiscal/390", async () => {
-        const result = await client.getFiscalModeloSummary("390", period);
-        return {
-            content: [getContent(formatRecord("Modelo 390 Summary", result))],
-            structuredContent: result,
-        };
-    })));
+    }, async ({ period }) => withToolLogging("get_modelo_390_summary", async () => invalidFiscalPeriod("get_modelo_390_summary", "390", period) ??
+        withBackendGuard("get_modelo_390_summary", "/v1/fiscal/modelo/390", () => fiscalModeloSummary(client, "get_modelo_390_summary", "390", period, "Modelo 390 Summary"))));
     // -- get_modelo_180_summary --
     server.registerTool("get_modelo_180_summary", {
         title: "Get Modelo 180 Summary (IRPF Rentals Annual)",
-        description: "Get IRPF annual informative summary for rental income withholdings (Modelo 180, Spain). " +
-            "Returns total retentions per tenant, property, and annual aggregate. " +
-            "Example: period='2025' / " +
-            "Obtiene el resumen anual de retenciones sobre alquileres para el Modelo 180. " +
-            "Devuelve retenciones totales por inquilino, inmueble y agregado anual.",
+        description: "NOT DEPLOYED: Modelo 180 (annual informative return of IRPF withholdings on rental income, Spain) has no Frihet backend yet; " +
+            "calling this tool returns a NOT_DEPLOYED error and never data. " +
+            "/ NO DESPLEGADO: el Modelo 180 (resumen anual de retenciones sobre alquileres) aun no tiene backend en Frihet; " +
+            "esta herramienta devuelve un error NOT_DEPLOYED y nunca datos.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {
             period: z
@@ -106,13 +158,7 @@ export function registerFiscalTools(server, client) {
                 .describe("Year in format YYYY (e.g. '2025') / Ejercicio en formato YYYY"),
         },
         outputSchema: fiscalModeloSummaryOutput,
-    }, async ({ period }) => withToolLogging("get_modelo_180_summary", () => withBackendGuard("get_modelo_180_summary", "/v1/fiscal/180", async () => {
-        const result = await client.getFiscalModeloSummary("180", period);
-        return {
-            content: [getContent(formatRecord("Modelo 180 Summary", result))],
-            structuredContent: result,
-        };
-    })));
+    }, async () => withToolLogging("get_modelo_180_summary", async () => notDeployedError("get_modelo_180_summary", "/v1/fiscal/modelo/180")));
     // -- get_modelo_347_summary --
     server.registerTool("get_modelo_347_summary", {
         title: "Get Modelo 347 Summary (Operations >€3,005 Annual Recap)",
@@ -129,13 +175,8 @@ export function registerFiscalTools(server, client) {
                 .describe("Year in format YYYY (e.g. '2025') / Ejercicio en formato YYYY"),
         },
         outputSchema: fiscalModeloSummaryOutput,
-    }, async ({ period }) => withToolLogging("get_modelo_347_summary", () => withBackendGuard("get_modelo_347_summary", "/v1/fiscal/347", async () => {
-        const result = await client.getFiscalModeloSummary("347", period);
-        return {
-            content: [getContent(formatRecord("Modelo 347 Summary", result))],
-            structuredContent: result,
-        };
-    })));
+    }, async ({ period }) => withToolLogging("get_modelo_347_summary", async () => invalidFiscalPeriod("get_modelo_347_summary", "347", period) ??
+        withBackendGuard("get_modelo_347_summary", "/v1/fiscal/modelo/347", () => fiscalModeloSummary(client, "get_modelo_347_summary", "347", period, "Modelo 347 Summary"))));
     // -- verifactu_status --
     server.registerTool("verifactu_status", {
         title: "Get VeriFactu Submission Status",
@@ -222,18 +263,10 @@ export function registerFiscalTools(server, client) {
         outputSchema: verifactuStatusOutput,
     }, async ({ invoiceId, confirm }) => withToolLogging("verifactu_resubmit", async () => {
         if (!confirm) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "Error: confirm=true is required for VeriFactu resubmission. " +
-                            "This is a COMPLIANCE action that submits fiscal data to AEAT. " +
-                            "Verify the invoice data is correct before setting confirm=true. / " +
-                            "Se requiere confirm=true para el reenvio VeriFactu. Accion de COMPLIANCE que envia datos fiscales a AEAT.",
-                    },
-                ],
-                isError: true,
-            };
+            return confirmationRequiredError("Error: confirm=true is required for VeriFactu resubmission. " +
+                "This is a COMPLIANCE action that submits fiscal data to AEAT. " +
+                "Verify the invoice data is correct before setting confirm=true. / " +
+                "Se requiere confirm=true para el reenvio VeriFactu. Accion de COMPLIANCE que envia datos fiscales a AEAT.");
         }
         return withBackendGuard("verifactu_resubmit", "/v1/fiscal/verifactu/resubmit", async () => {
             const result = await client.resubmitVerifactu(invoiceId);

package/dist/tools/gestoria.js

@@ -224,22 +224,30 @@ export function registerGestoriaTools(server, client) {
         title: "Consolidated AR Aging (Gestoria)",
         description: "Get a cross-client AR aging report for a gestor — totals bucketed by current / 30-60 / " +
             "60-90 / 90+ days overdue, a per-workspace breakdown, and the top overdue invoices. " +
-            "Defaults to the authenticated gestor; pass `ownerUid` to query a specific gestor " +
-            "(requires elevated scope). " +
+            "The ERP requires POST /v1/gestoria/aging with a body listing the workspaces to include " +
+            "(defaults to the authenticated gestor when `workspaceIds` is omitted). " +
             "Useful for dunning prioritisation and end-of-month chase lists. " +
-            "/ Obtiene un informe de antiguedad de saldos cruzando todos los clientes del gestor — " +
+            "/ Obtiene un informe de antiguedad de saldos cruzando los clientes del gestor — " +
             "totales por tramo (al dia / 30-60 / 60-90 / 90+ dias), desglose por espacio y top vencidas. " +
             "Util para priorizar reclamaciones y listas de cobro de fin de mes.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {
-            ownerUid: z
+            workspaceIds: z
+                .array(z.string().min(1))
+                .optional()
+                .describe("Workspace IDs to include (defaults to the authenticated gestor when omitted) / IDs de espacios a incluir (por defecto los del gestor)"),
+            asOf: z
                 .string()
                 .optional()
-                .describe("Gestor UID to query (defaults to authenticated caller; elevated scope required for other UIDs) / UID del gestor (por defecto el llamante)"),
+                .describe("Reference date in ISO 8601 (YYYY-MM-DD). Defaults to today / Fecha de referencia"),
+            bustCache: z
+                .boolean()
+                .optional()
+                .describe("Force-refresh server cache (default false) / Forzar refresco de cache del servidor"),
         },
         outputSchema: gestoriaAgingConsolidatedOutput,
-    }, async ({ ownerUid }) => withToolLogging("gestoria_aging_consolidated", () => withBackendGuard("gestoria_aging_consolidated", "/v1/gestoria/aging/consolidated", async () => {
-        const result = await client.getGestoriaAgingConsolidated({ ownerUid });
+    }, async ({ workspaceIds, asOf, bustCache }) => withToolLogging("gestoria_aging_consolidated", () => withBackendGuard("gestoria_aging_consolidated", "/v1/gestoria/aging", async () => {
+        const result = await client.getGestoriaAgingConsolidated({ workspaceIds, asOf, bustCache });
         return {
             content: [getContent(formatRecord("Aging consolidated", result))],
             structuredContent: result,

package/dist/tools/hr.js

@@ -25,13 +25,15 @@ export function registerHrTools(server, client) {
     server.registerTool("leave_request_create", {
         title: "Create Leave Request",
         description: "Create a new leave/PTO request for an employee. " +
-            "Types: 'vacation', 'sick', 'personal', 'parental', 'unpaid', 'training'. " +
+            "Types: 'vacation', 'sick', 'personal', 'parental', 'bereavement', 'other'. " +
             "Dates must be ISO 8601 (YYYY-MM-DD). Status starts as 'pending' awaiting manager approval. " +
             "/ Crea una nueva solicitud de vacaciones/permiso. Estado inicial 'pending' pendiente aprobacion.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
             employeeId: z.string().describe("Employee ID / ID del empleado"),
-            type: z.string().describe("Leave type slug (vacation, sick, personal, parental, unpaid, training) / Tipo de permiso"),
+            type: z
+                .enum(["vacation", "sick", "personal", "parental", "bereavement", "other"])
+                .describe("Leave type slug (vacation, sick, personal, parental, bereavement, other) / Tipo de permiso"),
             startDate: z.string().describe("Start date ISO 8601 (YYYY-MM-DD) / Fecha inicio"),
             endDate: z.string().describe("End date ISO 8601 (YYYY-MM-DD) / Fecha fin"),
             reason: z.string().optional().describe("Optional reason / Motivo opcional"),
@@ -140,10 +142,19 @@ export function registerHrTools(server, client) {
             employeeId: z.string().describe("Employee ID / ID del empleado"),
             mood: z.string().optional().describe("Optional mood slug (e.g. 'great','ok','tired') / Estado de animo"),
             location: z.string().optional().describe("Optional location ('remote','office','site') / Ubicacion"),
+            idempotencyKey: z
+                .string()
+                .max(64)
+                .optional()
+                .describe("Optional idempotency key, max 64 chars. One is generated per call when omitted or blank; " +
+                "pass your own to make a retry replay the stored open entry instead of creating a second clock-in. " +
+                "Reusing a key with a different body returns 409 IDEMPOTENCY_KEY_REUSED — reconcile, do not " +
+                "retry with a new key. / Clave de idempotencia opcional (max 64). Se genera una por llamada si se omite."),
         },
         outputSchema: attendanceEntryItemOutput,
     }, async (input) => withToolLogging("attendance_clock_in", () => withBackendGuard("attendance_clock_in", "/v1/time-entries/clock-in", async () => {
-        const result = await client.attendanceClockIn(input);
+        const { idempotencyKey, ...data } = input;
+        const result = await client.attendanceClockIn(data, idempotencyKey);
         return {
             content: [mutateContent(formatRecord("Clocked in", result))],
             structuredContent: result,
@@ -158,10 +169,18 @@ export function registerHrTools(server, client) {
         annotations: UPDATE_ANNOTATIONS,
         inputSchema: {
             entryId: z.string().describe("Open attendance entry ID / ID de la entrada abierta"),
+            idempotencyKey: z
+                .string()
+                .max(64)
+                .optional()
+                .describe("Optional idempotency key, max 64 chars. One is generated per call when omitted or blank; " +
+                "pass your own to make a retry replay the stored close instead of erroring on a closed entry. " +
+                "/ Clave de idempotencia opcional (max 64). Se genera una por llamada si se omite."),
         },
         outputSchema: attendanceEntryItemOutput,
-    }, async ({ entryId }) => withToolLogging("attendance_clock_out", () => withBackendGuard("attendance_clock_out", "/v1/time-entries/clock-out", async () => {
-        const result = await client.attendanceClockOut(entryId);
+    }, async (input) => withToolLogging("attendance_clock_out", () => withBackendGuard("attendance_clock_out", "/v1/time-entries/clock-out", async () => {
+        const { entryId, idempotencyKey } = input;
+        const result = await client.attendanceClockOut(entryId, idempotencyKey);
         return {
             content: [mutateContent(formatRecord("Clocked out", result))],
             structuredContent: result,
@@ -191,19 +210,30 @@ export function registerHrTools(server, client) {
     server.registerTool("anomaly_list", {
         title: "List Anomalies",
         description: "List HR / operational / financial anomalies detected by the system. " +
-            "Filter by type (duplicate_clock_in, overtime_spike, missing_clock_out, expense_outlier, etc.), " +
-            "severity (low/medium/high/critical), or period. " +
+            "Filter by type (daily_exceeded, weekly_exceeded, annual_approaching, " +
+            "annual_exceeded, missing_break), severity (warning/critical), or period. " +
+            "Anomalies are COMPUTE-ON-READ over the live attendance records (Art.34/35 ET " +
+            "overtime engine) — there is no stored anomalies collection. " +
             "Useful for daily HR review and compliance audits. " +
             "/ Lista anomalias detectadas (RRHH/operativas/financieras) con filtros opcionales.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {
-            type: z.string().optional().describe("Filter by anomaly type slug / Tipo"),
+            type: z
+                .enum([
+                "daily_exceeded",
+                "weekly_exceeded",
+                "annual_approaching",
+                "annual_exceeded",
+                "missing_break",
+            ])
+                .optional()
+                .describe("Filter by anomaly type slug / Tipo"),
             severity: z
-                .enum(["low", "medium", "high", "critical"])
+                .enum(["warning", "critical"])
                 .optional()
                 .describe("Filter by severity / Severidad"),
-            from: z.string().optional().describe("Period start ISO 8601 / Inicio"),
-            to: z.string().optional().describe("Period end ISO 8601 / Fin"),
+            from: z.string().optional().describe("Period start ISO 8601 (YYYY-MM-DD) / Inicio"),
+            to: z.string().optional().describe("Period end ISO 8601 (YYYY-MM-DD) / Fin"),
             limit: z.number().int().min(1).max(100).optional().describe("Max results / Maximos"),
             offset: z.number().int().min(0).optional().describe("Offset / Desplazamiento"),
         },

package/dist/tools/igic.d.ts

@@ -2,18 +2,19 @@
  * IGIC (Canary Islands indirect tax) tools for the Frihet MCP server — Day 1 Megasprint (4 tools).
  *
  * Tools:
- *   1. frihet_modelo_415_summary — M415 operations >€3,005 annual (Canarias)
- *   2. frihet_modelo_425_summary — M425 resumen anual IGIC (Canarias)
- *   3. frihet_modelo_418_summary — M418 mensual grandes empresas IGIC (Canarias)
- *   4. frihet_aiem_calculate     — Arbitrio sobre Importaciones y Entrega de Mercancías calculation
+ *   1. frihet_modelo_415_summary — M415 operations >€3,005 annual (Canarias) — NOT DEPLOYED
+ *   2. frihet_modelo_425_summary — M425 resumen anual IGIC (Canarias) — NOT DEPLOYED
+ *   3. frihet_modelo_418_summary — M418 autoliquidacion mensual individual, regimen especial
+ *                                  del grupo de entidades (ATC) — NOT DEPLOYED
+ *   4. frihet_aiem_calculate     — AIEM (Arbitrio sobre Importaciones y Entrega de Mercancías) — NOT DEPLOYED
  *
  * NOTE: ATC SOAP integration skipped — internal infrastructure, not exposed via MCP.
  *
- * REST surface: /v1/igic/* — service-layer reads of workspace fiscal data.
- *   Backend callables: #390 IGIC services (Frihet-ERP PR #390).
- *   Tools surface 404 until REST shell ships.
+ * REST surface: Frihet-ERP functions/src/publicApi.ts has NO /v1/igic/* route
+ * (neither modelo summaries nor AIEM), so all four tools return NOT_DEPLOYED
+ * without calling (capability truth: `unavailable`, src/capability-truth.ts).
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { IFrihetClient } from "../client-interface.js";
-export declare function registerIgicTools(server: McpServer, client: IFrihetClient): void;
+export declare function registerIgicTools(server: McpServer, _client: IFrihetClient): void;
 //# sourceMappingURL=igic.d.ts.map