@frihet/mcp-server 1.16.4 → 1.16.6

package/README.md

@@ -47,7 +47,7 @@
 | **ChatGPT Apps** | Coming soon | [chatgpt.com](https://chatgpt.com) |
 | **Anthropic Claude Directory** | Coming soon | [claude.ai/settings/connectors](https://claude.ai/settings/connectors) |
 
-> **Tool count:** npm `latest` (1.16.4) ships all 157 tools, same as the remote endpoint (`mcp.frihet.io`).
+> **Tool count:** the package (1.16.6) ships all 157 tools, same as the remote endpoint (`mcp.frihet.io`).
 
 ---
 

package/dist/client-interface.d.ts

@@ -104,7 +104,7 @@ export interface IFrihetClient {
         reasonDescription?: string;
         fullCredit?: boolean;
         issueDate?: string;
-    }): Promise<Record<string, unknown>>;
+    }, idempotencyKey?: string): Promise<Record<string, unknown>>;
     applyLateFee(invoiceId: string, data?: {
         amount?: number;
         daysOverdue?: number;

package/dist/client.d.ts

@@ -153,12 +153,24 @@ export declare class FrihetClient {
     markInvoicePaid(id: string, paidDate?: string): Promise<Record<string, unknown>>;
     getInvoicePdf(id: string): Promise<Record<string, unknown>>;
     getInvoiceEInvoice(invoiceId: string): Promise<any>;
+    /**
+     * `POST /v1/invoices/:id/credit-note` — creates a rectificativa DRAFT.
+     *
+     * The backend REQUIRES an `Idempotency-Key` header (`400
+     * IDEMPOTENCY_KEY_REQUIRED` without it). `request` mints one for every
+     * mutation, so passing `idempotencyKey` is optional: supply it to make a
+     * caller-driven retry replay the stored 201 instead of creating a second
+     * draft. The backend marks that replay with `X-Idempotent-Replayed: true`,
+     * but this client reads no response headers, so the replayed 201 and the
+     * original are indistinguishable to the caller — both are the same draft,
+     * which is the property that matters here.
+     */
     createCreditNote(invoiceId: string, data: {
         reason: string;
         reasonDescription?: string;
         fullCredit?: boolean;
         issueDate?: string;
-    }): Promise<Record<string, unknown>>;
+    }, idempotencyKey?: string): Promise<Record<string, unknown>>;
     applyLateFee(invoiceId: string, data?: {
         amount?: number;
         daysOverdue?: number;

package/dist/client.js

@@ -16,6 +16,76 @@ const BASE_URL = "https://api.frihet.io/v1";
 const MAX_RETRIES = 3;
 const DEFAULT_RETRY_DELAY_MS = 1000;
 const REQUEST_TIMEOUT_MS = 30000;
+/**
+ * HTTP methods for which the backend treats the request as a mutation and
+ * therefore accepts (and for some endpoints REQUIRES) an `Idempotency-Key`
+ * header. `POST /v1/invoices/:id/credit-note` rejects a keyless request with
+ * `400 IDEMPOTENCY_KEY_REQUIRED`, so a client that never sends one fails 100%
+ * of the time — see src/__tests__/idempotency-key-contract.test.ts.
+ */
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/**
+ * Origin marker sent on every request so the backend can tell an MCP-driven
+ * create apart from a direct-API one.
+ *
+ * The backend classifier (`detectApiInvoiceSource`, Frihet-ERP
+ * functions/src/publicApi.ts) matches `mcp` / `frihet-mcp` / `@frihet/mcp`
+ * across three headers: `x-frihet-source`, `x-frihet-client` and `user-agent`.
+ * We send TWO markers because they survive different network paths:
+ *
+ *  - `X-Frihet-Source: mcp` is the explicit, documented marker. It reaches the
+ *    backend when the client talks to the Cloud Function directly (custom
+ *    `baseUrl`, self-hosted proxy).
+ *  - `User-Agent` is what actually reaches the backend on the DEFAULT baseUrl:
+ *    `api.frihet.io` is fronted by workers/api-proxy/worker.js, whose
+ *    `ALLOWED_REQUEST_HEADERS` allowlist forwards `user-agent` but drops
+ *    `x-frihet-source` (verified live: /agents.json answers 200 at
+ *    api.frihet.io and 401 at the Cloud Function, so the Worker is in path).
+ *    Without the UA the source header is a phantom — set, then stripped at the
+ *    edge, and every MCP invoice still lands as `source: 'api'`.
+ *
+ * Deliberately carries no version: the version lives in package.json only
+ * (see src/index.ts PKG_VERSION) and a second hardcoded copy is exactly the
+ * drift `scripts/audit-mcp-refs.mjs` exists to catch.
+ *
+ * Pinned on the wire by src/__tests__/source-header-contract.test.ts.
+ */
+const SOURCE_MARKER = "mcp";
+const SOURCE_USER_AGENT = "frihet-mcp-server";
+/**
+ * Fresh idempotency key, always a syntactically valid UUID v4.
+ *
+ * `crypto.randomUUID` is a global on the Cloudflare Workers runtime and on
+ * Node >= 19. On Node 18 — our declared `engines` floor — `globalThis.crypto`
+ * is behind `--experimental-global-webcrypto`, so the fallback is a REAL code
+ * path there, not a theoretical one. It therefore has to produce a UUID and
+ * not an ad-hoc string: the backend documents "UUID v4 recommended", and
+ * src/__tests__/idempotency-key-contract.test.ts asserts the shape.
+ */
+function newIdempotencyKey() {
+    const c = globalThis.crypto;
+    if (typeof c?.randomUUID === "function") {
+        return c.randomUUID();
+    }
+    // RFC 4122 v4 layout from Math.random. Weaker entropy than the CSPRNG, but
+    // the key only has to be unique per caller, never unguessable.
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
+        const r = (Math.random() * 16) | 0;
+        const v = ch === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * A caller-supplied key counts only if it carries a value. An empty or
+ * whitespace-only string is what an LLM client emits for "I have nothing to
+ * put here" on an optional string param — treating it as PRESENT would leave
+ * the request keyless and reproduce the very `400 IDEMPOTENCY_KEY_REQUIRED`
+ * this client exists to prevent.
+ */
+function normalizeIdempotencyKey(key) {
+    const trimmed = key?.trim();
+    return trimmed ? trimmed : undefined;
+}
 export class FrihetApiError extends Error {
     statusCode;
     errorCode;
@@ -40,8 +110,15 @@ export class FrihetClient {
     }
     // ------------------------------------------------------------------ HTTP
     // ------------------------------------------------------------------
-    async request(method, path, body, query, retryCount = 0) {
+    async request(method, path, body, query, retryCount = 0, idempotencyKey) {
         const url = new URL(`${this.baseUrl}${path}`);
+        // Resolved once, at the top of the call chain: a caller-supplied key wins,
+        // otherwise mutations get a freshly minted one. The resolved value is then
+        // threaded through the 429 recursion below so a retry replays the SAME key
+        // — retrying with a new key is exactly the duplicate the key exists to
+        // prevent (a retried credit-note would create a second draft).
+        const resolvedIdempotencyKey = normalizeIdempotencyKey(idempotencyKey) ??
+            (MUTATING_METHODS.has(method) ? newIdempotencyKey() : undefined);
         if (query) {
             for (const [key, value] of Object.entries(query)) {
                 if (value !== undefined) {
@@ -53,7 +130,12 @@ export class FrihetClient {
             "X-API-Key": this.apiKey,
             "Content-Type": "application/json",
             Accept: "application/json",
+            "X-Frihet-Source": SOURCE_MARKER,
+            "User-Agent": SOURCE_USER_AGENT,
         };
+        if (resolvedIdempotencyKey) {
+            headers["Idempotency-Key"] = resolvedIdempotencyKey;
+        }
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
         const startTime = Date.now();
@@ -91,7 +173,7 @@ export class FrihetClient {
                 : DEFAULT_RETRY_DELAY_MS * Math.pow(2, retryCount);
             logRetry(method, path, retryCount, delayMs);
             await this.sleep(delayMs);
-            return this.request(method, path, body, query, retryCount + 1);
+            return this.request(method, path, body, query, retryCount + 1, resolvedIdempotencyKey);
         }
         // Error responses
         if (!response.ok) {
@@ -150,8 +232,8 @@ export class FrihetClient {
      * not an envelope (legacy endpoints that return the item directly), it is
      * returned unchanged so existing callers keep working.
      */
-    async requestUnwrapped(method, path, body, query) {
-        const raw = await this.request(method, path, body, query);
+    async requestUnwrapped(method, path, body, query, idempotencyKey) {
+        const raw = await this.request(method, path, body, query, 0, idempotencyKey);
         if (raw !== null &&
             typeof raw === "object" &&
             !Array.isArray(raw) &&
@@ -358,8 +440,20 @@ export class FrihetClient {
         // (e.g. a bare XML string), so this is safe either way.
         return this.requestUnwrapped("GET", `/invoices/${encodeURIComponent(invoiceId)}/xml`);
     }
-    async createCreditNote(invoiceId, data) {
-        return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(invoiceId)}/credit-note`, data);
+    /**
+     * `POST /v1/invoices/:id/credit-note` — creates a rectificativa DRAFT.
+     *
+     * The backend REQUIRES an `Idempotency-Key` header (`400
+     * IDEMPOTENCY_KEY_REQUIRED` without it). `request` mints one for every
+     * mutation, so passing `idempotencyKey` is optional: supply it to make a
+     * caller-driven retry replay the stored 201 instead of creating a second
+     * draft. The backend marks that replay with `X-Idempotent-Replayed: true`,
+     * but this client reads no response headers, so the replayed 201 and the
+     * original are indistinguishable to the caller — both are the same draft,
+     * which is the property that matters here.
+     */
+    async createCreditNote(invoiceId, data, idempotencyKey) {
+        return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(invoiceId)}/credit-note`, data, undefined, idempotencyKey);
     }
     async applyLateFee(invoiceId, data) {
         return this.requestUnwrapped("POST", `/invoices/${encodeURIComponent(invoiceId)}/late-fee`, data ?? {});
@@ -599,10 +693,10 @@ export class FrihetClient {
     // ---------------------------------------------------------------- Intelligence
     // ----------------------------------------------------------------
     async getBusinessContext() {
-        return this.request("GET", "/context");
+        return this.requestUnwrapped("GET", "/context");
     }
     async getMonthlySummary(month) {
-        return this.request("GET", "/monthly", undefined, {
+        return this.requestUnwrapped("GET", "/monthly", undefined, {
             month,
         });
     }

package/dist/demo-client.d.ts

@@ -82,7 +82,7 @@ export declare class DemoFrihetClient implements IFrihetClient {
         reasonDescription?: string;
         fullCredit?: boolean;
         issueDate?: string;
-    }): Promise<Rec>;
+    }, _idempotencyKey?: string): Promise<Rec>;
     applyLateFee(invoiceId: string, data?: {
         amount?: number;
         daysOverdue?: number;

package/dist/demo-client.js

@@ -149,15 +149,35 @@ export class DemoFrihetClient {
             ...FISCAL_STAMP,
         };
     }
-    async createCreditNote(invoiceId, data) {
+    // Mirrors the live 201 body: a DRAFT rectificativa, always by differences
+    // (`rectificationMethod: "I"`), R-type derived from `reason` server-side
+    // (`error` → R1, everything else → R4 — R2/R3/R5 are unreachable via the API).
+    async createCreditNote(invoiceId, data, _idempotencyKey) {
+        // Shape rules taken from the live 201 (functions/src/publicApi.ts) rather
+        // than invented:
+        //  - documentNumber is `CN-<original document number>` and NEVER encodes
+        //    the R-type (creditNoteService.ts: `CN-${originalDocNumber}`). An
+        //    earlier fixture emitted `R1-DEMO-001`, teaching an agent to parse a
+        //    field that carries no R-type live.
+        //  - fullCredit is hardcoded `true` in the live body: `false` never
+        //    reaches a 201, it is refused with 400 PARTIAL_CREDIT_NOT_IMPLEMENTED.
+        //    Echoing the input would contradict this tool's own description.
+        // Documented divergence: demo mode never throws (the seam's contract), so
+        // `fullCredit: false` returns the same simulated draft instead of the live
+        // 400. Pinned in src/__tests__/demo-mode.test.ts.
+        const original = findOrStub(demoInvoices, invoiceId);
+        const originalNumber = typeof original.documentNumber === "string" ? original.documentNumber : "DEMO-001";
         return {
             success: true,
             creditNote: {
                 id: demoId("demo_cn"),
-                documentNumber: "R4-DEMO-001",
+                documentNumber: `CN-${originalNumber}`,
                 originalInvoiceId: invoiceId,
                 reason: data.reason,
-                fullCredit: data.fullCredit ?? true,
+                fullCredit: true,
+                status: "draft",
+                rectificationMethod: "I",
+                totalCredited: 1210.0,
             },
             ...FISCAL_STAMP,
         };
@@ -237,23 +257,49 @@ export class DemoFrihetClient {
     // ---------------------------------------------------------------- Intelligence
     async getBusinessContext() {
         return {
-            businessName: "Demo Studio SL",
-            fiscalRegime: "autonomo",
-            currency: "EUR",
-            country: "ES",
-            metrics: { openInvoices: 4, overdueInvoices: 1, totalClients: demoClients.length, totalProducts: demoProducts.length },
+            business: {
+                name: "Demo Studio SL",
+                fiscalZone: "IVA",
+                currency: "EUR",
+                language: "es",
+                country: "ES",
+            },
+            defaults: { taxRate: 21, irpfRate: 15, dueDays: 30, currency: "EUR" },
+            plan: {
+                name: "free",
+                invoices: { used: 5, limit: 999 },
+                expenses: { used: demoExpenses.length, limit: 5 },
+                aiMessages: { used: 2, limit: 30 },
+            },
+            series: [{ id: "default", prefix: "F", current: 5, year: 2026 }],
+            recentActivity: {
+                lastInvoice: { number: "F-2026-005", date: "2026-07-18", client: "Acme Studio" },
+                lastExpense: { date: "2026-07-17", vendor: "Demo Supplies", amount: 405.6 },
+                overdueCount: 1,
+                overdueAmount: 640,
+                unpaidCount: 2,
+            },
+            topClients: [{ name: "Acme Studio", totalRevenue: 2200, invoiceCount: 2 }],
+            currentMonth: {
+                revenue: 3960.4,
+                expenses: 405.6,
+                profit: 3554.8,
+                invoiceCount: 5,
+                expenseCount: demoExpenses.length,
+            },
             ...READ_STAMP,
         };
     }
     async getMonthlySummary(month) {
         return {
-            month: month ?? "2026-07",
-            revenue: 3960.4,
-            expenses: 405.6,
-            net: 3554.8,
-            invoiceCount: 5,
-            expenseCount: demoExpenses.length,
-            currency: "EUR",
+            period: month ?? "2026-07",
+            revenue: { total: 3960.4, taxBase: 3273.06, tax: 687.34, irpf: 0 },
+            expenses: { total: 405.6, deductible: 405.6, tax: 70.4 },
+            profit: { gross: 3554.8, net: 2937.86 },
+            invoices: { created: 5, sent: 1, paid: 3, overdue: 1 },
+            topClients: [{ name: "Acme Studio", totalRevenue: 2200, invoiceCount: 2 }],
+            byCategory: { supplies: 405.6 },
+            taxLiability: { vatPayable: 616.94, irpfRetained: 0, estimatedModel303: 616.94 },
             ...READ_STAMP,
         };
     }

package/dist/openai-profile.d.ts

@@ -63,6 +63,14 @@ export declare const OPENAI_ALLOWED_TOOL_COUNT: number;
  * correct while the live tools/list still materialises 53 + 3 = 56 tools.
  */
 export declare const OPENAI_REVIEWED_TOOL_ALLOWLIST: ReadonlySet<string>;
+/**
+ * Apply the exact profile composition used by the ChatGPT review Worker.
+ *
+ * Keep this helper as the single source for the security-sensitive ordering:
+ * grouped exposure first (with the frozen allow-list), OpenAI profile second.
+ * Tool registration happens afterwards through registerAllTools().
+ */
+export declare function applyOpenAIReviewProfiles(server: any): void;
 /** Number of resources excluded in OpenAI mode (for logging). */
 export declare const OPENAI_EXCLUDED_RESOURCE_COUNT: number;
 //# sourceMappingURL=openai-profile.d.ts.map

package/dist/openai-profile.js

@@ -20,9 +20,10 @@
  *
  * @see https://developers.openai.com/apps-sdk/app-submission-guidelines
  */
-import { z } from "zod";
+import { z } from "zod/v4";
 import { MCP_RESOURCE_COUNT } from "./resources/register-all.js";
 import { SENSITIVE_FIELD_NAMES, deepRedact, redactText } from "./redaction.js";
+import { applyToolExposureProfile } from "./tool-exposure.js";
 const PROFILE = {
     // -- OpenAI-reviewed core surface ----------------------------------------
     //
@@ -164,6 +165,17 @@ const PROFILE = {
     // Government IDs (NIF/CIF/VAT), auth credentials, and unsolicited
     // email address collection removed from input schemas.
     stripInputFields: {
+        // Projection is useful to direct MCP clients, but unnecessary in the
+        // reviewed ChatGPT surface. OpenAI's scanner treats a comma-delimited
+        // free-form string as ambiguous (array vs JSON vs CSV), so omit it and
+        // return the full, redacted record shape instead.
+        list_invoices: ["fields"],
+        search_invoices: ["fields"],
+        list_expenses: ["fields"],
+        list_clients: ["fields"],
+        list_products: ["fields"],
+        list_quotes: ["fields"],
+        list_vendors: ["fields"],
         create_client: ["taxId"], // NIF/CIF/VAT — government-issued identifier
         update_client: ["taxId"],
         create_vendor: ["taxId"],
@@ -202,11 +214,7 @@ const PROFILE = {
  * sensitive field anywhere is returned unchanged (identity).
  */
 function stripSensitiveOutputSchema(schema, fields) {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const def = schema?._def;
-    const typeName = def?.typeName;
-    if (typeName === "ZodObject") {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if (schema instanceof z.ZodObject) {
         const shape = schema.shape;
         const newShape = {};
         let changed = false;
@@ -222,28 +230,42 @@ function stripSensitiveOutputSchema(schema, fields) {
         }
         if (!changed)
             return schema;
-        let rebuilt = z.object(newShape);
-        if (typeof def.description === "string")
-            rebuilt = rebuilt.describe(def.description);
+        const base = z.object(newShape);
+        // Zod v4 stores passthrough/strict behavior in `catchall`. Preserve it so
+        // redacting one declared field never changes validation of unrelated API
+        // fields. The previous implementation inspected Zod v3's `_def.typeName`,
+        // which is absent in v4 and silently returned the original schema.
+        const catchall = schema._def.catchall;
+        let rebuilt;
+        if (catchall instanceof z.ZodUnknown)
+            rebuilt = base.passthrough();
+        else if (catchall instanceof z.ZodNever)
+            rebuilt = base.strict();
+        else if (catchall)
+            rebuilt = base.catchall(catchall);
+        else
+            rebuilt = base;
+        if (typeof schema.description === "string")
+            rebuilt = rebuilt.describe(schema.description);
         return rebuilt;
     }
-    if (typeName === "ZodArray") {
-        const inner = def.type;
+    if (schema instanceof z.ZodArray) {
+        const inner = schema.element;
         const stripped = stripSensitiveOutputSchema(inner, fields);
         if (stripped === inner)
             return schema;
         let rebuilt = z.array(stripped);
-        if (typeof def.description === "string")
-            rebuilt = rebuilt.describe(def.description);
+        if (typeof schema.description === "string")
+            rebuilt = rebuilt.describe(schema.description);
         return rebuilt;
     }
-    if (typeName === "ZodOptional") {
-        const inner = def.innerType;
+    if (schema instanceof z.ZodOptional) {
+        const inner = schema.unwrap();
         const stripped = stripSensitiveOutputSchema(inner, fields);
         return stripped === inner ? schema : z.optional(stripped);
     }
-    if (typeName === "ZodNullable") {
-        const inner = def.innerType;
+    if (schema instanceof z.ZodNullable) {
+        const inner = schema.unwrap();
         const stripped = stripSensitiveOutputSchema(inner, fields);
         return stripped === inner ? schema : z.nullable(stripped);
     }
@@ -432,6 +454,20 @@ export const OPENAI_ALLOWED_TOOL_COUNT = PROFILE.includeTools.size;
  * correct while the live tools/list still materialises 53 + 3 = 56 tools.
  */
 export const OPENAI_REVIEWED_TOOL_ALLOWLIST = PROFILE.includeTools;
+/**
+ * Apply the exact profile composition used by the ChatGPT review Worker.
+ *
+ * Keep this helper as the single source for the security-sensitive ordering:
+ * grouped exposure first (with the frozen allow-list), OpenAI profile second.
+ * Tool registration happens afterwards through registerAllTools().
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyOpenAIReviewProfiles(server) {
+    applyToolExposureProfile(server, {
+        allowlist: OPENAI_REVIEWED_TOOL_ALLOWLIST,
+    });
+    applyOpenAIProfile(server);
+}
 /** Number of resources excluded in OpenAI mode (for logging). */
 export const OPENAI_EXCLUDED_RESOURCE_COUNT = PROFILE.excludeResources
     ? MCP_RESOURCE_COUNT

package/dist/openai-review-contract.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Fail-closed contract capture for the ChatGPT-reviewed MCP surface.
+ *
+ * This intentionally uses a real McpServer, real Client, in-memory MCP
+ * transport, and the production registration path. It therefore freezes what
+ * tools/list serializes, not an approximation of registration config objects.
+ */
+export declare const OPENAI_REVIEW_CONTRACT_VERSION = 1;
+export declare const OPENAI_REVIEW_BUSINESS_TOOL_COUNT = 53;
+export declare const OPENAI_REVIEW_DISCOVERY_TOOLS: readonly ["describe_tool", "list_tool_groups", "search_tools"];
+export declare const OPENAI_REVIEW_TOTAL_TOOL_COUNT = 56;
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface OpenAIReviewTool extends Record<string, JsonValue> {
+    name: string;
+}
+export interface OpenAIReviewContract {
+    contractVersion: number;
+    tools: OpenAIReviewTool[];
+    prompts: JsonValue[];
+    resources: JsonValue[];
+    oauth: Record<string, JsonValue>;
+}
+export interface OpenAIReviewMcpSurface {
+    tools: OpenAIReviewTool[];
+    prompts: JsonValue[];
+    resources: JsonValue[];
+}
+/** Capture the exact OpenAI grouped surface over a real tools/list request. */
+export declare function captureOpenAIReviewMcpSurface(): Promise<OpenAIReviewMcpSurface>;
+export declare function buildOpenAIReviewContract(surface: OpenAIReviewMcpSurface, oauth: Record<string, JsonValue>): OpenAIReviewContract;
+/** Canonicalize object-key and tools/list order only; arrays remain semantic. */
+export declare function canonicalizeOpenAIReviewContract(contract: OpenAIReviewContract): OpenAIReviewContract;
+export declare function serializeOpenAIReviewContract(contract: OpenAIReviewContract): string;
+/**
+ * Fail closed on any semantic drift from the reviewed descriptor snapshot.
+ */
+export declare function assertOpenAIReviewContract(actual: OpenAIReviewContract, expected: OpenAIReviewContract): void;
+//# sourceMappingURL=openai-review-contract.d.ts.map

package/dist/openai-review-contract.js

@@ -0,0 +1,245 @@
+/**
+ * Fail-closed contract capture for the ChatGPT-reviewed MCP surface.
+ *
+ * This intentionally uses a real McpServer, real Client, in-memory MCP
+ * transport, and the production registration path. It therefore freezes what
+ * tools/list serializes, not an approximation of registration config objects.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { applyOpenAIReviewProfiles, OPENAI_REVIEWED_TOOL_ALLOWLIST, } from "./openai-profile.js";
+import { SENSITIVE_FIELD_NAMES } from "./redaction.js";
+import { registerAllPrompts } from "./prompts/register-all.js";
+import { registerAllResources } from "./resources/register-all.js";
+import { registerAllTools } from "./tools/register-all.js";
+export const OPENAI_REVIEW_CONTRACT_VERSION = 1;
+export const OPENAI_REVIEW_BUSINESS_TOOL_COUNT = 53;
+export const OPENAI_REVIEW_DISCOVERY_TOOLS = [
+    "describe_tool",
+    "list_tool_groups",
+    "search_tools",
+];
+export const OPENAI_REVIEW_TOTAL_TOOL_COUNT = 56;
+function makeRegistrationClient() {
+    return new Proxy({}, {
+        get: () => async () => ({ data: [], total: 0, limit: 0, offset: 0 }),
+    });
+}
+function isMethodNotFound(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === -32601);
+}
+async function listPromptsOrEmpty(client) {
+    const prompts = [];
+    let cursor;
+    try {
+        do {
+            const page = await client.listPrompts(cursor ? { cursor } : undefined);
+            prompts.push(...page.prompts);
+            cursor = page.nextCursor;
+        } while (cursor);
+    }
+    catch (error) {
+        if (isMethodNotFound(error))
+            return [];
+        throw error;
+    }
+    return prompts;
+}
+async function listResourcesOrEmpty(client) {
+    const resources = [];
+    let cursor;
+    try {
+        do {
+            const page = await client.listResources(cursor ? { cursor } : undefined);
+            resources.push(...page.resources);
+            cursor = page.nextCursor;
+        } while (cursor);
+    }
+    catch (error) {
+        if (isMethodNotFound(error))
+            return [];
+        throw error;
+    }
+    return resources;
+}
+/** Capture the exact OpenAI grouped surface over a real tools/list request. */
+export async function captureOpenAIReviewMcpSurface() {
+    const server = new McpServer({
+        name: "frihet-openai-review-freeze",
+        version: "1.0.0",
+    });
+    applyOpenAIReviewProfiles(server);
+    registerAllTools(server, makeRegistrationClient());
+    registerAllResources(server);
+    registerAllPrompts(server);
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "frihet-openai-review-freeze-client", version: "1.0.0" }, { capabilities: {} });
+    try {
+        await Promise.all([
+            server.connect(serverTransport),
+            client.connect(clientTransport),
+        ]);
+        const tools = [];
+        let cursor;
+        do {
+            const page = await client.listTools(cursor ? { cursor } : undefined);
+            tools.push(...page.tools);
+            cursor = page.nextCursor;
+        } while (cursor);
+        const [prompts, resources] = await Promise.all([
+            listPromptsOrEmpty(client),
+            listResourcesOrEmpty(client),
+        ]);
+        return { tools, prompts, resources };
+    }
+    finally {
+        await Promise.allSettled([client.close(), server.close()]);
+    }
+}
+export function buildOpenAIReviewContract(surface, oauth) {
+    return {
+        contractVersion: OPENAI_REVIEW_CONTRACT_VERSION,
+        tools: surface.tools,
+        prompts: surface.prompts,
+        resources: surface.resources,
+        oauth,
+    };
+}
+function canonicalizeValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeValue);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, child]) => [key, canonicalizeValue(child)]));
+    }
+    return value;
+}
+/** Canonicalize object-key and tools/list order only; arrays remain semantic. */
+export function canonicalizeOpenAIReviewContract(contract) {
+    const canonical = canonicalizeValue(contract);
+    canonical.tools.sort((left, right) => left.name.localeCompare(right.name));
+    return canonical;
+}
+export function serializeOpenAIReviewContract(contract) {
+    return `${JSON.stringify(canonicalizeOpenAIReviewContract(contract), null, 2)}\n`;
+}
+function schemaSensitivePaths(tools) {
+    const sensitive = new Set(SENSITIVE_FIELD_NAMES.map((field) => field.toLowerCase()));
+    // `documentNumber` is an invoice sequence identifier on these two tools,
+    // not the guest/customer identity-document field covered by the shared
+    // redaction policy. Keep the exception exact so any future occurrence is
+    // still rejected by default.
+    const nonSensitiveBusinessPaths = new Set([
+        "create_invoice.inputSchema.properties.documentNumber",
+        "update_invoice.inputSchema.properties.documentNumber",
+    ]);
+    const paths = new Set();
+    const visit = (value, path) => {
+        if (value === undefined || value === null || typeof value !== "object")
+            return;
+        if (Array.isArray(value)) {
+            value.forEach((child, index) => visit(child, `${path}[${index}]`));
+            return;
+        }
+        for (const [key, child] of Object.entries(value)) {
+            const childPath = `${path}.${key}`;
+            if (sensitive.has(key.toLowerCase()) &&
+                !nonSensitiveBusinessPaths.has(childPath)) {
+                paths.add(childPath);
+            }
+            visit(child, childPath);
+        }
+    };
+    for (const tool of tools) {
+        visit(tool.inputSchema, `${tool.name}.inputSchema`);
+        visit(tool.outputSchema, `${tool.name}.outputSchema`);
+    }
+    return paths;
+}
+function firstDifference(expected, actual, path = "$") {
+    if (Object.is(expected, actual))
+        return undefined;
+    if (Array.isArray(expected) || Array.isArray(actual)) {
+        if (!Array.isArray(expected) || !Array.isArray(actual)) {
+            return { path, expected, actual };
+        }
+        if (expected.length !== actual.length)
+            return { path: `${path}.length`, expected: expected.length, actual: actual.length };
+        for (let index = 0; index < expected.length; index += 1) {
+            const difference = firstDifference(expected[index], actual[index], `${path}[${index}]`);
+            if (difference)
+                return difference;
+        }
+        return undefined;
+    }
+    if (expected !== null &&
+        actual !== null &&
+        typeof expected === "object" &&
+        typeof actual === "object") {
+        const keys = [...new Set([...Object.keys(expected), ...Object.keys(actual)])].sort();
+        for (const key of keys) {
+            const difference = firstDifference(expected[key], actual[key], `${path}.${key}`);
+            if (difference)
+                return difference;
+        }
+        return undefined;
+    }
+    return { path, expected, actual };
+}
+function preview(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        return "<missing>";
+    return serialized.length > 180 ? `${serialized.slice(0, 177)}...` : serialized;
+}
+/**
+ * Fail closed on any semantic drift from the reviewed descriptor snapshot.
+ */
+export function assertOpenAIReviewContract(actual, expected) {
+    if (actual.contractVersion !== OPENAI_REVIEW_CONTRACT_VERSION) {
+        throw new Error(`Unsupported OpenAI review contract version: ${actual.contractVersion}`);
+    }
+    if (actual.tools.length !== OPENAI_REVIEW_TOTAL_TOOL_COUNT) {
+        throw new Error(`OpenAI review surface must expose exactly ${OPENAI_REVIEW_TOTAL_TOOL_COUNT} tools; got ${actual.tools.length}`);
+    }
+    const names = actual.tools.map((tool) => tool.name);
+    if (new Set(names).size !== names.length) {
+        throw new Error("OpenAI review surface contains duplicate tool names");
+    }
+    const discovery = new Set(OPENAI_REVIEW_DISCOVERY_TOOLS);
+    const businessNames = names.filter((name) => !discovery.has(name));
+    if (businessNames.length !== OPENAI_REVIEW_BUSINESS_TOOL_COUNT) {
+        throw new Error(`OpenAI review surface must expose exactly ${OPENAI_REVIEW_BUSINESS_TOOL_COUNT} business tools; got ${businessNames.length}`);
+    }
+    const missingDiscovery = OPENAI_REVIEW_DISCOVERY_TOOLS.filter((name) => !names.includes(name));
+    if (missingDiscovery.length > 0) {
+        throw new Error(`Missing discovery tools: ${missingDiscovery.join(", ")}`);
+    }
+    const leaks = businessNames.filter((name) => !OPENAI_REVIEWED_TOOL_ALLOWLIST.has(name));
+    if (leaks.length > 0) {
+        throw new Error(`Non-reviewed tools leaked into OpenAI surface: ${leaks.join(", ")}`);
+    }
+    if (actual.prompts.length !== 0 || actual.resources.length !== 0) {
+        throw new Error(`OpenAI review surface must expose 0 prompts and 0 resources; got ${actual.prompts.length} prompts and ${actual.resources.length} resources`);
+    }
+    const sensitivePaths = [...schemaSensitivePaths(actual.tools)];
+    if (sensitivePaths.length > 0) {
+        throw new Error(`Sensitive schema fields are forbidden in the OpenAI review surface: ${sensitivePaths.join(", ")}`);
+    }
+    const expectedSensitivePaths = [...schemaSensitivePaths(expected.tools)];
+    if (expectedSensitivePaths.length > 0) {
+        throw new Error(`Frozen OpenAI review snapshot contains sensitive schema fields: ${expectedSensitivePaths.join(", ")}`);
+    }
+    const canonicalExpected = canonicalizeOpenAIReviewContract(expected);
+    const canonicalActual = canonicalizeOpenAIReviewContract(actual);
+    const difference = firstDifference(canonicalExpected, canonicalActual);
+    if (difference) {
+        throw new Error(`OpenAI review descriptor drift at ${difference.path}: expected ${preview(difference.expected)}, got ${preview(difference.actual)}`);
+    }
+}
+//# sourceMappingURL=openai-review-contract.js.map

package/dist/openai-review-oauth.d.ts

@@ -0,0 +1,51 @@
+/**
+ * OAuth contract inputs shared by the real Worker and the OpenAI descriptor
+ * freeze gate. Values in this module are public protocol metadata, not secrets.
+ */
+export declare const OPENAI_REVIEW_ORIGIN = "https://openai-mcp.frihet.io";
+/**
+ * Byte-compatible extraction of the options previously inlined in the Worker.
+ * index.ts spreads this object into the real OAuthProvider constructor.
+ */
+export declare const OAUTH_PROVIDER_REVIEW_OPTIONS: {
+    apiRoute: string;
+    authorizeEndpoint: string;
+    tokenEndpoint: string;
+    clientRegistrationEndpoint: string;
+    scopesSupported: string[];
+    accessTokenTTL: number;
+    refreshTokenTTL: number;
+    allowPlainPKCE: false;
+};
+/**
+ * Materialize the public metadata generated by workers-oauth-provider 0.3.0
+ * from the same options used by the Worker. The dependency version is pinned
+ * separately in the canonical descriptor snapshot.
+ */
+export declare function buildOpenAIReviewOAuthContract(origin?: string): {
+    authorizationServer: {
+        issuer: string;
+        authorization_endpoint: string;
+        token_endpoint: string;
+        registration_endpoint: string;
+        scopes_supported: string[];
+        response_types_supported: string[];
+        response_modes_supported: string[];
+        grant_types_supported: string[];
+        token_endpoint_auth_methods_supported: string[];
+        revocation_endpoint: string;
+        code_challenge_methods_supported: string[];
+        client_id_metadata_document_supported: boolean;
+    };
+    protectedResource: {
+        resource: string;
+        authorization_servers: string[];
+        scopes_supported: string[];
+        bearer_methods_supported: string[];
+    };
+    wwwAuthenticate: {
+        resourceMetadataUrl: string;
+        missingTokenHeader: string;
+    };
+};
+//# sourceMappingURL=openai-review-oauth.d.ts.map

package/dist/openai-review-oauth.js

@@ -0,0 +1,66 @@
+/**
+ * OAuth contract inputs shared by the real Worker and the OpenAI descriptor
+ * freeze gate. Values in this module are public protocol metadata, not secrets.
+ */
+export const OPENAI_REVIEW_ORIGIN = "https://openai-mcp.frihet.io";
+/**
+ * Byte-compatible extraction of the options previously inlined in the Worker.
+ * index.ts spreads this object into the real OAuthProvider constructor.
+ */
+export const OAUTH_PROVIDER_REVIEW_OPTIONS = {
+    apiRoute: "/mcp",
+    authorizeEndpoint: "/authorize",
+    tokenEndpoint: "/token",
+    clientRegistrationEndpoint: "/register",
+    scopesSupported: ["read", "write"],
+    accessTokenTTL: 3600,
+    refreshTokenTTL: 2592000,
+    allowPlainPKCE: false,
+};
+function endpoint(origin, path) {
+    return new URL(path, new URL(origin).origin).toString();
+}
+/**
+ * Materialize the public metadata generated by workers-oauth-provider 0.3.0
+ * from the same options used by the Worker. The dependency version is pinned
+ * separately in the canonical descriptor snapshot.
+ */
+export function buildOpenAIReviewOAuthContract(origin = OPENAI_REVIEW_ORIGIN) {
+    const normalizedOrigin = new URL(origin).origin;
+    const authorizationEndpoint = endpoint(normalizedOrigin, OAUTH_PROVIDER_REVIEW_OPTIONS.authorizeEndpoint);
+    const tokenEndpoint = endpoint(normalizedOrigin, OAUTH_PROVIDER_REVIEW_OPTIONS.tokenEndpoint);
+    const registrationEndpoint = endpoint(normalizedOrigin, OAUTH_PROVIDER_REVIEW_OPTIONS.clientRegistrationEndpoint);
+    const resourceMetadataUrl = endpoint(normalizedOrigin, "/.well-known/oauth-protected-resource");
+    return {
+        authorizationServer: {
+            issuer: normalizedOrigin,
+            authorization_endpoint: authorizationEndpoint,
+            token_endpoint: tokenEndpoint,
+            registration_endpoint: registrationEndpoint,
+            scopes_supported: [...OAUTH_PROVIDER_REVIEW_OPTIONS.scopesSupported],
+            response_types_supported: ["code"],
+            response_modes_supported: ["query"],
+            grant_types_supported: ["authorization_code", "refresh_token"],
+            token_endpoint_auth_methods_supported: [
+                "client_secret_basic",
+                "client_secret_post",
+                "none",
+            ],
+            revocation_endpoint: tokenEndpoint,
+            code_challenge_methods_supported: ["S256"],
+            client_id_metadata_document_supported: false,
+        },
+        protectedResource: {
+            resource: normalizedOrigin,
+            authorization_servers: [normalizedOrigin],
+            scopes_supported: [...OAUTH_PROVIDER_REVIEW_OPTIONS.scopesSupported],
+            bearer_methods_supported: ["header"],
+        },
+        wwwAuthenticate: {
+            resourceMetadataUrl,
+            missingTokenHeader: `Bearer realm="OAuth", resource_metadata="${resourceMetadataUrl}", ` +
+                'error="invalid_token", error_description="Missing or invalid access token"',
+        },
+    };
+}
+//# sourceMappingURL=openai-review-oauth.js.map

package/dist/tools/intelligence.js

@@ -10,7 +10,98 @@
  * - duplicate_invoice: Clone an invoice for a new period
  */
 import { z } from "zod/v4";
-import { withToolLogging, formatRecord, getContent, mutateContent, openObjectOutput, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, } from "./shared.js";
+import { withToolLogging, formatRecord, getContent, mutateContent, invoiceItemOutput, openObjectOutput, READ_ONLY_ANNOTATIONS, CREATE_ANNOTATIONS, } from "./shared.js";
+const usageLimitOutput = z.union([z.number(), z.literal("unlimited")]);
+const businessContextOutput = z.object({
+    business: z.object({
+        name: z.string(),
+        taxId: z.string().optional(),
+        fiscalZone: z.string(),
+        currency: z.string(),
+        language: z.string(),
+        country: z.string(),
+    }).passthrough(),
+    defaults: z.object({
+        taxRate: z.number(),
+        irpfRate: z.number(),
+        dueDays: z.number(),
+        currency: z.string(),
+    }).passthrough(),
+    plan: z.object({
+        name: z.string(),
+        invoices: z.object({ used: z.number(), limit: usageLimitOutput }),
+        expenses: z.object({ used: z.number(), limit: usageLimitOutput }),
+        aiMessages: z.object({ used: z.number(), limit: usageLimitOutput }),
+    }).passthrough(),
+    series: z.array(z.object({
+        id: z.string().optional(),
+        prefix: z.string().optional(),
+        current: z.number().optional(),
+        year: z.number().optional(),
+    }).passthrough()),
+    recentActivity: z.object({
+        lastInvoice: z.object({
+            number: z.string().optional(),
+            date: z.string().optional(),
+            client: z.string().optional(),
+        }).passthrough().nullable(),
+        lastExpense: z.object({
+            date: z.string().optional(),
+            vendor: z.string().optional(),
+            amount: z.number(),
+        }).passthrough().nullable(),
+        overdueCount: z.number(),
+        overdueAmount: z.number(),
+        unpaidCount: z.number(),
+    }).passthrough(),
+    topClients: z.array(z.object({
+        name: z.string(),
+        totalRevenue: z.number(),
+        invoiceCount: z.number(),
+    }).passthrough()),
+    currentMonth: z.object({
+        revenue: z.number(),
+        expenses: z.number(),
+        profit: z.number(),
+        invoiceCount: z.number(),
+        expenseCount: z.number(),
+    }).passthrough(),
+}).passthrough().describe("Business context snapshot: workspace profile, fiscal setup, plan usage, recent activity and current-month performance");
+const monthlySummaryOutput = z.object({
+    period: z.string(),
+    revenue: z.object({
+        total: z.number(),
+        taxBase: z.number(),
+        tax: z.number(),
+        irpf: z.number(),
+    }).passthrough(),
+    expenses: z.object({
+        total: z.number(),
+        deductible: z.number(),
+        tax: z.number(),
+    }).passthrough(),
+    profit: z.object({
+        gross: z.number(),
+        net: z.number(),
+    }).passthrough(),
+    invoices: z.object({
+        created: z.number(),
+        sent: z.number(),
+        paid: z.number(),
+        overdue: z.number(),
+    }).passthrough(),
+    topClients: z.array(z.object({
+        name: z.string(),
+        totalRevenue: z.number(),
+        invoiceCount: z.number(),
+    }).passthrough()),
+    byCategory: z.record(z.string(), z.number()),
+    taxLiability: z.object({
+        vatPayable: z.number(),
+        irpfRetained: z.number(),
+        estimatedModel303: z.number(),
+    }).passthrough(),
+}).passthrough().describe("Monthly financial summary with revenue, expenses, profit, invoice status, top clients and estimated tax liability");
 export function registerIntelligenceTools(server, client) {
     // -- get_business_context --
     server.registerTool("get_business_context", {
@@ -22,7 +113,7 @@ export function registerIntelligenceTools(server, client) {
             "principales clientes y resumen del mes actual. Llama a esto PRIMERO en cualquier sesion.",
         annotations: READ_ONLY_ANNOTATIONS,
         inputSchema: {},
-        outputSchema: openObjectOutput("Business context snapshot: workspace profile, fiscal setup, recent activity / Contexto de negocio: perfil, configuración fiscal y actividad reciente"),
+        outputSchema: businessContextOutput,
     }, async () => withToolLogging("get_business_context", async () => {
         const result = await client.getBusinessContext();
         return {
@@ -46,7 +137,7 @@ export function registerIntelligenceTools(server, client) {
                 .describe("Month in YYYY-MM format (defaults to current month). Example: '2026-03' " +
                 "/ Mes en formato YYYY-MM (por defecto el mes actual)"),
         },
-        outputSchema: openObjectOutput("Monthly P&L summary: revenue, expenses, profit, tax liability, invoice stats / Resumen mensual: ingresos, gastos, beneficio, impuestos"),
+        outputSchema: monthlySummaryOutput,
     }, async ({ month }) => withToolLogging("get_monthly_summary", async () => {
         const result = await client.getMonthlySummary(month);
         const label = month ? `Monthly Summary (${month})` : "Monthly Summary (current month)";
@@ -101,7 +192,7 @@ export function registerIntelligenceTools(server, client) {
                 .optional()
                 .describe("Due date for the new invoice (YYYY-MM-DD) / Fecha de vencimiento de la nueva factura"),
         },
-        outputSchema: openObjectOutput("The newly created draft invoice, cloned from the original / La nueva factura borrador, clonada de la original"),
+        outputSchema: invoiceItemOutput.describe("The newly created draft invoice, cloned from the original / La nueva factura borrador, clonada de la original"),
     }, async ({ id, newIssueDate, newDueDate }) => withToolLogging("duplicate_invoice", async () => {
         // 1. Fetch the original invoice (returns the FULL raw stored document —
         //    payments, verifactu, eInvoice, operationType, createdBy, etc.)

package/dist/tools/invoices.js

@@ -386,13 +386,14 @@ export function registerInvoiceTools(server, client) {
     // -- create_credit_note --
     server.registerTool("create_credit_note", {
         title: "Create Credit Note",
-        description: "Create a credit note (factura rectificativa) for an existing invoice. " +
-            "This reverses all or part of an invoice for compliance. " +
-            "Spanish market: generates VeriFactu-compliant R1-R5 rectificativa. " +
-            "Other markets: standard credit note with negative amounts. " +
-            "/ Crea una factura rectificativa para una factura existente. " +
-            "Mercado espanol: genera rectificativa R1-R5 conforme a VeriFactu. " +
-            "Otros mercados: nota de credito estandar con importes negativos.",
+        description: "Create a full credit note (factura rectificativa) for an existing invoice, as a DRAFT. " +
+            "It does NOT issue: the draft carries no fiscal number, no hash and is not sent to VeriFactu — " +
+            "issue it from the app when you are ready. Always rectifies by differences (TipoRectificativa = I). " +
+            "Spanish market: R-type is derived from `reason` (error -> R1, anything else -> R4). " +
+            "Partial credits are not supported. Requires the `pro` plan. " +
+            "/ Crea una factura rectificativa completa como BORRADOR. No emite: sin numero fiscal, sin hash, " +
+            "sin envio a VeriFactu. Siempre rectifica por diferencias (tipo I). El tipo R se deriva de `reason` " +
+            "(error -> R1, resto -> R4). No admite abonos parciales. Requiere plan `pro`.",
         annotations: CREATE_ANNOTATIONS,
         inputSchema: {
             invoiceId: z
@@ -409,21 +410,33 @@ export function registerInvoiceTools(server, client) {
             fullCredit: z
                 .boolean()
                 .optional()
-                .describe("true = full credit (tipo S, sustitucion), false = partial (tipo I, diferencias). Default: true " +
-                "/ true = abono total (tipo S), false = parcial (tipo I). Por defecto: true"),
+                .describe("Must be true (the default). `false` is rejected with 400 PARTIAL_CREDIT_NOT_IMPLEMENTED — " +
+                "the API has no line-level or partial credit. It does NOT select the rectification method: " +
+                "that is always I (por diferencias). " +
+                "/ Debe ser true (por defecto). `false` devuelve 400 PARTIAL_CREDIT_NOT_IMPLEMENTED. " +
+                "No elige el metodo de rectificacion: siempre es I (por diferencias)."),
             issueDate: z
                 .string()
                 .optional()
                 .describe("ISO date for the credit note (YYYY-MM-DD). Defaults to today. / Fecha de emision (YYYY-MM-DD). Por defecto hoy."),
+            idempotencyKey: z
+                .string()
+                .max(64)
+                .optional()
+                .describe("Optional idempotency key, max 64 chars. One is generated per call when omitted or blank; " +
+                "pass your own to make a retry replay the stored result instead of creating a second draft. " +
+                "Reusing a key with a different body returns 409 IDEMPOTENCY_KEY_REUSED — reconcile, do not " +
+                "retry with a new key. " +
+                "/ Clave de idempotencia opcional (max 64). Se genera una por llamada si se omite o va vacia."),
         },
         outputSchema: creditNoteResultOutput,
-    }, async ({ invoiceId, reason, reasonDescription, fullCredit, issueDate }) => withToolLogging("create_credit_note", async () => {
+    }, async ({ invoiceId, reason, reasonDescription, fullCredit, issueDate, idempotencyKey }) => withToolLogging("create_credit_note", async () => {
         const result = await client.createCreditNote(invoiceId, {
             reason,
             reasonDescription,
             fullCredit: fullCredit ?? true,
             issueDate,
-        });
+        }, idempotencyKey);
         const hints = enrichResponse("invoices", "create", result);
         return {
             content: [mutateContent(formatRecord("Credit note created", result))],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frihet/mcp-server",
-  "version": "1.16.4",
+  "version": "1.16.6",
   "description": "AI-native MCP server for Frihet ERP — 157 tools: invoicing, expenses, CRM, banking, POS + ES/EU fiscal compliance (VeriFactu, TicketBAI, Facturae). Zero-install at mcp.frihet.io. Works with Claude, ChatGPT, Cursor, Windsurf, Cline & any MCP client.",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,14 +9,19 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node --test dist/__tests__/openai-profile.test.js dist/__tests__/tool-exposure.test.js dist/__tests__/einvoice-tools.test.js dist/__tests__/einvoice-day4-tools.test.js dist/__tests__/stay-tools.test.js dist/__tests__/pos-tools.test.js dist/__tests__/kitchen-tools.test.js dist/__tests__/banking-tools.test.js dist/__tests__/banking-client-contract.test.js dist/__tests__/pagination-cursor-param.test.js dist/__tests__/fiscal-tools.test.js dist/__tests__/time-tools.test.js dist/__tests__/recurring-tools.test.js dist/__tests__/team-tools.test.js dist/__tests__/d4b-hr-payroll-onboarding-tools.test.js dist/__tests__/audit-server-version.test.js dist/__tests__/openai-grouped-compose.test.js dist/__tests__/contract.test.js dist/__tests__/observability-redaction.test.js dist/__tests__/intelligence-duplicate-invoice.test.js dist/__tests__/get-envelope-unwrap-regression.test.js dist/__tests__/mutation-unwrap-and-schema-regression.test.js dist/__tests__/schema-envelope-guard.test.js dist/__tests__/demo-mode.test.js",
+    "test": "npm run build && node --test dist/__tests__/openai-profile.test.js dist/__tests__/tool-exposure.test.js dist/__tests__/einvoice-tools.test.js dist/__tests__/einvoice-day4-tools.test.js dist/__tests__/stay-tools.test.js dist/__tests__/pos-tools.test.js dist/__tests__/kitchen-tools.test.js dist/__tests__/banking-tools.test.js dist/__tests__/banking-client-contract.test.js dist/__tests__/pagination-cursor-param.test.js dist/__tests__/fiscal-tools.test.js dist/__tests__/time-tools.test.js dist/__tests__/recurring-tools.test.js dist/__tests__/team-tools.test.js dist/__tests__/d4b-hr-payroll-onboarding-tools.test.js dist/__tests__/audit-server-version.test.js dist/__tests__/openai-grouped-compose.test.js dist/__tests__/openai-review-descriptor.test.js dist/__tests__/contract.test.js dist/__tests__/observability-redaction.test.js dist/__tests__/intelligence-duplicate-invoice.test.js dist/__tests__/get-envelope-unwrap-regression.test.js dist/__tests__/mutation-unwrap-and-schema-regression.test.js dist/__tests__/schema-envelope-guard.test.js dist/__tests__/demo-mode.test.js dist/__tests__/idempotency-key-contract.test.js dist/__tests__/source-header-contract.test.js",
+    "test:openai-review-descriptor": "npm run build && node --test dist/__tests__/openai-review-descriptor.test.js",
+    "gate:openai-review-descriptor": "npm run build && node scripts/check-openai-review-descriptor.mjs",
     "start": "node dist/index.js",
     "postinstall": "node scripts/postinstall.js || true",
     "prepublishOnly": "npm run build && npm run audit:mcp-refs -- --repo frihet-mcp && npm run gate:no-legacy-region",
     "audit:mcp-refs": "node scripts/audit-mcp-refs.mjs",
     "audit:mcp-refs:fix": "node scripts/audit-mcp-refs.mjs --fix",
     "gate:no-leak": "bash scripts/no-public-leak.sh",
-    "gate:no-legacy-region": "bash scripts/no-legacy-region.sh"
+    "gate:no-legacy-region": "bash scripts/no-legacy-region.sh",
+    "sync:openapi": "node scripts/sync-openapi.mjs",
+    "gate:openapi-fresh": "node scripts/sync-openapi.mjs --check",
+    "gate:openapi-fresh:live": "node scripts/sync-openapi.mjs --check --live"
   },
   "keywords": [
     "accounting",