@frihet/mcp-server 1.16.6 → 1.17.0

package/dist/demo-client.d.ts

@@ -18,7 +18,8 @@
  *     stamp; this is the one accepted, documented gap).
  */
 import type { IFrihetClient } from "./client-interface.js";
-import type { PaginatedResponse } from "./types.js";
+import type { CreateWebhookInput, CreateWebhookResult, PaginatedResponse, UpdateWebhookInput, Webhook } from "./types.js";
+import type { BinaryDocument, EInvoiceDocument } from "./client.js";
 type Rec = Record<string, unknown>;
 export declare class DemoFrihetClient implements IFrihetClient {
     listInvoices(params?: {
@@ -75,8 +76,8 @@ export declare class DemoFrihetClient implements IFrihetClient {
     deleteVendor(_id: string): Promise<void>;
     sendInvoice(id: string, to?: string): Promise<Rec>;
     markInvoicePaid(id: string, paidDate?: string): Promise<Rec>;
-    getInvoicePdf(id: string): Promise<Rec>;
-    getInvoiceEInvoice(invoiceId: string): Promise<Rec>;
+    getInvoicePdf(id: string): Promise<BinaryDocument>;
+    getInvoiceEInvoice(invoiceId: string): Promise<EInvoiceDocument>;
     createCreditNote(invoiceId: string, data: {
         reason: string;
         reasonDescription?: string;
@@ -88,13 +89,15 @@ export declare class DemoFrihetClient implements IFrihetClient {
         daysOverdue?: number;
     }): Promise<Rec>;
     sendQuote(id: string, to?: string): Promise<Rec>;
-    listWebhooks(params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<Rec>>;
-    getWebhook(id: string): Promise<Rec>;
-    createWebhook(data: Rec): Promise<Rec>;
-    updateWebhook(id: string, data: Rec): Promise<Rec>;
+    listWebhooks(): Promise<{
+        data: Webhook[];
+        total: number;
+        _demo?: true;
+        _demoNotice?: string;
+    }>;
+    getWebhook(id: string): Promise<Webhook>;
+    createWebhook(data: CreateWebhookInput): Promise<CreateWebhookResult>;
+    updateWebhook(id: string, data: UpdateWebhookInput): Promise<Webhook>;
     deleteWebhook(_id: string): Promise<void>;
     listClientContacts(_clientId: string, params?: {
         limit?: number;
@@ -106,7 +109,7 @@ export declare class DemoFrihetClient implements IFrihetClient {
         limit?: number;
         offset?: number;
     }): Promise<PaginatedResponse<Rec>>;
-    logClientActivity(clientId: string, data: Rec): Promise<Rec>;
+    logClientActivity(_clientId: string, data: Rec): Promise<Rec>;
     listClientNotes(_clientId: string, params?: {
         limit?: number;
         offset?: number;
@@ -441,7 +444,7 @@ export declare class DemoFrihetClient implements IFrihetClient {
         eventType?: string;
     }): Promise<Rec>;
     exportPayroll(params: {
-        format: "a3" | "contasol" | "sage" | "holded" | "siltra";
+        format: "a3" | "contasol" | "sage" | "siltra";
         month: string;
     }): Promise<Rec>;
     getPayrollChecklist(params: {
@@ -454,7 +457,7 @@ export declare class DemoFrihetClient implements IFrihetClient {
     getPermissionsMatrix(): Promise<Rec>;
     getMyPermissions(): Promise<Rec>;
     getCurrentPeriod(params?: {
-        periodId?: string;
+        fiscalYear?: string;
     }): Promise<Rec>;
     closePeriod(data: {
         type: "monthly" | "quarterly";

package/dist/demo-client.js

@@ -17,7 +17,62 @@
  *   - delete / remove methods → resolve void (interface return type forbids a
  *     stamp; this is the one accepted, documented gap).
  */
+import { Buffer } from "node:buffer";
 import { READ_STAMP, FISCAL_STAMP, DEMO_NOW, demoPage, demoEmptyPage, findOrStub, demoId, simulateWrite, simulateAction, demoClients, demoProducts, demoInvoices, demoExpenses, demoQuotes, demoVendors, demoBankAccounts, demoTransactions, } from "./demo-fixtures.js";
+const DEMO_RBAC_ROLES = ["owner", "admin", "manager", "sales", "accountant", "employee", "viewer"];
+const DEMO_RBAC_RESOURCES = [
+    "workspace", "invoices", "quotes", "expenses", "clients", "products", "accounting",
+    "people", "payroll", "integrations", "banking", "settings", "audit_log", "billing",
+];
+const DEMO_RBAC_ACTIONS = ["read", "create", "update", "delete", "bulk_delete", "export"];
+const DEMO_FULL_ACTIONS = [...DEMO_RBAC_ACTIONS];
+const DEMO_PERMISSION_MATRIX = {
+    owner: {
+        workspace: ["read", "update", "export"],
+        invoices: DEMO_FULL_ACTIONS, quotes: DEMO_FULL_ACTIONS, expenses: DEMO_FULL_ACTIONS,
+        clients: DEMO_FULL_ACTIONS, products: DEMO_FULL_ACTIONS, accounting: DEMO_FULL_ACTIONS,
+        people: DEMO_FULL_ACTIONS, payroll: DEMO_FULL_ACTIONS, integrations: DEMO_FULL_ACTIONS,
+        banking: ["read", "create", "update", "delete", "export"],
+        settings: ["read", "update"], audit_log: ["read", "export"],
+        billing: ["read", "create", "update", "delete", "export"],
+    },
+    admin: {
+        workspace: ["read", "update", "export"],
+        invoices: DEMO_FULL_ACTIONS, quotes: DEMO_FULL_ACTIONS, expenses: DEMO_FULL_ACTIONS,
+        clients: DEMO_FULL_ACTIONS, products: DEMO_FULL_ACTIONS, accounting: DEMO_FULL_ACTIONS,
+        people: DEMO_FULL_ACTIONS, payroll: DEMO_FULL_ACTIONS, integrations: DEMO_FULL_ACTIONS,
+        banking: ["read", "create", "update", "delete", "export"],
+        settings: ["read", "update"], audit_log: ["read", "export"],
+    },
+    manager: {
+        workspace: ["read"], invoices: ["read", "export"], quotes: ["read", "export"],
+        clients: ["read", "export"], products: ["read", "export"], expenses: ["read", "export"],
+        banking: ["read"], people: DEMO_FULL_ACTIONS, payroll: ["read", "export"],
+        settings: ["read"], integrations: ["read"], audit_log: ["read"],
+    },
+    sales: {
+        workspace: ["read"], invoices: ["read", "create", "update", "export"],
+        quotes: ["read", "create", "update", "export"], clients: ["read", "create", "update", "export"],
+        products: ["read", "export"], expenses: ["read", "export"],
+    },
+    accountant: {
+        workspace: ["read"], invoices: ["read", "create", "update", "export"],
+        quotes: ["read", "export"], expenses: ["read", "create", "update", "export"],
+        clients: ["read", "export"], products: ["read", "export"],
+        banking: ["read", "create", "update", "export"], accounting: ["read", "create", "update", "export"],
+        people: ["read"], audit_log: ["read", "export"],
+    },
+    employee: { workspace: ["read"] },
+    viewer: {
+        workspace: ["read", "export"], invoices: ["read", "export"], quotes: ["read", "export"],
+        expenses: ["read", "export"], clients: ["read", "export"], products: ["read", "export"],
+        banking: ["read"], accounting: ["read", "export"], people: ["read"], payroll: ["read"],
+        settings: ["read"], integrations: ["read"], audit_log: ["read"],
+    },
+};
+const DEMO_OWNER_CAPABILITIES = Object.entries(DEMO_PERMISSION_MATRIX.owner)
+    .flatMap(([resource, actions]) => actions.map((action) => `${resource}:${action}`))
+    .sort();
 export class DemoFrihetClient {
     // ---------------------------------------------------------------- Invoices
     async listInvoices(params) {
@@ -139,13 +194,27 @@ export class DemoFrihetClient {
         return simulateAction(id, { status: "paid", paidAt: paidDate ?? DEMO_NOW });
     }
     async getInvoicePdf(id) {
-        return { id, url: "https://app.frihet.io/demo/invoice.pdf", contentType: "application/pdf", ...READ_STAMP };
+        // #1393: shape mirrors the live BinaryDocument contract (id,
+        // contentType, sizeBytes, base64) so demo-mode outputSchema validation
+        // runs against the same fields as the live path.
+        const demoPdfBytes = Buffer.from("%PDF-1.4\n%%DEMO e-invoice for " + id + "\n%%EOF\n", "utf8");
+        return {
+            id,
+            contentType: "application/pdf",
+            sizeBytes: demoPdfBytes.byteLength,
+            base64: demoPdfBytes.toString("base64"),
+            ...READ_STAMP,
+        };
     }
     async getInvoiceEInvoice(invoiceId) {
+        // #1393: mirrors the live XML arm of the MIME-discriminated contract.
+        const xml = `<?xml version="1.0" encoding="UTF-8"?>\n<Invoice><!-- DEMO example e-invoice for ${invoiceId} --></Invoice>`;
         return {
-            xml: `<?xml version="1.0" encoding="UTF-8"?>\n<Invoice><!-- DEMO example e-invoice for ${invoiceId} --></Invoice>`,
+            id: invoiceId,
+            xml,
+            contentType: "application/xml; charset=utf-8",
+            sizeBytes: Buffer.byteLength(xml, "utf8"),
             filename: `${invoiceId}.xml`,
-            format: "facturae",
             ...FISCAL_STAMP,
         };
     }
@@ -190,17 +259,42 @@ export class DemoFrihetClient {
         return { id, status: "sent", sentAt: DEMO_NOW, ...(to ? { to } : {}), ...FISCAL_STAMP };
     }
     // ---------------------------------------------------------------- Webhooks
-    async listWebhooks(params) {
-        return demoEmptyPage(params);
+    async listWebhooks() {
+        const { data, total } = demoEmptyPage();
+        return { data: data, total };
     }
     async getWebhook(id) {
-        return { id, ...READ_STAMP };
+        return {
+            id,
+            name: "Demo webhook",
+            url: "https://example.com/webhooks/frihet",
+            events: ["invoice.paid"],
+            status: "active",
+            metadata: { demo: true },
+            hasSecret: false,
+            createdAt: DEMO_NOW,
+            updatedAt: DEMO_NOW,
+            ...READ_STAMP,
+        };
     }
     async createWebhook(data) {
-        return simulateWrite("demo_wh", data, { active: data.active ?? true });
+        return simulateWrite("demo_wh", { ...data }, {
+            status: data.status ?? "active",
+            hasSecret: typeof data.secret === "string" && data.secret.length > 0,
+        });
     }
     async updateWebhook(id, data) {
-        return simulateAction(id, { ...data });
+        const { secret, ...fields } = data;
+        const { success: _success, ...result } = simulateAction(id, {
+            name: "Demo webhook",
+            url: "https://example.com/webhooks/frihet",
+            events: ["invoice.paid"],
+            status: "active",
+            metadata: { demo: true },
+            hasSecret: typeof secret === "string" && secret.length > 0,
+            ...fields,
+        });
+        return result;
     }
     async deleteWebhook(_id) {
         return;
@@ -219,8 +313,13 @@ export class DemoFrihetClient {
     async listClientActivities(_clientId, params) {
         return demoEmptyPage(params);
     }
-    async logClientActivity(clientId, data) {
-        return simulateWrite("demo_act", data, { clientId });
+    async logClientActivity(_clientId, data) {
+        return simulateWrite("demo_act", data, {
+            type: data.type === "email" ? "email_sent" : data.type,
+            timestamp: DEMO_NOW,
+            createdBy: "user",
+            metadata: {},
+        });
     }
     // ---------------------------------------------------------------- CRM: Notes
     async listClientNotes(_clientId, params) {
@@ -556,7 +655,17 @@ export class DemoFrihetClient {
         return simulateAction(entryId, { status: "closed", clockOutAt: DEMO_NOW });
     }
     async getOvertimeReport(params) {
-        return { period: params.period, totalRegularHours: 0, totalOvertimeHours: 0, byEmployee: [], generatedAt: DEMO_NOW, ...READ_STAMP };
+        return {
+            period: params.period,
+            employeeId: params.employeeId ?? null,
+            recordCount: 0,
+            dailyOvertime: [],
+            weeklyOvertime: [],
+            monthlyTotal: { workedMinutes: 0, overtimeMinutes: 0, regularMinutes: 0 },
+            annualOvertimeHours: 0,
+            alerts: [],
+            ...READ_STAMP,
+        };
     }
     async listAnomalies(params) {
         return demoEmptyPage(params);
@@ -565,12 +674,23 @@ export class DemoFrihetClient {
     async testWebhook(id, data) {
         return { webhookId: id, delivered: true, statusCode: 200, responseTimeMs: 42, eventType: data?.eventType ?? "ping", attemptedAt: DEMO_NOW, ...FISCAL_STAMP };
     }
-    // ---------------------------------------------------------------- Payroll (simulated fiscal)
+    // ---------------------------------------------------------------- Payroll (read-only demo)
     async exportPayroll(params) {
-        return { format: params.format, month: params.month, fileUrl: "https://app.frihet.io/demo/payroll.txt", filename: "demo-payroll.txt", rowCount: 0, generatedAt: DEMO_NOW, ...FISCAL_STAMP };
+        return {
+            month: params.month,
+            format: params.format,
+            employees: [],
+            summary: { exportedCount: 0, skippedNotReady: 0, totalGrossAnnual: 0 },
+            ...READ_STAMP,
+        };
     }
     async getPayrollChecklist(params) {
-        return { month: params.month, totalEmployees: 0, readyEmployees: 0, missingEmployees: 0, employees: [], generatedAt: DEMO_NOW, ...FISCAL_STAMP };
+        return {
+            month: params.month,
+            employees: [],
+            summary: { total: 0, ready: 0, notReady: 0, reviewedThisMonth: 0 },
+            ...READ_STAMP,
+        };
     }
     // ---------------------------------------------------------------- Onboarding
     async getOnboardingStatus() {
@@ -581,14 +701,48 @@ export class DemoFrihetClient {
     }
     // ---------------------------------------------------------------- Permissions
     async getPermissionsMatrix() {
-        return { roles: [{ role: "owner", permissions: ["*"] }], resources: ["invoices", "expenses", "clients"], generatedAt: DEMO_NOW, ...READ_STAMP };
+        return {
+            roles: DEMO_RBAC_ROLES,
+            resources: DEMO_RBAC_RESOURCES,
+            actions: DEMO_RBAC_ACTIONS,
+            legacyAliases: { editor: "sales" },
+            matrix: DEMO_PERMISSION_MATRIX,
+            source: "hand-maintained demo snapshot of the Frihet RBAC model; not derived from firestore.rules and not verified against it",
+            ...READ_STAMP,
+        };
     }
     async getMyPermissions() {
-        return { userId: "demo_user_001", role: "owner", permissions: ["*"], workspaceId: "demo_ws_001", ...READ_STAMP };
+        return {
+            role: "owner",
+            isOwner: true,
+            resources: DEMO_PERMISSION_MATRIX.owner,
+            scopes: DEMO_OWNER_CAPABILITIES,
+            legacyFieldSemantics: { resources: "rbacResources", scopes: "rbacCapabilities" },
+            rbac: {
+                role: "owner",
+                isOwner: true,
+                resources: DEMO_PERMISSION_MATRIX.owner,
+                capabilities: DEMO_OWNER_CAPABILITIES,
+            },
+            apiKeyScopes: [],
+            apiKeyUnrestricted: true,
+            denied: { einvoice: false },
+            deniedSemantics: "Known API-key scope denials only; not an exhaustive effective-authorization report.",
+            notIncluded: ["featureFlags", "deployedEndpoints"],
+            ...READ_STAMP,
+        };
     }
     // ---------------------------------------------------------------- Period close
     async getCurrentPeriod(params) {
-        return { id: params?.periodId ?? "demo_period_2026_07", type: "monthly", status: "open", startDate: "2026-07-01", endDate: "2026-07-31", ...READ_STAMP };
+        const fiscalYear = params?.fiscalYear ?? "2026";
+        return {
+            fiscalYear,
+            fiscalYearStart: "01-01",
+            status: "open",
+            dateRange: { from: `${fiscalYear}-01-01`, to: `${fiscalYear}-12-31` },
+            closing: null,
+            ...READ_STAMP,
+        };
     }
     async closePeriod(data) {
         return simulateWrite("demo_period", { type: data.type }, { status: "closed", closedAt: DEMO_NOW });

package/dist/demo-fixtures.d.ts

@@ -30,13 +30,13 @@ export declare const EMPTY_STAMP: DemoStamp;
 export declare const DEMO_NOW = "2026-07-15T10:00:00.000Z";
 /** Test IBAN (ECBS/AEAT example — never a real account). */
 export declare const DEMO_TEST_IBAN = "ES9121000418450200051332";
-export type DemoPaginated = PaginatedResponse<Record<string, unknown>> & DemoStamp;
-/** Wrap a fixture array in a stamped PaginatedResponse. */
+export type DemoPaginated = PaginatedResponse<Record<string, unknown>>;
+/** Wrap a fixture array in a PaginatedResponse. */
 export declare function demoPage(data: Record<string, unknown>[], params?: {
     limit?: number;
     offset?: number;
 }): DemoPaginated;
-/** Empty stamped PaginatedResponse for surfaces without dedicated fixtures. */
+/** Empty PaginatedResponse for surfaces without dedicated fixtures. */
 export declare function demoEmptyPage(params?: {
     limit?: number;
     offset?: number;

package/dist/demo-fixtures.js

@@ -36,24 +36,24 @@ export const EMPTY_STAMP = {
 export const DEMO_NOW = "2026-07-15T10:00:00.000Z";
 /** Test IBAN (ECBS/AEAT example — never a real account). */
 export const DEMO_TEST_IBAN = "ES9121000418450200051332";
-/** Wrap a fixture array in a stamped PaginatedResponse. */
+/** Wrap a fixture array in a PaginatedResponse. */
 export function demoPage(data, params) {
+    const limit = params?.limit ?? 50;
+    const offset = params?.offset ?? 0;
     return {
-        data,
+        data: data.slice(offset, offset + limit),
         total: data.length,
-        limit: params?.limit ?? 50,
-        offset: params?.offset ?? 0,
-        ...READ_STAMP,
+        limit,
+        offset,
     };
 }
-/** Empty stamped PaginatedResponse for surfaces without dedicated fixtures. */
+/** Empty PaginatedResponse for surfaces without dedicated fixtures. */
 export function demoEmptyPage(params) {
     return {
         data: [],
         total: 0,
         limit: params?.limit ?? 50,
         offset: params?.offset ?? 0,
-        ...EMPTY_STAMP,
     };
 }
 /* ------------------------------------------------------------------ */

package/dist/fiscal-aliases.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Fiscal `modelo` tool naming aliases — prefix-drift fix (issue #50).
+ *
+ * ── Problem ──────────────────────────────────────────────────────────────
+ * The `modelo` fiscal tools split 5/5 on naming prefix: the mainland AEAT
+ * models (`fiscal.ts`) use `get_modelo_*`, while the Canary IGIC + Impuesto
+ * Sociedades models (`igic.ts`, `impuesto_sociedades.ts`) use the house
+ * `frihet_*` convention. An agent that learns the `frihet_modelo_NNN_summary`
+ * pattern from IGIC/IS will guess `frihet_modelo_303_summary` for VAT and get
+ * tool-not-found — 303/130/347 are the most-used models.
+ *
+ * ── Fix ──────────────────────────────────────────────────────────────────
+ * Register thin NAME ALIASES that resolve to the exact same registered tool
+ * (same handler, same schema, same annotations — zero semantic divergence),
+ * WITHOUT calling `registerTool()` a second time. The MCP SDK's `McpServer`
+ * resolves `tools/call` by looking up `this._registeredTools[name]`
+ * (mcp.js: `setToolRequestHandlers` -> `CallToolRequestSchema` handler), so
+ * pointing an alias key at the SAME registered-tool object makes it callable
+ * with zero duplication and zero drift risk.
+ *
+ * This intentionally does NOT touch `src/tools/*.ts` (where the 157-tool
+ * audit / pin tests count literal `registerTool(` call sites) and is applied
+ * to the REAL `McpServer` instance only, AFTER `registerAllTools()` — the
+ * `tool-exposure.test.ts` / `openai-*.test.ts` suites exercise
+ * `registerAllTools()` against a bare `StubMcpServer` and never call
+ * `applyFiscalAliases`, so the 157-tool pins are untouched by design.
+ *
+ * KNOWN LIMITATION: this relies on the SDK's internal (unprefixed-by-type,
+ * but underscore-private) `_registeredTools` field. It is FAIL-OPEN — if a
+ * future SDK release renames/removes that field, `applyFiscalAliases` is a
+ * silent no-op (the canonical `get_modelo_*` names keep working; only the
+ * alias convenience is lost). Pinned by `fiscal-aliases.test.ts`.
+ */
+/** alias name -> canonical registered tool name. */
+export declare const FISCAL_MODELO_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Apply the fiscal `modelo` aliases to a live `McpServer` instance. Call this
+ * AFTER `registerAllTools()` so every canonical tool already exists.
+ *
+ * Fail-open: if the SDK's internal registry is missing or reshaped, this is a
+ * silent no-op — it never throws, and never blocks server startup.
+ */
+export declare function applyFiscalAliases(server: unknown): void;
+//# sourceMappingURL=fiscal-aliases.d.ts.map

package/dist/fiscal-aliases.js

@@ -0,0 +1,62 @@
+/**
+ * Fiscal `modelo` tool naming aliases — prefix-drift fix (issue #50).
+ *
+ * ── Problem ──────────────────────────────────────────────────────────────
+ * The `modelo` fiscal tools split 5/5 on naming prefix: the mainland AEAT
+ * models (`fiscal.ts`) use `get_modelo_*`, while the Canary IGIC + Impuesto
+ * Sociedades models (`igic.ts`, `impuesto_sociedades.ts`) use the house
+ * `frihet_*` convention. An agent that learns the `frihet_modelo_NNN_summary`
+ * pattern from IGIC/IS will guess `frihet_modelo_303_summary` for VAT and get
+ * tool-not-found — 303/130/347 are the most-used models.
+ *
+ * ── Fix ──────────────────────────────────────────────────────────────────
+ * Register thin NAME ALIASES that resolve to the exact same registered tool
+ * (same handler, same schema, same annotations — zero semantic divergence),
+ * WITHOUT calling `registerTool()` a second time. The MCP SDK's `McpServer`
+ * resolves `tools/call` by looking up `this._registeredTools[name]`
+ * (mcp.js: `setToolRequestHandlers` -> `CallToolRequestSchema` handler), so
+ * pointing an alias key at the SAME registered-tool object makes it callable
+ * with zero duplication and zero drift risk.
+ *
+ * This intentionally does NOT touch `src/tools/*.ts` (where the 157-tool
+ * audit / pin tests count literal `registerTool(` call sites) and is applied
+ * to the REAL `McpServer` instance only, AFTER `registerAllTools()` — the
+ * `tool-exposure.test.ts` / `openai-*.test.ts` suites exercise
+ * `registerAllTools()` against a bare `StubMcpServer` and never call
+ * `applyFiscalAliases`, so the 157-tool pins are untouched by design.
+ *
+ * KNOWN LIMITATION: this relies on the SDK's internal (unprefixed-by-type,
+ * but underscore-private) `_registeredTools` field. It is FAIL-OPEN — if a
+ * future SDK release renames/removes that field, `applyFiscalAliases` is a
+ * silent no-op (the canonical `get_modelo_*` names keep working; only the
+ * alias convenience is lost). Pinned by `fiscal-aliases.test.ts`.
+ */
+/** alias name -> canonical registered tool name. */
+export const FISCAL_MODELO_ALIASES = {
+    frihet_modelo_303_summary: "get_modelo_303_summary",
+    frihet_modelo_130_summary: "get_modelo_130_summary",
+    frihet_modelo_390_summary: "get_modelo_390_summary",
+    frihet_modelo_180_summary: "get_modelo_180_summary",
+    frihet_modelo_347_summary: "get_modelo_347_summary",
+};
+/**
+ * Apply the fiscal `modelo` aliases to a live `McpServer` instance. Call this
+ * AFTER `registerAllTools()` so every canonical tool already exists.
+ *
+ * Fail-open: if the SDK's internal registry is missing or reshaped, this is a
+ * silent no-op — it never throws, and never blocks server startup.
+ */
+export function applyFiscalAliases(server) {
+    const registry = server._registeredTools;
+    if (!registry || typeof registry !== "object")
+        return;
+    for (const [alias, canonical] of Object.entries(FISCAL_MODELO_ALIASES)) {
+        const target = registry[canonical];
+        if (!target)
+            continue; // Canonical tool not registered in this profile (e.g. an allow-listed mode) — skip, no divergence.
+        if (registry[alias])
+            continue; // Never overwrite an existing registration.
+        registry[alias] = target; // Same object reference as the canonical tool — zero semantic divergence.
+    }
+}
+//# sourceMappingURL=fiscal-aliases.js.map

package/dist/index.js

@@ -15,6 +15,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { FrihetClient } from "./client.js";
 import { DemoFrihetClient } from "./demo-client.js";
+import { normalizePublicApiBaseUrl } from "./api-origin.js";
 // Single source of truth for the server version: package.json (read at runtime
 // from dist/../package.json). Hardcoding it here caused repeated version drift
 // (server.json/index.ts/console out of sync → audit:mcp-refs gate failure).
@@ -28,11 +29,10 @@ const PKG_VERSION = (() => {
         return "0.0.0";
     }
 })();
-import { registerAllTools } from "./tools/register-all.js";
-import { registerAllResources } from "./resources/register-all.js";
-import { registerAllPrompts } from "./prompts/register-all.js";
-import { applyOpenAIProfile, OPENAI_ALLOWED_TOOL_COUNT, OPENAI_EXCLUDED_COUNT, OPENAI_EXCLUDED_RESOURCE_COUNT, OPENAI_REVIEWED_TOOL_ALLOWLIST } from "./openai-profile.js";
-import { resolveToolMode, applyToolExposureProfile, GROUPED_META_TOOL_COUNT } from "./tool-exposure.js";
+import { OPENAI_ALLOWED_TOOL_COUNT, OPENAI_EXCLUDED_COUNT, OPENAI_EXCLUDED_RESOURCE_COUNT } from "./openai-profile.js";
+import { resolveToolMode, GROUPED_META_TOOL_COUNT } from "./tool-exposure.js";
+import { localMcpSurfaceComposition, registerMcpSurface, } from "./server-composition.js";
+import { AGENT_SERVER_INSTRUCTIONS, API_KEY_LOCATION, } from "./agent-onboarding.js";
 import { log } from "./logger.js";
 import { registerShutdownHook } from "./metrics.js";
 import { setTraceContext } from "./observability.js";
@@ -44,33 +44,40 @@ function main() {
     const demoFlag = process.env.FRIHET_DEMO;
     const demoMode = demoFlag === "1" || demoFlag === "true";
     if (!demoMode && !apiKey) {
+        // Human-readable first, then one machine-readable line. An agent that only
+        // gets prose here has to guess; the JSON line gives it a code to branch on
+        // and the two recoveries that actually exist. /settings/api is the real,
+        // routable screen — there is no "Developers" section in the app.
         console.error("Error: FRIHET_API_KEY environment variable is required.\n\n" +
             "Get your API key:\n" +
             "  1. Create a free account at https://app.frihet.io\n" +
-            "  2. Go to Settings > Developers > API Keys\n" +
-            "  3. Create a key and add it to your MCP configuration\n\n" +
+            "  2. Open https://app.frihet.io/settings/api\n" +
+            "  3. Create a key (it starts with fri_) and add it to your MCP configuration\n\n" +
             "Or try it instantly with no key: set FRIHET_DEMO=1 for example data.\n\n" +
             "Documentation: https://docs.frihet.io/desarrolladores/mcp-server\n");
+        console.error(JSON.stringify({
+            error: {
+                code: "FRIHET_API_KEY_MISSING",
+                message: "FRIHET_API_KEY environment variable is required",
+                obtainAt: API_KEY_LOCATION,
+                recovery: [
+                    { action: "set_env", env: { FRIHET_API_KEY: "fri_<key>" } },
+                    { action: "run_without_credentials", env: { FRIHET_DEMO: "1" } },
+                ],
+                docs: "https://docs.frihet.io/desarrolladores/mcp-server",
+            },
+        }));
         process.exit(1);
     }
-    const baseUrl = process.env.FRIHET_API_URL;
-    if (!demoMode && baseUrl !== undefined) {
-        let parsed;
+    const baseUrlRaw = process.env.FRIHET_API_URL;
+    let baseUrl;
+    if (!demoMode && baseUrlRaw !== undefined) {
         try {
-            parsed = new URL(baseUrl);
+            baseUrl = normalizePublicApiBaseUrl(baseUrlRaw);
         }
-        catch {
-            console.error(`Error: FRIHET_API_URL is not a valid URL: "${baseUrl}"\n` +
-                "It must be a valid https:// URL with a frihet.io hostname.\n");
-            process.exit(1);
-        }
-        if (parsed.protocol !== "https:") {
-            console.error(`Error: FRIHET_API_URL must use https:// (got "${parsed.protocol}").\n`);
-            process.exit(1);
-        }
-        if (!parsed.hostname.endsWith("frihet.io")) {
-            console.error(`Error: FRIHET_API_URL hostname must be under frihet.io (got "${parsed.hostname}").\n` +
-                "This prevents redirection to untrusted servers.\n");
+        catch (error) {
+            console.error(`Error: ${error instanceof Error ? error.message : "FRIHET_API_URL is invalid"}.\n` +
+                "It must be a canonical https:// URL with a trusted frihet.io hostname.\n");
             process.exit(1);
         }
     }
@@ -80,69 +87,47 @@ function main() {
     if (demoMode) {
         console.error("[frihet-mcp] DEMO MODE — serving example fixtures, no real data, nothing persisted");
     }
-    // Set trace context for Langfuse (reads LANGFUSE_* from process.env automatically).
-    // clientName can be overridden via FRIHET_CLIENT_NAME env var by the MCP host.
+    // Set the fixed protocol fact for Langfuse (reads LANGFUSE_* from process.env automatically).
+    // Client identity is deliberately omitted from telemetry.
     setTraceContext({
         mcpVersion: "mcp/1.0",
-        clientName: process.env.FRIHET_CLIENT_NAME,
     });
     const server = new McpServer({
         name: "frihet-erp",
         version: PKG_VERSION,
         description: "AI-native MCP server for Frihet ERP — invoices, expenses, clients, products, quotes, webhooks, and deposits. " +
-            "Provides 157 tools (including business context, monthly summaries, quarterly taxes, invoice duplication, CRM subcollections, and deposit management), " +
-            "11 resources (7 static + 4 live), and 10 workflow prompts for business management " +
+            "Provides a catalogue of 157 canonical operations; fiscal aliases and optional grouped discovery names are reported separately. " +
+            "The local package serves 11 resources (7 static + 4 API-backed) and 10 workflow prompts " +
             "with full Spanish tax compliance (IVA, IGIC, IPSI).",
+    }, {
+        // Delivered by `initialize` to every MCP client, which hands it to the model
+        // before the first tool call. This is the only onboarding channel that costs
+        // the operator zero configuration. Source: src/agent-onboarding.ts.
+        instructions: AGENT_SERVER_INSTRUCTIONS,
     });
     const openaiMode = process.env.FRIHET_OPENAI_MODE === "true";
     const toolMode = resolveToolMode();
-    // PROFILE COMPOSITION ORDER (both interceptors wrap registerTool):
-    //   1. applyToolExposureProfile FIRST (innermost) — so the 3 discovery
-    //      meta-tools register against the REAL server.registerTool and bypass the
-    //      OpenAI allow-list gate. In allow-list mode it catalogs ONLY the reviewed
-    //      tools, keeping the progressive-disclosure surface == the reviewed 53.
-    //   2. applyOpenAIProfile SECOND (outermost) — a business-tool registration is
-    //      first gated/redacted/annotated/openWorldHint-justified by OpenAI, THEN
-    //      collapsed by the grouped interceptor, so the terse collapsed line is the
-    //      final description and OpenAI's handler redaction survives.
-    // Order only matters when BOTH are active (openai-mcp grouped); openai-only and
-    // grouped-only are unaffected by the swap.
-    // Apply grouped tool-exposure profile if enabled (progressive disclosure).
-    // FRIHET_TOOL_MODE=grouped collapses the full tool descriptions into terse
-    // one-liners + adds list_tool_groups / search_tools / describe_tool meta-tools,
-    // so agents load depth on demand instead of a flat 157-tool wall of context.
-    // Default (unset / "full") is byte-identical to current behavior. When OpenAI
-    // mode is also on, pass the reviewed allow-list so the catalog/meta-tools are
-    // pinned to exactly the 53 reviewed tools.
     if (toolMode === "grouped") {
-        applyToolExposureProfile(server, openaiMode ? { allowlist: OPENAI_REVIEWED_TOOL_ALLOWLIST } : undefined);
         log({
             level: "info",
             message: `Grouped tool-exposure active — tools collapsed to terse summaries, ${GROUPED_META_TOOL_COUNT} discovery meta-tools added (list_tool_groups, search_tools, describe_tool); full depth served on demand`,
             operation: "startup",
         });
     }
-    // Apply OpenAI-safe profile if enabled (strips sensitive fields, fixes annotations)
     if (openaiMode) {
-        applyOpenAIProfile(server);
         log({
             level: "info",
             message: `OpenAI safety profile active — ${OPENAI_ALLOWED_TOOL_COUNT} tools allowed, prompts hidden, ${OPENAI_EXCLUDED_COUNT} defense-in-depth exclusions, ${OPENAI_EXCLUDED_RESOURCE_COUNT} resources excluded, gov IDs + credentials redacted`,
             operation: "startup",
         });
     }
-    // Register tools (62 full / 60 in OpenAI mode)
-    registerAllTools(server, client);
-    // Register 11 resources (7 static + 4 dynamic via API)
-    registerAllResources(server, client);
-    // Register 10 workflow prompts
-    registerAllPrompts(server);
+    registerMcpSurface(server, client, localMcpSurfaceComposition(openaiMode, toolMode === "grouped"));
     // Register shutdown hook to log final metrics summary
     registerShutdownHook();
     // Connect via stdio transport
     const transport = new StdioServerTransport();
     server.connect(transport).then(() => {
-        console.error(`[frihet-mcp] v${PKG_VERSION} | 157 tools | https://github.com/Frihet-io/frihet-mcp`);
+        console.error(`[frihet-mcp] v${PKG_VERSION} | capability truth enabled | https://github.com/Frihet-io/frihet-mcp`);
         log({
             level: "info",
             message: "Frihet MCP server running on stdio",