actual-mcp-server 0.5.0

package/dist/src/lib/query-validator.js

@@ -0,0 +1,221 @@
+/**
+ * SQL Query Validator
+ *
+ * Validates SQL queries against the Actual Budget schema before execution
+ * to prevent server crashes from invalid table/field references.
+ */
+import { getTableFields, getTableNames, isValidTable, isValidField, isValidJoinPath, } from './actual-schema.js';
+/**
+ * Extract table name from SQL query
+ * Handles: FROM table, FROM table1, table2, JOIN table
+ */
+function extractTableNames(sql) {
+    const tables = new Set();
+    const normalized = sql.toUpperCase();
+    // Extract FROM clause tables - handle queries without WHERE/ORDER/LIMIT
+    const fromMatch = normalized.match(/FROM\s+(\w+)/i);
+    if (fromMatch) {
+        tables.add(fromMatch[1].toLowerCase());
+    }
+    // Extract JOIN clause tables
+    const joinMatches = sql.matchAll(/JOIN\s+(\w+)/gi);
+    for (const match of joinMatches) {
+        tables.add(match[1].toLowerCase());
+    }
+    return Array.from(tables);
+}
+/**
+ * Extract field references from SELECT clause
+ * Handles: *, field, table.field, field AS alias, payee.name
+ */
+function extractSelectFields(sql) {
+    const fields = [];
+    // Handle SELECT *
+    if (/SELECT\s+\*/i.test(sql)) {
+        return [{ field: '*' }];
+    }
+    // Extract SELECT clause
+    const selectMatch = sql.match(/SELECT\s+(.*?)\s+FROM/is);
+    if (!selectMatch)
+        return fields;
+    const selectClause = selectMatch[1];
+    // Split by commas (but not inside functions)
+    const fieldParts = selectClause.split(/,(?![^()]*\))/);
+    for (let part of fieldParts) {
+        part = part.trim();
+        // Remove AS alias
+        part = part.replace(/\s+AS\s+.+$/i, '');
+        // Check for table.field or field
+        const dotMatch = part.match(/^(\w+)\.(\w+)$/);
+        if (dotMatch) {
+            fields.push({ table: dotMatch[1], field: dotMatch[2] });
+        }
+        else if (/^\w+$/.test(part)) {
+            // Simple field name
+            fields.push({ field: part });
+        }
+        // Ignore functions like COUNT(*), SUM(amount), etc.
+    }
+    return fields;
+}
+/**
+ * Extract field references from WHERE clause
+ */
+function extractWhereFields(sql) {
+    const fields = [];
+    const whereMatch = sql.match(/WHERE\s+(.*?)(?:GROUP|ORDER|LIMIT|;|$)/is);
+    if (!whereMatch)
+        return fields;
+    const whereClause = whereMatch[1];
+    // Find field references (table.field or field)
+    const fieldMatches = whereClause.matchAll(/(\w+)\.(\w+)|(?:^|\s)(\w+)\s*[=<>!]/g);
+    for (const match of fieldMatches) {
+        if (match[1] && match[2]) {
+            // table.field
+            fields.push({ table: match[1], field: match[2] });
+        }
+        else if (match[3]) {
+            // simple field
+            fields.push({ field: match[3] });
+        }
+    }
+    return fields;
+}
+/**
+ * Validate a SQL query against the Actual Budget schema
+ */
+export function validateQuery(sql) {
+    const errors = [];
+    try {
+        // Normalize SQL
+        sql = sql.trim();
+        if (!sql) {
+            return { valid: false, errors: [{ type: 'invalid_field', message: 'Empty query' }] };
+        }
+        // Extract tables
+        const tables = extractTableNames(sql);
+        if (tables.length === 0) {
+            return { valid: false, errors: [{ type: 'invalid_table', message: 'No table found in query' }] };
+        }
+        // Validate tables exist
+        for (const table of tables) {
+            if (!isValidTable(table)) {
+                errors.push({
+                    type: 'invalid_table',
+                    message: `Table "${table}" does not exist`,
+                    table,
+                    suggestions: getTableNames(),
+                });
+            }
+        }
+        // If table is invalid, stop here
+        if (errors.length > 0) {
+            return { valid: false, errors };
+        }
+        const primaryTable = tables[0]; // First table is primary
+        // Extract and validate SELECT fields
+        const selectFields = extractSelectFields(sql);
+        for (const { field, table } of selectFields) {
+            if (field === '*')
+                continue; // SELECT * is always valid
+            // Check for join paths (e.g., payee.name)
+            const fullPath = table ? `${table}.${field}` : field;
+            if (table && field) {
+                // If it's a dot notation, check if it's a valid join path
+                if (isValidJoinPath(fullPath)) {
+                    continue; // Valid join path
+                }
+            }
+            // Check if field exists in primary table or specified table
+            const targetTable = table || primaryTable;
+            if (!isValidField(targetTable, field)) {
+                const availableFields = getTableFields(targetTable);
+                // If table doesn't exist, suggest valid tables instead of empty field list
+                if (availableFields === null) {
+                    errors.push({
+                        type: 'invalid_table',
+                        message: `Table "${targetTable}" does not exist (referenced in "${table ? table + '.' + field : field}")`,
+                        table: targetTable,
+                        field,
+                        suggestions: getTableNames(),
+                    });
+                }
+                else {
+                    errors.push({
+                        type: 'invalid_field',
+                        message: `Field "${field}" does not exist in table "${targetTable}"`,
+                        table: targetTable,
+                        field,
+                        suggestions: availableFields,
+                    });
+                }
+            }
+        }
+        // Extract and validate WHERE fields
+        const whereFields = extractWhereFields(sql);
+        for (const { field, table } of whereFields) {
+            const fullPath = table ? `${table}.${field}` : field;
+            // Check for join paths
+            if (table && field && isValidJoinPath(fullPath)) {
+                continue;
+            }
+            // Check if field exists
+            const targetTable = table || primaryTable;
+            if (!isValidField(targetTable, field)) {
+                const availableFields = getTableFields(targetTable);
+                // If table doesn't exist, suggest valid tables instead of empty field list
+                if (availableFields === null) {
+                    errors.push({
+                        type: 'invalid_table',
+                        message: `Table "${targetTable}" does not exist (referenced in "${table ? table + '.' + field : field}")`,
+                        table: targetTable,
+                        field,
+                        suggestions: getTableNames(),
+                    });
+                }
+                else {
+                    errors.push({
+                        type: 'invalid_field',
+                        message: `Field "${field}" does not exist in table "${targetTable}"`,
+                        table: targetTable,
+                        field,
+                        suggestions: availableFields,
+                    });
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            errors: [{
+                    type: 'invalid_field',
+                    message: `Query parsing error: ${error instanceof Error ? error.message : String(error)}`,
+                }],
+        };
+    }
+}
+/**
+ * Format validation errors into a user-friendly message
+ */
+export function formatValidationErrors(result) {
+    if (result.valid)
+        return '';
+    const messages = [];
+    for (const error of result.errors) {
+        messages.push(`❌ ${error.message}`);
+        if (error.suggestions && error.suggestions.length > 0) {
+            if (error.type === 'invalid_table') {
+                messages.push(`   Available tables: ${error.suggestions.join(', ')}`);
+            }
+            else if (error.type === 'invalid_field') {
+                messages.push(`   Available fields: ${error.suggestions.join(', ')}`);
+            }
+        }
+    }
+    return messages.join('\n');
+}

package/dist/src/lib/retry.js

@@ -0,0 +1,26 @@
+import { DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_BACKOFF_MS, MAX_RETRY_DELAY_MS } from './constants.js';
+import { ModuleLoggers } from './loggerFactory.js';
+const log = ModuleLoggers.RETRY;
+export async function retry(fn, opts) {
+    const retries = opts?.retries ?? DEFAULT_RETRY_ATTEMPTS;
+    const backoffMs = opts?.backoffMs ?? DEFAULT_RETRY_BACKOFF_MS;
+    let attempt = 0;
+    while (true) {
+        try {
+            // Ensure the promise from fn() is properly awaited and any rejection is caught
+            const result = await Promise.resolve().then(() => fn());
+            return result;
+        }
+        catch (err) {
+            attempt++;
+            if (attempt > retries) {
+                log.error(`All retry attempts exhausted after ${retries} tries`, err);
+                throw err;
+            }
+            const delay = Math.min(backoffMs * Math.pow(2, attempt - 1), MAX_RETRY_DELAY_MS);
+            log.debug(`Retry attempt ${attempt}/${retries} after ${delay}ms`, { error: err.message });
+            await new Promise(r => setTimeout(r, delay));
+        }
+    }
+}
+export default retry;

package/dist/src/lib/schemas/common.js

@@ -0,0 +1,203 @@
+/**
+ * Shared Zod Validation Schemas
+ *
+ * Common validation schemas used across MCP tools for Actual Budget.
+ * These schemas provide consistent validation, better error messages,
+ * and reduce duplication across the 43 tool definitions.
+ */
+import { z } from 'zod';
+import { MAX_NAME_LENGTH, MAX_NOTES_LENGTH, DATE_PATTERN, MONTH_PATTERN, UUID_PATTERN } from '../constants.js';
+// ============================================================================
+// ID SCHEMAS
+// ============================================================================
+/**
+ * Account UUID validation
+ * Used for: account operations, transactions, transfers
+ */
+export const accountIdSchema = z
+    .string()
+    .regex(UUID_PATTERN, 'Invalid account ID format (expected UUID)')
+    .describe('Account UUID');
+/**
+ * Transaction UUID validation
+ * Used for: transaction updates, deletions
+ */
+export const transactionIdSchema = z
+    .string()
+    .regex(UUID_PATTERN, 'Invalid transaction ID format (expected UUID)')
+    .describe('Transaction UUID');
+/**
+ * Category UUID validation
+ * Used for: budget operations, transactions, category management
+ */
+export const categoryIdSchema = z
+    .string()
+    .regex(UUID_PATTERN, 'Invalid category ID format (expected UUID)')
+    .describe('Category UUID');
+/**
+ * Category group UUID validation
+ * Used for: category group management
+ */
+export const categoryGroupIdSchema = z
+    .string()
+    .regex(UUID_PATTERN, 'Invalid category group ID format (expected UUID)')
+    .describe('Category group UUID');
+/**
+ * Payee UUID validation
+ * Used for: transactions, payee management, rules
+ */
+export const payeeIdSchema = z
+    .string()
+    .regex(UUID_PATTERN, 'Invalid payee ID format (expected UUID)')
+    .describe('Payee UUID');
+/**
+ * Rule UUID validation
+ * Used for: rule management operations
+ */
+export const ruleIdSchema = z
+    .string()
+    .regex(UUID_PATTERN, 'Invalid rule ID format (expected UUID)')
+    .describe('Rule UUID');
+// ============================================================================
+// DATE SCHEMAS
+// ============================================================================
+/**
+ * Date in YYYY-MM-DD format
+ * Used for: transactions, account balance queries, date range filters
+ * Example: "2025-11-24"
+ */
+export const dateSchema = z
+    .string()
+    .regex(DATE_PATTERN, 'Invalid date format (expected YYYY-MM-DD)')
+    .describe('Date in YYYY-MM-DD format');
+/**
+ * Month in YYYY-MM format
+ * Used for: budget months, monthly reports
+ * Example: "2025-11"
+ */
+export const monthYearSchema = z
+    .string()
+    .regex(MONTH_PATTERN, 'Invalid month format (expected YYYY-MM)')
+    .describe('Month in YYYY-MM format');
+// ============================================================================
+// AMOUNT SCHEMAS
+// ============================================================================
+/**
+ * Amount in cents (integer)
+ * Negative for expenses, positive for income
+ * Example: -12.34 USD = -1234 cents
+ */
+export const amountCentsSchema = z
+    .number()
+    .int('Amount must be an integer (cents)')
+    .describe('Amount in cents (negative for expenses, positive for income)');
+/**
+ * Optional amount in cents
+ * Used for: account balance initialization, optional transaction amounts
+ */
+export const optionalAmountCentsSchema = amountCentsSchema
+    .optional()
+    .describe('Optional amount in cents');
+// ============================================================================
+// TEXT FIELD SCHEMAS
+// ============================================================================
+/**
+ * Name field (1-255 characters)
+ * Used for: accounts, categories, payees, category groups
+ */
+export const nameSchema = z
+    .string()
+    .min(1, 'Name cannot be empty')
+    .max(MAX_NAME_LENGTH, `Name cannot exceed ${MAX_NAME_LENGTH} characters`)
+    .describe('Name (1-255 characters)');
+/**
+ * Notes/description field (max 1000 characters)
+ * Used for: transactions, categories, accounts, rules
+ */
+export const notesSchema = z
+    .string()
+    .max(MAX_NOTES_LENGTH, `Notes cannot exceed ${MAX_NOTES_LENGTH} characters`)
+    .optional()
+    .describe('Optional notes (max 1000 characters)');
+// ============================================================================
+// STATUS FLAGS
+// ============================================================================
+/**
+ * Transaction cleared flag
+ * Indicates whether a transaction has cleared the bank
+ */
+export const clearedSchema = z
+    .boolean()
+    .optional()
+    .describe('Whether the transaction has cleared');
+/**
+ * Transaction reconciled flag
+ * Indicates whether a transaction has been reconciled
+ */
+export const reconciledSchema = z
+    .boolean()
+    .optional()
+    .describe('Whether the transaction has been reconciled');
+/**
+ * Account closed flag
+ * Indicates whether an account is closed
+ */
+export const closedSchema = z
+    .boolean()
+    .optional()
+    .describe('Whether the account is closed');
+/**
+ * Account off-budget flag
+ * Indicates whether an account is excluded from budget calculations
+ */
+export const offBudgetSchema = z
+    .boolean()
+    .optional()
+    .describe('Whether the account is off-budget');
+// ============================================================================
+// COMPOSITE SCHEMAS
+// ============================================================================
+/**
+ * Common schemas object for easy import
+ * Usage: import { CommonSchemas } from '../lib/schemas/common.js';
+ */
+export const CommonSchemas = {
+    // IDs
+    accountId: accountIdSchema,
+    transactionId: transactionIdSchema,
+    categoryId: categoryIdSchema,
+    categoryGroupId: categoryGroupIdSchema,
+    payeeId: payeeIdSchema,
+    ruleId: ruleIdSchema,
+    // Dates
+    date: dateSchema,
+    monthYear: monthYearSchema,
+    // Amounts
+    amountCents: amountCentsSchema,
+    optionalAmountCents: optionalAmountCentsSchema,
+    // Text fields
+    name: nameSchema,
+    notes: notesSchema,
+    // Status flags
+    cleared: clearedSchema,
+    reconciled: reconciledSchema,
+    closed: closedSchema,
+    offBudget: offBudgetSchema,
+};
+// ============================================================================
+// EXAMPLES
+// ============================================================================
+/**
+ * Example usage in tool definitions:
+ *
+ * ```typescript
+ * import { z } from 'zod';
+ * import { CommonSchemas } from '../lib/schemas/common.js';
+ *
+ * const InputSchema = z.object({
+ *   accountId: CommonSchemas.accountId,
+ *   name: CommonSchemas.name,
+ *   balance: CommonSchemas.optionalAmountCents,
+ * });
+ * ```
+ */

package/dist/src/lib/toolFactory.js

@@ -0,0 +1,109 @@
+/**
+ * Tool Factory
+ *
+ * Factory function for creating MCP tool definitions with consistent structure,
+ * error handling, logging, and observability. This eliminates code duplication
+ * across the 43 tool files and ensures consistent behavior.
+ *
+ * Benefits:
+ * - Reduces boilerplate from ~25 LOC to ~10 LOC per tool
+ * - Automatic error handling and logging
+ * - Consistent observability integration
+ * - Type-safe tool configuration
+ * - Easier to test and maintain
+ */
+import { createModuleLogger } from './loggerFactory.js';
+import observability from '../observability.js';
+const log = createModuleLogger('TOOLS');
+/**
+ * Create a tool definition with automatic error handling and logging
+ *
+ * @param config - Tool configuration
+ * @returns MCP tool definition ready for registration
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { createTool } from '../lib/toolFactory.js';
+ * import { CommonSchemas } from '../lib/schemas/common.js';
+ * import adapter from '../lib/actual-adapter.js';
+ *
+ * export default createTool({
+ *   name: 'actual_accounts_create',
+ *   description: 'Create a new account in Actual Budget',
+ *   schema: z.object({
+ *     id: z.string().optional(),
+ *     name: CommonSchemas.name,
+ *     balance: CommonSchemas.optionalAmountCents,
+ *   }),
+ *   handler: async (input) => {
+ *     const result = await adapter.createAccount(input, input.balance);
+ *     return { id: result };
+ *   },
+ * });
+ * ```
+ */
+export function createTool(config) {
+    const { name, description, schema, handler, examples } = config;
+    return {
+        name,
+        description: examples
+            ? `${description}\n\nExamples:\n${examples.map((ex, i) => `${i + 1}. ${ex.description}\n   Input: ${JSON.stringify(ex.input, null, 2)}`).join('\n')}`
+            : description,
+        inputSchema: schema,
+        call: async (args, meta) => {
+            const startTime = Date.now();
+            try {
+                // Validate input against schema
+                log.debug(`Validating input for ${name}`, { args });
+                const input = schema.parse(args || {});
+                // Execute handler
+                log.debug(`Executing ${name}`, { input });
+                const result = await handler(input, meta);
+                // Log success
+                const duration = Date.now() - startTime;
+                log.debug(`${name} completed in ${duration}ms`, { result });
+                // Track observability
+                await observability.incrementToolCall(name);
+                return { result };
+            }
+            catch (error) {
+                // Log error with details
+                const duration = Date.now() - startTime;
+                log.error(`${name} failed after ${duration}ms`, error, { args });
+                // Track observability (still increment even on failure)
+                await observability.incrementToolCall(name);
+                // Re-throw for MCP error handling
+                throw error;
+            }
+        },
+    };
+}
+/**
+ * Batch create multiple tools with shared configuration
+ * Useful for creating related tools (CRUD operations) with common patterns
+ *
+ * @param baseConfig - Shared configuration for all tools
+ * @param tools - Array of tool-specific overrides
+ * @returns Array of tool definitions
+ *
+ * @example
+ * ```typescript
+ * export const accountTools = createTools(
+ *   { namePrefix: 'actual_accounts_' },
+ *   [
+ *     { name: 'create', schema: createSchema, handler: createHandler },
+ *     { name: 'update', schema: updateSchema, handler: updateHandler },
+ *     { name: 'delete', schema: deleteSchema, handler: deleteHandler },
+ *   ]
+ * );
+ * ```
+ */
+export function createTools(baseConfig, tools) {
+    const { namePrefix = '', ...sharedConfig } = baseConfig;
+    return tools.map((toolConfig) => createTool({
+        ...sharedConfig,
+        ...toolConfig,
+        name: namePrefix + toolConfig.name,
+    }));
+}

package/dist/src/logger.js

@@ -0,0 +1,127 @@
+import winston from 'winston';
+import DailyRotateFile from 'winston-daily-rotate-file';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// env-configurable
+const STORE_LOGS = process.env.MCP_BRIDGE_STORE_LOGS === 'true';
+const LOG_DIR = process.env.MCP_BRIDGE_LOG_DIR
+    ? path.isAbsolute(process.env.MCP_BRIDGE_LOG_DIR)
+        ? process.env.MCP_BRIDGE_LOG_DIR
+        : path.join(process.cwd(), process.env.MCP_BRIDGE_LOG_DIR)
+    : path.join(__dirname, '..', 'app', 'logs');
+const DATE_PATTERN = process.env.MCP_BRIDGE_ROTATE_DATEPATTERN || 'YYYY-MM-DD';
+const MAX_SIZE = process.env.MCP_BRIDGE_MAX_LOG_SIZE || '20m';
+const MAX_FILES = process.env.MCP_BRIDGE_MAX_FILES || '14d';
+const DEFAULT_LEVEL = process.env.MCP_BRIDGE_LOG_LEVEL || 'debug';
+function safeStringify(obj, maxLen = 2000) {
+    try {
+        const seen = new WeakSet();
+        const s = JSON.stringify(obj, (_key, value) => {
+            if (typeof value === 'object' && value !== null) {
+                if (seen.has(value))
+                    return '[Circular]';
+                seen.add(value);
+            }
+            return value;
+        }, 2);
+        if (s.length > maxLen)
+            return s.slice(0, maxLen) + '...';
+        return s;
+    }
+    catch {
+        try {
+            return String(obj).slice(0, maxLen) + '...';
+        }
+        catch {
+            return '[Unstringifiable]';
+        }
+    }
+}
+const transports = [];
+// file transports when enabled (capture debug+)
+if (STORE_LOGS) {
+    const createDailyRotateTransport = (level) => new DailyRotateFile({
+        level,
+        dirname: LOG_DIR,
+        filename: `${level}-%DATE%.log`,
+        datePattern: DATE_PATTERN,
+        zippedArchive: true,
+        maxSize: MAX_SIZE,
+        maxFiles: MAX_FILES,
+        format: winston.format.combine(winston.format.timestamp(), winston.format.printf(({ timestamp, level, message }) => `${timestamp} ${level}: ${message}`)),
+    });
+    // debug transport collects debug+ messages into debug-%DATE%.log
+    transports.push(createDailyRotateTransport('debug'));
+    // errors into error-%DATE%.log
+    transports.push(createDailyRotateTransport('error'));
+}
+// single console transport for terminal output (use same level)
+// In stdio mode all output must go to stderr — writing to stdout corrupts JSON-RPC framing.
+// MCP_STDIO_MODE is set by src/index.ts before this module is first imported.
+transports.push(new winston.transports.Console({
+    level: DEFAULT_LEVEL,
+    ...(process.env.MCP_STDIO_MODE === 'true'
+        ? { stderrLevels: ['error', 'warn', 'info', 'verbose', 'debug', 'silly', 'http'] }
+        : {}),
+    format: winston.format.combine(winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss.SSS' }), winston.format.colorize(), winston.format.printf(({ timestamp, level, message }) => `${timestamp} ${level}: ${message}`)),
+}));
+const logger = winston.createLogger({
+    level: DEFAULT_LEVEL,
+    transports,
+    exitOnError: false,
+});
+export function logTransportWithDirection(direction, clientIp, req, data) {
+    const meta = {
+        direction,
+        clientIp,
+        method: req.method,
+        url: req.originalUrl,
+        headers: req.headers,
+        payload: safeStringify(data, 2000),
+    };
+    logger.debug(safeStringify(meta, 4000));
+}
+// --- Wire debug module into winston and route console.* to winston only ---
+// NOTE: avoid writing to both original console and winston to prevent duplicates.
+(function wireConsoleAndDebug() {
+    const writeToWinston = (level, args) => {
+        try {
+            const text = args.map((a) => (typeof a === 'string' ? a : safeStringify(a, 2000))).join(' ');
+            // call winston at the requested level
+            // @ts-ignore dynamic level
+            logger[level](text);
+        }
+        catch {
+            // ignore
+        }
+    };
+    // Replace global console methods to feed winston (do NOT call original console.*)
+    console.log = (...args) => writeToWinston('info', args);
+    console.info = (...args) => writeToWinston('info', args);
+    console.warn = (...args) => writeToWinston('warn', args);
+    console.error = (...args) => writeToWinston('error', args);
+    console.debug = (...args) => writeToWinston('debug', args);
+    // Patch debug module (express, undici, debug(...) callers) to forward to winston.debug
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const debugModule = require('debug');
+        if (debugModule) {
+            // replace debug.log so debug(...) prints go into winston
+            debugModule.log = (...args) => {
+                try {
+                    const s = args.map((a) => (typeof a === 'string' ? a : safeStringify(a, 1000))).join(' ');
+                    logger.debug(s);
+                }
+                catch {
+                    // ignore
+                }
+            };
+        }
+    }
+    catch {
+        // debug module not available or failed to patch — ignore
+    }
+})();
+export default logger;