@frihet/mcp-server 1.16.6 → 2.0.0

package/dist/tools/deposits.js

@@ -2,7 +2,14 @@
  * Deposit 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, depositItemOutput, actionResultOutput } from "./shared.js";
+import { applyDepositFields, depositFields, DepositInputError } from "../deposit-contract.js";
+import { withToolLogging, confirmationRequiredError, formatPaginatedResponse, formatRecord, listContent, getContent, mutateContent, enrichResponse, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, DELETE_ANNOTATIONS, ERROR_CONTENT_ANNOTATIONS, paginatedOutput, deleteResultOutput, depositItemOutput, actionResultOutput } from "./shared.js";
+function depositValidationResponse(error) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: `Error: ${error.message}`, annotations: ERROR_CONTENT_ANNOTATIONS }],
+    };
+}
 export function registerDepositTools(server, client) {
     // -- list_deposits --
     server.registerTool("list_deposits", {
@@ -45,8 +52,8 @@ export function registerDepositTools(server, client) {
         const result = await client.listDeposits({ limit, offset, after, fields, from, to, clientId, status });
         const hints = enrichResponse("deposits", "list", result.data);
         return {
-            content: [listContent(formatPaginatedResponse("deposits", result))],
-            structuredContent: { ...result, ...hints },
+            content: [listContent(formatPaginatedResponse("deposits", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- get_deposit --
@@ -69,69 +76,71 @@ export function registerDepositTools(server, client) {
     // -- create_deposit --
     server.registerTool("create_deposit", {
         title: "Create Deposit",
-        description: "Record a new deposit from a client. Requires clientId and amount. " +
-            "Useful for tracking advance payments, retainers, and security deposits. " +
-            "Example: clientId='abc123', amount=500, currency='EUR', description='Project retainer' " +
-            "/ Registra un nuevo deposito de un cliente. Requiere clientId e importe. " +
-            "Util para adelantos, retenciones y depositos de garantia.",
+        description: "Record a deposit in Frihet's bookkeeping; no money is transferred. Requires clientId, clientName, amount, date and description. " +
+            "The API initializes status='active'; status and notes are not writable. " +
+            "Example: clientId='abc123', clientName='Example Client', amount=500, date='2026-10-21', description='Project retainer' " +
+            "/ Registra un depósito contable sin transferir dinero. Requiere clientId, clientName, amount, date y description. " +
+            "La API inicia el estado 'active'; status y notes no son campos editables.",
         annotations: CREATE_ANNOTATIONS,
-        inputSchema: {
-            clientId: z.string().describe("Client ID / ID del cliente"),
-            clientName: z.string().optional().describe("Client name (denormalized) / Nombre del cliente"),
-            amount: z.number().describe("Deposit amount / Importe del deposito"),
-            currency: z.string().optional().describe("Currency code (e.g. 'EUR', 'USD') / Codigo de moneda"),
-            date: z
-                .string()
-                .optional()
-                .describe("Deposit date in ISO 8601 (YYYY-MM-DD) / Fecha del deposito"),
-            description: z.string().optional().describe("Deposit description / Descripcion del deposito"),
-            status: z
-                .string()
-                .optional()
-                .describe("Status (e.g. 'pending', 'applied', 'refunded') / Estado"),
-            paymentMethod: z
-                .string()
-                .optional()
-                .describe("Payment method (e.g. 'bank_transfer', 'card') / Metodo de pago"),
-            reference: z.string().optional().describe("External reference or receipt number / Referencia externa"),
-            notes: z.string().optional().describe("Internal notes / Notas internas"),
-        },
+        inputSchema: z.object({
+            clientId: depositFields.clientId.describe("Client ID / ID del cliente"),
+            clientName: depositFields.clientName.describe("Client name / Nombre del cliente"),
+            amount: depositFields.amount.describe("Positive deposit amount / Importe positivo del depósito"),
+            currency: depositFields.currency.optional().describe("Currency code, defaults to EUR / Moneda, EUR por defecto"),
+            date: depositFields.receivedDate.describe("Received date (YYYY-MM-DD), sent as receivedDate / Fecha de recepción"),
+            description: depositFields.description.describe("Deposit description / Descripción del depósito"),
+            paymentMethod: depositFields.paymentMethod.describe("Payment method (e.g. bank_transfer) / Método de pago"),
+            reference: depositFields.paymentReference.describe("Payment reference, sent as paymentReference / Referencia del pago"),
+        }).strict(),
         outputSchema: depositItemOutput,
     }, async (input) => withToolLogging("create_deposit", async () => {
-        const result = await client.createDeposit(input);
-        const hints = enrichResponse("deposits", "create", result);
-        return {
-            content: [mutateContent(formatRecord("Deposit created", result))],
-            structuredContent: { ...result, ...hints },
-        };
+        try {
+            const result = await client.createDeposit(input);
+            const hints = enrichResponse("deposits", "create", result);
+            return {
+                content: [mutateContent(formatRecord("Deposit created", result) + hints)],
+                structuredContent: { ...result },
+            };
+        }
+        catch (error) {
+            if (error instanceof DepositInputError)
+                return depositValidationResponse(error);
+            throw error;
+        }
     }));
     // -- update_deposit --
     server.registerTool("update_deposit", {
         title: "Update Deposit",
         description: "Update an existing deposit using PATCH semantics. Only the provided fields will be changed. " +
-            "Example: id='abc123', amount=750, notes='Updated retainer amount' " +
-            "/ Actualiza un deposito existente. Solo se modifican los campos proporcionados.",
+            "At least one writable field is required; status and notes are not writable. " +
+            "Example: id='abc123', reference='RECEIPT-42' " +
+            "/ Actualiza un depósito existente. Requiere al menos un campo editable; status y notes no se pueden guardar.",
         annotations: UPDATE_ANNOTATIONS,
-        inputSchema: {
-            id: z.string().describe("Deposit ID / ID del deposito"),
-            clientId: z.string().optional().describe("Client ID / ID del cliente"),
-            clientName: z.string().optional().describe("Client name / Nombre del cliente"),
-            amount: z.number().optional().describe("Amount / Importe"),
-            currency: z.string().optional().describe("Currency code / Moneda"),
-            date: z.string().optional().describe("Date (YYYY-MM-DD) / Fecha"),
-            description: z.string().optional().describe("Description / Descripcion"),
-            status: z.string().optional().describe("Status / Estado"),
-            paymentMethod: z.string().optional().describe("Payment method / Metodo de pago"),
-            reference: z.string().optional().describe("Reference / Referencia"),
-            notes: z.string().optional().describe("Notes / Notas"),
-        },
+        inputSchema: z.object({
+            id: z.string().min(1).describe("Deposit ID / ID del depósito"),
+            clientId: depositFields.clientId.optional().describe("Client ID / ID del cliente"),
+            clientName: depositFields.clientName.optional().describe("Client name / Nombre del cliente"),
+            amount: depositFields.amount.optional().describe("Positive amount / Importe positivo"),
+            currency: depositFields.currency.optional().describe("Currency code / Moneda"),
+            date: depositFields.receivedDate.optional().describe("Received date (YYYY-MM-DD) / Fecha de recepción"),
+            description: depositFields.description.optional().describe("Description / Descripción"),
+            paymentMethod: depositFields.paymentMethod.describe("Payment method / Método de pago"),
+            reference: depositFields.paymentReference.describe("Payment reference / Referencia del pago"),
+        }).strict().refine(({ id: _id, ...fields }) => Object.values(fields).some((value) => value !== undefined), { message: "Provide at least one writable deposit field / Indica al menos un campo del depósito" }),
         outputSchema: depositItemOutput,
     }, async ({ id, ...data }) => withToolLogging("update_deposit", async () => {
-        const result = await client.updateDeposit(id, data);
-        return {
-            content: [mutateContent(formatRecord("Deposit updated", result))],
-            structuredContent: result,
-        };
+        try {
+            const result = await client.updateDeposit(id, data);
+            return {
+                content: [mutateContent(formatRecord("Deposit updated", result))],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            if (error instanceof DepositInputError)
+                return depositValidationResponse(error);
+            throw error;
+        }
     }));
     // -- delete_deposit --
     server.registerTool("delete_deposit", {
@@ -147,8 +156,8 @@ export function registerDepositTools(server, client) {
         await client.deleteDeposit(id);
         const hints = enrichResponse("deposits", "delete", { id });
         return {
-            content: [mutateContent(`Deposit ${id} deleted successfully. / Deposito ${id} eliminado correctamente.`)],
-            structuredContent: { success: true, id, ...hints },
+            content: [mutateContent(`Deposit ${id} deleted successfully. / Deposito ${id} eliminado correctamente.` + hints)],
+            structuredContent: { success: true, id },
         };
     }));
     // -- apply_deposit --
@@ -156,43 +165,63 @@ export function registerDepositTools(server, client) {
         title: "Apply Deposit",
         description: "Apply a deposit to an invoice or mark it as used. " +
             "Transitions the deposit status to 'applied'. " +
-            "Example: id='dep_abc123', invoiceId='inv_xyz' " +
-            "/ Aplica un deposito a una factura o lo marca como utilizado.",
+            "ERP requires invoiceId + invoiceNumber + amount on the body; id is the deposit ID; notes is not writable. " +
+            "Example: id='dep_abc123', invoiceId='inv_xyz', invoiceNumber='F-2026-007', amount=150 " +
+            "/ Aplica un deposito a una factura o lo marca como utilizado. Requiere invoiceId, invoiceNumber y amount; notes no se puede guardar.",
         annotations: UPDATE_ANNOTATIONS,
-        inputSchema: {
-            id: z.string().describe("Deposit ID / ID del deposito"),
-            invoiceId: z
-                .string()
-                .optional()
+        inputSchema: z.object({
+            id: z.string().min(1).describe("Deposit ID / ID del deposito"),
+            invoiceId: applyDepositFields.invoiceId
                 .describe("Invoice ID to apply the deposit to / ID de la factura a la que aplicar el deposito"),
-            notes: z.string().optional().describe("Application notes / Notas de aplicacion"),
-        },
+            invoiceNumber: applyDepositFields.invoiceNumber
+                .describe("Invoice number (document number) the deposit applies to / Numero de la factura"),
+            amount: applyDepositFields.amount
+                .describe("Amount of the deposit to apply in EUR / Importe del deposito a aplicar en EUR"),
+        }).strict(),
         outputSchema: actionResultOutput,
     }, async ({ id, ...data }) => withToolLogging("apply_deposit", async () => {
-        const result = await client.applyDeposit(id, data);
-        return {
-            content: [mutateContent(formatRecord("Deposit applied", result))],
-            structuredContent: result,
-        };
+        try {
+            const result = await client.applyDeposit(id, data);
+            return {
+                content: [mutateContent(formatRecord("Deposit applied", result))],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            if (error instanceof DepositInputError)
+                return depositValidationResponse(error);
+            throw error;
+        }
     }));
     // -- refund_deposit --
     server.registerTool("refund_deposit", {
-        title: "Refund Deposit",
-        description: "Refund a deposit back to the client. " +
-            "Transitions the deposit status to 'refunded'. " +
-            "Example: id='dep_abc123', reason='Project cancelled' " +
-            "/ Devuelve un deposito al cliente.",
-        annotations: UPDATE_ANNOTATIONS,
-        inputSchema: {
-            id: z.string().describe("Deposit ID / ID del deposito"),
-            reason: z.string().optional().describe("Reason for the refund / Motivo de la devolucion"),
-            notes: z.string().optional().describe("Refund notes / Notas de la devolucion"),
-        },
+        title: "Record Deposit Refund",
+        description: "Record a full or partial deposit refund in Frihet's bookkeeping; no money is transferred. Requires confirm=true. " +
+            "Omit amount to record a refund of the remaining balance. Only a full refund sets status='refunded'. " +
+            "A new call can record another partial refund; after an uncertain result, check get_deposit before retrying. " +
+            "Example: id='dep_abc123', amount=50, confirm=true " +
+            "/ Registra una devolución total o parcial del depósito sin transferir dinero. Requiere confirm=true. " +
+            "Omite amount para registrar la devolución del saldo restante. Solo la devolución total marca el estado 'refunded'. " +
+            "Una nueva llamada puede registrar otra devolución parcial; ante un resultado incierto, consulta get_deposit antes de repetir.",
+        annotations: { ...UPDATE_ANNOTATIONS, destructiveHint: true, idempotentHint: false },
+        inputSchema: z.object({
+            id: z.string().min(1).describe("Deposit ID / ID del depósito"),
+            amount: z.number().positive().optional().describe("Positive refund amount in the deposit currency; omit for the remaining balance / Importe positivo en la moneda del depósito; omite para el saldo restante"),
+            confirm: z
+                .boolean()
+                .describe("Must be true to record the refund; no money is transferred / Debe ser true para registrar la devolución; no se transfiere dinero"),
+        }).strict(),
         outputSchema: actionResultOutput,
-    }, async ({ id, ...data }) => withToolLogging("refund_deposit", async () => {
-        const result = await client.refundDeposit(id, data);
+    }, async ({ id, confirm, amount }) => withToolLogging("refund_deposit", async () => {
+        if (confirm !== true) {
+            return confirmationRequiredError("Error: confirm=true is required to record a deposit refund. " +
+                "This reduces the recorded remaining balance; no money is transferred and this tool cannot undo the entry. / " +
+                "Se requiere confirm=true para registrar la devolución y reducir el saldo contable. " +
+                "No se transfiere dinero y esta herramienta no permite deshacer el registro.");
+        }
+        const result = await client.refundDeposit(id, amount === undefined ? {} : { amount });
         return {
-            content: [mutateContent(formatRecord("Deposit refunded", result))],
+            content: [mutateContent(formatRecord("Deposit refund recorded (no money transferred)", result))],
             structuredContent: result,
         };
     }));

package/dist/tools/einvoice.d.ts

@@ -52,15 +52,29 @@ export declare const eInvoiceFormatSchema: z.ZodEnum<{
     "xrechnung-cii": "xrechnung-cii";
     "xrechnung-ubl": "xrechnung-ubl";
     "facturx-en16931": "facturx-en16931";
+    fatturapa: "fatturapa";
+    "peppol-bis-3": "peppol-bis-3";
+    ubl: "ubl";
+    cii: "cii";
     "facturx-extended": "facturx-extended";
     "facturx-basic": "facturx-basic";
     "facturx-minimum": "facturx-minimum";
+}>;
+export type EInvoiceFormat = z.infer<typeof eInvoiceFormatSchema>;
+/** 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 declare const eInvoiceExportFormatSchema: z.ZodEnum<{
+    facturae: "facturae";
+    "xrechnung-cii": "xrechnung-cii";
+    "xrechnung-ubl": "xrechnung-ubl";
+    "facturx-en16931": "facturx-en16931";
     fatturapa: "fatturapa";
+    "peppol-bis-3": "peppol-bis-3";
+    "fa-2-ksef": "fa-2-ksef";
     ubl: "ubl";
     cii: "cii";
-    "peppol-bis-3": "peppol-bis-3";
 }>;
-export type EInvoiceFormat = z.infer<typeof eInvoiceFormatSchema>;
 export declare const sendEInvoiceOutput: z.ZodObject<{
     workflowRunId: z.ZodString;
     status: z.ZodLiteral<"queued">;

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/expenses.d.ts

@@ -2,6 +2,22 @@
  * Expense tools for the Frihet MCP server.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod/v4";
 import type { IFrihetClient } from "../client-interface.js";
+/**
+ * Public Zod schema for `create_expense` input — exported for tests so the
+ * validation contract can be exercised directly without spinning up a stub
+ * MCP server. The registered tool's inputSchema MUST wrap this exact object
+ * (MCP serializes the live Zod object to JSON Schema).
+ */
+export declare const createExpenseInputSchema: z.ZodObject<{
+    description: z.ZodString;
+    amount: z.ZodNumber;
+    category: z.ZodOptional<z.ZodString>;
+    date: z.ZodOptional<z.ZodISODate>;
+    vendor: z.ZodOptional<z.ZodString>;
+    taxDeductible: z.ZodOptional<z.ZodBoolean>;
+    paidDate: z.ZodOptional<z.ZodISODate>;
+}, z.core.$strict>;
 export declare function registerExpenseTools(server: McpServer, client: IFrihetClient): void;
 //# sourceMappingURL=expenses.d.ts.map

package/dist/tools/expenses.js

@@ -3,6 +3,38 @@
  */
 import { z } from "zod/v4";
 import { withToolLogging, formatPaginatedResponse, formatRecord, listContent, getContent, mutateContent, enrichResponse, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, DELETE_ANNOTATIONS, paginatedOutput, deleteResultOutput, expenseItemOutput } from "./shared.js";
+/**
+ * Public Zod schema for `create_expense` input — exported for tests so the
+ * validation contract can be exercised directly without spinning up a stub
+ * MCP server. The registered tool's inputSchema MUST wrap this exact object
+ * (MCP serializes the live Zod object to JSON Schema).
+ */
+export const createExpenseInputSchema = z
+    .object({
+    description: z.string().trim().min(1).max(1000).describe("Expense description / Descripcion del gasto"),
+    amount: z.number().finite().min(0.01).max(10_000_000).describe("Amount in EUR / Importe en EUR"),
+    category: z
+        .string()
+        .max(10_000)
+        .optional()
+        .describe("Expense category (e.g. 'office', 'travel', 'software') / Categoria"),
+    date: z
+        .iso.date()
+        .optional()
+        .describe("Expense date in ISO 8601 (YYYY-MM-DD) / Fecha del gasto"),
+    vendor: z.string().trim().max(200).optional().describe("Vendor/supplier name / Nombre del proveedor"),
+    taxDeductible: z
+        .boolean()
+        .optional()
+        .describe("Whether the expense is tax deductible / Si el gasto es deducible fiscalmente"),
+    paidDate: z
+        .iso.date()
+        .optional()
+        .describe("Optional payment date in ISO 8601 (YYYY-MM-DD). Determines when the expense is treated as paid. " +
+        "Must be a real calendar date (2028-02-29 is valid, 2026-02-29 is not). " +
+        "/ Fecha de pago opcional en ISO 8601 (YYYY-MM-DD). Determina cuando se considera pagado el gasto."),
+})
+    .strict();
 export function registerExpenseTools(server, client) {
     // -- list_expenses --
     server.registerTool("list_expenses", {
@@ -45,8 +77,8 @@ export function registerExpenseTools(server, client) {
         const result = await client.listExpenses({ limit, offset, after, fields, from, to, vendorId, category });
         const hints = enrichResponse("expenses", "list", result.data);
         return {
-            content: [listContent(formatPaginatedResponse("expenses", result))],
-            structuredContent: { ...result, ...hints },
+            content: [listContent(formatPaginatedResponse("expenses", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- get_expense --
@@ -67,38 +99,26 @@ export function registerExpenseTools(server, client) {
         };
     }));
     // -- create_expense --
+    // paidDate (#1062): optional ISO calendar date. Strict shape (zero-padded
+    // YYYY-MM-DD) AND real-calendar validity (rejects 2026-02-29, 2026-04-31,
+    // non-zero-padded forms). Forwards verbatim to the REST paidDate field —
+    // the existing pass-through in client.createExpense handles the wire shape.
     server.registerTool("create_expense", {
         title: "Create Expense",
         description: "Record a new expense. Requires a description and amount. " +
             "Useful for tracking business costs, deductible expenses, and vendor payments. " +
-            "Example: description='Office supplies', amount=49.99, category='office', vendor='Amazon', taxDeductible=true " +
+            "Example: description='Office supplies', amount=49.99, category='office', vendor='Amazon', taxDeductible=true, paidDate='2026-03-15' " +
             "/ Registra un nuevo gasto. Requiere descripcion e importe. " +
             "Util para seguimiento de costes, gastos deducibles y pagos a proveedores.",
         annotations: CREATE_ANNOTATIONS,
-        inputSchema: {
-            description: z.string().describe("Expense description / Descripcion del gasto"),
-            amount: z.number().describe("Amount in EUR / Importe en EUR"),
-            category: z
-                .string()
-                .optional()
-                .describe("Expense category (e.g. 'office', 'travel', 'software') / Categoria"),
-            date: z
-                .string()
-                .optional()
-                .describe("Expense date in ISO 8601 (YYYY-MM-DD) / Fecha del gasto"),
-            vendor: z.string().optional().describe("Vendor/supplier name / Nombre del proveedor"),
-            taxDeductible: z
-                .boolean()
-                .optional()
-                .describe("Whether the expense is tax deductible / Si el gasto es deducible fiscalmente"),
-        },
+        inputSchema: createExpenseInputSchema,
         outputSchema: expenseItemOutput,
     }, async (input) => withToolLogging("create_expense", async () => {
         const result = await client.createExpense(input);
         const hints = enrichResponse("expenses", "create", result);
         return {
-            content: [mutateContent(formatRecord("Expense created", result))],
-            structuredContent: { ...result, ...hints },
+            content: [mutateContent(formatRecord("Expense created", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- update_expense --
@@ -110,10 +130,10 @@ export function registerExpenseTools(server, client) {
         annotations: UPDATE_ANNOTATIONS,
         inputSchema: {
             id: z.string().describe("Expense ID / ID del gasto"),
-            description: z.string().optional().describe("Description / Descripcion"),
+            description: z.string().max(10_000).optional().describe("Description / Descripcion"),
             amount: z.number().optional().describe("Amount in EUR / Importe"),
-            category: z.string().optional().describe("Category / Categoria"),
-            date: z.string().optional().describe("Date (YYYY-MM-DD) / Fecha"),
+            category: z.string().max(10_000).optional().describe("Category / Categoria"),
+            date: z.iso.date().optional().describe("Date (YYYY-MM-DD) / Fecha"),
             vendor: z.string().optional().describe("Vendor / Proveedor"),
             taxDeductible: z.boolean().optional().describe("Tax deductible / Deducible"),
         },
@@ -139,8 +159,8 @@ export function registerExpenseTools(server, client) {
         await client.deleteExpense(id);
         const hints = enrichResponse("expenses", "delete", { id });
         return {
-            content: [mutateContent(`Expense ${id} deleted successfully. / Gasto ${id} eliminado correctamente.`)],
-            structuredContent: { success: true, id, ...hints },
+            content: [mutateContent(`Expense ${id} deleted successfully. / Gasto ${id} eliminado correctamente.` + hints)],
+            structuredContent: { success: true, id },
         };
     }));
 }

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