ynab-mcp-deluxe 0.1.9

package/dist/helpers.js

@@ -0,0 +1,226 @@
+/**
+ * Helper functions for the YNAB MCP server
+ */
+import jmespath from '@metrichor/jmespath';
+/**
+ * Apply a JMESPath query to data
+ * @throws Error with helpful message if query is invalid
+ */
+export function applyJMESPath(data, query) {
+    try {
+        // Cast through unknown for type safety with jmespath
+        const jsonData = data;
+        return jmespath.search(jsonData, query);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        throw new Error(`Invalid JMESPath expression: ${message}. Expression: '${query}'.`);
+    }
+}
+/**
+ * Sort transactions by the specified criteria
+ */
+export function sortTransactions(transactions, sortBy) {
+    const sorted = [...transactions];
+    switch (sortBy) {
+        case 'newest':
+            sorted.sort((a, b) => b.date.localeCompare(a.date));
+            break;
+        case 'oldest':
+            sorted.sort((a, b) => a.date.localeCompare(b.date));
+            break;
+        case 'amount_desc':
+            // Largest outflows first (most negative first)
+            sorted.sort((a, b) => a.amount - b.amount);
+            break;
+        case 'amount_asc':
+            // Largest inflows first (most positive first)
+            sorted.sort((a, b) => b.amount - a.amount);
+            break;
+    }
+    return sorted;
+}
+/**
+ * Filter transactions by payee name (case-insensitive partial match)
+ */
+export function filterByPayee(transactions, payeeContains) {
+    const searchLower = payeeContains.toLowerCase();
+    return transactions.filter((tx) => {
+        const payeeName = tx.payee_name?.toLowerCase() ?? '';
+        const importPayeeName = tx.import_payee_name?.toLowerCase() ?? '';
+        const importPayeeNameOriginal = tx.import_payee_name_original?.toLowerCase() ?? '';
+        return (payeeName.includes(searchLower) ||
+            importPayeeName.includes(searchLower) ||
+            importPayeeNameOriginal.includes(searchLower));
+    });
+}
+/**
+ * Filter transactions by date range
+ */
+export function filterByDateRange(transactions, sinceDate, untilDate) {
+    return transactions.filter((tx) => {
+        if (sinceDate !== undefined && sinceDate !== '' && tx.date < sinceDate)
+            return false;
+        if (untilDate !== undefined && untilDate !== '' && tx.date > untilDate)
+            return false;
+        return true;
+    });
+}
+/**
+ * Filter transactions by account ID
+ */
+export function filterByAccount(transactions, accountId) {
+    return transactions.filter((tx) => tx.account_id === accountId);
+}
+/**
+ * Calculate category distribution for a set of transactions
+ */
+export function calculateCategoryDistribution(transactions) {
+    const counts = new Map();
+    for (const tx of transactions) {
+        const key = tx.category_id ?? 'uncategorized';
+        const existing = counts.get(key);
+        if (existing !== undefined) {
+            existing.count++;
+        }
+        else {
+            counts.set(key, {
+                count: 1,
+                groupName: tx.category_group_name,
+                name: tx.category_name,
+            });
+        }
+    }
+    const total = transactions.length;
+    const distribution = [];
+    for (const { name, groupName, count } of counts.values()) {
+        distribution.push({
+            category_group_name: groupName,
+            category_name: name,
+            count,
+            percentage: Math.round((count / total) * 1000) / 10, // One decimal place
+        });
+    }
+    // Sort by count descending
+    distribution.sort((a, b) => b.count - a.count);
+    return distribution;
+}
+/**
+ * Create an MCP error response
+ */
+export function createErrorResponse(message) {
+    return {
+        content: [{ text: message, type: 'text' }],
+        isError: true,
+    };
+}
+/**
+ * Validate a selector has exactly one of name or id
+ */
+export function validateSelector(selector, entityType) {
+    if (selector === undefined || selector === null)
+        return;
+    const hasName = selector.name !== undefined && selector.name !== '';
+    const hasId = selector.id !== undefined && selector.id !== '';
+    if (hasName && hasId) {
+        throw new Error(`${entityType} selector must specify exactly one of: 'name' or 'id'.`);
+    }
+}
+/**
+ * Check if a value looks like it might be a JMESPath query result
+ * (i.e., it's been transformed by a projection)
+ */
+export function isTransformed(value) {
+    if (!Array.isArray(value))
+        return true;
+    if (value.length === 0)
+        return false;
+    // If the first item doesn't have standard transaction fields, it's been transformed
+    const first = value[0];
+    if (typeof first !== 'object' || first === null)
+        return true;
+    return !('id' in first && 'date' in first && 'amount' in first);
+}
+// ============================================================================
+// YNAB Error Handling
+// ============================================================================
+/**
+ * Type guard for YNAB SDK ResponseError (HTTP errors from API)
+ */
+function isYnabResponseError(error) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        'response' in error &&
+        'name' in error &&
+        error.name === 'ResponseError');
+}
+/**
+ * Type guard for YNAB SDK FetchError (network errors)
+ */
+function isYnabFetchError(error) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        'cause' in error &&
+        'name' in error &&
+        error.name === 'FetchError');
+}
+/**
+ * Create an enhanced MCP error response with context from YNAB errors
+ *
+ * Extracts HTTP status codes and error details from YNAB SDK errors
+ * to provide actionable error messages for the LLM.
+ */
+export async function createEnhancedErrorResponse(error, operation) {
+    let message;
+    if (isYnabResponseError(error)) {
+        const statusCode = error.response.status;
+        // Try to extract YNAB error detail from response body
+        let detail = null;
+        try {
+            const body = (await error.response.json());
+            if (body?.error?.detail !== undefined &&
+                body.error.detail !== null &&
+                body.error.detail !== '') {
+                detail = body.error.detail;
+            }
+        }
+        catch {
+            // Response body not available or not JSON
+        }
+        if (detail !== null) {
+            message = `${operation} failed: ${detail}`;
+        }
+        else {
+            message = `${operation} failed: HTTP ${statusCode}`;
+        }
+        // Add specific guidance for common HTTP errors
+        if (statusCode === 401) {
+            message += ' (Check your YNAB API token)';
+        }
+        else if (statusCode === 404) {
+            message += ' (Resource not found - verify the ID exists)';
+        }
+        else if (statusCode === 429) {
+            message += ' (Rate limited - wait before retrying)';
+        }
+        else if (statusCode >= 500) {
+            message += ' (YNAB server error - try again later)';
+        }
+    }
+    else if (isYnabFetchError(error)) {
+        const causeMessage = error.cause?.message ?? error.message;
+        message = `${operation} failed: Network error - ${causeMessage}`;
+    }
+    else if (error instanceof Error) {
+        // Application-level errors (validation, resolution failures, etc.)
+        // These already have good messages from ynab-client.ts
+        message = error.message;
+    }
+    else {
+        message = `${operation} failed: Unknown error`;
+    }
+    return {
+        content: [{ text: message, type: 'text' }],
+        isError: true,
+    };
+}

package/dist/local-budget.d.ts

@@ -0,0 +1,86 @@
+/**
+ * LocalBudget building and merging utilities.
+ *
+ * This module handles:
+ * - Building a LocalBudget from a full YNAB API response
+ * - Merging delta sync responses into an existing LocalBudget
+ * - Rebuilding O(1) lookup maps after modifications
+ */
+import type { LocalBudget } from './types.js';
+import type { BudgetDetail, MonthDetail } from 'ynab';
+/**
+ * Entity with an ID and optional deleted flag (for delta sync)
+ */
+interface EntityWithId {
+    deleted?: boolean;
+    id: string;
+}
+/**
+ * Rebuild all O(1) lookup maps from the arrays in a LocalBudget.
+ * Call this after any modification to the arrays.
+ *
+ * @param localBudget - The LocalBudget to rebuild maps for (mutated in place)
+ */
+export declare function rebuildLookupMaps(localBudget: LocalBudget): void;
+/**
+ * Build a LocalBudget from a full YNAB API budget response.
+ *
+ * @param budgetId - The budget ID
+ * @param budget - The BudgetDetail from YNAB API
+ * @param serverKnowledge - The server_knowledge from the API response
+ * @returns A fully populated LocalBudget with lookup maps
+ */
+export declare function buildLocalBudget(budgetId: string, budget: BudgetDetail, serverKnowledge: number): LocalBudget;
+/**
+ * Merge an array of entities from a delta response into an existing array.
+ * Handles additions, updates, and deletions (entities with deleted: true).
+ *
+ * @param existing - The current array of entities
+ * @param delta - The delta array from the API (may include deleted entities)
+ * @returns A new merged array with deletions removed
+ */
+export declare function mergeEntityArray<T extends EntityWithId>(existing: T[], delta: T[]): T[];
+/**
+ * Merge an array of MonthDetail entities (keyed by 'month' instead of 'id').
+ * MonthDetail doesn't have an 'id' field - it uses 'month' as its unique key.
+ *
+ * IMPORTANT: MonthDetail contains a nested `categories` array that must be
+ * merged separately. Delta responses may only include CHANGED categories,
+ * so we must merge them with existing categories rather than replacing.
+ *
+ * @param existing - The current array of months
+ * @param delta - The delta array from the API
+ * @returns A new merged array
+ */
+export declare function mergeMonthArray(existing: MonthDetail[], delta: MonthDetail[]): MonthDetail[];
+/**
+ * Merge a delta sync response into an existing LocalBudget.
+ * Returns a new LocalBudget with the merged data.
+ *
+ * @param existing - The current LocalBudget
+ * @param deltaBudget - The delta BudgetDetail from YNAB API
+ * @param newServerKnowledge - The new server_knowledge from the delta response
+ * @returns A new LocalBudget with merged data and change counts
+ */
+export declare function mergeDelta(existing: LocalBudget, deltaBudget: BudgetDetail, newServerKnowledge: number): {
+    changesReceived: {
+        accounts: number;
+        categories: number;
+        months: number;
+        payees: number;
+        scheduledTransactions: number;
+        transactions: number;
+    };
+    localBudget: LocalBudget;
+};
+/**
+ * Compare two LocalBudgets and report any discrepancies.
+ * Useful for sanity checking after a full re-fetch.
+ *
+ * @param local - The local budget (before full re-fetch)
+ * @param remote - The remote budget (from full re-fetch)
+ * @returns Array of discrepancy descriptions, empty if no drift
+ */
+export declare function detectDrift(local: LocalBudget, remote: LocalBudget): string[];
+export {};
+//# sourceMappingURL=local-budget.d.ts.map

package/dist/local-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-budget.d.ts","sourceRoot":"","sources":["../src/local-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAEV,YAAY,EAGZ,WAAW,EAOZ,MAAM,MAAM,CAAC;AAEd;;GAEG;AACH,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAsEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,EACpB,eAAe,EAAE,MAAM,GACtB,WAAW,CAwCb;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,YAAY,EACrD,QAAQ,EAAE,CAAC,EAAE,EACb,KAAK,EAAE,CAAC,EAAE,GACT,CAAC,EAAE,CAmBL;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,WAAW,EAAE,EACvB,KAAK,EAAE,WAAW,EAAE,GACnB,WAAW,EAAE,CA+Bf;AAYD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,WAAW,EACrB,WAAW,EAAE,YAAY,EACzB,kBAAkB,EAAE,MAAM,GACzB;IACD,eAAe,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,qBAAqB,EAAE,MAAM,CAAC;QAC9B,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,WAAW,EAAE,WAAW,CAAC;CAC1B,CA2EA;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CA0B7E"}

package/dist/local-budget.js

@@ -0,0 +1,277 @@
+/**
+ * LocalBudget building and merging utilities.
+ *
+ * This module handles:
+ * - Building a LocalBudget from a full YNAB API response
+ * - Merging delta sync responses into an existing LocalBudget
+ * - Rebuilding O(1) lookup maps after modifications
+ */
+/**
+ * Rebuild all O(1) lookup maps from the arrays in a LocalBudget.
+ * Call this after any modification to the arrays.
+ *
+ * @param localBudget - The LocalBudget to rebuild maps for (mutated in place)
+ */
+export function rebuildLookupMaps(localBudget) {
+    // Account maps
+    localBudget.accountById.clear();
+    localBudget.accountByName.clear();
+    for (const account of localBudget.accounts) {
+        localBudget.accountById.set(account.id, account);
+        localBudget.accountByName.set(account.name.toLowerCase(), account);
+    }
+    // Category maps
+    localBudget.categoryById.clear();
+    localBudget.categoryByName.clear();
+    for (const category of localBudget.categories) {
+        localBudget.categoryById.set(category.id, category);
+        localBudget.categoryByName.set(category.name.toLowerCase(), category);
+    }
+    // Category group name map
+    localBudget.categoryGroupNameById.clear();
+    for (const group of localBudget.categoryGroups) {
+        localBudget.categoryGroupNameById.set(group.id, group.name);
+    }
+    // Payee map
+    localBudget.payeeById.clear();
+    for (const payee of localBudget.payees) {
+        localBudget.payeeById.set(payee.id, payee);
+    }
+    // Subtransaction maps (for O(1) joins during enrichment)
+    // Guard against null/undefined transaction_id (defensive against malformed API responses)
+    localBudget.subtransactionsByTransactionId.clear();
+    for (const sub of localBudget.subtransactions) {
+        // Skip orphaned subtransactions with missing transaction_id
+        if (sub.transaction_id === null || sub.transaction_id === undefined) {
+            continue;
+        }
+        const existing = localBudget.subtransactionsByTransactionId.get(sub.transaction_id);
+        if (existing !== undefined) {
+            existing.push(sub);
+        }
+        else {
+            localBudget.subtransactionsByTransactionId.set(sub.transaction_id, [sub]);
+        }
+    }
+    // Guard against null/undefined scheduled_transaction_id (defensive against malformed API responses)
+    localBudget.scheduledSubtransactionsByScheduledTransactionId.clear();
+    for (const sub of localBudget.scheduledSubtransactions) {
+        // Skip orphaned scheduled subtransactions with missing scheduled_transaction_id
+        if (sub.scheduled_transaction_id === null ||
+            sub.scheduled_transaction_id === undefined) {
+            continue;
+        }
+        const existing = localBudget.scheduledSubtransactionsByScheduledTransactionId.get(sub.scheduled_transaction_id);
+        if (existing !== undefined) {
+            existing.push(sub);
+        }
+        else {
+            localBudget.scheduledSubtransactionsByScheduledTransactionId.set(sub.scheduled_transaction_id, [sub]);
+        }
+    }
+}
+/**
+ * Build a LocalBudget from a full YNAB API budget response.
+ *
+ * @param budgetId - The budget ID
+ * @param budget - The BudgetDetail from YNAB API
+ * @param serverKnowledge - The server_knowledge from the API response
+ * @returns A fully populated LocalBudget with lookup maps
+ */
+export function buildLocalBudget(budgetId, budget, serverKnowledge) {
+    const localBudget = {
+        // Lookup maps (will be populated by rebuildLookupMaps)
+        accountById: new Map(),
+        accountByName: new Map(),
+        // Budget data (arrays from the API response)
+        accounts: budget.accounts ?? [],
+        // Budget identity
+        budgetId,
+        budgetName: budget.name,
+        categories: budget.categories ?? [],
+        categoryById: new Map(),
+        categoryByName: new Map(),
+        categoryGroupNameById: new Map(),
+        categoryGroups: budget.category_groups ?? [],
+        // Budget settings
+        currencyFormat: budget.currency_format ?? null,
+        // Sync metadata
+        lastSyncedAt: new Date(),
+        months: budget.months ?? [],
+        needsSync: false,
+        payeeById: new Map(),
+        payeeLocations: budget.payee_locations ?? [],
+        payees: budget.payees ?? [],
+        scheduledSubtransactions: budget.scheduled_subtransactions ?? [],
+        scheduledSubtransactionsByScheduledTransactionId: new Map(),
+        scheduledTransactions: budget.scheduled_transactions ?? [],
+        serverKnowledge,
+        subtransactions: budget.subtransactions ?? [],
+        subtransactionsByTransactionId: new Map(),
+        transactions: budget.transactions ?? [],
+    };
+    // Build the lookup maps
+    rebuildLookupMaps(localBudget);
+    return localBudget;
+}
+/**
+ * Merge an array of entities from a delta response into an existing array.
+ * Handles additions, updates, and deletions (entities with deleted: true).
+ *
+ * @param existing - The current array of entities
+ * @param delta - The delta array from the API (may include deleted entities)
+ * @returns A new merged array with deletions removed
+ */
+export function mergeEntityArray(existing, delta) {
+    // Build a map from existing entities
+    const byId = new Map();
+    for (const entity of existing) {
+        byId.set(entity.id, entity);
+    }
+    // Apply delta changes
+    for (const entity of delta) {
+        if (entity.deleted === true) {
+            // Remove deleted entities
+            byId.delete(entity.id);
+        }
+        else {
+            // Add or update entity
+            byId.set(entity.id, entity);
+        }
+    }
+    return Array.from(byId.values());
+}
+/**
+ * Merge an array of MonthDetail entities (keyed by 'month' instead of 'id').
+ * MonthDetail doesn't have an 'id' field - it uses 'month' as its unique key.
+ *
+ * IMPORTANT: MonthDetail contains a nested `categories` array that must be
+ * merged separately. Delta responses may only include CHANGED categories,
+ * so we must merge them with existing categories rather than replacing.
+ *
+ * @param existing - The current array of months
+ * @param delta - The delta array from the API
+ * @returns A new merged array
+ */
+export function mergeMonthArray(existing, delta) {
+    // Build a map from existing months using 'month' as key
+    const byMonth = new Map();
+    for (const month of existing) {
+        byMonth.set(month.month, month);
+    }
+    // Apply delta changes
+    for (const deltaMonth of delta) {
+        if (deltaMonth.deleted === true) {
+            byMonth.delete(deltaMonth.month);
+        }
+        else {
+            const existingMonth = byMonth.get(deltaMonth.month);
+            if (existingMonth !== undefined) {
+                // Month exists - merge the nested categories array
+                const mergedCategories = mergeEntityArray(existingMonth.categories, deltaMonth.categories);
+                byMonth.set(deltaMonth.month, {
+                    ...deltaMonth,
+                    categories: mergedCategories,
+                });
+            }
+            else {
+                // New month - use as-is
+                byMonth.set(deltaMonth.month, deltaMonth);
+            }
+        }
+    }
+    return Array.from(byMonth.values());
+}
+/**
+ * Count changes in a delta array.
+ *
+ * @param delta - The delta array from the API
+ * @returns The number of entities in the delta
+ */
+function countChanges(delta) {
+    return delta?.length ?? 0;
+}
+/**
+ * Merge a delta sync response into an existing LocalBudget.
+ * Returns a new LocalBudget with the merged data.
+ *
+ * @param existing - The current LocalBudget
+ * @param deltaBudget - The delta BudgetDetail from YNAB API
+ * @param newServerKnowledge - The new server_knowledge from the delta response
+ * @returns A new LocalBudget with merged data and change counts
+ */
+export function mergeDelta(existing, deltaBudget, newServerKnowledge) {
+    // Count changes before merging
+    const changesReceived = {
+        accounts: countChanges(deltaBudget.accounts),
+        categories: countChanges(deltaBudget.categories),
+        months: countChanges(deltaBudget.months),
+        payees: countChanges(deltaBudget.payees),
+        scheduledTransactions: countChanges(deltaBudget.scheduled_transactions),
+        transactions: countChanges(deltaBudget.transactions),
+    };
+    // Create new LocalBudget with merged arrays
+    const localBudget = {
+        // Lookup maps (will be rebuilt)
+        accountById: new Map(),
+        accountByName: new Map(),
+        // Merge all entity arrays
+        accounts: mergeEntityArray(existing.accounts, deltaBudget.accounts ?? []),
+        // Budget identity (unchanged)
+        budgetId: existing.budgetId,
+        budgetName: deltaBudget.name ?? existing.budgetName,
+        categories: mergeEntityArray(existing.categories, deltaBudget.categories ?? []),
+        categoryById: new Map(),
+        categoryByName: new Map(),
+        categoryGroupNameById: new Map(),
+        categoryGroups: mergeEntityArray(existing.categoryGroups, deltaBudget.category_groups ?? []),
+        // Budget settings (may be updated)
+        currencyFormat: deltaBudget.currency_format ?? existing.currencyFormat,
+        // Update sync metadata
+        lastSyncedAt: new Date(),
+        months: mergeMonthArray(existing.months, deltaBudget.months ?? []),
+        needsSync: false,
+        payeeById: new Map(),
+        payeeLocations: mergeEntityArray(existing.payeeLocations, deltaBudget.payee_locations ?? []),
+        payees: mergeEntityArray(existing.payees, deltaBudget.payees ?? []),
+        scheduledSubtransactions: mergeEntityArray(existing.scheduledSubtransactions, deltaBudget.scheduled_subtransactions ?? []),
+        scheduledSubtransactionsByScheduledTransactionId: new Map(),
+        scheduledTransactions: mergeEntityArray(existing.scheduledTransactions, deltaBudget.scheduled_transactions ?? []),
+        serverKnowledge: newServerKnowledge,
+        subtransactions: mergeEntityArray(existing.subtransactions, deltaBudget.subtransactions ?? []),
+        subtransactionsByTransactionId: new Map(),
+        transactions: mergeEntityArray(existing.transactions, deltaBudget.transactions ?? []),
+    };
+    // Rebuild lookup maps
+    rebuildLookupMaps(localBudget);
+    return { changesReceived, localBudget };
+}
+/**
+ * Compare two LocalBudgets and report any discrepancies.
+ * Useful for sanity checking after a full re-fetch.
+ *
+ * @param local - The local budget (before full re-fetch)
+ * @param remote - The remote budget (from full re-fetch)
+ * @returns Array of discrepancy descriptions, empty if no drift
+ */
+export function detectDrift(local, remote) {
+    const discrepancies = [];
+    // Check array lengths
+    const checks = [
+        { field: 'accounts', name: 'accounts' },
+        { field: 'categories', name: 'categories' },
+        { field: 'categoryGroups', name: 'categoryGroups' },
+        { field: 'months', name: 'months' },
+        { field: 'payees', name: 'payees' },
+        { field: 'transactions', name: 'transactions' },
+        { field: 'scheduledTransactions', name: 'scheduledTransactions' },
+    ];
+    for (const { field, name } of checks) {
+        const localArray = local[field];
+        const remoteArray = remote[field];
+        if (localArray.length !== remoteArray.length) {
+            discrepancies.push(`${name}: local=${localArray.length}, remote=${remoteArray.length}, drift=${remoteArray.length - localArray.length}`);
+        }
+    }
+    return discrepancies;
+}

package/dist/logger.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pino-based logger for the MCP server.
+ *
+ * Writes JSON logs to ~/.config/ynab-mcp-deluxe/logs/ with date-based rotation.
+ * Use `bun run logs` to tail the log file, optionally piping through pino-pretty.
+ */
+/**
+ * Logger that implements FastMCP's Logger interface.
+ * Wraps pino to write structured JSON logs to a rotating file.
+ */
+export declare const logger: {
+    debug(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+};
+/**
+ * Context logger interface (matches FastMCP's context.log)
+ */
+interface ContextLog {
+    debug: (message: string, data?: unknown) => void;
+    error: (message: string, data?: unknown) => void;
+    info: (message: string, data?: unknown) => void;
+    warn: (message: string, data?: unknown) => void;
+}
+/**
+ * File-only logger for use when there's no context logger available.
+ * Writes directly to the pino log file.
+ */
+export declare const fileLogger: ContextLog;
+/**
+ * Create a combined logger that writes to both the file logger and a context logger.
+ * This ensures logs are visible both in `bun run logs` and in MCP clients that surface context logs.
+ *
+ * @param contextLog - The FastMCP context logger (from tool execute context)
+ * @returns A logger that writes to both destinations
+ */
+export declare function createCombinedLogger(contextLog: ContextLog): ContextLog;
+/**
+ * Get the glob pattern for log files.
+ * pino-roll names files as server.N.log where N is the rotation counter.
+ */
+export declare function getLogFilePattern(): string;
+/**
+ * Get the log directory path.
+ */
+export declare function getLogDir(): string;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoDH;;;GAGG;AACH,eAAO,MAAM,MAAM;mBACF,OAAO,EAAE,GAAG,IAAI;mBAGhB,OAAO,EAAE,GAAG,IAAI;kBAGjB,OAAO,EAAE,GAAG,IAAI;iBAGjB,OAAO,EAAE,GAAG,IAAI;kBAIf,OAAO,EAAE,GAAG,IAAI;CAG/B,CAAC;AAEF;;GAEG;AACH,UAAU,UAAU;IAClB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACjD;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,UAaxB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAwBvE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC"}