@frihet/mcp-server 1.16.5 → 1.17.0

package/dist/tools/intelligence.js

@@ -10,7 +10,98 @@
  * - duplicate_invoice: Clone an invoice for a new period
  */
 import { z } from "zod/v4";
-import { withToolLogging, formatRecord, getContent, mutateContent, openObjectOutput, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, } from "./shared.js";
+import { withToolLogging, formatRecord, getContent, mutateContent, invoiceItemOutput, openObjectOutput, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, } from "./shared.js";
+const usageLimitOutput = z.union([z.number(), z.literal("unlimited")]);
+const businessContextOutput = z.object({
+    business: z.object({
+        name: z.string(),
+        taxId: z.string().optional(),
+        fiscalZone: z.string(),
+        currency: z.string(),
+        language: z.string(),
+        country: z.string(),
+    }).passthrough(),
+    defaults: z.object({
+        taxRate: z.number(),
+        irpfRate: z.number(),
+        dueDays: z.number(),
+        currency: z.string(),
+    }).passthrough(),
+    plan: z.object({
+        name: z.string(),
+        invoices: z.object({ used: z.number(), limit: usageLimitOutput }),
+        expenses: z.object({ used: z.number(), limit: usageLimitOutput }),
+        aiMessages: z.object({ used: z.number(), limit: usageLimitOutput }),
+    }).passthrough(),
+    series: z.array(z.object({
+        id: z.string().optional(),
+        prefix: z.string().optional(),
+        current: z.number().optional(),
+        year: z.number().optional(),
+    }).passthrough()),
+    recentActivity: z.object({
+        lastInvoice: z.object({
+            number: z.string().optional(),
+            date: z.string().optional(),
+            client: z.string().optional(),
+        }).passthrough().nullable(),
+        lastExpense: z.object({
+            date: z.string().optional(),
+            vendor: z.string().optional(),
+            amount: z.number(),
+        }).passthrough().nullable(),
+        overdueCount: z.number(),
+        overdueAmount: z.number(),
+        unpaidCount: z.number(),
+    }).passthrough(),
+    topClients: z.array(z.object({
+        name: z.string(),
+        totalRevenue: z.number(),
+        invoiceCount: z.number(),
+    }).passthrough()),
+    currentMonth: z.object({
+        revenue: z.number(),
+        expenses: z.number(),
+        profit: z.number(),
+        invoiceCount: z.number(),
+        expenseCount: z.number(),
+    }).passthrough(),
+}).passthrough().describe("Business context snapshot: workspace profile, defaults, plan usage, recent activity and current-month performance");
+const monthlySummaryOutput = z.object({
+    period: z.string(),
+    revenue: z.object({
+        total: z.number(),
+        taxBase: z.number(),
+        tax: z.number(),
+        irpf: z.number(),
+    }).passthrough(),
+    expenses: z.object({
+        total: z.number(),
+        deductible: z.number(),
+        tax: z.number(),
+    }).passthrough(),
+    profit: z.object({
+        gross: z.number(),
+        net: z.number(),
+    }).passthrough(),
+    invoices: z.object({
+        created: z.number(),
+        sent: z.number(),
+        paid: z.number(),
+        overdue: z.number(),
+    }).passthrough(),
+    topClients: z.array(z.object({
+        name: z.string(),
+        totalRevenue: z.number(),
+        invoiceCount: z.number(),
+    }).passthrough()),
+    byCategory: z.record(z.string(), z.number()),
+    taxLiability: z.object({
+        vatPayable: z.number(),
+        irpfRetained: z.number(),
+        estimatedModel303: z.number(),
+    }).passthrough(),
+}).passthrough().describe("Monthly business summary with revenue, expenses, profit, invoice status, top clients and expense categories");
 export function registerIntelligenceTools(server, client) {
     // -- get_business_context --
     server.registerTool("get_business_context", {
@@ -22,7 +113,7 @@ export function registerIntelligenceTools(server, client) {
             "principales clientes y resumen del mes actual. Llama a esto PRIMERO en cualquier sesion.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {},
-        outputSchema: openObjectOutput("Business context snapshot: workspace profile, fiscal setup, recent activity / Contexto de negocio: perfil, configuración fiscal y actividad reciente"),
+        outputSchema: businessContextOutput,
     }, async () => withToolLogging("get_business_context", async () => {
         const result = await client.getBusinessContext();
         return {
@@ -46,7 +137,7 @@ export function registerIntelligenceTools(server, client) {
                 .describe("Month in YYYY-MM format (defaults to current month). Example: '2026-03' " +
                 "/ Mes en formato YYYY-MM (por defecto el mes actual)"),
         },
-        outputSchema: openObjectOutput("Monthly P&L summary: revenue, expenses, profit, tax liability, invoice stats / Resumen mensual: ingresos, gastos, beneficio, impuestos"),
+        outputSchema: monthlySummaryOutput,
     }, async ({ month }) => withToolLogging("get_monthly_summary", async () => {
         const result = await client.getMonthlySummary(month);
         const label = month ? `Monthly Summary (${month})` : "Monthly Summary (current month)";
@@ -101,7 +192,7 @@ export function registerIntelligenceTools(server, client) {
                 .optional()
                 .describe("Due date for the new invoice (YYYY-MM-DD) / Fecha de vencimiento de la nueva factura"),
         },
-        outputSchema: openObjectOutput("The newly created draft invoice, cloned from the original / La nueva factura borrador, clonada de la original"),
+        outputSchema: invoiceItemOutput.describe("The newly created draft invoice, cloned from the original / La nueva factura borrador, clonada de la original"),
     }, async ({ id, newIssueDate, newDueDate }) => withToolLogging("duplicate_invoice", async () => {
         // 1. Fetch the original invoice (returns the FULL raw stored document —
         //    payments, verifactu, eInvoice, operationType, createdBy, etc.)

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, 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()
@@ -133,8 +141,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 +173,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 +193,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
@@ -200,8 +209,8 @@ export function registerInvoiceTools(server, client) {
         const result = await client.createInvoice(input);
         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 +244,73 @@ 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 {
+                content: [
+                    {
+                        type: "text",
+                        text: "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.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // 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,24 +355,71 @@ 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 {
+                content: [
+                    {
+                        type: "text",
+                        text: "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.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const invoice = await client.getInvoice(id);
+        if (invoice["status"] === "cancelled") {
+            return {
+                content: [{ type: "text", text: "Error: a cancelled invoice cannot be sent." }],
+                isError: true,
+            };
+        }
+        let recipientEmail = to;
+        if (!recipientEmail) {
+            const clientId = typeof invoice["clientId"] === "string" ? invoice["clientId"] : undefined;
+            if (!clientId) {
+                return {
+                    content: [{ type: "text", text: "Error: this invoice has no linked client with a saved email address." }],
+                    isError: true,
+                };
+            }
+            const linkedClient = await client.getClient(clientId);
+            recipientEmail = typeof linkedClient["email"] === "string" && linkedClient["email"].trim()
+                ? linkedClient["email"].trim()
+                : undefined;
+            if (!recipientEmail) {
+                return {
+                    content: [{ type: "text", text: "Error: the linked client has no saved email address." }],
+                    isError: true,
+                };
+            }
+        }
+        const result = await client.sendInvoice(id, recipientEmail);
         return {
             content: [mutateContent(formatRecord("Invoice sent", result))],
             structuredContent: result,
@@ -344,8 +447,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 +459,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,8 +542,8 @@ 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 --

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";

package/dist/tools/permissions.js

@@ -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 { withToolLogging, formatRecord, getContent, READ_ONLY_ANNOTATIONS, permissionsMatrixOutput, permissionsMeOutput, } from "./shared.js";
 import { withBackendGuard } from "./backend-availability.js";
@@ -19,10 +16,9 @@ export function registerPermissionsTools(server, client) {
     // -- permissions_matrix --
     server.registerTool("permissions_matrix", {
         title: "Permissions Matrix",
-        description: "Return the full role-to-permission matrix for the workspace. " +
-            "Lists every role with the permissions it grants and every protected resource. " +
-            "Useful for security audits, role design, and compliance reporting. " +
-            "/ Devuelve la matriz completa de roles y permisos del workspace.",
+        description: "Return the backend's documented RBAC-model snapshot by role, resource, and action. " +
+            "It is not derived from Firestore rules and is not a runtime authorization guarantee; " +
+            "a backend 403 is authoritative. / Devuelve el modelo RBAC documentado, no una garantia exhaustiva de autorizacion.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {},
         outputSchema: permissionsMatrixOutput,
@@ -36,9 +32,10 @@ export function registerPermissionsTools(server, client) {
     // -- permissions_me --
     server.registerTool("permissions_me", {
         title: "My Permissions",
-        description: "Return the caller's effective role + permissions in the current workspace. " +
-            "Useful for client-side UI gating, debugging access errors, and capability discovery. " +
-            "/ Devuelve el rol efectivo y los permisos del llamante en el workspace actual.",
+        description: "Return the caller's backwards-compatible RBAC-model fields separately from actual API-key scopes, " +
+            "unrestricted-key semantics, known e-invoice scope denial, and surfaces not reported here. " +
+            "This is non-exhaustive; use the exact backend 403 as authority. " +
+            "/ Separa el modelo RBAC de los scopes reales de la API key; no es una autorizacion exhaustiva.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {},
         outputSchema: permissionsMeOutput,