@frihet/mcp-server 1.17.0 → 2.0.0

package/dist/tools/vendors.js

@@ -13,6 +13,168 @@ const addressSchema = z
 })
     .optional()
     .describe("Vendor address / Direccion del proveedor");
+/**
+ * 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_VENDOR_STRING_FIELDS = [
+    "email",
+    "phone",
+    "taxId",
+    "createdAt",
+    "updatedAt",
+];
+/**
+ * Normalizes a vendor record returned by the Frihet API so it always satisfies
+ * `vendorItemOutput` without losing ERP-canonical data:
+ *  - Strips `null` on optional string fields (`email`, `phone`, `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`.
+ *  - Maps ERP canonical address keys (`province` -> `state`, `zip` -> `postalCode`,
+ *    `countryCode` -> `country`).
+ */
+function normalizeVendorRecord(vendorRecord) {
+    if (!vendorRecord || typeof vendorRecord !== "object" || Array.isArray(vendorRecord)) {
+        return vendorRecord;
+    }
+    const out = { ...vendorRecord };
+    for (const field of OPTIONAL_VENDOR_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 registerVendorTools(server, client) {
     // -- list_vendors --
     server.registerTool("list_vendors", {
@@ -31,10 +193,82 @@ export function registerVendorTools(server, client) {
         },
         outputSchema: paginatedOutput(vendorItemOutput, { projectable: true }),
     }, async ({ q, limit, offset, after, fields }) => withToolLogging("list_vendors", async () => {
-        const result = await client.listVendors({ q, limit, offset, after, fields });
+        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`). Protected profiles
+        // (Claude `claudeToolResult` and OpenAI `applyOpenAIProfile`) rebuild `content`
+        // from `structuredContent` while `paginatedOutput` is frozen, so fail closed
+        // (`isError: true` without `structuredContent`).
+        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.listVendors({ q, limit, offset, after, fields });
+        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.listVendors({ q: splitQ, limit, offset, after, fields });
+                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((v) => (v && typeof v === "object" ? normalizeVendorRecord(v) : v))
+            : [];
+        // 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: vendor 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 paginate without 'q' using 'after'. / ` +
+                            `Error: la busqueda de proveedores 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 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("vendors", result))],
-            structuredContent: result,
+            content: [listContent(formatPaginatedResponse("vendors", cleanEnvelope) + notes.join(""))],
+            structuredContent: cleanEnvelope,
         };
     }));
     // -- get_vendor --
@@ -48,7 +282,7 @@ export function registerVendorTools(server, client) {
         },
         outputSchema: vendorItemOutput,
     }, async ({ id }) => withToolLogging("get_vendor", async () => {
-        const result = await client.getVendor(id);
+        const result = normalizeVendorRecord(await client.getVendor(id));
         return {
             content: [getContent(formatRecord("Vendor", result))],
             structuredContent: result,
@@ -72,7 +306,7 @@ export function registerVendorTools(server, client) {
         },
         outputSchema: vendorItemOutput,
     }, async (input) => withToolLogging("create_vendor", async () => {
-        const result = await client.createVendor(input);
+        const result = normalizeVendorRecord(await client.createVendor(input));
         const hints = enrichResponse("vendors", "create", result);
         return {
             content: [mutateContent(formatRecord("Vendor created", result) + hints)],
@@ -96,7 +330,7 @@ export function registerVendorTools(server, client) {
         },
         outputSchema: vendorItemOutput,
     }, async ({ id, ...data }) => withToolLogging("update_vendor", async () => {
-        const result = await client.updateVendor(id, data);
+        const result = normalizeVendorRecord(await client.updateVendor(id, data));
         return {
             content: [mutateContent(formatRecord("Vendor updated", result))],
             structuredContent: result,

package/dist/types.d.ts

@@ -38,11 +38,13 @@ export interface Invoice {
     status?: string;
     notes?: string;
     taxRate?: number;
+    operationType?: "service" | "goods";
+    fiscalTreatment?: "not_subject_location" | "export_exempt";
     total?: number;
     createdAt?: string;
     updatedAt?: string;
 }
-export type CreateInvoiceInput = Pick<Invoice, "clientName" | "items"> & Partial<Pick<Invoice, "issueDate" | "dueDate" | "status" | "notes" | "taxRate">>;
+export type CreateInvoiceInput = Pick<Invoice, "clientName" | "items"> & Partial<Pick<Invoice, "issueDate" | "dueDate" | "status" | "notes" | "taxRate" | "operationType" | "fiscalTreatment">>;
 export type UpdateInvoiceInput = Partial<CreateInvoiceInput>;
 export interface Expense {
     id: string;

package/dist/workflows/daily-operational-brief.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Daily Operational Brief workflow ("¿Qué debería revisar hoy en mi negocio y por qué?").
+ *
+ * Grounded strictly in read-only Frihet workspace tools:
+ * - get_business_context
+ * - list_invoices
+ * - list_quotes
+ * - list_expenses
+ * - list_clients
+ * - list_client_activities
+ *
+ * Enforces:
+ * 1. Explicit temporal scope (`unfiltered_operational_sample_as_of_date` vs `currentMonthActivity`)
+ *    and per-resource coverage (inspected vs total records).
+ * 2. Strict separation between draft documents (non-issued) and real/issued activity.
+ * 3. Explicit amount provenance (`stored_field`, `derived_from_items`, `business_context_summary`,
+ *    `unavailable`, or `mixed_currency_unconverted`).
+ *    - Absent/corrupt amounts NEVER coerce to 0 (`amount: null`, `provenance: "unavailable"`).
+ *    - Multi-currency totals NEVER sum across currencies without conversion (`totalsByCurrency`, `currency: "MIXED"`).
+ *    - Derived line-item totals apply canonical per-line `discount`, document `discountRate`,
+ *      `taxRate`, `equivalenceSurchargeRate`, and `irpfRate` over the discounted tax-exclusive base.
+ * 4. Honest unpaid invoice semantics: full nominal totals of unpaid invoices are labeled
+ *    "importe nominal de facturas no marcadas como pagadas; saldo pendiente real no determinable
+ *    sin desglose de cobros parciales ni conciliación bancaria" (`realOutstandingBalanceDeterminable: false`).
+ * 5. Record-backed prioritized review items and suggested next actions without auto-executing writes.
+ * 6. Explicit declaration of what cannot be determined ("knownUnknowns").
+ */
+import type { IFrihetClient } from "../client-interface.js";
+export type AmountProvenanceKind = "stored_field" | "derived_from_items" | "business_context_summary" | "unavailable" | "mixed_currency_unconverted";
+export interface CurrencyBucketAmount {
+    amount: number;
+    currency: string;
+    provenance: "stored_field" | "derived_from_items";
+    documentCount: number;
+}
+export interface ProvenancedAmount {
+    amount: number | null;
+    currency: string;
+    provenance: AmountProvenanceKind;
+    fieldOrFormula: string;
+    totalsByCurrency?: Record<string, CurrencyBucketAmount>;
+    unavailableCount?: number;
+}
+export interface ResourceCoverage {
+    collection: "invoices" | "quotes" | "expenses" | "clients" | "client_activities";
+    sourceTool: string;
+    inspected: number;
+    total: number;
+    complete: boolean;
+}
+export interface BriefCoverageSummary {
+    asOfDate: string;
+    periodMonth: string;
+    referenceMonth: string;
+    temporalScope: "unfiltered_operational_sample_as_of_date";
+    temporalScopeNote: string;
+    isPartial: boolean;
+    resources: Record<"invoices" | "quotes" | "expenses" | "clients" | "client_activities", ResourceCoverage>;
+}
+export interface BriefDocumentSummary {
+    id: string;
+    documentNumber: string | null;
+    status: string;
+    counterpartyName: string;
+    issueDate: string | null;
+    dueDate: string | null;
+    amount: ProvenancedAmount;
+}
+export interface BriefPriorityItem {
+    priority: "high" | "medium" | "low";
+    category: "overdue_invoice" | "draft_invoice" | "draft_or_expiring_quote" | "expense_review" | "client_followup" | "plan_quota";
+    title: string;
+    why: string;
+    recordRefs: Array<{
+        type: "invoice" | "quote" | "expense" | "client" | "client_activity" | "plan_quota";
+        id: string;
+        label: string;
+    }>;
+    amount?: ProvenancedAmount;
+    suggestedNextAction: {
+        description: string;
+        recommendedTool: string;
+        requiresConfirmation: boolean;
+        autoExecuted: false;
+    };
+}
+export interface DailyOperationalBrief {
+    question: string;
+    coverage: BriefCoverageSummary;
+    activitySeparation: {
+        draftActivity: {
+            note: string;
+            invoiceDraftsCount: number;
+            invoiceDraftsTotal: ProvenancedAmount;
+            invoiceDrafts: BriefDocumentSummary[];
+            quoteDraftsCount: number;
+            quoteDraftsTotal: ProvenancedAmount;
+            quoteDrafts: BriefDocumentSummary[];
+        };
+        issuedActivity: {
+            note: string;
+            realOutstandingBalanceDeterminable: false;
+            unpaidNominalSemantics: "nominal_unpaid_invoice_totals_without_partial_payments";
+            issuedInvoicesCount: number;
+            issuedInvoicesByStatus: Record<string, number>;
+            issuedInvoicesTotal: ProvenancedAmount;
+            issuedInvoices: BriefDocumentSummary[];
+            paidInvoicesCount: number;
+            paidInvoicesTotal: ProvenancedAmount;
+            paidInvoices: BriefDocumentSummary[];
+            unpaidNominalInvoicesCount: number;
+            unpaidNominalTotal: ProvenancedAmount;
+            unpaidNominalTotalsByCurrency: Record<string, CurrencyBucketAmount>;
+            overdueNominalInvoicesCount: number;
+            overdueNominalTotal: ProvenancedAmount;
+            onTimeNominalPendingCount: number;
+            onTimeNominalPendingTotal: ProvenancedAmount;
+            outstandingInvoicesCount: number;
+            outstandingInvoicesTotal: ProvenancedAmount;
+            overdueInvoicesCount: number;
+            overdueInvoicesTotal: ProvenancedAmount;
+            onTimePendingCount: number;
+            onTimePendingTotal: ProvenancedAmount;
+            outstandingInvoices: BriefDocumentSummary[];
+        };
+        recordedExpenses: {
+            note: string;
+            expensesCount: number;
+            expensesTotal: ProvenancedAmount;
+            deductibleCount: number;
+            deductibleTotal: ProvenancedAmount;
+            nonDeductibleCount: number;
+            nonDeductibleTotal: ProvenancedAmount;
+            pendingReviewCount: number;
+        };
+        currentMonthActivity: {
+            referenceMonth: string;
+            note: string;
+            issuedInvoicesInMonthCount: number;
+            issuedInvoicesInMonthTotal: ProvenancedAmount;
+            invoiceDraftsInMonthCount: number;
+            invoiceDraftsInMonthTotal: ProvenancedAmount;
+            expensesInMonthCount: number;
+            expensesInMonthTotal: ProvenancedAmount;
+        };
+    };
+    priorities: BriefPriorityItem[];
+    knownUnknowns: string[];
+    mutationsExecuted: 0;
+    markdown: string;
+}
+export interface GenerateDailyBriefOptions {
+    asOfDate?: string;
+    pageLimit?: number;
+    maxActivityClients?: number;
+}
+export declare function formatProvenancedAmount(p: ProvenancedAmount): string;
+export declare function resolveDocumentAmount(doc: Record<string, unknown>, defaultCurrency?: string): ProvenancedAmount;
+export declare function sumProvenancedAmounts(amounts: ProvenancedAmount[], defaultCurrency?: string): ProvenancedAmount;
+export declare function generateDailyOperationalBrief(client: Pick<IFrihetClient, "getBusinessContext" | "listInvoices" | "listQuotes" | "listExpenses" | "listClients" | "listClientActivities">, options?: GenerateDailyBriefOptions): Promise<DailyOperationalBrief>;
+export declare function buildScenario1CompleteWorkspaceClient(callLog: string[]): Pick<IFrihetClient, "getBusinessContext" | "listInvoices" | "listQuotes" | "listExpenses" | "listClients" | "listClientActivities">;
+export declare function buildScenario2PartialCoverageClient(callLog: string[]): Pick<IFrihetClient, "getBusinessContext" | "listInvoices" | "listQuotes" | "listExpenses" | "listClients" | "listClientActivities">;
+//# sourceMappingURL=daily-operational-brief.d.ts.map