@frihet/mcp-server 1.16.6 → 2.0.0

package/dist/resources/register-all.js

@@ -14,7 +14,12 @@ export const MCP_RESOURCE_COUNT = MCP_STATIC_RESOURCE_COUNT + MCP_DYNAMIC_RESOUR
 /* ------------------------------------------------------------------ */
 /*  Static data                                                        */
 /* ------------------------------------------------------------------ */
-const API_SCHEMA_SUMMARY = `Frihet ERP REST API — OpenAPI 3.1
+const API_SCHEMA_SUMMARY = `Frihet ERP REST API — Informational Reference Summary Snapshot
+=============================================================
+Notice: This resource is an informational, non-exhaustive reference snapshot
+of core REST endpoints for LLM context. The canonical, authoritative live
+contract is the OpenAPI 3.1 specification at https://api.frihet.io/v1/openapi.json.
+
 Base URL: https://api.frihet.io/v1
 Docs: https://docs.frihet.io/desarrolladores/api-reference
 
@@ -58,13 +63,13 @@ Endpoints:
   PATCH  /quotes/:id        — Update quote
   DELETE /quotes/:id        — Delete quote
 
-  GET    /webhooks          — List webhooks (paginated)
+  GET    /webhooks          — List webhooks (unpaginated)
   GET    /webhooks/:id      — Get webhook by ID
   POST   /webhooks          — Create webhook
   PATCH  /webhooks/:id      — Update webhook
   DELETE /webhooks/:id      — Delete webhook
 
-Pagination:
+Pagination (list families that expose limit/offset; webhooks are unpaginated):
   Query params: limit (1-100, default 50), offset (default 0)
   Response: { data: [...], total: number, limit: number, offset: number }
 
@@ -77,10 +82,20 @@ Error responses:
   500 — Internal server error
 
 Content-Type: application/json
-All monetary values in EUR (cents not used — decimal euros).
+Monetary values use the currency declared by each record; amounts are decimal major units.
 Dates in ISO 8601 format (YYYY-MM-DD or full datetime).`;
-const TAX_RATES = `Spanish Tax Rates by Fiscal Zone
-================================
+const TAX_RATES = `Spanish Tax Rates & Fiscal Zones — Informational Reference Schedule
+===================================================================
+Authority:
+  - Peninsula & Balearics (IVA): Ley 37/1992 del IVA (AEAT)
+  - Canary Islands (IGIC): Ley 20/1991 del IGIC (Agencia Tributaria Canaria)
+  - Ceuta & Melilla (IPSI): Ley 8/1991 del IPSI (Servicios Tributarios locales)
+  - Withholding (IRPF): Ley 35/2006 del IRPF (AEAT)
+  - EU Intra-community: Council Directive 2006/112/EC (Reverse Charge / OSS)
+
+Notice: This resource provides reference rate schedules and classification guidelines.
+It is NOT a dynamic tax engine. Transaction rates must be validated against the operation
+date, place of supply, and fiscal status. Server endpoints validate fiscal rules server-side.
 
 PENINSULA & BALEARIC ISLANDS — IVA (Impuesto sobre el Valor Añadido)
   General:    21%  — Most goods and services
@@ -121,8 +136,15 @@ SPECIAL REGIMES
     Applies to: Retail businesses (comercio minorista) buying from wholesalers
   Simplified regime: Fixed quarterly quotas based on activity modules
   Agriculture: 12% / 10.5% flat-rate compensation`;
-const TAX_CALENDAR = `Spanish Quarterly Tax Calendar
-===============================
+const TAX_CALENDAR = `Spanish Tax Calendar — Statutory Filing Deadlines Reference
+===========================================================
+Authority: Calendario del Contribuyente (Agencia Tributaria AEAT / ATC)
+
+Notice: Informational reference of general quarterly and annual statutory filing
+deadlines in Spain. Deadlines shifting to next business day on weekends/holidays
+or direct-debit (domiciliación bancaria) advance deadlines (typically 5 days earlier)
+are not modeled here. Always verify filing dates with your gestoría or official
+AEAT/ATC electronic office.
 
 All deadlines apply to the corresponding fiscal quarter unless noted.
 
@@ -163,19 +185,21 @@ CANARY ISLANDS (IGIC instead of IVA)
   Modelo 425  — Annual IGIC summary (same deadline as Modelo 390)
   Filed with ATC (Administración Tributaria Canaria), NOT AEAT
 
-VERIFACTU (mandatory e-invoicing, phased rollout)
-  2026: Voluntary adoption
-  2027: Mandatory for large companies
-  2028: Mandatory for all businesses
-
 KEY DATES SUMMARY
   Apr 20 — Q1 filings
   Jul 20 — Q2 filings
   Oct 20 — Q3 filings
   Jan 30 — Q4 filings + annual summaries (390, 180, 190)
   Apr 1–Jun 30 — Annual income tax (Modelo 100)`;
-const EXPENSE_CATEGORIES = `Frihet Expense Categories & Deductibility Rules
-=================================================
+const EXPENSE_CATEGORIES = `Frihet Expense Categories & Statutory Deductibility Guidelines
+==============================================================
+Authority: Statutory deductibility rules derived from Ley 35/2006 (IRPF, art. 30)
+and Ley 37/1992 (IVA, arts. 92-96).
+
+Notice: Frihet standard business category mapping with statutory deductibility rules.
+Deductibility requires valid invoices, direct correlation with business activity
+(afectación exclusiva), and accounting registration. Consult your tax advisor
+(gestoría) for specific amortizations or mixed-use deductions.
 
 1. OFFICE (oficina)
    Examples: Rent, utilities, internet, phone, office supplies, cleaning
@@ -232,13 +256,25 @@ const INVOICE_STATUSES = `Frihet Invoice Status Flow
 Statuses and transitions:
 
   DRAFT ──────► SENT ──────► PAID
-    │             │
-    │             └──────► OVERDUE ────► PAID
-    │                         │
-    │                         └────────► CANCELLED
-    │
+    │             │            ▲
+    │             ├──────► PARTIAL ────┤
+    │             │            │       │
+    │             └──────► OVERDUE ────┤
+    │                         │        │
+    │                         └────────┼───► CANCELLED
+    │                                  │
+    │                                  ▼
+    │                            REFUND / RECTIFICATIVE
     └─────────────────────────────────► CANCELLED
 
+Legal transition paths:
+  draft     -> sent | cancelled
+  sent      -> paid | partial | overdue | cancelled
+  partial   -> paid | overdue | cancelled
+  overdue   -> paid | partial | cancelled
+  paid      -> refund (via credit note / rectificative invoice)
+  partial   -> refund (via credit note / rectificative invoice)
+
 Status definitions:
 
   draft     — Invoice created but not yet sent to client.
@@ -249,31 +285,40 @@ Status definitions:
               Payment is expected. The invoice number and date become
               fiscally relevant — avoid modifications after this point.
 
-  paid      — Payment received in full. Terminal state.
+  partial   — Invoice partially paid. A partial payment has been recorded,
+              with a remaining positive balance due. Can transition to
+              paid upon full payment, overdue if dueDate passes with
+              remaining balance, or cancelled/credit note.
+
+  paid      — Payment received in full. Terminal state for settlement.
               Records the payment date. Invoice is complete.
 
-  overdue   — Payment deadline (dueDate) has passed without payment.
-              Triggers follow-up workflows. Can transition to paid
-              (late payment) or cancelled (write-off / bad debt).
+  overdue   — Payment deadline (dueDate) has passed without full payment.
+              Applies to sent or partial invoices. Triggers follow-up
+              workflows. Can transition to paid (late payment), partial,
+              or cancelled (write-off / bad debt).
 
   cancelled — Invoice voided. Requires a corrective invoice or
               credit note for fiscal compliance if previously sent.
               Terminal state. Cannot transition to other statuses.
 
 Automation rules (when configured):
-  - Auto-transition sent → overdue when dueDate passes (daily check)
-  - Webhook events: invoice.created, invoice.sent, invoice.paid,
-    invoice.overdue, invoice.cancelled
+  - Auto-transition sent/partial → overdue when dueDate passes (daily check)
+  - Webhook events: invoice.created, invoice.updated, invoice.generated,
+    invoice.one_off_created, invoice.paid, invoice.overdue, invoice.voided,
+    invoice.payment_status_updated, invoice.payment_failure
+  - A partial payment is reported via invoice.payment_status_updated;
+    cancellation is reported via invoice.voided
   - Overdue reminders can be configured per-client
 
 Best practices:
   - Always set a dueDate when creating invoices (default: 30 days)
   - Use draft status while iterating with the client
   - Once sent, create a new corrective invoice rather than editing
-  - For partial payments, keep status as sent until full payment
+  - For partial payments, invoice transitions to partial with remaining balance tracked
   - cancelled requires a reason (notes field) for audit trail`;
 const CURRENCIES = JSON.stringify({
-    EUR: { name: "Euro", symbol: "\u20ac", decimals: 2, format: "1.234,56 \u20ac", countries: ["ES", "DE", "FR", "IT", "NL", "PT", "BE", "AT", "IE", "FI", "GR", "LU", "SK", "SI", "EE", "LV", "LT", "CY", "MT"] },
+    EUR: { name: "Euro", symbol: "\u20ac", decimals: 2, format: "1.234,56 \u20ac", countries: ["ES", "DE", "FR", "IT", "NL", "PT", "BE", "AT", "IE", "FI", "GR", "LU", "SK", "SI", "EE", "LV", "LT", "CY", "MT", "BG", "HR"] },
     USD: { name: "US Dollar", symbol: "$", decimals: 2, format: "$1,234.56", countries: ["US"] },
     GBP: { name: "British Pound", symbol: "\u00a3", decimals: 2, format: "\u00a31,234.56", countries: ["GB"] },
     CHF: { name: "Swiss Franc", symbol: "CHF", decimals: 2, format: "CHF 1'234.56", countries: ["CH"] },
@@ -289,8 +334,8 @@ const CURRENCIES = JSON.stringify({
     CZK: { name: "Czech Koruna", symbol: "K\u010d", decimals: 2, format: "1 234,56 K\u010d", countries: ["CZ"] },
     HUF: { name: "Hungarian Forint", symbol: "Ft", decimals: 0, format: "1 234 Ft", countries: ["HU"] },
     RON: { name: "Romanian Leu", symbol: "lei", decimals: 2, format: "1.234,56 lei", countries: ["RO"] },
-    BGN: { name: "Bulgarian Lev", symbol: "\u043b\u0432", decimals: 2, format: "1 234,56 \u043b\u0432", countries: ["BG"] },
-    HRK: { name: "Croatian Kuna", symbol: "kn", decimals: 2, format: "1.234,56 kn", countries: ["HR"] },
+    BGN: { name: "Bulgarian Lev", symbol: "\u043b\u0432", decimals: 2, format: "1 234,56 \u043b\u0432", countries: [] },
+    HRK: { name: "Croatian Kuna", symbol: "kn", decimals: 2, format: "1.234,56 kn", countries: [] },
     ISK: { name: "Icelandic Kr\u00f3na", symbol: "kr", decimals: 0, format: "1.234 kr", countries: ["IS"] },
     TRY: { name: "Turkish Lira", symbol: "\u20ba", decimals: 2, format: "\u20ba1.234,56", countries: ["TR"] },
     ILS: { name: "Israeli Shekel", symbol: "\u20aa", decimals: 2, format: "\u20aa1,234.56", countries: ["IL"] },
@@ -327,12 +372,12 @@ const COUNTRIES = JSON.stringify([
     { name: "Portugal", code: "PT", fiscalZone: "eu", defaultTaxRate: 23, taxName: "IVA", currency: "EUR", invoicePrefix: "FT" },
     { name: "Austria", code: "AT", fiscalZone: "eu", defaultTaxRate: 20, taxName: "USt", currency: "EUR", invoicePrefix: "RE" },
     { name: "Ireland", code: "IE", fiscalZone: "eu", defaultTaxRate: 23, taxName: "VAT", currency: "EUR", invoicePrefix: "INV" },
-    { name: "Finland", code: "FI", fiscalZone: "eu", defaultTaxRate: 24, taxName: "ALV", currency: "EUR", invoicePrefix: "INV" },
+    { name: "Finland", code: "FI", fiscalZone: "eu", defaultTaxRate: 25.5, taxName: "ALV", currency: "EUR", invoicePrefix: "INV" },
     { name: "Greece", code: "GR", fiscalZone: "eu", defaultTaxRate: 24, taxName: "FPA", currency: "EUR", invoicePrefix: "TIM" },
     { name: "Luxembourg", code: "LU", fiscalZone: "eu", defaultTaxRate: 17, taxName: "TVA", currency: "EUR", invoicePrefix: "F" },
-    { name: "Slovakia", code: "SK", fiscalZone: "eu", defaultTaxRate: 20, taxName: "DPH", currency: "EUR", invoicePrefix: "F" },
+    { name: "Slovakia", code: "SK", fiscalZone: "eu", defaultTaxRate: 23, taxName: "DPH", currency: "EUR", invoicePrefix: "F" },
     { name: "Slovenia", code: "SI", fiscalZone: "eu", defaultTaxRate: 22, taxName: "DDV", currency: "EUR", invoicePrefix: "F" },
-    { name: "Estonia", code: "EE", fiscalZone: "eu", defaultTaxRate: 22, taxName: "KM", currency: "EUR", invoicePrefix: "INV" },
+    { name: "Estonia", code: "EE", fiscalZone: "eu", defaultTaxRate: 24, taxName: "KM", currency: "EUR", invoicePrefix: "INV" },
     { name: "Latvia", code: "LV", fiscalZone: "eu", defaultTaxRate: 21, taxName: "PVN", currency: "EUR", invoicePrefix: "INV" },
     { name: "Lithuania", code: "LT", fiscalZone: "eu", defaultTaxRate: 21, taxName: "PVM", currency: "EUR", invoicePrefix: "SF" },
     { name: "Cyprus", code: "CY", fiscalZone: "eu", defaultTaxRate: 19, taxName: "VAT", currency: "EUR", invoicePrefix: "INV" },
@@ -342,8 +387,8 @@ const COUNTRIES = JSON.stringify([
     { name: "Poland", code: "PL", fiscalZone: "eu", defaultTaxRate: 23, taxName: "VAT", currency: "PLN", invoicePrefix: "FV" },
     { name: "Czech Republic", code: "CZ", fiscalZone: "eu", defaultTaxRate: 21, taxName: "DPH", currency: "CZK", invoicePrefix: "F" },
     { name: "Hungary", code: "HU", fiscalZone: "eu", defaultTaxRate: 27, taxName: "\u00c1FA", currency: "HUF", invoicePrefix: "SZ" },
-    { name: "Romania", code: "RO", fiscalZone: "eu", defaultTaxRate: 19, taxName: "TVA", currency: "RON", invoicePrefix: "F" },
-    { name: "Bulgaria", code: "BG", fiscalZone: "eu", defaultTaxRate: 20, taxName: "DDS", currency: "BGN", invoicePrefix: "F" },
+    { name: "Romania", code: "RO", fiscalZone: "eu", defaultTaxRate: 21, taxName: "TVA", currency: "RON", invoicePrefix: "F" },
+    { name: "Bulgaria", code: "BG", fiscalZone: "eu", defaultTaxRate: 20, taxName: "DDS", currency: "EUR", invoicePrefix: "F" },
     { name: "Croatia", code: "HR", fiscalZone: "eu", defaultTaxRate: 25, taxName: "PDV", currency: "EUR", invoicePrefix: "R" },
     { name: "United Kingdom", code: "GB", fiscalZone: "international", defaultTaxRate: 20, taxName: "VAT", currency: "GBP", invoicePrefix: "INV" },
     { name: "United States", code: "US", fiscalZone: "international", defaultTaxRate: 0, taxName: "Sales Tax", currency: "USD", invoicePrefix: "INV" },
@@ -382,8 +427,9 @@ const COUNTRIES = JSON.stringify([
 /* ------------------------------------------------------------------ */
 export function registerAllResources(server, client) {
     server.registerResource("api-schema", "frihet://api/schema", {
-        description: "OpenAPI schema summary: all endpoints, authentication method, rate limits, pagination, and error codes. " +
-            "/ Resumen del esquema OpenAPI: endpoints, autenticación, límites, paginación y errores.",
+        description: "Informational snapshot summary of selected core REST endpoints, auth, and rate limits. " +
+            "Canonical contract: https://api.frihet.io/v1/openapi.json. " +
+            "/ Resumen informativo no exhaustivo de endpoints REST principales; el contrato canónico reside en openapi.json.",
         mimeType: "text/plain",
     }, async () => ({
         contents: [
@@ -395,9 +441,9 @@ export function registerAllResources(server, client) {
         ],
     }));
     server.registerResource("tax-rates", "frihet://tax/rates", {
-        description: "Current tax rates by Spanish fiscal zone: Peninsula IVA (21/10/4%), Canary Islands IGIC (7/3/0%), " +
-            "Ceuta IPSI, EU reverse charge, international exports, IRPF withholding, and special regimes. " +
-            "/ Tipos impositivos por zona fiscal: IVA, IGIC, IPSI, intracomunitario, exportaciones, IRPF, regímenes especiales.",
+        description: "Spanish statutory tax rate reference (AEAT/ATC/IPSI, IVA/IGIC/IPSI/IRPF). " +
+            "Informational reference schedule; server validates tax math per transaction. " +
+            "/ Referencia normativa de tipos impositivos por zona fiscal en España.",
         mimeType: "text/plain",
     }, async () => ({
         contents: [
@@ -409,9 +455,9 @@ export function registerAllResources(server, client) {
         ],
     }));
     server.registerResource("tax-calendar", "frihet://tax/calendar", {
-        description: "Spanish quarterly tax calendar with filing deadlines for Modelo 303, 130, 390, 420 (IGIC), and annual returns. " +
-            "Includes VeriFactu e-invoicing timeline. " +
-            "/ Calendario fiscal trimestral español con plazos de presentación de modelos y VeriFactu.",
+        description: "Spanish tax filing calendar reference (Calendario del Contribuyente AEAT/ATC). " +
+            "Informational reference for statutory filing deadlines. " +
+            "/ Calendario fiscal trimestral español con plazos de presentación de modelos.",
         mimeType: "text/plain",
     }, async () => ({
         contents: [
@@ -423,8 +469,8 @@ export function registerAllResources(server, client) {
         ],
     }));
     server.registerResource("expense-categories", "frihet://config/expense-categories", {
-        description: "The 8 expense categories in Frihet with deductibility rules, IVA treatment, and amortization periods. " +
-            "Essential for correctly categorizing business expenses. " +
+        description: "Frihet standard expense categories and statutory deductibility guidelines (LIRPF/LIVA). " +
+            "Informational classification guide. " +
             "/ Las 8 categorías de gastos con reglas de deducibilidad, IVA y amortización.",
         mimeType: "text/plain",
     }, async () => ({
@@ -451,9 +497,9 @@ export function registerAllResources(server, client) {
         ],
     }));
     server.registerResource("currencies", "frihet://config/currencies", {
-        description: "40 supported currencies with ISO codes, symbols, decimal places, locale formatting examples, and associated countries. " +
-            "Use to validate currency inputs and format monetary values. " +
-            "/ 40 divisas soportadas con códigos ISO, símbolos, decimales, formato local y países asociados.",
+        description: "Currency codes, symbols and display formatting examples with associated countries, including historical codes. " +
+            "Decimals describe these display examples, not authoritative payment precision, conversion rates or API acceptance. " +
+            "/ Códigos y ejemplos de formato de divisas; no determinan precisión de pagos ni tipos de cambio.",
         mimeType: "application/json",
     }, async () => ({
         contents: [
@@ -465,9 +511,9 @@ export function registerAllResources(server, client) {
         ],
     }));
     server.registerResource("countries", "frihet://config/countries", {
-        description: "61 supported countries with ISO codes, fiscal zones (peninsula, canarias, ceuta, melilla, eu, international), " +
-            "default tax rates, tax names, default currencies, and invoice prefixes. " +
-            "/ 61 países soportados con zonas fiscales, tipos impositivos, divisas y prefijos de factura.",
+        description: "Supported countries with ISO codes, fiscal zones (peninsula, canarias, ceuta, melilla, eu, international), " +
+            "default tax rates, tax names, default currencies, and invoice prefixes. Note: default rates are onboarding suggestions only, not legal determination. " +
+            "/ Países soportados con zonas fiscales, tipos impositivos por defecto y prefijos de factura.",
         mimeType: "application/json",
     }, async () => ({
         contents: [
@@ -517,33 +563,77 @@ export function registerAllResources(server, client) {
             };
         });
         server.registerResource("overdue-invoices", "frihet://overdue-invoices", {
-            description: "Live list of all overdue invoices — invoices past their due date that haven't been paid. " +
-                "Includes client names, amounts, due dates, and days overdue. Critical for cash flow management. " +
-                "/ Lista en vivo de facturas vencidas — facturas cuya fecha de vencimiento ha pasado sin cobrar.",
+            description: "Live invoice records filtered by status overdue (first page up to 100 items). " +
+                "Returns stored fields and pagination bounds; does not calculate unpaid balances or days overdue. " +
+                "Paginate list_invoices without a status filter and select sent, partial and overdue records client-side for a complete receivables review. " +
+                "/ Registros con estado vencida (primera página hasta 100); no calcula saldos pendientes ni días de retraso.",
             mimeType: "application/json",
         }, async () => {
-            const data = await client.listInvoices({ status: "overdue", limit: 100 });
+            const response = await client.listInvoices({ status: "overdue", limit: 100 });
+            const list = Array.isArray(response)
+                ? response
+                : Array.isArray(response.data)
+                    ? (response.data)
+                    : [];
+            const total = typeof response.total === "number"
+                ? (response.total)
+                : list.length;
+            const result = {
+                data: list,
+                total,
+                limit: 100,
+                offset: 0,
+                hasMore: total > 100 || list.length === 100,
+                note: "First 100 records with status overdue; not a complete receivables or unpaid-balance report",
+            };
             return {
                 contents: [
                     {
                         uri: "frihet://overdue-invoices",
                         mimeType: "application/json",
-                        text: JSON.stringify(data, null, 2),
+                        text: JSON.stringify(result, null, 2),
                     },
                 ],
             };
         });
         server.registerResource("plan-limits", "frihet://status/plan-limits", {
-            description: "Live plan limits and current usage — plan tier, invoices/month, AI messages/day, team members, " +
-                "integrations, API requests/minute, and real-time usage counters. " +
-                "/ Límites del plan y uso actual en vivo — tier, facturas/mes, mensajes IA/día, miembros, integraciones, API req/min.",
+            description: "Live plan tier, quotas, and usage counters (invoices, expenses, AI messages) from business context. " +
+                "/ Nivel de plan, cuotas y contadores de uso (facturas, gastos, mensajes IA) del contexto del negocio.",
             mimeType: "application/json",
         }, async () => {
             const ctx = await client.getBusinessContext();
-            const plan = ctx.plan ?? "free";
-            const limits = ctx.limits ?? {};
-            const usage = ctx.usage ?? {};
-            const result = { plan, limits, usage };
+            const planRaw = ctx.plan;
+            let plan = "free";
+            let limits = ctx.limits;
+            let usage = ctx.usage;
+            if (typeof planRaw === "string") {
+                plan = planRaw;
+            }
+            else if (typeof planRaw === "object" && planRaw !== null) {
+                const planObj = planRaw;
+                plan = typeof planObj.name === "string" ? planObj.name : "free";
+                if ((!limits || Object.keys(limits).length === 0) && (!usage || Object.keys(usage).length === 0)) {
+                    const extractedLimits = {};
+                    const extractedUsage = {};
+                    for (const [key, val] of Object.entries(planObj)) {
+                        if (key !== "name" && typeof val === "object" && val !== null) {
+                            const item = val;
+                            if ("limit" in item)
+                                extractedLimits[key] = item.limit;
+                            if ("used" in item)
+                                extractedUsage[key] = item.used;
+                        }
+                    }
+                    limits = extractedLimits;
+                    usage = extractedUsage;
+                }
+            }
+            const result = {
+                plan,
+                limits: limits ?? {},
+                usage: usage ?? {},
+                ...(typeof planRaw === "object" && planRaw !== null ? { breakdown: planRaw } : {}),
+            };
             return {
                 contents: [
                     {

package/dist/retry-after.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `Retry-After` parsing per RFC 9110 §10.2.3: either `delay-seconds`
+ * (1*DIGIT) or an HTTP-date. Returns the wait in milliseconds, or `null` when
+ * the value is absent or malformed so the caller falls back to its own
+ * backoff — never NaN, never negative.
+ *
+ * Semantics:
+ * - delay-seconds: strict non-negative integer digits only (no sign, decimal
+ *   point, exponent or whitespace inside). Values too large to represent
+ *   safely are clamped to MAX_SAFE_INTEGER ms, which always exceeds any retry
+ *   budget and therefore defers instead of sleeping.
+ * - HTTP-date: IMF-fixdate, obsolete RFC 850 and ANSI C asctime() forms, all
+ *   read as GMT. The wait is `date - now`; a date already in the past means
+ *   the server's embargo has expired, so the wait is 0 (not negative). Clock
+ *   skew is NOT compensated: shortening the wait would retry earlier than the
+ *   server asked, lengthening it would hide a valid answer.
+ */
+export declare function parseRetryAfter(value: string | null | undefined, nowMs: number): number | null;
+//# sourceMappingURL=retry-after.d.ts.map

package/dist/retry-after.js

@@ -0,0 +1,84 @@
+/**
+ * `Retry-After` parsing per RFC 9110 §10.2.3: either `delay-seconds`
+ * (1*DIGIT) or an HTTP-date. Returns the wait in milliseconds, or `null` when
+ * the value is absent or malformed so the caller falls back to its own
+ * backoff — never NaN, never negative.
+ *
+ * Semantics:
+ * - delay-seconds: strict non-negative integer digits only (no sign, decimal
+ *   point, exponent or whitespace inside). Values too large to represent
+ *   safely are clamped to MAX_SAFE_INTEGER ms, which always exceeds any retry
+ *   budget and therefore defers instead of sleeping.
+ * - HTTP-date: IMF-fixdate, obsolete RFC 850 and ANSI C asctime() forms, all
+ *   read as GMT. The wait is `date - now`; a date already in the past means
+ *   the server's embargo has expired, so the wait is 0 (not negative). Clock
+ *   skew is NOT compensated: shortening the wait would retry earlier than the
+ *   server asked, lengthening it would hide a valid answer.
+ */
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const DAYS_LONG = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
+const DAYS_SHORT = DAYS_LONG.map((d) => d.slice(0, 3));
+const IMF_FIXDATE = /^([A-Z][a-z]{2}), (\d{2}) ([A-Z][a-z]{2}) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
+const RFC850_DATE = /^([A-Z][a-z]+day), (\d{2})-([A-Z][a-z]{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
+const ASCTIME_DATE = /^([A-Z][a-z]{2}) ([A-Z][a-z]{2}) ([ \d]\d) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/;
+function utcMs(year, monthName, day, h, m, s) {
+    const month = MONTHS.indexOf(monthName);
+    if (month < 0 || h > 23 || m > 59 || s > 60)
+        return null;
+    const ms = Date.UTC(year, month, day, h, m, s);
+    const check = new Date(ms);
+    // Reject roll-over such as "31 Feb" that Date.UTC silently normalizes.
+    if (check.getUTCFullYear() !== year
+        || check.getUTCMonth() !== month
+        || check.getUTCDate() !== day) {
+        return null;
+    }
+    return ms;
+}
+function weekdayMatches(ms, name, list) {
+    // getUTCDay: 0 = Sunday; the lists start on Monday.
+    return list[(new Date(ms).getUTCDay() + 6) % 7] === name;
+}
+function parseHttpDate(value, nowMs) {
+    let m = IMF_FIXDATE.exec(value);
+    if (m) {
+        const ms = utcMs(+m[4], m[3], +m[2], +m[5], +m[6], +m[7]);
+        return ms !== null && weekdayMatches(ms, m[1], DAYS_SHORT) ? ms : null;
+    }
+    m = RFC850_DATE.exec(value);
+    if (m) {
+        // RFC 9110 §5.6.7: a two-digit year more than 50 years ahead is the past century.
+        const yy = +m[4];
+        const nowYear = new Date(nowMs).getUTCFullYear();
+        let year = Math.floor(nowYear / 100) * 100 + yy;
+        if (year > nowYear + 50)
+            year -= 100;
+        const ms = utcMs(year, m[3], +m[2], +m[5], +m[6], +m[7]);
+        return ms !== null && weekdayMatches(ms, m[1], DAYS_LONG) ? ms : null;
+    }
+    m = ASCTIME_DATE.exec(value);
+    if (m) {
+        const ms = utcMs(+m[7], m[2], +m[3].trim(), +m[4], +m[5], +m[6]);
+        return ms !== null && weekdayMatches(ms, m[1], DAYS_SHORT) ? ms : null;
+    }
+    return null;
+}
+export function parseRetryAfter(value, nowMs) {
+    if (value === null || value === undefined)
+        return null;
+    const v = value.trim();
+    if (v === "")
+        return null;
+    if (/^\d+$/.test(v)) {
+        const seconds = Number(v);
+        if (!Number.isFinite(seconds) || seconds * 1000 > Number.MAX_SAFE_INTEGER) {
+            return Number.MAX_SAFE_INTEGER;
+        }
+        return seconds * 1000;
+    }
+    const dateMs = parseHttpDate(v, nowMs);
+    if (dateMs === null)
+        return null;
+    return Math.max(0, dateMs - nowMs);
+}
+//# sourceMappingURL=retry-after.js.map

package/dist/server-composition.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Canonical registration path shared by the stdio server, remote Worker, and
+ * generated public-surface contract. Transport/auth setup stays with each host;
+ * the exposed MCP operations/resources/prompts are composed here exactly once.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { IFrihetClient } from "./client-interface.js";
+export interface McpSurfaceComposition {
+    readonly openaiMode: boolean;
+    readonly groupedMode: boolean;
+    readonly includeDynamicResources: boolean;
+    readonly claudeMode?: boolean;
+    readonly googleMode?: boolean;
+    readonly museMode?: boolean;
+}
+export declare function localMcpSurfaceComposition(openaiMode: boolean, groupedMode: boolean, claudeMode?: boolean, googleMode?: boolean, museMode?: boolean): McpSurfaceComposition;
+export declare function remoteMcpSurfaceComposition(openaiMode: boolean, groupedMode: boolean, claudeMode?: boolean, googleMode?: boolean, museMode?: boolean): McpSurfaceComposition;
+export declare function registerMcpSurface(server: McpServer, client: IFrihetClient, options: McpSurfaceComposition): void;
+//# sourceMappingURL=server-composition.d.ts.map

package/dist/server-composition.js

@@ -0,0 +1,74 @@
+/**
+ * Canonical registration path shared by the stdio server, remote Worker, and
+ * generated public-surface contract. Transport/auth setup stays with each host;
+ * the exposed MCP operations/resources/prompts are composed here exactly once.
+ */
+import { applyPublicCapabilityTruth, buildLocalDiscoveryCapability, CAPABILITY_META_KEY, } from "./capability-truth.js";
+import { applyFiscalAliases } from "./fiscal-aliases.js";
+import { applyClaudeCandidateProfile, CLAUDE_CANDIDATE_TOOLS, CLAUDE_GROUP_METADATA } from "./claude-profile.js";
+import { applyGoogleProfile } from "./google-profile.js";
+import { applyMuseProfile } from "./muse-profile.js";
+import { applyOpenAIProfile, applyOpenAIReviewProfiles, } from "./openai-profile.js";
+import { registerAllPrompts } from "./prompts/register-all.js";
+import { registerAllResources } from "./resources/register-all.js";
+import { applyToolExposureProfile } from "./tool-exposure.js";
+import { registerAllTools } from "./tools/register-all.js";
+export function localMcpSurfaceComposition(openaiMode, groupedMode, claudeMode = false, googleMode = false, museMode = false) {
+    return { openaiMode, groupedMode, includeDynamicResources: true, claudeMode, googleMode, museMode };
+}
+export function remoteMcpSurfaceComposition(openaiMode, groupedMode, claudeMode = false, googleMode = false, museMode = false) {
+    return { openaiMode, groupedMode, includeDynamicResources: false, claudeMode, googleMode, museMode };
+}
+export function registerMcpSurface(server, client, options) {
+    const activeModes = [options.openaiMode, options.claudeMode, options.googleMode, options.museMode].filter(Boolean).length;
+    if (activeModes > 1) {
+        throw new Error("FRIHET_OPENAI_MODE, FRIHET_CLAUDE_MODE, FRIHET_GOOGLE_MODE, and FRIHET_MUSE_MODE are mutually exclusive");
+    }
+    if (options.claudeMode) {
+        // Directory reads annotations.title. Install before grouped discovery eagerly
+        // registers its meta-tools, and clone annotations to preserve shared hints.
+        const registerTool = server.registerTool.bind(server);
+        server.registerTool = (name, config, handler) => registerTool(name, {
+            ...config,
+            annotations: { ...config.annotations, title: config.title },
+        }, handler);
+    }
+    if (options.groupedMode) {
+        if (options.openaiMode) {
+            applyOpenAIReviewProfiles(server);
+        }
+        else {
+            applyToolExposureProfile(server, {
+                ...(options.claudeMode ? {
+                    allowlist: CLAUDE_CANDIDATE_TOOLS,
+                    groupMetadata: CLAUDE_GROUP_METADATA,
+                    describeToolExample: "list_invoices",
+                } : {}),
+                capabilityTruth: {
+                    metaKey: CAPABILITY_META_KEY,
+                    localDiscovery: buildLocalDiscoveryCapability,
+                },
+            });
+        }
+    }
+    else if (options.openaiMode) {
+        applyOpenAIProfile(server);
+    }
+    if (!options.openaiMode && !options.googleMode && !options.museMode) {
+        applyPublicCapabilityTruth(server);
+    }
+    if (options.claudeMode) {
+        applyClaudeCandidateProfile(server);
+    }
+    else if (options.googleMode) {
+        applyGoogleProfile(server);
+    }
+    else if (options.museMode) {
+        applyMuseProfile(server);
+    }
+    registerAllTools(server, client);
+    applyFiscalAliases(server);
+    registerAllResources(server, options.includeDynamicResources ? client : undefined);
+    registerAllPrompts(server);
+}
+//# sourceMappingURL=server-composition.js.map