@frihet/mcp-server 1.16.6 → 2.0.0

package/dist/tools/invoices.js

@@ -2,20 +2,28 @@
  * Invoice tools for the Frihet MCP server.
  */
 import { z } from "zod/v4";
-import { withToolLogging, formatPaginatedResponse, formatRecord, listContent, getContent, mutateContent, enrichResponse, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, DELETE_ANNOTATIONS, paginatedOutput, deleteResultOutput, invoiceItemOutput, actionResultOutput, creditNoteResultOutput, pdfResultOutput } from "./shared.js";
+import { withToolLogging, confirmationRequiredError, formatPaginatedResponse, formatRecord, listContent, getContent, mutateContent, enrichResponse, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, DELETE_ANNOTATIONS, paginatedOutput, documentDeleteResultOutput, invoiceItemOutput, actionResultOutput, creditNoteResultOutput, pdfResultOutput, einvoiceResultOutput } from "./shared.js";
 const invoiceItemSchema = z.object({
-    description: z.string().describe("Description of the line item / Descripcion del concepto"),
-    quantity: z.number().describe("Quantity / Cantidad"),
-    unitPrice: z.number().describe("Unit price in EUR / Precio unitario en EUR"),
-});
+    description: z.string().trim().min(1).max(500).describe("Description of the line item / Descripcion del concepto"),
+    quantity: z.number().finite().min(0.0001).max(1_000_000).describe("Quantity / Cantidad"),
+    unitPrice: z.number().finite().min(0).max(10_000_000).describe("Unit price in EUR / Precio unitario en EUR"),
+}).strict();
+function documentResultMetadata(result) {
+    return {
+        id: result.id,
+        contentType: result.contentType,
+        sizeBytes: result.sizeBytes,
+        ...(result.filename ? { filename: result.filename } : {}),
+    };
+}
 // Optional client-identity fields the Frihet API accepts on invoice/quote
-// create+update. When clientId is supplied the server back-fills taxId/address
-// from the stored client; clientTaxId/clientAddress override per-document.
+// create+update. When clientId is supplied the server snapshots the stored
+// client record; the other fields can override document-specific details.
 const clientIdentityFields = {
     clientId: z
         .string()
         .optional()
-        .describe("Existing client ID — server back-fills taxId/address / ID de cliente existente"),
+        .describe("Existing client ID — stored client details are used for the document / ID de cliente existente"),
     clientTaxId: z
         .string()
         .optional()
@@ -73,6 +81,10 @@ const invoiceFiscalFields = {
         .enum(["service", "goods"])
         .optional()
         .describe("Operation type (service or goods) / Tipo de operacion"),
+    fiscalTreatment: z
+        .enum(["not_subject_location", "export_exempt"])
+        .optional()
+        .describe("Explicit fiscal treatment declared by the user; never inferred / Tratamiento fiscal declarado expresamente por el usuario; nunca inferido"),
 };
 export function registerInvoiceTools(server, client) {
     // -- list_invoices --
@@ -133,8 +145,8 @@ export function registerInvoiceTools(server, client) {
         const result = await client.listInvoices({ limit, offset, after, fields, status, from, to, clientId, seriesId });
         const hints = enrichResponse("invoices", "list", result.data);
         return {
-            content: [listContent(formatPaginatedResponse("invoices", result))],
-            structuredContent: { ...result, ...hints },
+            content: [listContent(formatPaginatedResponse("invoices", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- get_invoice --
@@ -165,18 +177,18 @@ export function registerInvoiceTools(server, client) {
             "Soporta retencion IRPF (autonomos ES), recargo de equivalencia, serie, anticipo y descuento global.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
-            clientName: z.string().describe("Client/customer name / Nombre del cliente"),
+            clientName: z.string().trim().min(1).max(200).describe("Client/customer name / Nombre del cliente"),
             ...clientIdentityFields,
             items: z
                 .array(invoiceItemSchema)
                 .min(1)
                 .describe("Line items (each with description, quantity, unitPrice) / Conceptos de la factura"),
             issueDate: z
-                .string()
+                .iso.date()
                 .optional()
                 .describe("Issue date in ISO 8601 format (YYYY-MM-DD), defaults to today / Fecha de emision"),
             dueDate: z
-                .string()
+                .iso.date()
                 .optional()
                 .describe("Due date in ISO 8601 format (YYYY-MM-DD) / Fecha de vencimiento"),
             status: z
@@ -185,6 +197,7 @@ export function registerInvoiceTools(server, client) {
                 .describe("Invoice status (default: draft) / Estado de la factura"),
             notes: z
                 .string()
+                .max(10_000)
                 .optional()
                 .describe("Additional notes shown on the invoice / Notas adicionales"),
             taxRate: z
@@ -197,11 +210,16 @@ export function registerInvoiceTools(server, client) {
         },
         outputSchema: invoiceItemOutput,
     }, async (input) => withToolLogging("create_invoice", async () => {
-        const result = await client.createInvoice(input);
+        const status = input.status ?? "draft";
+        const payload = {
+            ...input,
+            status,
+        };
+        const result = await client.createInvoice(payload);
         const hints = enrichResponse("invoices", "create", result);
         return {
-            content: [mutateContent(formatRecord("Invoice created", result))],
-            structuredContent: { ...result, ...hints },
+            content: [mutateContent(formatRecord("Invoice created", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- update_invoice --
@@ -235,26 +253,65 @@ export function registerInvoiceTools(server, client) {
         const result = await client.updateInvoice(id, data);
         const hints = enrichResponse("invoices", "update", result);
         return {
-            content: [mutateContent(formatRecord("Invoice updated", result))],
-            structuredContent: { ...result, ...hints },
+            content: [mutateContent(formatRecord("Invoice updated", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- delete_invoice --
     server.registerTool("delete_invoice", {
         title: "Delete Invoice",
-        description: "Permanently delete an invoice by its ID. This action cannot be undone. " +
-            "/ Elimina permanentemente una factura por su ID. Esta accion no se puede deshacer.",
+        description: "Delete an invoice by its ID. Requires confirm=true. " +
+            "Only a DRAFT invoice is removed permanently. A sent/paid/overdue invoice is NOT destroyed: " +
+            "the backend CANCELS it (status=cancelled) so the VeriFactu hash chain stays intact, and the " +
+            "document remains readable via get_invoice. The result reports which happened in `outcome` " +
+            "(\"deleted\" or \"cancelled\"). " +
+            "/ Elimina una factura por su ID. Requiere confirm=true. Solo una factura en BORRADOR se elimina " +
+            "de forma permanente. Una factura emitida/pagada NO se destruye: se CANCELA (status=cancelled) para " +
+            "preservar la cadena de hash VeriFactu y sigue consultable con get_invoice.",
         annotations: DELETE_ANNOTATIONS,
         inputSchema: {
             id: z.string().describe("Invoice ID / ID de la factura"),
+            confirm: z
+                .boolean()
+                .describe("Must be true to confirm deletion / Debe ser true para confirmar la eliminacion"),
         },
-        outputSchema: deleteResultOutput,
-    }, async ({ id }) => withToolLogging("delete_invoice", async () => {
-        await client.deleteInvoice(id);
+        outputSchema: documentDeleteResultOutput,
+    }, async ({ id, confirm }) => withToolLogging("delete_invoice", async () => {
+        if (!confirm) {
+            return confirmationRequiredError("Error: confirm=true is required to delete an invoice. " +
+                "A draft invoice is removed permanently; a sent/paid invoice is CANCELLED " +
+                "(status=cancelled) instead, because VeriFactu forbids breaking the hash chain. " +
+                "Either way the invoice stops counting as a live receivable. Set confirm=true to proceed. / " +
+                "Se requiere confirm=true para eliminar una factura.");
+        }
+        // 204 → undefined (draft row destroyed). 200 → soft-cancel body (document
+        // kept, status=cancelled). Reporting both as "deleted" is the GAP-12 lie.
+        const outcome = await client.deleteInvoice(id);
+        const cancelled = !!outcome && typeof outcome === "object";
+        const body = cancelled ? outcome : {};
         const hints = enrichResponse("invoices", "delete", { id });
+        const previous = typeof body["previousStatus"] === "string" ? ` (was ${body["previousStatus"]})` : "";
+        // R3 fix (ERP #1580): extract the per-branch body text to a single
+        // variable and append `+ hints` ONCE, after the ternary closes. R2's
+        // `+ hints` was branch-local (only in the DELETED branch), so the
+        // CANCELLED branch silently dropped the "cannot be undone" warning —
+        // 15/16 behavioral paths had warnings, not 16/16. The OUTER concat
+        // guarantees both terminal branches carry the enrichment. The
+        // `paginated-strict-output.test.ts` runtime tests pin BOTH branches.
+        const bodyText = cancelled
+            ? `Invoice ${id} was CANCELLED, not deleted${previous}: it still exists with ` +
+                "status=cancelled because VeriFactu forbids destroying an issued invoice. / " +
+                `Factura ${id} CANCELADA, no eliminada: sigue existiendo con status=cancelled (VeriFactu).`
+            : `Invoice ${id} deleted permanently (it was a draft). / ` +
+                `Factura ${id} eliminada permanentemente (era un borrador).`;
         return {
-            content: [mutateContent(`Invoice ${id} deleted successfully. / Factura ${id} eliminada correctamente.`)],
-            structuredContent: { success: true, id, ...hints },
+            content: [mutateContent(bodyText + hints)],
+            structuredContent: {
+                success: true,
+                id,
+                ...body,
+                outcome: cancelled ? "cancelled" : "deleted",
+            },
         };
     }));
     // -- search_invoices --
@@ -299,27 +356,135 @@ export function registerInvoiceTools(server, client) {
         const label = query ? `invoices matching "${query}"` : "invoices";
         const hints = enrichResponse("invoices", "list", result.data);
         return {
-            content: [listContent(formatPaginatedResponse(label, result))],
-            structuredContent: { ...result, ...hints },
+            content: [listContent(formatPaginatedResponse(label, result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- send_invoice --
     server.registerTool("send_invoice", {
         title: "Send Invoice",
-        description: "Send an invoice to the client via email. Optionally override the recipient email address. " +
+        description: "Send an invoice to the client via email. Requires confirm=true. " +
+            "Optionally override the recipient email address. " +
             "The invoice must exist and should not already be cancelled. " +
-            "/ Envia una factura al cliente por email. Opcionalmente se puede cambiar el email destinatario.",
+            "Sending reaches a third party and cannot be recalled. " +
+            "/ Envia una factura al cliente por email. Requiere confirm=true. " +
+            "Opcionalmente se puede cambiar el email destinatario. El envio llega a un tercero y no se puede anular.",
         annotations: UPDATE_ANNOTATIONS,
         inputSchema: {
             id: z.string().describe("Invoice ID / ID de la factura"),
             to: z.string().optional().describe("Override recipient email / Email destinatario alternativo"),
+            confirm: z
+                .boolean()
+                .describe("Must be true to confirm sending / Debe ser true para confirmar el envio"),
         },
         outputSchema: actionResultOutput,
-    }, async ({ id, to }) => withToolLogging("send_invoice", async () => {
-        const result = await client.sendInvoice(id, to);
+    }, async ({ id, to, confirm }) => withToolLogging("send_invoice", async () => {
+        if (!confirm) {
+            return confirmationRequiredError("Error: confirm=true is required to send an invoice. " +
+                "This delivers an email to the client — a third party outside this workspace — " +
+                "and it cannot be recalled once sent. Set confirm=true to proceed. / " +
+                "Se requiere confirm=true para enviar una factura por email a un tercero.");
+        }
+        const invoice = await client.getInvoice(id);
+        if (invoice["status"] === "cancelled") {
+            return {
+                content: [{ type: "text", text: "Error: a cancelled invoice cannot be sent." }],
+                isError: true,
+            };
+        }
+        const isValidRecipientEmail = (email) => email.length <= 255 && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+        let recipientEmail;
+        if (to !== undefined) {
+            const trimmedTo = to.trim();
+            if (!trimmedTo || !isValidRecipientEmail(trimmedTo)) {
+                return {
+                    content: [{ type: "text", text: `Error: invalid recipient email address format: "${trimmedTo}".` }],
+                    isError: true,
+                };
+            }
+            recipientEmail = trimmedTo;
+        }
+        if (!recipientEmail) {
+            const clientId = typeof invoice["clientId"] === "string" && invoice["clientId"].trim()
+                ? invoice["clientId"].trim()
+                : undefined;
+            if (clientId) {
+                let linkedClient;
+                try {
+                    linkedClient = await client.getClient(clientId);
+                }
+                catch (err) {
+                    const isNotFound = typeof err === "object" &&
+                        err !== null &&
+                        "statusCode" in err &&
+                        err.statusCode === 404;
+                    if (!isNotFound) {
+                        throw err;
+                    }
+                }
+                const clientEmail = linkedClient && typeof linkedClient["email"] === "string" && linkedClient["email"].trim()
+                    ? linkedClient["email"].trim()
+                    : undefined;
+                if (clientEmail) {
+                    if (!isValidRecipientEmail(clientEmail)) {
+                        return {
+                            content: [{ type: "text", text: `Error: invalid recipient email address format: "${clientEmail}".` }],
+                            isError: true,
+                        };
+                    }
+                    recipientEmail = clientEmail;
+                }
+            }
+            if (!recipientEmail) {
+                const docFallbackEmail = typeof invoice["clientEmail"] === "string" && invoice["clientEmail"].trim()
+                    ? invoice["clientEmail"].trim()
+                    : typeof invoice["email"] === "string" && invoice["email"].trim()
+                        ? invoice["email"].trim()
+                        : undefined;
+                if (docFallbackEmail) {
+                    if (!isValidRecipientEmail(docFallbackEmail)) {
+                        return {
+                            content: [{ type: "text", text: `Error: invalid recipient email address format: "${docFallbackEmail}".` }],
+                            isError: true,
+                        };
+                    }
+                    const fallbackMsg = `Error: the linked client has no current email address; only a document-level fallback email ("${docFallbackEmail}") was found on the invoice, which may be outdated. ` +
+                        `Confirm this specific recipient with the user and re-run with to="${docFallbackEmail}" and confirm=true to send. / ` +
+                        `El cliente vinculado no tiene email actual; la factura conserva el correo documental "${docFallbackEmail}", que podria estar obsoleto. Confirma este destinatario concreto y vuelve a llamar con to="${docFallbackEmail}" y confirm=true.`;
+                    return {
+                        content: [{ type: "text", text: fallbackMsg }],
+                        structuredContent: {
+                            success: false,
+                            id,
+                            message: fallbackMsg,
+                            effectiveRecipient: docFallbackEmail,
+                            recipientSource: "document_fallback",
+                            requiresExplicitRecipientConfirmation: true,
+                        },
+                        isError: true,
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: clientId
+                                ? "Error: the linked client has no saved email address."
+                                : "Error: this invoice has no linked client with a saved email address.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        const result = await client.sendInvoice(id, recipientEmail);
+        const enrichedResult = {
+            ...(result && typeof result === "object" ? result : {}),
+            effectiveRecipient: recipientEmail,
+        };
         return {
-            content: [mutateContent(formatRecord("Invoice sent", result))],
-            structuredContent: result,
+            content: [mutateContent(formatRecord("Invoice sent", enrichedResult))],
+            structuredContent: enrichedResult,
         };
     }));
     // -- mark_invoice_paid --
@@ -344,8 +509,10 @@ export function registerInvoiceTools(server, client) {
     // -- get_invoice_pdf --
     server.registerTool("get_invoice_pdf", {
         title: "Get Invoice PDF",
-        description: "Get the PDF for an invoice. Returns a URL to download the PDF or binary info. " +
-            "/ Obtiene el PDF de una factura. Devuelve una URL de descarga o informacion del binario.",
+        description: "Get the PDF for an invoice. The body is served as raw `application/pdf` bytes, base64-encoded in `base64` " +
+            "with `sizeBytes` and `contentType`. PDFs larger than 25 MiB are rejected with `413 payload_too_large`. " +
+            "/ Obtiene el PDF de una factura. El cuerpo se sirve como bytes `application/pdf` en bruto, codificados en base64 " +
+            "en `base64`, con `sizeBytes` y `contentType`. PDFs mayores de 25 MiB se rechazan con `413 payload_too_large`.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {
             id: z.string().describe("Invoice ID / ID de la factura"),
@@ -354,33 +521,31 @@ export function registerInvoiceTools(server, client) {
     }, async ({ id }) => withToolLogging("get_invoice_pdf", async () => {
         const result = await client.getInvoicePdf(id);
         return {
-            content: [getContent(formatRecord("Invoice PDF", result))],
+            content: [getContent(formatRecord("Invoice PDF", documentResultMetadata(result)))],
             structuredContent: result,
         };
     }));
     // -- get_invoice_einvoice --
     server.registerTool("get_invoice_einvoice", {
-        title: "Get Invoice E-Invoice XML",
-        description: "Download the e-invoice XML for an invoice. Returns EN16931-compliant XML in the auto-detected format " +
-            "(UBL, CII, XRechnung, Factur-X, FatturaPA, PEPPOL). " +
+        title: "Get Invoice E-Invoice Artifact",
+        description: "Download the stored e-invoice artifact for an invoice. XML formats return strict UTF-8 text in `xml`; " +
+            "Factur-X returns `application/pdf` bytes encoded in `base64`. Both include `id`, `contentType`, and `sizeBytes`. " +
+            "XML larger than 5 MiB or PDF larger than 25 MiB is rejected with `413 payload_too_large`. " +
             "Only available after the invoice has been saved/sent. " +
-            "/ Descarga el XML de factura electronica para una factura. Devuelve XML conforme a EN16931 en el formato " +
-            "auto-detectado (UBL, CII, XRechnung, Factur-X, FatturaPA, PEPPOL). " +
+            "/ Descarga el artefacto de factura electronica guardado. Los formatos XML devuelven texto UTF-8 estricto en `xml`; " +
+            "Factur-X devuelve bytes `application/pdf` codificados en `base64`. Ambos incluyen `id`, `contentType` y `sizeBytes`. " +
+            "XML mayor de 5 MiB o PDF mayor de 25 MiB se rechaza con `413 payload_too_large`. " +
             "Solo disponible despues de guardar o enviar la factura.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {
             id: z.string().describe("Invoice ID / ID de la factura"),
         },
-        outputSchema: z.object({
-            xml: z.string().optional(),
-            filename: z.string().optional(),
-            format: z.string().optional(),
-        }).passthrough(),
+        outputSchema: einvoiceResultOutput,
     }, async ({ id }) => withToolLogging("get_invoice_einvoice", async () => {
         const result = await client.getInvoiceEInvoice(id);
         return {
-            content: [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result, null, 2) }],
-            structuredContent: (typeof result === "object" && result !== null ? result : { xml: result }),
+            content: [getContent(formatRecord("E-invoice artifact", documentResultMetadata(result)))],
+            structuredContent: result,
         };
     }));
     // -- create_credit_note --
@@ -439,17 +604,22 @@ export function registerInvoiceTools(server, client) {
         }, idempotencyKey);
         const hints = enrichResponse("invoices", "create", result);
         return {
-            content: [mutateContent(formatRecord("Credit note created", result))],
-            structuredContent: { ...result, ...hints },
+            content: [mutateContent(formatRecord("Credit note created", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- apply_late_fee --
     server.registerTool("apply_late_fee", {
         title: "Apply Late Fee",
-        description: "Apply late payment interest to an overdue invoice. Calculates interest based on EU Late Payment Directive (8% default) " +
-            "or auto-calculates from days overdue. Creates a debit note linked to the original invoice. " +
-            "/ Aplica intereses de demora a una factura vencida. Calcula intereses segun la Directiva Europea de Morosidad (8% por defecto) " +
-            "o los calcula automaticamente a partir de los dias de retraso. Crea una nota de debito vinculada a la factura original.",
+        description: "Apply late payment interest flags to an overdue invoice. " +
+            "Calculates interest based on EU Late Payment Directive (8% default) or auto-calculates " +
+            "from days overdue, and flips the `hasLateFee` / `lateFeeAmount` / `lateFeeDaysOverdue` " +
+            "fields on the invoice. The endpoint does NOT create a debit note — if a separate " +
+            "rectifying invoice is required, issue it explicitly with create_invoice or create_credit_note. " +
+            "/ Aplica los indicadores de intereses de demora a una factura vencida. Calcula intereses " +
+            "segun la Directiva Europea de Morosidad (8% por defecto) o a partir de los dias de retraso, " +
+            "y actualiza los flags `hasLateFee` / `lateFeeAmount` / `lateFeeDaysOverdue`. NO crea una " +
+            "nota de debito — si hace falta una factura rectificativa aparte, emitela con create_invoice o create_credit_note.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
             invoiceId: z.string().describe("ID of the overdue invoice / ID de la factura vencida"),

package/dist/tools/kitchen.js

@@ -177,21 +177,32 @@ export function registerKitchenTools(server, client) {
             }
         }
         const agg = new Map();
+        let totalOpenTickets = 0;
         for (const t of ticketsResult.data) {
             const ticket = t;
             const status = typeof ticket["status"] === "string" ? ticket["status"] : "";
-            if (status === "served" || status === "cancelled")
+            if (status === "served" || status === "cancelled" || status === "voided")
                 continue;
-            const stationId = typeof ticket["stationId"] === "string" ? ticket["stationId"] : "__unassigned__";
+            totalOpenTickets += 1;
+            // REST tickets can route to multiple stations; retain legacy single-station input.
+            const stationIds = Array.isArray(ticket["stationIds"])
+                ? [...new Set(ticket["stationIds"].filter((id) => typeof id === "string" && id.length > 0))]
+                : typeof ticket["stationId"] === "string" ? [ticket["stationId"]] : [];
+            if (stationIds.length === 0)
+                stationIds.push("__unassigned__");
             const createdAt = typeof ticket["createdAt"] === "string"
                 ? new Date(ticket["createdAt"]).getTime()
                 : null;
-            const existing = agg.get(stationId) ?? { openTickets: 0, oldestCreatedAt: null };
-            existing.openTickets += 1;
-            if (createdAt !== null && (existing.oldestCreatedAt === null || createdAt < existing.oldestCreatedAt)) {
-                existing.oldestCreatedAt = createdAt;
+            for (const stationId of stationIds) {
+                const existing = agg.get(stationId) ?? { openTickets: 0, oldestCreatedAt: null };
+                existing.openTickets += 1;
+                if (createdAt !== null && (existing.oldestCreatedAt === null || createdAt < existing.oldestCreatedAt)) {
+                    existing.oldestCreatedAt = createdAt;
+                }
+                agg.set(stationId, existing);
+                if (stationId !== "__unassigned__" && !stationMap.has(stationId))
+                    stationMap.set(stationId, stationId);
             }
-            agg.set(stationId, existing);
         }
         // Build station summaries, also include stations with zero open tickets
         let maxLoad = 0;
@@ -240,10 +251,9 @@ export function registerKitchenTools(server, client) {
                 }
             }
         }
-        const totalOpenTickets = summaries.reduce((acc, s) => acc + s.openTickets, 0);
         const result = {
             stations: summaries,
-            bottleneckStationId: maxLoad > 0 ? bottleneckId : undefined,
+            ...(maxLoad > 0 ? { bottleneckStationId: bottleneckId } : {}),
             totalOpenTickets,
             generatedAt: new Date().toISOString(),
         };

package/dist/tools/payroll.d.ts

@@ -2,17 +2,14 @@
  * Payroll preparation tools for the Frihet MCP server — D4-B megasprint (2 tools).
  *
  * Tools:
- *   1. payroll_export    — export payroll for a month in gestoria format (A3, Contasol, Sage, Holded, Siltra)
- *   2. payroll_checklist — list employees with status (ready / missing_data / blocked) for a month
+ *   1. payroll_export    — read the normalized export-ready employee dataset
+ *   2. payroll_checklist — read payroll-profile readiness for payable employees
  *
  * REST surface: /v1/payroll/prep/export, /v1/payroll/prep/employees
  *
- * Frihet does NOT process payroll. It exports to gestoria-compatible formats so
- * the asesoria handles SS/IRPF/contracts. Output formats track the most common
- * Spanish payroll software clusters.
- *
- * NOTE: ERP backend endpoints land in parallel D4-A wave. 404s propagate as isError
- * until backend ships. TODO: confirm A3 columns + SILTRA file extension.
+ * The ERP validates and echoes a destination-format label but returns the same
+ * normalized JSON dataset for each value. It does not generate a format-specific
+ * file, and Frihet does not process payroll. These read routes are live.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { IFrihetClient } from "../client-interface.js";

package/dist/tools/payroll.js

@@ -2,17 +2,14 @@
  * Payroll preparation tools for the Frihet MCP server — D4-B megasprint (2 tools).
  *
  * Tools:
- *   1. payroll_export    — export payroll for a month in gestoria format (A3, Contasol, Sage, Holded, Siltra)
- *   2. payroll_checklist — list employees with status (ready / missing_data / blocked) for a month
+ *   1. payroll_export    — read the normalized export-ready employee dataset
+ *   2. payroll_checklist — read payroll-profile readiness for payable employees
  *
  * REST surface: /v1/payroll/prep/export, /v1/payroll/prep/employees
  *
- * Frihet does NOT process payroll. It exports to gestoria-compatible formats so
- * the asesoria handles SS/IRPF/contracts. Output formats track the most common
- * Spanish payroll software clusters.
- *
- * NOTE: ERP backend endpoints land in parallel D4-A wave. 404s propagate as isError
- * until backend ships. TODO: confirm A3 columns + SILTRA file extension.
+ * The ERP validates and echoes a destination-format label but returns the same
+ * normalized JSON dataset for each value. It does not generate a format-specific
+ * file, and Frihet does not process payroll. These read routes are live.
  */
 import { z } from "zod/v4";
 import { withToolLogging, formatRecord, getContent, READ_ONLY_ANNOTATIONS, payrollExportOutput, payrollChecklistOutput, } from "./shared.js";
@@ -20,24 +17,18 @@ import { withBackendGuard } from "./backend-availability.js";
 export function registerPayrollTools(server, client) {
     // -- payroll_export --
     server.registerTool("payroll_export", {
-        title: "Export Payroll (Gestoria Format)",
-        description: "Export payroll data for a month in gestoria-compatible format. " +
-            "Supported formats:\n" +
-            "  - 'a3'       — Wolters Kluwer A3 (CSV with Spanish payroll columns)\n" +
-            "  - 'contasol' — Sage Contasol\n" +
-            "  - 'sage'     — Sage 50/200\n" +
-            "  - 'holded'   — Holded import format\n" +
-            "  - 'siltra'   — SILTRA Seguridad Social XML\n" +
-            "\n" +
-            "Frihet does NOT calculate payroll — it exports staged data for the gestoria. " +
-            "Month format: 'YYYY-MM'. " +
-            "/ Exporta datos de nominas en formato compatible con gestoria. Mes en formato 'YYYY-MM'.",
+        title: "Payroll Export-Ready Data",
+        description: "Read the normalized payroll-ready employee dataset for a month. " +
+            "The ERP accepts 'a3', 'contasol', 'sage', or 'siltra' as a destination label and echoes it; " +
+            "the response is JSON and is identical across formats apart from that label. " +
+            "No CSV, XML, PDF, or provider-specific file is generated. Frihet does not calculate payroll. " +
+            "/ Lee los datos normalizados listos para nomina; no genera un archivo especifico del proveedor.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {
             format: z
-                .enum(["a3", "contasol", "sage", "holded", "siltra"])
-                .describe("Gestoria payroll software format / Formato del software de gestoria"),
-            month: z.string().regex(/^\d{4}-\d{2}$/).describe("Month in 'YYYY-MM' format / Mes formato 'YYYY-MM'"),
+                .enum(["a3", "contasol", "sage", "siltra"])
+                .describe("Echoed destination label; does not change JSON serialization / Etiqueta de destino"),
+            month: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/).describe("Month in 'YYYY-MM' format / Mes formato 'YYYY-MM'"),
         },
         outputSchema: payrollExportOutput,
     }, async ({ format, month }) => withToolLogging("payroll_export", () => withBackendGuard("payroll_export", "/v1/payroll/prep/export", async () => {
@@ -50,17 +41,13 @@ export function registerPayrollTools(server, client) {
     // -- payroll_checklist --
     server.registerTool("payroll_checklist", {
         title: "Payroll Readiness Checklist",
-        description: "List all employees for a given month with their payroll readiness status. " +
-            "Status values:\n" +
-            "  - 'ready'         — all required data present, ready to export\n" +
-            "  - 'missing_data'  — some required fields missing (see missingFields[])\n" +
-            "  - 'blocked'       — manually blocked or data inconsistency detected\n" +
-            "\n" +
-            "Use BEFORE payroll_export to identify gaps. Month format: 'YYYY-MM'. " +
-            "/ Lista empleados con estado de preparacion para nomina. Usar antes de payroll_export.",
+        description: "List payable employees (active or on leave) for a month, whether each has a payroll profile, " +
+            "whether its required fields are ready, which fields are missing, and monthly review state. " +
+            "Suspended and offboarded employees are excluded. Use before payroll_export. " +
+            "/ Lista empleados pagables y la preparacion real de su perfil de nomina.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {
-            month: z.string().regex(/^\d{4}-\d{2}$/).describe("Month in 'YYYY-MM' format / Mes formato 'YYYY-MM'"),
+            month: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/).describe("Month in 'YYYY-MM' format / Mes formato 'YYYY-MM'"),
         },
         outputSchema: payrollChecklistOutput,
     }, async ({ month }) => withToolLogging("payroll_checklist", () => withBackendGuard("payroll_checklist", "/v1/payroll/prep/employees", async () => {

package/dist/tools/permissions.d.ts

@@ -2,16 +2,13 @@
  * Permissions tools for the Frihet MCP server — D4-B megasprint (2 tools).
  *
  * Tools:
- *   1. permissions_matrix — full role/permission matrix for the workspace
- *   2. permissions_me     — caller's own role + permissions
+ *   1. permissions_matrix — documented RBAC-model snapshot
+ *   2. permissions_me     — RBAC model + actual API-key scope reporting
  *
  * REST surface: /v1/permissions/matrix, /v1/permissions/me
  *
- * Permissions are derived from role + workspace overrides. Tools are read-only —
- * mutating roles is done via team_invite / team_role_update (existing).
- *
- * NOTE: ERP backend endpoints land in parallel D4-A wave. 404s propagate as isError
- * until backend ships.
+ * These read-only reports are useful for discovery, but neither is an exhaustive
+ * runtime-authorization prediction. A backend 403 remains authoritative.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { IFrihetClient } from "../client-interface.js";