@frihet/mcp-server 1.16.6 → 2.0.0

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,

package/dist/tools/products.js

@@ -67,9 +67,9 @@ export function registerProductTools(server, client) {
             "Los productos se pueden usar al crear facturas y presupuestos para entrada rapida de datos.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
-            name: z.string().describe("Product/service name / Nombre del producto o servicio"),
-            unitPrice: z.number().describe("Unit price in EUR / Precio unitario en EUR"),
-            description: z.string().optional().describe("Product description / Descripcion"),
+            name: z.string().trim().min(1).max(200).describe("Product/service name / Nombre del producto o servicio"),
+            unitPrice: z.number().finite().min(0).max(10_000_000).describe("Unit price in EUR / Precio unitario en EUR"),
+            description: z.string().max(2000).optional().describe("Product description / Descripcion"),
             taxRate: z
                 .number()
                 .min(0)
@@ -94,9 +94,9 @@ export function registerProductTools(server, client) {
         annotations: UPDATE_ANNOTATIONS,
         inputSchema: {
             id: z.string().describe("Product ID / ID del producto"),
-            name: z.string().optional().describe("Name / Nombre"),
-            unitPrice: z.number().optional().describe("Unit price / Precio unitario"),
-            description: z.string().optional().describe("Description / Descripcion"),
+            name: z.string().trim().min(1).max(200).optional().describe("Name / Nombre"),
+            unitPrice: z.number().finite().min(0).max(10_000_000).optional().describe("Unit price / Precio unitario"),
+            description: z.string().max(2000).optional().describe("Description / Descripcion"),
             taxRate: z.number().min(0).max(100).optional().describe("Tax rate % / IVA %"),
         },
         outputSchema: productItemOutput,

package/dist/tools/quotes.js

@@ -2,19 +2,19 @@
  * Quote 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, quoteItemOutput, actionResultOutput } from "./shared.js";
+import { withToolLogging, confirmationRequiredError, formatPaginatedResponse, formatRecord, listContent, getContent, mutateContent, enrichResponse, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, DELETE_ANNOTATIONS, paginatedOutput, documentDeleteResultOutput, quoteItemOutput, actionResultOutput } from "./shared.js";
 const quoteItemSchema = 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();
 // Optional client-identity + ES fiscal fields the Frihet API accepts on quote
 // create+update (mirrors the invoice subset the backend supports for quotes).
 const quoteOptionalFields = {
     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()
@@ -24,11 +24,11 @@ const quoteOptionalFields = {
         .optional()
         .describe("Client billing address / Direccion fiscal del cliente"),
     issueDate: z
-        .string()
+        .iso.date()
         .optional()
         .describe("Issue date in ISO 8601 (YYYY-MM-DD), defaults to today / Fecha de emision"),
     dueDate: z
-        .string()
+        .iso.date()
         .optional()
         .describe("Due date in ISO 8601 (YYYY-MM-DD) / Fecha de vencimiento"),
     taxRate: z
@@ -132,17 +132,17 @@ export function registerQuoteTools(server, client) {
             "Los presupuestos se pueden convertir en facturas despues.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
-            clientName: z.string().describe("Client name / Nombre del cliente"),
+            clientName: z.string().trim().min(1).max(200).describe("Client name / Nombre del cliente"),
             ...quoteOptionalFields,
             items: z
                 .array(quoteItemSchema)
                 .min(1)
                 .describe("Line items (each with description, quantity, unitPrice) / Conceptos del presupuesto"),
             validUntil: z
-                .string()
+                .iso.date()
                 .optional()
                 .describe("Expiry date in ISO 8601 (YYYY-MM-DD) / Fecha de validez"),
-            notes: z.string().optional().describe("Additional notes shown on the quote / Notas adicionales"),
+            notes: z.string().max(10_000).optional().describe("Additional notes shown on the quote / Notas adicionales"),
             status: z
                 .enum(["draft", "sent", "accepted", "rejected", "expired"])
                 .optional()
@@ -153,8 +153,8 @@ export function registerQuoteTools(server, client) {
         const result = await client.createQuote(input);
         const hints = enrichResponse("quotes", "create", result);
         return {
-            content: [mutateContent(formatRecord("Quote created", result))],
-            structuredContent: { ...result, ...hints },
+            content: [mutateContent(formatRecord("Quote created", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- update_quote --
@@ -187,37 +187,183 @@ export function registerQuoteTools(server, client) {
     // -- delete_quote --
     server.registerTool("delete_quote", {
         title: "Delete Quote",
-        description: "Permanently delete a quote by its ID. This action cannot be undone. " +
-            "/ Elimina permanentemente un presupuesto por su ID. Esta accion no se puede deshacer.",
+        description: "Delete a quote by its ID. Requires confirm=true. " +
+            "Only a clean DRAFT with no delivery, response, attachment, or conversion evidence is removed permanently; a protected draft is refused and left unchanged. A sent/accepted/rejected/expired quote is NOT " +
+            "destroyed: the backend CANCELS it (status=cancelled) — the same non-destructive path invoices " +
+            "take — and it stays readable via get_quote. The result reports which happened in `outcome` " +
+            "(\"deleted\" or \"cancelled\"). " +
+            "/ Elimina un presupuesto por su ID. Requiere confirm=true. Solo un BORRADOR limpio sin evidencia de entrega, respuesta, adjuntos o conversion se " +
+            "elimina de forma permanente; un borrador protegido se rechaza sin cambios. Uno ya enviado/aceptado/rechazado NO se destruye: se CANCELA " +
+            "(status=cancelled) y sigue consultable con get_quote.",
         annotations: DELETE_ANNOTATIONS,
         inputSchema: {
             id: z.string().describe("Quote ID / ID del presupuesto"),
+            confirm: z
+                .boolean()
+                .describe("Must be true to confirm deletion / Debe ser true para confirmar la eliminacion"),
         },
-        outputSchema: deleteResultOutput,
-    }, async ({ id }) => withToolLogging("delete_quote", async () => {
-        await client.deleteQuote(id);
+        outputSchema: documentDeleteResultOutput,
+    }, async ({ id, confirm }) => withToolLogging("delete_quote", async () => {
+        if (!confirm) {
+            return confirmationRequiredError("Error: confirm=true is required to delete a quote. " +
+                "A clean draft without delivery, response, attachment, or conversion evidence is removed permanently; a protected draft is refused; a sent/accepted quote is CANCELLED " +
+                "(status=cancelled) instead and remains in the record. " +
+                "Set confirm=true to proceed. / " +
+                "Se requiere confirm=true para eliminar un presupuesto.");
+        }
+        // 204 → undefined (draft row destroyed). 200 → soft-cancel body. See GAP-12.
+        const outcome = await client.deleteQuote(id);
+        const cancelled = !!outcome && typeof outcome === "object";
+        const body = cancelled ? outcome : {};
+        const previous = typeof body["previousStatus"] === "string" ? ` (was ${body["previousStatus"]})` : "";
         return {
-            content: [mutateContent(`Quote ${id} deleted successfully. / Presupuesto ${id} eliminado correctamente.`)],
-            structuredContent: { success: true, id },
+            content: [mutateContent(cancelled
+                    ? `Quote ${id} was CANCELLED, not deleted${previous}: it still exists with status=cancelled. / ` +
+                        `Presupuesto ${id} CANCELADO, no eliminado: sigue existiendo con status=cancelled.`
+                    : `Quote ${id} deleted permanently (it was a draft). / ` +
+                        `Presupuesto ${id} eliminado permanentemente (era un borrador).`)],
+            structuredContent: {
+                success: true,
+                id,
+                ...body,
+                outcome: cancelled ? "cancelled" : "deleted",
+            },
         };
     }));
     // -- send_quote --
     server.registerTool("send_quote", {
         title: "Send Quote",
-        description: "Send a quote/estimate to the client via email. Optionally override the recipient email address. " +
+        description: "Send a quote/estimate to the client via email. Requires confirm=true. " +
+            "Optionally override the recipient email address. " +
             "The quote must exist and should not already be expired or rejected. " +
-            "/ Envia un presupuesto al cliente por email. Opcionalmente se puede cambiar el email destinatario.",
+            "Sending reaches a third party and cannot be recalled. " +
+            "/ Envia un presupuesto 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("Quote ID / ID del presupuesto"),
             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_quote", async () => {
-        const result = await client.sendQuote(id, to);
+    }, async ({ id, to, confirm }) => withToolLogging("send_quote", async () => {
+        if (!confirm) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: confirm=true is required to send a quote. " +
+                            "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 un presupuesto por email a un tercero.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const quote = await client.getQuote(id);
+        const status = typeof quote["status"] === "string" ? quote["status"] : undefined;
+        if (status && ["expired", "rejected", "cancelled"].includes(status)) {
+            return {
+                content: [{ type: "text", text: `Error: a ${status} quote 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 quote["clientId"] === "string" && quote["clientId"].trim()
+                ? quote["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 quote["clientEmail"] === "string" && quote["clientEmail"].trim()
+                    ? quote["clientEmail"].trim()
+                    : typeof quote["email"] === "string" && quote["email"].trim()
+                        ? quote["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 quote, 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; el presupuesto 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 quote has no linked client with a saved email address.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        const result = await client.sendQuote(id, recipientEmail);
+        const enrichedResult = {
+            ...(result && typeof result === "object" ? result : {}),
+            effectiveRecipient: recipientEmail,
+        };
         return {
-            content: [mutateContent(formatRecord("Quote sent", result))],
-            structuredContent: result,
+            content: [mutateContent(formatRecord("Quote sent", enrichedResult))],
+            structuredContent: enrichedResult,
         };
     }));
 }

package/dist/tools/recurring.js

@@ -16,7 +16,7 @@
  * Backend: /v1/recurring/* endpoints live as of Wave 4-A (Frihet-ERP functions/src/publicApi.ts).
  */
 import { z } from "zod/v4";
-import { withToolLogging, formatPaginatedResponse, formatRecord, listContent, getContent, mutateContent, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, DELETE_ANNOTATIONS, paginatedOutput, actionResultOutput, deleteResultOutput, recurringInvoiceItemOutput, } from "./shared.js";
+import { withToolLogging, confirmationRequiredError, formatPaginatedResponse, formatRecord, listContent, getContent, mutateContent, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, UPDATE_ANNOTATIONS, DELETE_ANNOTATIONS, paginatedOutput, actionResultOutput, deleteResultOutput, recurringInvoiceItemOutput, } from "./shared.js";
 export function registerRecurringTools(server, client) {
     // -- list_recurring_invoices --
     server.registerTool("list_recurring_invoices", {
@@ -191,17 +191,9 @@ export function registerRecurringTools(server, client) {
         outputSchema: deleteResultOutput,
     }, async ({ id, confirm }) => withToolLogging("delete_recurring_invoice", async () => {
         if (!confirm) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "Error: confirm=true is required to delete a recurring invoice template. " +
-                            "This will stop all future invoice generation from this template. Set confirm=true to proceed. / " +
-                            "Se requiere confirm=true para eliminar la plantilla de factura recurrente.",
-                    },
-                ],
-                isError: true,
-            };
+            return confirmationRequiredError("Error: confirm=true is required to delete a recurring invoice template. " +
+                "This will stop all future invoice generation from this template. Set confirm=true to proceed. / " +
+                "Se requiere confirm=true para eliminar la plantilla de factura recurrente.");
         }
         await client.deleteRecurringInvoice(id);
         return {
@@ -212,23 +204,32 @@ export function registerRecurringTools(server, client) {
     // -- run_recurring_now --
     server.registerTool("run_recurring_now", {
         title: "Run Recurring Invoice Now",
-        description: "Manually trigger immediate generation of the next invoice instance from a recurring template. " +
-            "Useful for billing ahead of schedule or recovering from a missed automated run. " +
-            "The generated invoice is created as a draft; review and send separately. " +
-            "Example: templateId='rec_abc123' " +
-            "/ Genera manualmente la siguiente instancia de una factura recurrente. " +
-            "Util para facturar antes de lo programado o recuperar un ciclo perdido. " +
-            "La factura generada se crea como borrador; revisar y enviar por separado.",
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-        inputSchema: {
-            templateId: z.string().describe("Recurring invoice template ID / ID de la plantilla de factura recurrente"),
+        description: "Generate an invoice from a recurring template and update its run count and last-run date. Requires confirm=true. " +
+            "draftOnly defaults to true. With draftOnly=false, the invoice is created with status='sent' and may trigger fiscal numbering and automatic tax submission. " +
+            "Both modes may deliver configured invoice-created webhooks and notify workspace admins/accountants; this endpoint does not email the invoice to the client. " +
+            "Each new call can create another invoice; check the template and invoices after an uncertain result before retrying. " +
+            "Example: templateId='rec_abc123', confirm=true " +
+            "/ Genera una factura recurrente y actualiza el contador y la fecha de ejecución. Requiere confirm=true. " +
+            "Por defecto crea un borrador; con draftOnly=false crea el estado 'sent' y puede activar la numeración y remisión fiscal automática. " +
+            "Ambas opciones pueden activar webhooks y avisos internos; esta operación no envía la factura por correo al cliente. " +
+            "Una nueva llamada puede crear otra factura; comprueba la plantilla y las facturas antes de repetir un resultado incierto.",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+        inputSchema: z.object({
+            templateId: z.string().min(1).describe("Recurring invoice template ID / ID de la plantilla de factura recurrente"),
             draftOnly: z
                 .boolean()
                 .optional()
-                .describe("If true, create as draft only (default true). Set false to create and mark as sent immediately. / Si true, crea como borrador. Set false para crear y marcar como enviada."),
-        },
+                .describe("Default true creates a draft; false creates status='sent' and may trigger automatic fiscal submission. Neither option emails the client. / Por defecto true crea un borrador; false crea el estado 'sent' y puede activar la remisión fiscal automática. Ninguna opción envía correo al cliente."),
+            confirm: z.boolean().describe("Must be true to authorize invoice creation, configured webhooks and possible fiscal issuance / Debe ser true para autorizar la creación, los webhooks configurados y la posible emisión fiscal"),
+        }).strict(),
         outputSchema: actionResultOutput,
-    }, async ({ templateId, draftOnly }) => withToolLogging("run_recurring_now", async () => {
+    }, async ({ templateId, draftOnly, confirm }) => withToolLogging("run_recurring_now", async () => {
+        if (confirm !== true) {
+            return confirmationRequiredError("Error: confirm=true is required to create a recurring invoice and allow configured webhooks. " +
+                "draftOnly=false may also trigger fiscal numbering and automatic tax submission. / " +
+                "Se requiere confirm=true para crear la factura y permitir los webhooks configurados. " +
+                "draftOnly=false también puede activar la numeración y remisión fiscal automática.");
+        }
         const result = await client.runRecurringNow(templateId, { draftOnly: draftOnly ?? true });
         return {
             content: [mutateContent(formatRecord("Recurring invoice triggered", result))],

package/dist/tools/register-all.d.ts

@@ -1,12 +1,12 @@
 /**
- * Barrel module that registers all 157 Frihet ERP tools on an McpServer.
+ * Barrel module that registers every Frihet ERP tool on an McpServer.
  *
  * Used by both the local (stdio) and remote (Cloudflare Workers) servers
  * so tool definitions stay in sync — one source of truth.
  *
  * Langfuse observability is injected by patching server.registerTool once
  * before any tool registration. This wraps every tool callback with
- * traceMCPTool so all 157 tools are instrumented at zero per-tool cost.
+ * traceMCPTool so every registered tool is instrumented at zero per-tool cost.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { IFrihetClient } from "../client-interface.js";

package/dist/tools/register-all.js

@@ -1,12 +1,12 @@
 /**
- * Barrel module that registers all 157 Frihet ERP tools on an McpServer.
+ * Barrel module that registers every Frihet ERP tool on an McpServer.
  *
  * Used by both the local (stdio) and remote (Cloudflare Workers) servers
  * so tool definitions stay in sync — one source of truth.
  *
  * Langfuse observability is injected by patching server.registerTool once
  * before any tool registration. This wraps every tool callback with
- * traceMCPTool so all 157 tools are instrumented at zero per-tool cost.
+ * traceMCPTool so every registered tool is instrumented at zero per-tool cost.
  */
 import { traceMCPTool } from "../observability.js";
 import { registerInvoiceTools } from "./invoices.js";
@@ -37,13 +37,13 @@ import { registerImpuestoSociedadesTools } from "./impuesto_sociedades.js";
 import { registerBankRulesTools } from "./bank_rules.js";
 import { registerHrTools } from "./hr.js";
 import { registerPayrollTools } from "./payroll.js";
-import { registerOnboardingTools } from "./onboarding.js";
 import { registerPermissionsTools } from "./permissions.js";
 import { registerAccountingCloseTools } from "./accountingClose.js";
+import { registerSearchTools } from "./search.js";
 /**
  * Patches server.registerTool to wrap every tool callback with Langfuse tracing.
  *
- * The patch is applied once before tool registration so all 157 tools are
+ * The patch is applied once before tool registration so every registered tool is
  * instrumented without per-tool edits. Tool call signatures are unchanged —
  * existing MCP clients continue to work identically.
  *
@@ -57,7 +57,10 @@ import { registerAccountingCloseTools } from "./accountingClose.js";
  *           attendance_clock_in, attendance_clock_out, overtime_report, anomaly_list
  *   Webhook trust (1): test_webhook (added to registerWebhookTools)
  *   Payroll (2): payroll_export, payroll_checklist
- *   Onboarding (2): onboarding_status, onboarding_persona_set
+ *   (Onboarding tools onboarding_status / onboarding_persona_set withdrawn
+ *    via #124 — Frihet-ERP /v1/onboarding/* family absent; tools were deleted,
+ *    not stubbed, to keep the catalogue honest. See src/tools/igic.ts for the
+ *    precedent of an inline NOT_DEPLOYED stub where the tool is retained.)
  *   Permissions (2): permissions_matrix, permissions_me
  *   Period close (3): period_close_status, period_close, period_reopen
  */
@@ -106,8 +109,8 @@ export function registerAllTools(server, client) {
     registerBankRulesTools(server, client);
     registerHrTools(server, client);
     registerPayrollTools(server, client);
-    registerOnboardingTools(server, client);
     registerPermissionsTools(server, client);
     registerAccountingCloseTools(server, client);
+    registerSearchTools(server, client);
 }
 //# sourceMappingURL=register-all.js.map

package/dist/tools/search.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cross-resource global search tool — Phase 10 second-wave safe parity.
+ *
+ * Wraps `GET /v1/search/global?q=&types=&limit=&offset=` (publicApi.ts:4476).
+ * Read-only fan-out across invoices / expenses / vendors / clients / products
+ * with workspace scoping preserved by Firestore subcollection paths on the
+ * server. No mutating counterpart; no auth boundary different from any other
+ * list tool.
+ *
+ * Why this lives alone (not in clients.ts): it is not a clients/* endpoint,
+ * has its own canonical envelope (`{data, total, ..., query, types,
+ * truncated?}` instead of the standard paginated one), and is the only
+ * server-side fan-out tool — coupling it with one resource would mislead the
+ * tool listing.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { IFrihetClient } from "../client-interface.js";
+export declare function registerSearchTools(server: McpServer, client: IFrihetClient): void;
+//# sourceMappingURL=search.d.ts.map

package/dist/tools/search.js

@@ -0,0 +1,84 @@
+/**
+ * Cross-resource global search tool — Phase 10 second-wave safe parity.
+ *
+ * Wraps `GET /v1/search/global?q=&types=&limit=&offset=` (publicApi.ts:4476).
+ * Read-only fan-out across invoices / expenses / vendors / clients / products
+ * with workspace scoping preserved by Firestore subcollection paths on the
+ * server. No mutating counterpart; no auth boundary different from any other
+ * list tool.
+ *
+ * Why this lives alone (not in clients.ts): it is not a clients/* endpoint,
+ * has its own canonical envelope (`{data, total, ..., query, types,
+ * truncated?}` instead of the standard paginated one), and is the only
+ * server-side fan-out tool — coupling it with one resource would mislead the
+ * tool listing.
+ */
+import { z } from "zod/v4";
+import { withToolLogging, listContent, READ_ONLY_ANNOTATIONS, formatPaginatedResponse, } from "./shared.js";
+const GLOBAL_SEARCH_TYPES = ["invoices", "expenses", "vendors", "clients", "products"];
+const globalSearchOutputSchema = z.object({
+    data: z.array(z.record(z.string(), z.unknown())),
+    total: z.number().int().nonnegative(),
+    limit: z.number().int().positive(),
+    offset: z.number().int().nonnegative(),
+    hasMore: z.boolean(),
+    query: z.string(),
+    types: z.array(z.enum(GLOBAL_SEARCH_TYPES)),
+    truncated: z.boolean().optional(),
+});
+export function registerSearchTools(server, client) {
+    server.registerTool("global_search", {
+        title: "Global Search",
+        description: "Search across invoices, expenses, vendors, clients, and products in one call. " +
+            "Use this to resolve an entity name/email/number when you do not yet know the resource type. " +
+            "Returns per-hit {type, id, name, ...} so the caller can dispatch to the right list/get tool. " +
+            "Read-only and workspace-scoped. " +
+            "Example: q='acme', types=['clients','invoices'], limit=10 " +
+            "/ Busca en facturas, gastos, proveedores, clientes y productos en una sola llamada. " +
+            "Util para resolver un nombre/correo/numero cuando no se sabe aun el tipo de recurso.",
+        annotations: READ_ONLY_ANNOTATIONS,
+        inputSchema: {
+            q: z
+                .string()
+                .trim()
+                .min(1)
+                .max(200)
+                .describe("Free-text query (1-200 chars) / Texto a buscar"),
+            types: z
+                .array(z.enum(GLOBAL_SEARCH_TYPES))
+                .optional()
+                .describe("Restrict to these resource types. Defaults to all 5. / Tipos a incluir (por defecto todos)"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe("Max results across all types (1-50, default 25) / Resultados maximos"),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .max(1000)
+                .optional()
+                .describe("Offset / Desplazamiento"),
+        },
+        outputSchema: globalSearchOutputSchema,
+    }, async ({ q, types, limit, offset }) => withToolLogging("global_search", async () => {
+        // Trim defensively: the JSON Schema serialization of `z.string().trim()`
+        // drops the trim hint, so leading/trailing whitespace survives MCP's
+        // input validation and would reach the ERP's q-length check as junk.
+        const cleanQ = q.trim();
+        const result = await client.globalSearch({
+            q: cleanQ,
+            types: types,
+            limit,
+            offset,
+        });
+        return {
+            content: [listContent(formatPaginatedResponse("search", result))],
+            structuredContent: result,
+        };
+    }));
+}
+//# sourceMappingURL=search.js.map