@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/server/prompts.js

@@ -0,0 +1,205 @@
+const defaultPromptDefinitions = [
+    {
+        name: 'create-transaction',
+        description: 'Create a new transaction in YNAB',
+        arguments: [
+            {
+                name: 'budget_name',
+                description: 'Name of the budget (optional, uses first budget if not specified)',
+                required: false,
+            },
+            {
+                name: 'account_name',
+                description: 'Name of the account',
+                required: true,
+            },
+            {
+                name: 'amount',
+                description: 'Transaction amount (negative for expenses, positive for income)',
+                required: true,
+            },
+            {
+                name: 'payee',
+                description: 'Who you paid or received money from',
+                required: true,
+            },
+            {
+                name: 'category',
+                description: 'Budget category (optional)',
+                required: false,
+            },
+            {
+                name: 'memo',
+                description: 'Additional notes (optional)',
+                required: false,
+            },
+        ],
+    },
+    {
+        name: 'budget-summary',
+        description: 'Get a summary of your budget status',
+        arguments: [
+            {
+                name: 'budget_name',
+                description: 'Name of the budget (optional, uses first budget if not specified)',
+                required: false,
+            },
+            {
+                name: 'month',
+                description: 'Month to analyze (YYYY-MM format, optional, uses current month if not specified)',
+                required: false,
+            },
+        ],
+    },
+    {
+        name: 'account-balances',
+        description: 'Check balances across all accounts',
+        arguments: [
+            {
+                name: 'budget_name',
+                description: 'Name of the budget (optional, uses first budget if not specified)',
+                required: false,
+            },
+            {
+                name: 'account_type',
+                description: 'Filter by account type (checking, savings, creditCard, etc.)',
+                required: false,
+            },
+        ],
+    },
+];
+const defaultPromptHandlers = {
+    'create-transaction': async (_name, args) => {
+        const budgetName = args?.['budget_name'] || 'first available budget';
+        const accountName = args?.['account_name'] || '[ACCOUNT_NAME]';
+        const amount = args?.['amount'] || '[AMOUNT]';
+        const payee = args?.['payee'] || '[PAYEE]';
+        const category = args?.['category'] || '[CATEGORY]';
+        const memo = args?.['memo'] || '';
+        return {
+            description: `Create a transaction for ${payee} in ${accountName}`,
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Please create a transaction with the following details:
+- Budget: ${budgetName}
+- Account: ${accountName}
+- Amount: $${amount}
+- Payee: ${payee}
+- Category: ${category}
+- Memo: ${memo}
+
+Use the appropriate YNAB MCP tools to:
+1. First, list budgets to find the budget ID
+2. List accounts for that budget to find the account ID
+3. If a category is specified, list categories to find the category ID
+4. Create the transaction with the correct amount in milliunits (multiply by 1000)
+5. Confirm the transaction was created successfully`,
+                    },
+                },
+            ],
+        };
+    },
+    'budget-summary': async (_name, args) => {
+        const summaryBudget = args?.['budget_name'] || 'first available budget';
+        const month = args?.['month'] || 'current month';
+        return {
+            description: `Get budget summary for ${summaryBudget}`,
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Please provide a comprehensive budget summary for ${summaryBudget} (${month}):
+
+IMPORTANT: In YNAB, understand these key fields:
+- budgeted: Amount assigned to the category this month
+- activity: Spending/income in the category this month (negative = spending)
+- balance: Available amount in the category = previous balance + budgeted + activity
+- OVERSPENDING occurs when balance < 0 (Available goes negative), NOT when spending > budgeted for the month
+
+SPENDING TRENDS: The analysis uses linear regression over multiple months to detect real spending patterns. Each trend includes:
+- explanation: User-friendly description of what the trend means
+- reliability_score: Confidence level (0-100%) indicating how reliable the trend is
+- data_points: Number of months used in the analysis
+Focus on trends with high reliability scores for actionable insights.
+
+BUDGET OPTIMIZATION: The system provides three types of optimization insights:
+1. "Consistently Under-Spent Categories" - Based on multi-month historical trends (reliable patterns)
+2. "Categories Over Monthly Assignment" - Current month only (spending > budgeted but Available still positive)
+3. "Large Unused Category Balances" - Categories with substantial unused funds
+Distinguish between current-month patterns vs historical trends when presenting insights.
+
+1. List all budgets and select the appropriate one
+2. Get monthly data for ${month}
+3. List categories to show budget vs actual spending
+4. Provide insights on:
+   - Total budgeted vs actual spending
+   - Categories where Available balance is negative (true overspending - when the category's balance field is < 0)
+   - Categories where spending exceeded this month's assignment (but still have positive Available balance)
+   - Available money to budget
+   - Any true overspending where categories went into the red (negative Available balance)
+
+Format the response in a clear, easy-to-read summary.`,
+                    },
+                },
+            ],
+        };
+    },
+    'account-balances': async (_name, args) => {
+        const balanceBudget = args?.['budget_name'] || 'first available budget';
+        const accountType = args?.['account_type'] || 'all accounts';
+        return {
+            description: `Check account balances for ${accountType}`,
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Please show account balances for ${balanceBudget}:
+
+1. List all budgets and select the appropriate one
+2. List accounts for that budget
+3. Filter by account type: ${accountType}
+4. Show balances in a clear format with:
+   - Account name and type
+   - Current balance
+   - Cleared vs uncleared amounts
+   - Total by account type
+   - Net worth summary (assets - liabilities)
+
+Convert milliunits to dollars for easy reading.`,
+                    },
+                },
+            ],
+        };
+    },
+};
+export class PromptManager {
+    constructor() {
+        this.promptDefinitions = [...defaultPromptDefinitions];
+        this.promptHandlers = { ...defaultPromptHandlers };
+    }
+    registerPrompt(definition, handler) {
+        this.promptDefinitions.push(definition);
+        this.promptHandlers[definition.name] = handler;
+    }
+    listPrompts() {
+        return {
+            prompts: this.promptDefinitions,
+        };
+    }
+    async getPrompt(name, args) {
+        const handler = this.promptHandlers[name];
+        if (!handler) {
+            throw new Error(`Unknown prompt: ${name}`);
+        }
+        const definition = this.promptDefinitions.find((p) => p.name === name);
+        if (!definition) {
+            throw new Error(`Prompt definition not found: ${name}`);
+        }
+        return await handler(name, args);
+    }
+}

package/dist/server/rateLimiter.d.ts

@@ -0,0 +1,27 @@
+export interface RateLimitConfig {
+    maxRequests: number;
+    windowMs: number;
+    enableLogging?: boolean;
+}
+export interface RateLimitInfo {
+    remaining: number;
+    resetTime: Date;
+    isLimited: boolean;
+}
+export declare class RateLimiter {
+    private requests;
+    private config;
+    constructor(config?: Partial<RateLimitConfig>);
+    isAllowed(identifier: string): RateLimitInfo;
+    recordRequest(identifier: string): void;
+    getStatus(identifier: string): RateLimitInfo;
+    reset(identifier?: string): void;
+    cleanup(): void;
+    private hashIdentifier;
+}
+export declare class RateLimitError extends Error {
+    readonly resetTime: Date;
+    readonly remaining: number;
+    constructor(message: string, resetTime: Date, remaining?: number);
+}
+export declare const globalRateLimiter: RateLimiter;

package/dist/server/rateLimiter.js

@@ -0,0 +1,82 @@
+export class RateLimiter {
+    constructor(config = {}) {
+        this.requests = new Map();
+        this.config = {
+            maxRequests: 200,
+            windowMs: 60 * 60 * 1000,
+            enableLogging: false,
+            ...config,
+        };
+    }
+    isAllowed(identifier) {
+        const now = Date.now();
+        const windowStart = now - this.config.windowMs;
+        let requests = this.requests.get(identifier) || [];
+        requests = requests.filter((timestamp) => timestamp > windowStart);
+        this.requests.set(identifier, requests);
+        const remaining = Math.max(0, this.config.maxRequests - requests.length);
+        const resetTime = new Date(now + this.config.windowMs);
+        const isLimited = requests.length >= this.config.maxRequests;
+        if (this.config.enableLogging) {
+            console.error(`Rate limit check for ${this.hashIdentifier(identifier)}: ${requests.length}/${this.config.maxRequests} requests, remaining: ${remaining}, limited: ${isLimited}`);
+        }
+        return {
+            remaining,
+            resetTime,
+            isLimited,
+        };
+    }
+    recordRequest(identifier) {
+        const now = Date.now();
+        const requests = this.requests.get(identifier) || [];
+        requests.push(now);
+        this.requests.set(identifier, requests);
+        if (this.config.enableLogging) {
+            console.error(`Recorded request for ${this.hashIdentifier(identifier)}: ${requests.length}/${this.config.maxRequests} requests`);
+        }
+    }
+    getStatus(identifier) {
+        return this.isAllowed(identifier);
+    }
+    reset(identifier) {
+        if (identifier) {
+            this.requests.delete(identifier);
+        }
+        else {
+            this.requests.clear();
+        }
+    }
+    cleanup() {
+        const now = Date.now();
+        const windowStart = now - this.config.windowMs;
+        for (const [identifier, requests] of this.requests.entries()) {
+            const validRequests = requests.filter((timestamp) => timestamp > windowStart);
+            if (validRequests.length === 0) {
+                this.requests.delete(identifier);
+            }
+            else {
+                this.requests.set(identifier, validRequests);
+            }
+        }
+    }
+    hashIdentifier(identifier) {
+        let hash = 0;
+        for (let i = 0; i < identifier.length; i++) {
+            const char = identifier.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash = hash & hash;
+        }
+        return `token_${Math.abs(hash).toString(16)}`;
+    }
+}
+export class RateLimitError extends Error {
+    constructor(message, resetTime, remaining = 0) {
+        super(message);
+        this.resetTime = resetTime;
+        this.remaining = remaining;
+        this.name = 'RateLimitError';
+    }
+}
+export const globalRateLimiter = new RateLimiter({
+    enableLogging: process.env['NODE_ENV'] !== 'production',
+});

package/dist/server/requestLogger.d.ts

@@ -0,0 +1,62 @@
+export interface LogEntry {
+    timestamp: Date;
+    toolName: string;
+    operation: string;
+    parameters: Record<string, unknown>;
+    success: boolean;
+    duration?: number;
+    error?: string;
+    rateLimitInfo?: {
+        remaining: number;
+        isLimited: boolean;
+    };
+}
+export interface LoggerConfig {
+    enabled: boolean;
+    logLevel: 'error' | 'warn' | 'info' | 'debug';
+    maxLogEntries: number;
+    sanitizeParameters: boolean;
+}
+export declare class RequestLogger {
+    private logs;
+    private config;
+    constructor(config?: Partial<LoggerConfig>);
+    logRequest(toolName: string, operation: string, parameters: Record<string, unknown>, success: boolean, duration?: number, error?: string, rateLimitInfo?: {
+        remaining: number;
+        isLimited: boolean;
+    }): void;
+    logSuccess(toolName: string, operation: string, parameters: Record<string, unknown>, duration?: number, rateLimitInfo?: {
+        remaining: number;
+        isLimited: boolean;
+    }): void;
+    logError(toolName: string, operation: string, parameters: Record<string, unknown>, error: string, duration?: number, rateLimitInfo?: {
+        remaining: number;
+        isLimited: boolean;
+    }): void;
+    getRecentLogs(count?: number): LogEntry[];
+    getFilteredLogs(filter: {
+        toolName?: string;
+        success?: boolean;
+        since?: Date;
+        limit?: number;
+    }): LogEntry[];
+    clearLogs(): void;
+    getStats(): {
+        totalRequests: number;
+        successfulRequests: number;
+        failedRequests: number;
+        averageDuration: number;
+        rateLimitedRequests: number;
+        toolUsage: Record<string, number>;
+    };
+    private sanitizeParameters;
+    private isSensitiveParameter;
+    private sanitizeString;
+    private sanitizeObject;
+    private sanitizeError;
+    private outputLog;
+    private shouldLog;
+    private formatLogMessage;
+}
+export declare const globalRequestLogger: RequestLogger;
+export default globalRequestLogger;

package/dist/server/requestLogger.js

@@ -0,0 +1,190 @@
+export class RequestLogger {
+    constructor(config = {}) {
+        this.logs = [];
+        this.config = {
+            enabled: process.env['NODE_ENV'] !== 'production',
+            logLevel: process.env['LOG_LEVEL'] || 'info',
+            maxLogEntries: 1000,
+            sanitizeParameters: true,
+            ...config,
+        };
+    }
+    logRequest(toolName, operation, parameters, success, duration, error, rateLimitInfo) {
+        if (!this.config.enabled)
+            return;
+        const logEntry = {
+            timestamp: new Date(),
+            toolName,
+            operation,
+            parameters: this.config.sanitizeParameters ? this.sanitizeParameters(parameters) : parameters,
+            success,
+            ...(duration !== undefined && { duration }),
+            ...(error && { error: this.sanitizeError(error) }),
+            ...(rateLimitInfo && { rateLimitInfo }),
+        };
+        this.logs.push(logEntry);
+        if (this.logs.length > this.config.maxLogEntries) {
+            this.logs.shift();
+        }
+        this.outputLog(logEntry);
+    }
+    logSuccess(toolName, operation, parameters, duration, rateLimitInfo) {
+        this.logRequest(toolName, operation, parameters, true, duration, undefined, rateLimitInfo);
+    }
+    logError(toolName, operation, parameters, error, duration, rateLimitInfo) {
+        this.logRequest(toolName, operation, parameters, false, duration, error, rateLimitInfo);
+    }
+    getRecentLogs(count = 50) {
+        return this.logs.slice(-count);
+    }
+    getFilteredLogs(filter) {
+        let filtered = this.logs;
+        if (filter.toolName) {
+            filtered = filtered.filter((log) => log.toolName === filter.toolName);
+        }
+        if (filter.success !== undefined) {
+            filtered = filtered.filter((log) => log.success === filter.success);
+        }
+        if (filter.since) {
+            filtered = filtered.filter((log) => log.timestamp >= filter.since);
+        }
+        if (filter.limit) {
+            filtered = filtered.slice(-filter.limit);
+        }
+        return filtered;
+    }
+    clearLogs() {
+        this.logs = [];
+    }
+    getStats() {
+        const totalRequests = this.logs.length;
+        const successfulRequests = this.logs.filter((log) => log.success).length;
+        const failedRequests = totalRequests - successfulRequests;
+        const durationsWithValues = this.logs
+            .filter((log) => log.duration !== undefined)
+            .map((log) => log.duration);
+        const averageDuration = durationsWithValues.length > 0
+            ? durationsWithValues.reduce((sum, duration) => sum + duration, 0) /
+                durationsWithValues.length
+            : 0;
+        const rateLimitedRequests = this.logs.filter((log) => log.rateLimitInfo?.isLimited).length;
+        const toolUsage = {};
+        this.logs.forEach((log) => {
+            toolUsage[log.toolName] = (toolUsage[log.toolName] || 0) + 1;
+        });
+        return {
+            totalRequests,
+            successfulRequests,
+            failedRequests,
+            averageDuration,
+            rateLimitedRequests,
+            toolUsage,
+        };
+    }
+    sanitizeParameters(parameters) {
+        const sanitized = {};
+        for (const [key, value] of Object.entries(parameters)) {
+            if (this.isSensitiveParameter(key)) {
+                sanitized[key] = '***';
+            }
+            else if (typeof value === 'string') {
+                sanitized[key] = this.sanitizeString(value);
+            }
+            else if (typeof value === 'object' && value !== null) {
+                sanitized[key] = this.sanitizeObject(value);
+            }
+            else {
+                sanitized[key] = value;
+            }
+        }
+        return sanitized;
+    }
+    isSensitiveParameter(key) {
+        const sensitiveKeys = [
+            'token',
+            'access_token',
+            'api_key',
+            'password',
+            'secret',
+            'authorization',
+            'auth',
+            'key',
+            'credential',
+        ];
+        return sensitiveKeys.some((sensitiveKey) => key.toLowerCase().includes(sensitiveKey));
+    }
+    sanitizeString(value) {
+        return value
+            .replace(/[a-zA-Z0-9]{30,}/g, '***')
+            .replace(/Bearer\s+[a-zA-Z0-9_-]+/gi, 'Bearer ***')
+            .replace(/token[s]?[:\s=]+[a-zA-Z0-9_-]+/gi, 'token=***')
+            .replace(/key[s]?[:\s=]+[a-zA-Z0-9_-]+/gi, 'key=***');
+    }
+    sanitizeObject(obj) {
+        if (Array.isArray(obj)) {
+            return obj.map((item) => typeof item === 'object' && item !== null ? this.sanitizeObject(item) : item);
+        }
+        if (typeof obj === 'object' && obj !== null) {
+            const sanitized = {};
+            for (const [key, value] of Object.entries(obj)) {
+                if (this.isSensitiveParameter(key)) {
+                    sanitized[key] = '***';
+                }
+                else if (typeof value === 'string') {
+                    sanitized[key] = this.sanitizeString(value);
+                }
+                else if (typeof value === 'object' && value !== null) {
+                    sanitized[key] = this.sanitizeObject(value);
+                }
+                else {
+                    sanitized[key] = value;
+                }
+            }
+            return sanitized;
+        }
+        return obj;
+    }
+    sanitizeError(error) {
+        return this.sanitizeString(error);
+    }
+    outputLog(logEntry) {
+        const logMessage = this.formatLogMessage(logEntry);
+        if (logEntry.success) {
+            if (this.shouldLog('info')) {
+                console.error(`[INFO] ${logMessage}`);
+            }
+        }
+        else {
+            if (this.shouldLog('error')) {
+                console.error(`[ERROR] ${logMessage}`);
+            }
+        }
+        if (logEntry.rateLimitInfo?.isLimited && this.shouldLog('warn')) {
+            console.error(`[WARN] Rate limit exceeded for ${logEntry.toolName}`);
+        }
+    }
+    shouldLog(level) {
+        const levels = ['error', 'warn', 'info', 'debug'];
+        const currentLevelIndex = levels.indexOf(this.config.logLevel);
+        const requestedLevelIndex = levels.indexOf(level);
+        return requestedLevelIndex <= currentLevelIndex;
+    }
+    formatLogMessage(logEntry) {
+        const parts = [
+            `${logEntry.toolName}:${logEntry.operation}`,
+            logEntry.success ? 'SUCCESS' : 'FAILED',
+        ];
+        if (logEntry.duration !== undefined) {
+            parts.push(`${logEntry.duration}ms`);
+        }
+        if (logEntry.rateLimitInfo) {
+            parts.push(`rate_limit_remaining:${logEntry.rateLimitInfo.remaining}`);
+        }
+        if (logEntry.error) {
+            parts.push(`error:"${logEntry.error}"`);
+        }
+        return parts.join(' | ');
+    }
+}
+export const globalRequestLogger = new RequestLogger();
+export default globalRequestLogger;

package/dist/server/resources.d.ts

@@ -0,0 +1,39 @@
+import type * as ynab from 'ynab';
+interface ResponseFormatter {
+    format(data: unknown): string;
+}
+export type ResourceHandler = (uri: string, dependencies: ResourceDependencies) => Promise<{
+    contents: {
+        uri: string;
+        mimeType: string;
+        text: string;
+    }[];
+}>;
+export interface ResourceDefinition {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}
+export interface ResourceDependencies {
+    ynabAPI: ynab.API;
+    responseFormatter: ResponseFormatter;
+}
+export declare class ResourceManager {
+    private dependencies;
+    private resourceHandlers;
+    private resourceDefinitions;
+    constructor(dependencies: ResourceDependencies);
+    registerResource(definition: ResourceDefinition, handler: ResourceHandler): void;
+    listResources(): {
+        resources: ResourceDefinition[];
+    };
+    readResource(uri: string): Promise<{
+        contents: {
+            uri: string;
+            mimeType: string;
+            text: string;
+        }[];
+    }>;
+}
+export {};

package/dist/server/resources.js

@@ -0,0 +1,85 @@
+const defaultResourceHandlers = {
+    'ynab://budgets': async (uri, { ynabAPI, responseFormatter }) => {
+        try {
+            const response = await ynabAPI.budgets.getBudgets();
+            const budgets = response.data.budgets.map((budget) => ({
+                id: budget.id,
+                name: budget.name,
+                last_modified_on: budget.last_modified_on,
+                first_month: budget.first_month,
+                last_month: budget.last_month,
+                currency_format: budget.currency_format,
+            }));
+            return {
+                contents: [
+                    {
+                        uri: uri,
+                        mimeType: 'application/json',
+                        text: responseFormatter.format({ budgets }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to fetch budgets: ${error}`);
+        }
+    },
+    'ynab://user': async (uri, { ynabAPI, responseFormatter }) => {
+        try {
+            const response = await ynabAPI.user.getUser();
+            const userInfo = response.data.user;
+            const user = {
+                id: userInfo.id,
+            };
+            return {
+                contents: [
+                    {
+                        uri: uri,
+                        mimeType: 'application/json',
+                        text: responseFormatter.format({ user }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to fetch user info: ${error}`);
+        }
+    },
+};
+const defaultResourceDefinitions = [
+    {
+        uri: 'ynab://budgets',
+        name: 'YNAB Budgets',
+        description: 'List of all available budgets',
+        mimeType: 'application/json',
+    },
+    {
+        uri: 'ynab://user',
+        name: 'YNAB User Info',
+        description: 'Current user information including ID and email address',
+        mimeType: 'application/json',
+    },
+];
+export class ResourceManager {
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+        this.resourceHandlers = { ...defaultResourceHandlers };
+        this.resourceDefinitions = [...defaultResourceDefinitions];
+    }
+    registerResource(definition, handler) {
+        this.resourceDefinitions.push(definition);
+        this.resourceHandlers[definition.uri] = handler;
+    }
+    listResources() {
+        return {
+            resources: this.resourceDefinitions,
+        };
+    }
+    async readResource(uri) {
+        const handler = this.resourceHandlers[uri];
+        if (!handler) {
+            throw new Error(`Unknown resource: ${uri}`);
+        }
+        return await handler(uri, this.dependencies);
+    }
+}