@frihet/mcp-server 1.16.6 → 2.0.0

package/dist/tools/clients.js

@@ -13,6 +13,171 @@ const addressSchema = z
 })
     .optional()
     .describe("Client address / Direccion del cliente");
+/**
+ * Splits a concatenated / camelCase / snake_case / kebab-case search query into
+ * space-separated tokens (e.g. "CanariasBlue" -> "Canarias Blue",
+ * "SLCanarias" -> "SL Canarias", "Canarias_Blue" -> "Canarias Blue").
+ */
+function splitCompoundQuery(q) {
+    return q
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+const OPTIONAL_CLIENT_STRING_FIELDS = [
+    "email",
+    "phone",
+    "stage",
+    "taxId",
+    "createdAt",
+    "updatedAt",
+];
+/**
+ * Normalizes a client record returned by the Frihet API so it always satisfies
+ * `clientItemOutput` without losing ERP-canonical data:
+ *  - Strips `null` on optional string fields (`email`, `phone`, `stage`, `taxId`,
+ *    `createdAt`, `updatedAt`) so `z.string().optional()` never rejects legacy docs.
+ *  - Backfills `taxId` from legacy `nif` / `cif` / `vatNumber` / `tax_id` when
+ *    `taxId` is absent or null, preserving all original fields.
+ *  - Converts legacy string `address` into `{ street }`.
+ *  - Omits `null` or empty `address` (which otherwise fails `addressOutputSchema`).
+ *  - Maps ERP canonical address keys (`province` -> `state`, `zip` -> `postalCode`,
+ *    `countryCode` -> `country`) because `publicApi.ts` (`normalizeAddress`) stores
+ *    `zip` and `province`, whereas `addressOutputSchema` only declares `postalCode`
+ *    and `state` (and strips unknown keys in `structuredContent`).
+ */
+function normalizeClientRecord(clientRecord) {
+    if (!clientRecord || typeof clientRecord !== "object" || Array.isArray(clientRecord)) {
+        return clientRecord;
+    }
+    const out = { ...clientRecord };
+    for (const field of OPTIONAL_CLIENT_STRING_FIELDS) {
+        if (out[field] === null) {
+            delete out[field];
+        }
+    }
+    if (typeof out.taxId !== "string" || !out.taxId.trim()) {
+        for (const alias of ["nif", "cif", "vatNumber", "tax_id"]) {
+            const candidate = out[alias];
+            if (typeof candidate === "string" && candidate.trim()) {
+                out.taxId = candidate.trim();
+                break;
+            }
+        }
+    }
+    const rawAddress = out.address;
+    const rootStreet = typeof out.street === "string" && out.street.trim() ? out.street.trim() : undefined;
+    const rootCity = typeof out.city === "string" && out.city.trim() ? out.city.trim() : undefined;
+    const rootState = typeof out.state === "string" && out.state.trim()
+        ? out.state.trim()
+        : typeof out.province === "string" && out.province.trim()
+            ? out.province.trim()
+            : undefined;
+    const rootPostalCode = typeof out.postalCode === "string" && out.postalCode.trim()
+        ? out.postalCode.trim()
+        : typeof out.zip === "string" && out.zip.trim()
+            ? out.zip.trim()
+            : undefined;
+    const rootCountry = typeof out.country === "string" && out.country.trim()
+        ? out.country.trim()
+        : typeof out.countryCode === "string" && out.countryCode.trim()
+            ? out.countryCode.trim()
+            : undefined;
+    const buildFlatAddress = (streetOverride) => {
+        const built = {};
+        const st = streetOverride ?? rootStreet;
+        if (st !== undefined)
+            built.street = st;
+        if (rootCity !== undefined)
+            built.city = rootCity;
+        if (rootState !== undefined)
+            built.state = rootState;
+        if (rootPostalCode !== undefined)
+            built.postalCode = rootPostalCode;
+        if (rootCountry !== undefined)
+            built.country = rootCountry;
+        return Object.keys(built).length > 0 ? built : undefined;
+    };
+    if (rawAddress === undefined || rawAddress === null) {
+        if (rawAddress === null) {
+            delete out.address;
+        }
+        const flatAddr = buildFlatAddress();
+        if (flatAddr) {
+            out.address = flatAddr;
+        }
+        return out;
+    }
+    if (typeof rawAddress === "string") {
+        const trimmed = rawAddress.trim();
+        const flatAddr = buildFlatAddress(trimmed || undefined);
+        if (!flatAddr) {
+            delete out.address;
+            return out;
+        }
+        out.address = flatAddr;
+        return out;
+    }
+    if (typeof rawAddress === "object" && !Array.isArray(rawAddress)) {
+        const addrObj = rawAddress;
+        const normalizedAddress = {};
+        for (const [k, v] of Object.entries(addrObj)) {
+            if (v !== null && v !== undefined) {
+                normalizedAddress[k] = v;
+            }
+        }
+        const street = typeof addrObj.street === "string" && addrObj.street.trim()
+            ? addrObj.street.trim()
+            : rootStreet;
+        const city = typeof addrObj.city === "string" && addrObj.city.trim()
+            ? addrObj.city.trim()
+            : rootCity;
+        const state = typeof addrObj.state === "string" && addrObj.state.trim()
+            ? addrObj.state.trim()
+            : typeof addrObj.province === "string" && addrObj.province.trim()
+                ? addrObj.province.trim()
+                : rootState;
+        const postalCode = typeof addrObj.postalCode === "string" && addrObj.postalCode.trim()
+            ? addrObj.postalCode.trim()
+            : typeof addrObj.zip === "string" && addrObj.zip.trim()
+                ? addrObj.zip.trim()
+                : rootPostalCode;
+        const country = typeof addrObj.country === "string" && addrObj.country.trim()
+            ? addrObj.country.trim()
+            : typeof addrObj.countryCode === "string" && addrObj.countryCode.trim()
+                ? addrObj.countryCode.trim()
+                : rootCountry;
+        if (street !== undefined)
+            normalizedAddress.street = street;
+        else
+            delete normalizedAddress.street;
+        if (city !== undefined)
+            normalizedAddress.city = city;
+        else
+            delete normalizedAddress.city;
+        if (state !== undefined)
+            normalizedAddress.state = state;
+        else
+            delete normalizedAddress.state;
+        if (postalCode !== undefined)
+            normalizedAddress.postalCode = postalCode;
+        else
+            delete normalizedAddress.postalCode;
+        if (country !== undefined)
+            normalizedAddress.country = country;
+        else
+            delete normalizedAddress.country;
+        if (Object.keys(normalizedAddress).length === 0) {
+            delete out.address;
+            return out;
+        }
+        out.address = normalizedAddress;
+        return out;
+    }
+    return out;
+}
 export function registerClientTools(server, client) {
     // -- list_clients --
     server.registerTool("list_clients", {
@@ -44,10 +209,91 @@ export function registerClientTools(server, client) {
         },
         outputSchema: paginatedOutput(clientItemOutput, { projectable: true }),
     }, async ({ limit, offset, q, stage, fields, after }) => withToolLogging("list_clients", async () => {
-        const result = await client.listClients({ limit, offset, after, fields, q, stage });
+        const trimmedQ = q?.trim();
+        const trimmedAfter = after?.trim();
+        // Limitation in Frihet-ERP `listResources` (publicApi.ts L8158-8268):
+        // When `search` (`q`) is provided, the backend slices results by `offset`/`limit`
+        // and returns before evaluating `cursorParam` (`after`). Moreover, protected
+        // profiles (Claude `claudeToolResult` and OpenAI `applyOpenAIProfile`) rebuild
+        // `content` from `structuredContent` while `paginatedOutput` is frozen, so a
+        // text-only note would be silently discarded. Fail closed (`isError: true`
+        // without `structuredContent`) so no profile mistakes page 1 for a cursor page.
+        if (trimmedQ && trimmedAfter) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "Error: text search ('q') cannot be combined with cursor pagination ('after') because the ERP backend slices search results by 'offset'/'limit' and ignores 'after'. Use 'offset' and 'limit' when searching with 'q', or omit 'q' when paginating with 'after'. / " +
+                            "Error: la busqueda textual ('q') no se puede combinar con el cursor 'after' porque el backend pagina las busquedas mediante 'offset'/'limit' e ignora 'after'. Usa 'offset' y 'limit' con 'q', u omite 'q' al paginar con 'after'.",
+                    }],
+                isError: true,
+            };
+        }
+        let result = await client.listClients({ limit, offset, after, fields, q, stage });
+        // When a concatenated / camelCase query (e.g. "CanariasBlue") yields zero total matches,
+        // retry with split tokens ("Canarias Blue") using the same offset/limit/fields/stage.
+        // Guardrails matching publicApi.ts `listResources`:
+        //  1. Never fallback when `after` cursor is supplied with `q`.
+        //  2. Never fallback when the first scan hit the 500-document cap (`truncated === true`),
+        //     since total===0 only reflects the first 500 scanned records.
+        //  3. On page 2+ (`offset > 0`), only fallback when `result.total === 0` explicitly (not
+        //     when `total === undefined`, which indicates an exhausted offset).
+        let usedFallback = false;
+        const splitQ = trimmedQ ? splitCompoundQuery(trimmedQ) : undefined;
+        const isSubsequentPage = (offset !== undefined && offset > 0) || Boolean(after);
+        const initialTruncated = result?.truncated === true;
+        const canFallback = splitQ !== undefined && splitQ !== trimmedQ && !after && !initialTruncated;
+        const hasZeroTotalMatches = Array.isArray(result?.data) &&
+            result.data.length === 0 &&
+            (isSubsequentPage ? result.total === 0 : result.total === 0 || result.total === undefined);
+        if (canFallback && hasZeroTotalMatches) {
+            try {
+                const fallbackResult = await client.listClients({ limit, offset, after, fields, q: splitQ, stage });
+                const fallbackTruncated = fallbackResult?.truncated === true;
+                if (fallbackTruncated ||
+                    (fallbackResult?.data && (fallbackResult.data.length > 0 || (fallbackResult.total !== undefined && fallbackResult.total > 0)))) {
+                    result = fallbackResult;
+                    usedFallback = true;
+                }
+            }
+            catch {
+                // Preserve original response if fallback fails
+            }
+        }
+        const rawEnvelope = (result ?? {});
+        const isTruncated = rawEnvelope.truncated === true;
+        const normalizedData = Array.isArray(result?.data)
+            ? result.data.map((c) => (c && typeof c === "object" ? normalizeClientRecord(c) : c))
+            : [];
+        // Conservative refusal when the ERP 500-document scan cap was saturated (`truncated: true`).
+        // Because `paginatedOutput` is a frozen schema contract and both Claude (`claudeToolResult`)
+        // and OpenAI (`applyOpenAIProfile`) overwrite `content` whenever `structuredContent` is
+        // present, returning `structuredContent` here would hide the truncation warning and present
+        // an incomplete 500-doc scan as exhaustive.
+        if (isTruncated) {
+            const partialCount = typeof result?.total === "number" ? result.total : normalizedData.length;
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error: client search hit the ERP 500-document scan cap (truncated=true; ${partialCount} match(es) within the first 500 scanned records) and cannot be returned as an exhaustive result across protected profiles. Narrow 'q' (or filter by 'stage') or paginate without 'q' using 'after'. / ` +
+                            `Error: la busqueda de clientes alcanzo el limite de escaneo de 500 documentos del ERP (truncated=true; ${partialCount} coincidencia(s) en los primeros 500 registros) y no puede devolverse como resultado exhaustivo. Acota 'q' (o filtra por 'stage') o pagina sin 'q' usando 'after'.`,
+                    }],
+                isError: true,
+            };
+        }
+        const cleanEnvelope = {
+            data: normalizedData,
+            total: typeof result?.total === "number" ? result.total : normalizedData.length,
+            limit: typeof result?.limit === "number" ? result.limit : (limit ?? 20),
+            offset: typeof result?.offset === "number" ? result.offset : (offset ?? 0),
+            ...(typeof result?.nextCursor === "string" ? { nextCursor: result.nextCursor } : {}),
+        };
+        const notes = [];
+        if (usedFallback) {
+            notes.push(` (criterio aplicado: "${splitQ}")`);
+        }
         return {
-            content: [listContent(formatPaginatedResponse("clients", result))],
-            structuredContent: result,
+            content: [listContent(formatPaginatedResponse("clients", cleanEnvelope) + notes.join(""))],
+            structuredContent: cleanEnvelope,
         };
     }));
     // -- get_client --
@@ -61,7 +307,7 @@ export function registerClientTools(server, client) {
         },
         outputSchema: clientItemOutput,
     }, async ({ id }) => withToolLogging("get_client", async () => {
-        const result = await client.getClient(id);
+        const result = normalizeClientRecord(await client.getClient(id));
         return {
             content: [getContent(formatRecord("Client", result))],
             structuredContent: result,
@@ -77,19 +323,19 @@ export function registerClientTools(server, client) {
             "Los clientes se usan al crear facturas y presupuestos.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
-            name: z.string().describe("Client/company name / Nombre del cliente o empresa"),
-            email: z.string().optional().describe("Email address / Correo electronico"),
-            phone: z.string().optional().describe("Phone number / Telefono"),
+            name: z.string().trim().min(1).max(200).describe("Client/company name / Nombre del cliente o empresa"),
+            email: z.string().trim().email().max(255).optional().describe("Email address / Correo electronico"),
+            phone: z.string().trim().min(1).max(50).optional().describe("Phone number / Telefono"),
             taxId: z.string().optional().describe("Tax ID (NIF/CIF/VAT) / NIF o CIF"),
             address: addressSchema,
         },
         outputSchema: clientItemOutput,
     }, async (input) => withToolLogging("create_client", async () => {
-        const result = await client.createClient(input);
+        const result = normalizeClientRecord(await client.createClient(input));
         const hints = enrichResponse("clients", "create", result);
         return {
-            content: [mutateContent(formatRecord("Client created", result))],
-            structuredContent: { ...result, ...hints },
+            content: [mutateContent(formatRecord("Client created", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- update_client --
@@ -100,16 +346,16 @@ export function registerClientTools(server, client) {
             "/ Actualiza un cliente existente. Solo se modifican los campos proporcionados.",
         annotations: UPDATE_ANNOTATIONS,
         inputSchema: {
-            id: z.string().describe("Client ID / ID del cliente"),
-            name: z.string().optional().describe("Name / Nombre"),
-            email: z.string().optional().describe("Email / Correo"),
-            phone: z.string().optional().describe("Phone / Telefono"),
+            id: z.string().trim().min(1).max(128).describe("Client ID / ID del cliente"),
+            name: z.string().trim().min(1).max(200).optional().describe("Name / Nombre"),
+            email: z.string().trim().email().max(255).optional().describe("Email / Correo"),
+            phone: z.string().trim().min(1).max(50).optional().describe("Phone / Telefono"),
             taxId: z.string().optional().describe("Tax ID / NIF/CIF"),
             address: addressSchema,
         },
         outputSchema: clientItemOutput,
     }, async ({ id, ...data }) => withToolLogging("update_client", async () => {
-        const result = await client.updateClient(id, data);
+        const result = normalizeClientRecord(await client.updateClient(id, data));
         return {
             content: [mutateContent(formatRecord("Client updated", result))],
             structuredContent: result,

package/dist/tools/crm.js

@@ -37,11 +37,11 @@ export function registerCrmTools(server, client) {
             "/ Anade un nuevo contacto a un cliente. Requiere al menos un nombre.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
-            clientId: z.string().describe("Client ID / ID del cliente"),
-            name: z.string().describe("Contact name / Nombre del contacto"),
-            email: z.string().optional().describe("Email address / Correo electronico"),
-            phone: z.string().optional().describe("Phone number / Telefono"),
-            role: z.string().optional().describe("Role or title (e.g. CEO, CTO, Billing) / Cargo o rol"),
+            clientId: z.string().trim().min(1).max(128).describe("Client ID / ID del cliente"),
+            name: z.string().trim().min(1).max(200).describe("Contact name / Nombre del contacto"),
+            email: z.string().trim().email().max(255).optional().describe("Email address / Correo electronico"),
+            phone: z.string().trim().min(1).max(50).optional().describe("Phone number / Telefono"),
+            role: z.string().trim().min(1).max(200).optional().describe("Role or title (e.g. CEO, CTO, Billing) / Cargo o rol"),
             isPrimary: z.boolean().optional().describe("Whether this is the primary contact / Si es el contacto principal"),
         },
         outputSchema: contactItemOutput,
@@ -49,8 +49,8 @@ export function registerCrmTools(server, client) {
         const result = await client.createClientContact(clientId, data);
         const hints = enrichResponse("contacts", "create", result);
         return {
-            content: [mutateContent(formatRecord("Contact created", result))],
-            structuredContent: { ...result, ...hints },
+            content: [mutateContent(formatRecord("Contact created", result) + hints)],
+            structuredContent: { ...result },
         };
     }));
     // -- delete_client_contact --
@@ -60,8 +60,8 @@ export function registerCrmTools(server, client) {
             "/ Elimina permanentemente un contacto de un cliente. Esta accion no se puede deshacer.",
         annotations: DELETE_ANNOTATIONS,
         inputSchema: {
-            clientId: z.string().describe("Client ID / ID del cliente"),
-            contactId: z.string().describe("Contact ID / ID del contacto"),
+            clientId: z.string().trim().min(1).max(128).describe("Client ID / ID del cliente"),
+            contactId: z.string().trim().min(1).max(128).describe("Contact ID / ID del contacto"),
         },
         outputSchema: deleteResultOutput,
     }, async ({ clientId, contactId }) => withToolLogging("delete_client_contact", async () => {
@@ -82,7 +82,7 @@ export function registerCrmTools(server, client) {
             "/ Lista todas las actividades CRM de un cliente con paginacion opcional.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {
-            clientId: z.string().describe("Client ID / ID del cliente"),
+            clientId: z.string().trim().min(1).max(128).describe("Client ID / ID del cliente"),
             limit: z.number().int().min(1).max(100).optional().describe("Max results (1-100) / Resultados maximos"),
             offset: z.number().int().min(0).optional().describe("Offset / Desplazamiento"),
         },
@@ -98,18 +98,18 @@ export function registerCrmTools(server, client) {
     server.registerTool("log_client_activity", {
         title: "Log Client Activity",
         description: "Log a CRM activity against a client. Use to track calls, emails, meetings, or tasks. " +
+            "Do not include passwords, credentials, payment-card data, health data, or official/government identifiers in free-text fields. " +
             "Example: clientId='abc123', type='call', title='Discussed Q2 proposal', description='Client interested in upgrade' " +
-            "/ Registra una actividad CRM para un cliente. Usa para rastrear llamadas, emails, reuniones o tareas.",
+            "/ Registra una actividad CRM para un cliente. No incluyas contrasenas, credenciales, datos de tarjetas, datos de salud ni identificadores oficiales en los campos de texto libre.",
         annotations: CREATE_ANNOTATIONS,
-        inputSchema: {
+        inputSchema: z.object({
             clientId: z.string().describe("Client ID / ID del cliente"),
             type: z
                 .enum(["call", "email", "meeting", "task"])
                 .describe("Activity type / Tipo de actividad"),
-            title: z.string().describe("Activity title / Titulo de la actividad"),
-            description: z.string().optional().describe("Detailed description / Descripcion detallada"),
-            date: z.string().optional().describe("Activity date (ISO 8601, defaults to now) / Fecha de la actividad"),
-        },
+            title: z.string().trim().min(1).max(500).describe("Activity title / Titulo de la actividad"),
+            description: z.string().trim().min(1).max(5000).optional().describe("Detailed description; exclude secrets, credentials, card or health data, and official identifiers / Descripcion detallada; excluye secretos, credenciales, datos de tarjetas o salud e identificadores oficiales"),
+        }).strict(),
         outputSchema: activityItemOutput,
     }, async ({ clientId, ...data }) => withToolLogging("log_client_activity", async () => {
         const result = await client.logClientActivity(clientId, data);
@@ -144,12 +144,13 @@ export function registerCrmTools(server, client) {
     server.registerTool("create_client_note", {
         title: "Create Client Note",
         description: "Add a note to a client. Notes are free-form text entries useful for keeping context. " +
+            "Do not include passwords, credentials, payment-card data, health data, or official/government identifiers. " +
             "Example: clientId='abc123', content='Prefers invoices in English. Payment NET 30.' " +
-            "/ Anade una nota a un cliente. Las notas son texto libre para mantener contexto.",
+            "/ Anade una nota a un cliente. No incluyas contrasenas, credenciales, datos de tarjetas, datos de salud ni identificadores oficiales.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
-            clientId: z.string().describe("Client ID / ID del cliente"),
-            content: z.string().describe("Note content / Contenido de la nota"),
+            clientId: z.string().trim().min(1).max(128).describe("Client ID / ID del cliente"),
+            content: z.string().trim().min(1).max(10000).describe("Note content; exclude secrets, credentials, card or health data, and official identifiers / Contenido; excluye secretos, credenciales, datos de tarjetas o salud e identificadores oficiales"),
         },
         outputSchema: noteItemOutput,
     }, async ({ clientId, content }) => withToolLogging("create_client_note", async () => {
@@ -166,8 +167,8 @@ export function registerCrmTools(server, client) {
             "/ Elimina permanentemente una nota de un cliente. Esta accion no se puede deshacer.",
         annotations: DELETE_ANNOTATIONS,
         inputSchema: {
-            clientId: z.string().describe("Client ID / ID del cliente"),
-            noteId: z.string().describe("Note ID / ID de la nota"),
+            clientId: z.string().trim().min(1).max(128).describe("Client ID / ID del cliente"),
+            noteId: z.string().trim().min(1).max(128).describe("Note ID / ID de la nota"),
         },
         outputSchema: deleteResultOutput,
     }, async ({ clientId, noteId }) => withToolLogging("delete_client_note", async () => {