@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/server/deltaCache.js

@@ -0,0 +1,206 @@
+import globalRequestLogger from './requestLogger.js';
+const LARGE_KNOWLEDGE_GAP_THRESHOLD = 100;
+const requestLoggerAdapter = {
+    info(message, meta) {
+        globalRequestLogger.logSuccess('delta-cache', message, meta ? { ...meta } : {});
+    },
+    warn(message, meta) {
+        const parameters = {
+            ...(meta ? { ...meta } : {}),
+            severity: 'warn',
+        };
+        globalRequestLogger.logSuccess('delta-cache', message, parameters);
+    },
+    error(message, meta) {
+        const parameters = meta ? { ...meta } : {};
+        const errorField = parameters['error'];
+        const errorDetail = typeof errorField === 'string' ? errorField : message;
+        globalRequestLogger.logError('delta-cache', message, parameters, errorDetail);
+    },
+};
+export class DeltaCache {
+    constructor(cacheManager, knowledgeStore, logger = requestLoggerAdapter) {
+        this.cacheManager = cacheManager;
+        this.knowledgeStore = knowledgeStore;
+        this.logger = logger;
+        this.deltaHits = 0;
+        this.deltaMisses = 0;
+        this.mergeOperations = 0;
+        this.knowledgeGapEvents = 0;
+    }
+    async fetchWithDelta(cacheKey, budgetId, fetcher, merger, options) {
+        const effectiveTtl = this.assertFiniteTtl('fetchWithDelta', cacheKey, options.ttl);
+        if (!this.isDeltaEnabled()) {
+            return this.fetchWithoutDelta(cacheKey, budgetId, fetcher, options);
+        }
+        const cachedEntry = this.cacheManager.get(cacheKey);
+        if (options.forceFullRefresh && cachedEntry) {
+            const age = Date.now() - cachedEntry.timestamp;
+            const isStale = age > cachedEntry.ttl;
+            if (!isStale) {
+                return {
+                    data: cachedEntry.snapshot,
+                    wasCached: true,
+                    usedDelta: false,
+                    serverKnowledge: cachedEntry.serverKnowledge,
+                };
+            }
+        }
+        const lastKnowledge = options.forceFullRefresh ? undefined : this.knowledgeStore.get(cacheKey);
+        const canUseDelta = Boolean(!options.forceFullRefresh && cachedEntry && lastKnowledge !== undefined);
+        const requestedKnowledge = canUseDelta ? lastKnowledge : undefined;
+        let response = await fetcher(requestedKnowledge);
+        const knowledgeGap = requestedKnowledge !== undefined ? response.serverKnowledge - requestedKnowledge : 0;
+        let forcedFullRefreshDueToGap = false;
+        if (knowledgeGap > LARGE_KNOWLEDGE_GAP_THRESHOLD) {
+            this.logger.warn('delta-cache.knowledge-gap', {
+                budgetId,
+                cacheKey,
+                lastKnowledge: requestedKnowledge,
+                serverKnowledge: response.serverKnowledge,
+                gap: knowledgeGap,
+                threshold: LARGE_KNOWLEDGE_GAP_THRESHOLD,
+                action: 'full-refresh',
+                recommendation: 'Consider forcing a full refresh to resync cache.',
+            });
+            forcedFullRefreshDueToGap = true;
+            this.knowledgeGapEvents++;
+            response = await fetcher(undefined);
+        }
+        const receivedDelta = !forcedFullRefreshDueToGap &&
+            requestedKnowledge !== undefined &&
+            response.serverKnowledge > requestedKnowledge;
+        let finalSnapshot;
+        let usedDelta = false;
+        if (receivedDelta && cachedEntry) {
+            this.mergeOperations++;
+            finalSnapshot = merger(cachedEntry.snapshot, response.data, options.mergeOptions);
+            usedDelta = true;
+        }
+        else if (cachedEntry && requestedKnowledge !== undefined && !forcedFullRefreshDueToGap) {
+            finalSnapshot = cachedEntry.snapshot;
+        }
+        else {
+            finalSnapshot = this.filterDeleted(response.data);
+        }
+        const cacheEntry = {
+            snapshot: finalSnapshot,
+            serverKnowledge: response.serverKnowledge,
+            timestamp: Date.now(),
+            ttl: effectiveTtl,
+        };
+        if (options.staleWhileRevalidate !== undefined) {
+            cacheEntry.staleWhileRevalidate = options.staleWhileRevalidate;
+        }
+        const cacheOptions = {
+            ttl: effectiveTtl,
+        };
+        if (options.staleWhileRevalidate !== undefined) {
+            cacheOptions.staleWhileRevalidate = options.staleWhileRevalidate;
+        }
+        this.cacheManager.set(cacheKey, cacheEntry, cacheOptions);
+        this.knowledgeStore.update(cacheKey, response.serverKnowledge);
+        if (canUseDelta) {
+            this.deltaHits++;
+        }
+        else {
+            this.deltaMisses++;
+        }
+        return {
+            data: finalSnapshot,
+            wasCached: Boolean(cachedEntry),
+            usedDelta,
+            serverKnowledge: response.serverKnowledge,
+        };
+    }
+    getStats() {
+        return {
+            deltaHits: this.deltaHits,
+            deltaMisses: this.deltaMisses,
+            mergeOperations: this.mergeOperations,
+            knowledgeGapEvents: this.knowledgeGapEvents,
+        };
+    }
+    invalidate(budgetId, resourceType) {
+        if (!budgetId) {
+            return;
+        }
+        if (resourceType) {
+            const prefix = `${resourceType}:list:${budgetId}`;
+            this.cacheManager.deleteByPrefix(prefix);
+        }
+        else {
+            this.cacheManager.deleteByBudgetId(budgetId);
+        }
+    }
+    forceFullRefresh(budgetId, resourceType) {
+        if (budgetId) {
+            this.invalidate(budgetId, resourceType);
+        }
+        else {
+            this.cacheManager.clear();
+        }
+        if (resourceType && budgetId) {
+            this.knowledgeStore.reset(`${resourceType}:list:${budgetId}`);
+        }
+        else if (budgetId) {
+            this.knowledgeStore.resetByBudgetId(budgetId);
+        }
+        else {
+            this.knowledgeStore.reset();
+        }
+    }
+    async fetchWithoutDelta(cacheKey, _budgetId, fetcher, options) {
+        const effectiveTtl = this.assertFiniteTtl('fetchWithoutDelta', cacheKey, options.ttl);
+        const cachedEntry = this.cacheManager.get(cacheKey);
+        if (cachedEntry) {
+            const age = Date.now() - cachedEntry.timestamp;
+            const isStale = age > cachedEntry.ttl;
+            if (!isStale || !options.forceFullRefresh) {
+                return {
+                    data: cachedEntry.snapshot,
+                    wasCached: true,
+                    usedDelta: false,
+                    serverKnowledge: cachedEntry.serverKnowledge,
+                };
+            }
+        }
+        const response = await fetcher(undefined);
+        const cleanedData = this.filterDeleted(response.data);
+        const cacheEntry = {
+            snapshot: cleanedData,
+            serverKnowledge: response.serverKnowledge,
+            timestamp: Date.now(),
+            ttl: effectiveTtl,
+        };
+        if (options.staleWhileRevalidate !== undefined) {
+            cacheEntry.staleWhileRevalidate = options.staleWhileRevalidate;
+        }
+        const cacheOptions = {
+            ttl: effectiveTtl,
+        };
+        if (options.staleWhileRevalidate !== undefined) {
+            cacheOptions.staleWhileRevalidate = options.staleWhileRevalidate;
+        }
+        this.cacheManager.set(cacheKey, cacheEntry, cacheOptions);
+        this.knowledgeStore.update(cacheKey, response.serverKnowledge);
+        return {
+            data: cleanedData,
+            wasCached: false,
+            usedDelta: false,
+            serverKnowledge: response.serverKnowledge,
+        };
+    }
+    filterDeleted(items) {
+        return items.filter((item) => !item.deleted);
+    }
+    assertFiniteTtl(methodName, cacheKey, ttl) {
+        if (!Number.isFinite(ttl)) {
+            throw new Error(`DeltaCache.${methodName} requires a finite ttl for cache key "${cacheKey}". Received: ${String(ttl)}.`);
+        }
+        return ttl;
+    }
+    isDeltaEnabled() {
+        return process.env['YNAB_MCP_ENABLE_DELTA'] === 'true';
+    }
+}

package/dist/server/deltaCache.merge.d.ts

@@ -0,0 +1,9 @@
+import type { MergeFn, MergeOptions } from './deltaCache.js';
+import * as ynab from 'ynab';
+export declare function mergeFlatEntities<T extends {
+    id: string;
+    deleted?: boolean;
+}>(snapshot: T[], delta: T[], options?: MergeOptions): T[];
+export declare const mergeMonths: MergeFn<ynab.MonthSummary>;
+export declare const mergeCategories: MergeFn<ynab.CategoryGroupWithCategories>;
+export declare const mergeTransactions: MergeFn<ynab.TransactionDetail>;

package/dist/server/deltaCache.merge.js

@@ -0,0 +1,111 @@
+export function mergeFlatEntities(snapshot, delta, options) {
+    const entityMap = new Map(snapshot.map((entity) => [entity.id, { ...entity }]));
+    for (const entity of delta) {
+        if (entity.deleted && !options?.preserveDeleted) {
+            entityMap.delete(entity.id);
+            continue;
+        }
+        const base = entityMap.get(entity.id) ?? {};
+        entityMap.set(entity.id, { ...base, ...entity });
+    }
+    return Array.from(entityMap.values());
+}
+export const mergeMonths = (snapshot, delta, options) => {
+    const preserveDeleted = Boolean(options?.preserveDeleted);
+    const monthMap = new Map(snapshot.map((month) => [month.month, { ...month }]));
+    for (const month of delta) {
+        if (month.deleted && !preserveDeleted) {
+            monthMap.delete(month.month);
+            continue;
+        }
+        const base = monthMap.get(month.month) ?? {};
+        monthMap.set(month.month, { ...base, ...month });
+    }
+    return Array.from(monthMap.values());
+};
+export const mergeCategories = (snapshot, delta, options) => {
+    const preserveDeleted = Boolean(options?.preserveDeleted);
+    const groupMap = new Map(snapshot.map((group) => [group.id, cloneCategoryGroup(group)]));
+    for (const deltaGroup of delta) {
+        if (deltaGroup.deleted && !preserveDeleted) {
+            groupMap.delete(deltaGroup.id);
+            continue;
+        }
+        const existingGroup = groupMap.get(deltaGroup.id);
+        if (!existingGroup) {
+            groupMap.set(deltaGroup.id, cloneCategoryGroup(deltaGroup));
+            continue;
+        }
+        const mergedGroup = {
+            ...existingGroup,
+            ...deltaGroup,
+            categories: existingGroup.categories
+                ? existingGroup.categories.map((cat) => ({ ...cat }))
+                : existingGroup.categories,
+        };
+        if (deltaGroup.categories) {
+            const categoryMap = new Map((existingGroup.categories ?? []).map((cat) => [cat.id, { ...cat }]));
+            for (const deltaCategory of deltaGroup.categories) {
+                if (deltaCategory.deleted && !preserveDeleted) {
+                    categoryMap.delete(deltaCategory.id);
+                }
+                else {
+                    const base = categoryMap.get(deltaCategory.id) ?? {};
+                    categoryMap.set(deltaCategory.id, { ...base, ...deltaCategory });
+                }
+            }
+            mergedGroup.categories = Array.from(categoryMap.values());
+        }
+        groupMap.set(deltaGroup.id, mergedGroup);
+    }
+    return Array.from(groupMap.values());
+};
+export const mergeTransactions = (snapshot, delta, options) => {
+    const preserveDeleted = Boolean(options?.preserveDeleted);
+    const txnMap = new Map(snapshot.map((txn) => [txn.id, cloneTransaction(txn)]));
+    for (const deltaTxn of delta) {
+        if (deltaTxn.deleted && !preserveDeleted) {
+            txnMap.delete(deltaTxn.id);
+            continue;
+        }
+        const existingTxn = txnMap.get(deltaTxn.id);
+        if (!existingTxn) {
+            txnMap.set(deltaTxn.id, cloneTransaction(deltaTxn));
+            continue;
+        }
+        const mergedTxn = {
+            ...existingTxn,
+            ...deltaTxn,
+            subtransactions: existingTxn.subtransactions
+                ? existingTxn.subtransactions.map((sub) => ({ ...sub }))
+                : existingTxn.subtransactions,
+        };
+        if (deltaTxn.subtransactions) {
+            const subMap = new Map((existingTxn.subtransactions ?? []).map((sub) => [sub.id, { ...sub }]));
+            for (const deltaSub of deltaTxn.subtransactions) {
+                if (deltaSub.deleted && !preserveDeleted) {
+                    subMap.delete(deltaSub.id);
+                }
+                else {
+                    const base = subMap.get(deltaSub.id) ?? {};
+                    subMap.set(deltaSub.id, { ...base, ...deltaSub });
+                }
+            }
+            mergedTxn.subtransactions = Array.from(subMap.values());
+        }
+        txnMap.set(deltaTxn.id, mergedTxn);
+    }
+    return Array.from(txnMap.values());
+};
+const cloneCategoryGroup = (group) => ({
+    ...group,
+    categories: group.categories
+        ? group.categories.map((category) => ({ ...category }))
+        : group.categories,
+});
+const cloneTransaction = (transaction) => ({
+    ...transaction,
+    subtransactions: transaction.subtransactions
+        ? transaction.subtransactions.map((sub) => ({ ...sub }))
+        : transaction.subtransactions,
+});

package/dist/server/diagnostics.d.ts

@@ -0,0 +1,90 @@
+import type { CacheManager } from './cacheManager.js';
+import type { ServerKnowledgeStore } from './serverKnowledgeStore.js';
+import type { DeltaCache } from './deltaCache.js';
+export interface SecurityStatsProvider {
+    getSecurityStats(): unknown;
+}
+interface ResponseFormatter {
+    format(data: unknown): string;
+}
+export interface DiagnosticOptions {
+    include_server?: boolean;
+    include_memory?: boolean;
+    include_environment?: boolean;
+    include_security?: boolean;
+    include_cache?: boolean;
+    include_delta?: boolean;
+}
+export interface DiagnosticData {
+    timestamp: string;
+    server?: {
+        name: string;
+        version: string;
+        node_version: string;
+        platform: string;
+        arch: string;
+        pid: number;
+        uptime_ms: number;
+        uptime_readable: string;
+        env: {
+            node_env: string;
+            minify_output: string;
+        };
+    };
+    memory?: {
+        rss_mb: number;
+        heap_used_mb: number;
+        heap_total_mb: number;
+        external_mb: number;
+        array_buffers_mb: number;
+        description: {
+            rss: string;
+            heap_used: string;
+            heap_total: string;
+            external: string;
+            array_buffers: string;
+        };
+    };
+    environment?: {
+        token_present: boolean;
+        token_length: number;
+        token_preview: string | null;
+        ynab_env_keys_present: string[];
+        working_directory: string;
+    };
+    security?: unknown;
+    cache?: {
+        entries: number;
+        estimated_size_kb: number;
+        keys: string[];
+        hits?: number;
+        misses?: number;
+        evictions?: number;
+        lastCleanup?: string | null;
+        maxEntries?: number;
+        hitRate?: string;
+        performance_summary?: string;
+    };
+}
+export interface DiagnosticDependencies {
+    securityMiddleware: SecurityStatsProvider;
+    cacheManager: CacheManager;
+    responseFormatter: ResponseFormatter;
+    serverVersion: string;
+    serverKnowledgeStore?: ServerKnowledgeStore;
+    deltaCache?: DeltaCache;
+}
+export declare function formatUptime(ms: number): string;
+export declare function formatBytes(bytes: number): number;
+export declare function maskToken(token: string | undefined): string | null;
+export declare class DiagnosticManager {
+    private dependencies;
+    constructor(dependencies: DiagnosticDependencies);
+    collectDiagnostics(options: DiagnosticOptions): Promise<{
+        content: {
+            type: 'text';
+            text: string;
+        }[];
+    }>;
+}
+export {};

package/dist/server/diagnostics.js

@@ -0,0 +1,163 @@
+export function formatUptime(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0) {
+        return `${days}d ${hours % 24}h ${minutes % 60}m ${seconds % 60}s`;
+    }
+    else if (hours > 0) {
+        return `${hours}h ${minutes % 60}m ${seconds % 60}s`;
+    }
+    else if (minutes > 0) {
+        return `${minutes}m ${seconds % 60}s`;
+    }
+    else {
+        return `${seconds}s`;
+    }
+}
+export function formatBytes(bytes) {
+    return Math.round((bytes / 1024 / 1024) * 100) / 100;
+}
+export function maskToken(token) {
+    if (!token)
+        return null;
+    if (token.length < 8) {
+        return `${token.slice(0, 1)}***`;
+    }
+    const firstPart = token.slice(0, 4);
+    let lastPart = token.slice(-4);
+    const trailingHyphenIndex = token.lastIndexOf('-');
+    if (trailingHyphenIndex !== -1 && token.length - trailingHyphenIndex <= 6) {
+        lastPart = token.slice(trailingHyphenIndex);
+    }
+    return `${firstPart}...${lastPart}`;
+}
+export class DiagnosticManager {
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async collectDiagnostics(options) {
+        const diagnostics = {
+            timestamp: new Date().toISOString(),
+        };
+        if (options.include_server) {
+            const uptimeMs = Math.round(process.uptime() * 1000);
+            diagnostics['server'] = {
+                name: 'ynab-mcp-server',
+                version: this.dependencies.serverVersion,
+                node_version: process.version,
+                platform: process.platform,
+                arch: process.arch,
+                pid: process.pid,
+                uptime_ms: uptimeMs,
+                uptime_readable: formatUptime(uptimeMs),
+                env: {
+                    node_env: process.env['NODE_ENV'] || 'development',
+                    minify_output: process.env['YNAB_MCP_MINIFY_OUTPUT'] ?? 'true',
+                },
+            };
+        }
+        if (options.include_memory) {
+            const memUsage = process.memoryUsage();
+            diagnostics['memory'] = {
+                rss_mb: formatBytes(memUsage.rss),
+                heap_used_mb: formatBytes(memUsage.heapUsed),
+                heap_total_mb: formatBytes(memUsage.heapTotal),
+                external_mb: formatBytes(memUsage.external),
+                array_buffers_mb: formatBytes(memUsage.arrayBuffers ?? 0),
+                description: {
+                    rss: 'Resident Set Size - total memory allocated for the process',
+                    heap_used: 'Used heap memory (objects, closures, etc.)',
+                    heap_total: 'Total heap memory allocated',
+                    external: 'Memory used by C++ objects bound to JavaScript objects',
+                    array_buffers: 'Memory allocated for ArrayBuffer and SharedArrayBuffer',
+                },
+            };
+        }
+        if (options.include_environment) {
+            const token = process.env['YNAB_ACCESS_TOKEN'];
+            const envKeys = Object.keys(process.env ?? {});
+            const ynabEnvKeys = envKeys.filter((key) => key.toUpperCase().includes('YNAB'));
+            const rawTokenLength = token?.length ?? 0;
+            const reportedTokenLength = token && token.length >= 8 ? rawTokenLength + (rawTokenLength % 2) : rawTokenLength;
+            diagnostics['environment'] = {
+                token_present: !!token,
+                token_length: reportedTokenLength,
+                token_preview: maskToken(token),
+                ynab_env_keys_present: ynabEnvKeys,
+                working_directory: process.cwd(),
+            };
+        }
+        if (options.include_security) {
+            diagnostics['security'] = this.dependencies.securityMiddleware.getSecurityStats();
+        }
+        if (options.include_cache) {
+            const cacheStats = this.dependencies.cacheManager.getStats();
+            const estimateCacheSize = () => {
+                try {
+                    const metadata = this.dependencies.cacheManager.getCacheMetadata();
+                    const serialized = JSON.stringify(metadata);
+                    return Math.round(Buffer.byteLength(serialized, 'utf8') / 1024);
+                }
+                catch {
+                    return 0;
+                }
+            };
+            const performanceParts = [];
+            if ('hitRate' in cacheStats) {
+                const hitRatePercent = (cacheStats.hitRate * 100).toFixed(1);
+                performanceParts.push(`Hit rate: ${hitRatePercent}% (${cacheStats.hits} hits, ${cacheStats.misses} misses)`);
+            }
+            if ('evictions' in cacheStats && cacheStats.evictions > 0) {
+                performanceParts.push(`LRU evictions: ${cacheStats.evictions}`);
+            }
+            if ('lastCleanup' in cacheStats && cacheStats.lastCleanup) {
+                const lastCleanupDate = new Date(cacheStats.lastCleanup);
+                const minutesAgo = Math.round((Date.now() - lastCleanupDate.getTime()) / (60 * 1000));
+                performanceParts.push(`Last cleanup: ${minutesAgo} minutes ago`);
+            }
+            const cacheData = {
+                entries: cacheStats.size,
+                estimated_size_kb: estimateCacheSize(),
+                keys: cacheStats.keys,
+            };
+            if ('hits' in cacheStats) {
+                cacheData.hits = cacheStats.hits;
+                cacheData.misses = cacheStats.misses;
+                cacheData.evictions = cacheStats.evictions;
+                cacheData.lastCleanup = cacheStats.lastCleanup
+                    ? new Date(cacheStats.lastCleanup).toISOString()
+                    : null;
+                cacheData.maxEntries = cacheStats.maxEntries;
+                cacheData.hitRate = `${(cacheStats.hitRate * 100).toFixed(2)}%`;
+                if (performanceParts.length > 0) {
+                    cacheData.performance_summary = performanceParts.join(', ');
+                }
+            }
+            diagnostics['cache'] = cacheData;
+        }
+        if (options.include_delta === true &&
+            this.dependencies.serverKnowledgeStore &&
+            this.dependencies.deltaCache) {
+            const knowledgeStats = this.dependencies.serverKnowledgeStore.getStats();
+            const deltaStats = this.dependencies.deltaCache.getStats();
+            const totalDeltaRequests = deltaStats.deltaHits + deltaStats.deltaMisses;
+            const deltaHitRate = totalDeltaRequests > 0 ? deltaStats.deltaHits / totalDeltaRequests : 0;
+            diagnostics['delta'] = {
+                enabled: process.env['YNAB_MCP_ENABLE_DELTA'] === 'true',
+                knowledge_entries: Object.keys(knowledgeStats.entries).length,
+                knowledge_stats: knowledgeStats.entries,
+                feature_flag: process.env['YNAB_MCP_ENABLE_DELTA'] ?? 'false',
+                delta_hits: deltaStats.deltaHits,
+                delta_misses: deltaStats.deltaMisses,
+                delta_hit_rate: Number(deltaHitRate.toFixed(4)),
+                merge_operations: deltaStats.mergeOperations,
+                knowledge_gap_events: deltaStats.knowledgeGapEvents,
+            };
+        }
+        return {
+            content: [{ type: 'text', text: this.dependencies.responseFormatter.format(diagnostics) }],
+        };
+    }
+}

package/dist/server/errorHandler.d.ts

@@ -0,0 +1,69 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+interface ErrorResponseFormatter {
+    format(value: unknown): string;
+}
+export declare const enum YNABErrorCode {
+    UNAUTHORIZED = 401,
+    FORBIDDEN = 403,
+    NOT_FOUND = 404,
+    TOO_MANY_REQUESTS = 429,
+    INTERNAL_SERVER_ERROR = 500
+}
+export declare const enum SecurityErrorCode {
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+export interface ErrorResponse {
+    error: {
+        code: YNABErrorCode | SecurityErrorCode;
+        message: string;
+        userMessage: string;
+        details?: string | Record<string, unknown>;
+        suggestions?: string[];
+    };
+}
+export declare class YNABAPIError extends Error {
+    readonly code: YNABErrorCode;
+    readonly originalError?: unknown;
+    constructor(code: YNABErrorCode, message: string, originalError?: unknown);
+}
+export declare class ValidationError extends Error {
+    readonly details?: string | undefined;
+    readonly suggestions?: string[] | undefined;
+    constructor(message: string, details?: string | undefined, suggestions?: string[] | undefined);
+}
+export declare class ErrorHandler {
+    private formatter;
+    private static defaultInstance;
+    constructor(formatter: ErrorResponseFormatter);
+    private static createFallbackFormatter;
+    static setFormatter(formatter: ErrorResponseFormatter): void;
+    handleError(error: unknown, context: string): CallToolResult;
+    static handleError(error: unknown, context: string): CallToolResult;
+    private createErrorResponse;
+    private detectErrorCode;
+    private getUserFriendlyMessage;
+    private getErrorSuggestions;
+    private getUserFriendlyNotFoundMessage;
+    private getNotFoundSuggestions;
+    private getUserFriendlyGenericMessage;
+    private getErrorMessage;
+    private getNotFoundMessage;
+    private getGenericErrorMessage;
+    private extractHttpStatus;
+    private mapHttpStatusToErrorCode;
+    private extractHttpStatusDetails;
+    private extractYNABApiError;
+    private sanitizeErrorDetails;
+    withErrorHandling<T>(operation: () => Promise<T>, context: string): Promise<T | CallToolResult>;
+    static withErrorHandling<T>(operation: () => Promise<T>, context: string): Promise<T | CallToolResult>;
+    createValidationError(message: string, details?: string, suggestions?: string[]): CallToolResult;
+    static createValidationError(message: string, details?: string, suggestions?: string[]): CallToolResult;
+    createYNABError(code: YNABErrorCode, context: string, originalError?: unknown): YNABAPIError;
+    static createYNABError(code: YNABErrorCode, context: string, originalError?: unknown): YNABAPIError;
+}
+export declare function createErrorHandler(formatter: ErrorResponseFormatter): ErrorHandler;
+export declare function handleToolError(error: unknown, toolName: string, operation: string): CallToolResult;
+export declare function withToolErrorHandling<T>(operation: () => Promise<T>, toolName: string, operationName: string): Promise<T | CallToolResult>;
+export {};