actual-mcp-server 0.5.0

package/dist/src/lib/actual-schema.js

@@ -0,0 +1,222 @@
+/**
+ * Actual Budget Database Schema
+ *
+ * This module provides the schema definition for Actual Budget's database tables
+ * and fields. Used for pre-validation of SQL queries before execution to prevent
+ * server crashes from invalid field references.
+ *
+ * Based on: @actual-app/api schema definition
+ * Source: packages/loot-core/src/server/aql/schema/index.ts
+ */
+/**
+ * Core Actual Budget database schema
+ * Defines all available tables and their fields
+ */
+export const ACTUAL_SCHEMA = {
+    transactions: {
+        id: { type: 'id' },
+        is_parent: { type: 'boolean' },
+        is_child: { type: 'boolean' },
+        parent_id: { type: 'id' },
+        account: { type: 'id', ref: 'accounts', required: true },
+        category: { type: 'id', ref: 'categories' },
+        amount: { type: 'integer', default: 0, required: true },
+        payee: { type: 'id', ref: 'payees' },
+        notes: { type: 'string' },
+        date: { type: 'date', required: true },
+        imported_id: { type: 'string' },
+        imported_payee: { type: 'string' },
+        error: { type: 'json' },
+        cleared: { type: 'boolean' },
+        pending: { type: 'boolean' },
+        transfer_id: { type: 'id' },
+        sort_order: { type: 'float' },
+        starting_balance_flag: { type: 'boolean' },
+        reconciled: { type: 'boolean' },
+        schedule: { type: 'id', ref: 'schedules' },
+        tombstone: { type: 'boolean' },
+    },
+    accounts: {
+        id: { type: 'id' },
+        name: { type: 'string', required: true },
+        type: { type: 'string' },
+        offbudget: { type: 'boolean' },
+        closed: { type: 'boolean' },
+        sort_order: { type: 'float' },
+        tombstone: { type: 'boolean' },
+        account_id: { type: 'string' },
+        official_name: { type: 'string' },
+        balance_current: { type: 'integer' },
+        balance_available: { type: 'integer' },
+        balance_limit: { type: 'integer' },
+        mask: { type: 'string' },
+        bank: { type: 'id', ref: 'banks' },
+        account_sync_source: { type: 'string' },
+    },
+    categories: {
+        id: { type: 'id' },
+        name: { type: 'string', required: true },
+        is_income: { type: 'boolean', required: true },
+        group: { type: 'id', ref: 'category_groups', required: true },
+        sort_order: { type: 'float' },
+        tombstone: { type: 'boolean' },
+        hidden: { type: 'boolean' },
+        goal_def: { type: 'json' },
+    },
+    category_groups: {
+        id: { type: 'id' },
+        name: { type: 'string', required: true },
+        is_income: { type: 'boolean', required: true },
+        sort_order: { type: 'float' },
+        tombstone: { type: 'boolean' },
+        hidden: { type: 'boolean' },
+    },
+    payees: {
+        id: { type: 'id' },
+        name: { type: 'string', required: true },
+        category: { type: 'id', ref: 'categories' },
+        tombstone: { type: 'boolean' },
+        transfer_acct: { type: 'id', ref: 'accounts' },
+    },
+    schedules: {
+        id: { type: 'id' },
+        name: { type: 'string' },
+        rule: { type: 'id', ref: 'rules', required: true },
+        next_date: { type: 'date' },
+        completed: { type: 'boolean' },
+        posts_transaction: { type: 'boolean' },
+        tombstone: { type: 'boolean' },
+        _payee: { type: 'id', ref: 'payees' },
+        _account: { type: 'id', ref: 'accounts' },
+        _amount: { type: 'json/fallback' },
+        _amountOp: { type: 'string' },
+        _date: { type: 'json/fallback' },
+        _conditions: { type: 'json' },
+        _actions: { type: 'json' },
+    },
+    rules: {
+        id: { type: 'id' },
+        stage: { type: 'string' },
+        conditions_op: { type: 'string' },
+        conditions: { type: 'json' },
+        actions: { type: 'json' },
+        tombstone: { type: 'boolean' },
+    },
+    notes: {
+        id: { type: 'id' },
+        note: { type: 'string' },
+    },
+    banks: {
+        id: { type: 'id' },
+        bank_id: { type: 'string' },
+        name: { type: 'string' },
+        tombstone: { type: 'boolean' },
+    },
+    preferences: {
+        id: { type: 'id' },
+        value: { type: 'string' },
+    },
+    transaction_filters: {
+        id: { type: 'id' },
+        name: { type: 'string' },
+        conditions_op: { type: 'string' },
+        conditions: { type: 'json' },
+        tombstone: { type: 'boolean' },
+    },
+    custom_reports: {
+        id: { type: 'id' },
+        name: { type: 'string' },
+        start_date: { type: 'string', default: '2023-06' },
+        end_date: { type: 'string', default: '2023-09' },
+        date_static: { type: 'integer', default: 0 },
+        date_range: { type: 'string' },
+        mode: { type: 'string', default: 'total' },
+        group_by: { type: 'string', default: 'Category' },
+        sort_by: { type: 'string', default: 'desc' },
+        balance_type: { type: 'string', default: 'Expense' },
+        show_empty: { type: 'integer', default: 0 },
+        show_offbudget: { type: 'integer', default: 0 },
+        show_hidden: { type: 'integer', default: 0 },
+        show_uncategorized: { type: 'integer', default: 0 },
+        trim_intervals: { type: 'integer', default: 0 },
+        include_current: { type: 'integer', default: 0 },
+        graph_type: { type: 'string', default: 'BarGraph' },
+        conditions: { type: 'json' },
+        conditions_op: { type: 'string' },
+        metadata: { type: 'json' },
+        interval: { type: 'string', default: 'Monthly' },
+        color_scheme: { type: 'json' },
+        tombstone: { type: 'boolean' },
+    },
+    dashboard: {
+        id: { type: 'id' },
+        type: { type: 'string', required: true },
+        width: { type: 'integer', required: true },
+        height: { type: 'integer', required: true },
+        x: { type: 'integer', required: true },
+        y: { type: 'integer', required: true },
+        meta: { type: 'json' },
+        tombstone: { type: 'boolean' },
+    },
+};
+/**
+ * Common join paths for transactions
+ * Format: "field.joinField" maps to referenced table
+ */
+export const JOIN_PATHS = {
+    'payee.name': { table: 'payees', field: 'name' },
+    'payee.category': { table: 'payees', field: 'category' },
+    'category.name': { table: 'categories', field: 'name' },
+    'category.group': { table: 'categories', field: 'group' },
+    'category.is_income': { table: 'categories', field: 'is_income' },
+    'category.hidden': { table: 'categories', field: 'hidden' },
+    'account.name': { table: 'accounts', field: 'name' },
+    'account.type': { table: 'accounts', field: 'type' },
+    'account.offbudget': { table: 'accounts', field: 'offbudget' },
+    'account.closed': { table: 'accounts', field: 'closed' },
+};
+/**
+ * Get all valid field names for a table
+ */
+export function getTableFields(tableName) {
+    const table = ACTUAL_SCHEMA[tableName];
+    if (!table)
+        return null;
+    return Object.keys(table);
+}
+/**
+ * Get all valid table names
+ */
+export function getTableNames() {
+    return Object.keys(ACTUAL_SCHEMA);
+}
+/**
+ * Check if a table exists
+ */
+export function isValidTable(tableName) {
+    return tableName in ACTUAL_SCHEMA;
+}
+/**
+ * Check if a field exists in a table
+ */
+export function isValidField(tableName, fieldName) {
+    const table = ACTUAL_SCHEMA[tableName];
+    if (!table)
+        return false;
+    return fieldName in table;
+}
+/**
+ * Check if a join path is valid
+ */
+export function isValidJoinPath(path) {
+    return path in JOIN_PATHS;
+}
+/**
+ * Get field type information
+ */
+export function getFieldType(tableName, fieldName) {
+    const table = ACTUAL_SCHEMA[tableName];
+    if (!table || !(fieldName in table))
+        return null;
+    return table[fieldName].type;
+}

package/dist/src/lib/budget-registry.js

@@ -0,0 +1,64 @@
+/**
+ * Budget Registry — pre-configured multi-budget, multi-server support.
+ *
+ * Budgets are declared via environment variables:
+ *
+ *   # Default budget (always present, from existing ACTUAL_* vars)
+ *   BUDGET_DEFAULT_NAME=My Budget        # optional, defaults to "Default"
+ *   ACTUAL_SERVER_URL=http://actual:5006
+ *   ACTUAL_PASSWORD=secret
+ *   ACTUAL_BUDGET_SYNC_ID=uuid-here
+ *   ACTUAL_BUDGET_PASSWORD=              # optional, for E2E-encrypted budgets
+ *
+ *   # Additional named budgets — each group can point to a different server
+ *   BUDGET_1_NAME=Shared Family Account
+ *   BUDGET_1_SERVER_URL=http://actual:5006    # optional, falls back to ACTUAL_SERVER_URL
+ *   BUDGET_1_PASSWORD=secret                   # optional, falls back to ACTUAL_PASSWORD
+ *   BUDGET_1_SYNC_ID=uuid-here                 # required
+ *   BUDGET_1_ENCRYPTION_PASSWORD=              # optional
+ *
+ *   BUDGET_2_NAME=Office
+ *   BUDGET_2_SERVER_URL=http://actual-office:5006
+ *   BUDGET_2_PASSWORD=officepassword
+ *   BUDGET_2_SYNC_ID=uuid-here
+ *
+ * The AI uses `actual_budgets_list_available` to see all configured budgets,
+ * then `actual_budgets_switch` with the budget name to switch between them.
+ */
+/**
+ * Parse the budget registry from environment variables.
+ * Always includes the default budget from the provided defaults (ACTUAL_* vars).
+ * Additional budgets are read from sequential BUDGET_n_* groups.
+ */
+export function parseBudgetRegistry(env, defaults) {
+    const registry = new Map();
+    const defaultName = env.BUDGET_DEFAULT_NAME ?? 'Default';
+    registry.set(defaultName.toLowerCase(), {
+        name: defaultName,
+        serverUrl: defaults.serverUrl,
+        password: defaults.password,
+        syncId: defaults.syncId,
+        encryptionPassword: defaults.encryptionPassword,
+    });
+    let i = 1;
+    while (env[`BUDGET_${i}_NAME`]) {
+        const prefix = `BUDGET_${i}_`;
+        const name = env[`${prefix}NAME`];
+        const serverUrl = env[`${prefix}SERVER_URL`] ?? defaults.serverUrl;
+        const password = env[`${prefix}PASSWORD`] ?? defaults.password;
+        const syncId = env[`${prefix}SYNC_ID`];
+        if (!syncId) {
+            console.error(`[CONFIG] BUDGET_${i}_SYNC_ID is required when BUDGET_${i}_NAME="${name}" is set`);
+            process.exit(1);
+        }
+        registry.set(name.toLowerCase(), {
+            name,
+            serverUrl,
+            password,
+            syncId,
+            encryptionPassword: env[`${prefix}ENCRYPTION_PASSWORD`],
+        });
+        i++;
+    }
+    return registry;
+}

package/dist/src/lib/constants.js

@@ -0,0 +1,121 @@
+/**
+ * Application-wide constants
+ *
+ * Centralized constant values for retry logic, timeouts, limits, and other
+ * configuration that should remain consistent across the application.
+ */
+// ============================================================================
+// RETRY & RESILIENCE
+// ============================================================================
+/**
+ * Default number of retry attempts for transient failures
+ */
+export const DEFAULT_RETRY_ATTEMPTS = 3;
+/**
+ * Initial backoff delay in milliseconds for exponential backoff retry
+ */
+export const DEFAULT_RETRY_BACKOFF_MS = 200;
+/**
+ * Maximum delay between retries (prevents unbounded exponential growth)
+ */
+export const MAX_RETRY_DELAY_MS = 10000;
+// ============================================================================
+// CONCURRENCY & RATE LIMITING
+// ============================================================================
+/**
+ * Default concurrency limit for Actual Budget API operations
+ * Prevents overwhelming the API with too many simultaneous requests
+ */
+export const DEFAULT_CONCURRENCY_LIMIT = 5;
+// ============================================================================
+// TIMEOUTS
+// ============================================================================
+/**
+ * Default timeout for API operations in milliseconds
+ */
+export const DEFAULT_OPERATION_TIMEOUT_MS = 30000;
+/**
+ * Timeout for server shutdown grace period
+ */
+export const SHUTDOWN_GRACE_PERIOD_MS = 5000;
+/**
+ * How long (ms) to wait after calling rawRunBankSync for the SDK's background
+ * promise to surface a BankSyncError as an unhandledRejection.
+ *
+ * Bank provider errors (GoCardless RATE_LIMIT_EXCEEDED, auth failures, etc.)
+ * arrive as HTTP responses. Fast banks respond within 1-3 seconds; slower
+ * institutions can take considerably longer. 30 seconds gives a comfortable
+ * margin while keeping the tool's wall-clock time acceptable for MCP clients.
+ */
+export const BANK_SYNC_SETTLE_MS = 30_000;
+/**
+ * How long (ms) to wait for additional queued writes before closing the
+ * shared budget session. Increasing this value batches more writes per
+ * session at the cost of slightly higher latency.
+ */
+export const WRITE_SESSION_DELAY_MS = 100;
+// ============================================================================
+// MCP SERVER
+// ============================================================================
+/**
+ * Default HTTP server bind host
+ */
+export const DEFAULT_BIND_HOST = 'localhost';
+/**
+ * Default HTTP port for MCP server
+ */
+export const DEFAULT_HTTP_PORT = 3000;
+/**
+ * Default HTTP path for MCP server endpoint
+ */
+export const DEFAULT_HTTP_PATH = '/';
+/**
+ * Server information
+ * Note: version is read from package.json at startup and passed as a parameter.
+ */
+export const SERVER_INFO = {
+    name: 'actual-budget-mcp',
+    description: 'MCP server for Actual Budget - 60 tools for finance management',
+};
+// ============================================================================
+// VALIDATION & LIMITS
+// ============================================================================
+/**
+ * Maximum length for name fields (accounts, categories, payees)
+ */
+export const MAX_NAME_LENGTH = 255;
+/**
+ * Maximum length for notes/description fields
+ */
+export const MAX_NOTES_LENGTH = 1000;
+/**
+ * Date format pattern (YYYY-MM-DD)
+ */
+export const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Month format pattern (YYYY-MM)
+ */
+export const MONTH_PATTERN = /^\d{4}-\d{2}$/;
+/**
+ * UUID pattern for ID validation
+ */
+export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// ============================================================================
+// LOGGING
+// ============================================================================
+/**
+ * Log level for production environments
+ */
+export const PRODUCTION_LOG_LEVEL = 'info';
+/**
+ * Log level for development environments
+ */
+export const DEVELOPMENT_LOG_LEVEL = 'debug';
+/**
+ * Maximum number of log files to retain
+ */
+export const MAX_LOG_FILES = 14;
+/**
+ * Maximum size of a single log file before rotation
+ */
+export const MAX_LOG_FILE_SIZE = '20m';

package/dist/src/lib/errors.js

@@ -0,0 +1,19 @@
+/**
+ * Build a "not found" error message with a next-step hint.
+ * @param entityType  Human-readable entity name, e.g. "Account", "Category"
+ * @param id          The ID that was not found
+ * @param listTool    MCP tool name the caller should use to get valid IDs
+ */
+export function notFoundMsg(entityType, id, listTool) {
+    return `${entityType} "${id}" not found. Use ${listTool} to list available ${entityType.toLowerCase()}s.`;
+}
+/**
+ * Build a "constraint error" message for SQLite-level failures.
+ * @param entityType  Human-readable entity name
+ * @param id          The ID that failed
+ * @param listTool    MCP tool name for listing
+ */
+export function constraintErrorMsg(entityType, id, listTool) {
+    return `Failed to delete ${entityType.toLowerCase()} "${id}". ` +
+        `It may be referenced by other records. Use ${listTool} to verify it exists.`;
+}

package/dist/src/lib/loggerFactory.js

@@ -0,0 +1,72 @@
+/**
+ * Module Logger Factory
+ *
+ * Creates module-specific loggers with consistent formatting.
+ * Each logger automatically prefixes messages with [MODULE_NAME] for
+ * easier tracing and debugging in production.
+ */
+import logger from '../logger.js';
+/**
+ * Create a module-specific logger
+ *
+ * @param moduleName - Name of the module (e.g., 'HTTP', 'ADAPTER', 'TOOLS')
+ * @returns Module logger with automatic prefixing
+ *
+ * @example
+ * ```typescript
+ * import { createModuleLogger } from '../lib/loggerFactory.js';
+ *
+ * const log = createModuleLogger('HTTP');
+ * log.info('Server started', { port: 3000 });
+ * // Output: [HTTP] Server started { port: 3000 }
+ *
+ * log.error('Connection failed', new Error('Timeout'), { retries: 3 });
+ * // Output: [HTTP] Connection failed { error: 'Timeout', stack: '...', retries: 3 }
+ * ```
+ */
+export function createModuleLogger(moduleName) {
+    const prefix = `[${moduleName}]`;
+    return {
+        info: (message, meta) => {
+            logger.info(`${prefix} ${message}`, meta);
+        },
+        debug: (message, meta) => {
+            logger.debug(`${prefix} ${message}`, meta);
+        },
+        warn: (message, meta) => {
+            logger.warn(`${prefix} ${message}`, meta);
+        },
+        error: (message, error, meta) => {
+            if (error) {
+                logger.error(`${prefix} ${message}`, {
+                    error: error.message,
+                    stack: error.stack,
+                    ...meta,
+                });
+            }
+            else {
+                logger.error(`${prefix} ${message}`, meta);
+            }
+        },
+    };
+}
+/**
+ * Pre-configured module loggers for common components
+ * Can be imported directly for convenience
+ *
+ * @example
+ * ```typescript
+ * import { ModuleLoggers } from '../lib/loggerFactory.js';
+ *
+ * ModuleLoggers.HTTP.info('Request received');
+ * ModuleLoggers.ADAPTER.debug('Processing transaction');
+ * ```
+ */
+export const ModuleLoggers = {
+    HTTP: createModuleLogger('HTTP'),
+    ADAPTER: createModuleLogger('ADAPTER'),
+    TOOLS: createModuleLogger('TOOLS'),
+    SESSION: createModuleLogger('SESSION'),
+    CONNECTION: createModuleLogger('CONNECTION'),
+    RETRY: createModuleLogger('RETRY'),
+};

package/dist/src/lib/node-polyfills.js

@@ -0,0 +1,20 @@
+/**
+ * Node.js polyfills for browser globals required by @actual-app/api.
+ *
+ * @actual-app/api v26.3.0 introduced `navigator.platform` usage at the module
+ * top level (inside the Electron/browser bundle) which crashes on Node.js with
+ * `ReferenceError: navigator is not defined`.
+ *
+ * This file must be imported BEFORE any `@actual-app/api` import so that the
+ * global is defined when the bundle is first evaluated.
+ */
+if (typeof globalThis.navigator === 'undefined') {
+    Object.defineProperty(globalThis, 'navigator', {
+        value: {
+            platform: process.platform === 'win32' ? 'Win32' : 'Linux',
+        },
+        writable: true,
+        configurable: true,
+    });
+}
+export {};