actual-mcp-server 0.5.0

package/dist/src/tools/schedules_delete.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+import { UUID_PATTERN } from '../lib/constants.js';
+import { notFoundMsg, constraintErrorMsg } from '../lib/errors.js';
+const InputSchema = z.object({
+    id: z.string().regex(UUID_PATTERN, 'Invalid UUID format')
+        .describe('UUID of the schedule to delete (from actual_schedules_get)'),
+});
+const tool = {
+    name: 'actual_schedules_delete',
+    description: `Permanently delete a schedule from Actual Budget. The schedule's underlying rule is also removed. This operation cannot be undone.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Pre-flight: verify schedule exists (BUG-11)
+        const schedules = await adapter.getSchedules();
+        const scheduleExists = schedules.some((s) => s.id === input.id);
+        if (!scheduleExists) {
+            return {
+                error: notFoundMsg('Schedule', input.id, 'actual_schedules_get'),
+                success: false,
+            };
+        }
+        try {
+            await adapter.deleteSchedule(input.id);
+            return { success: true };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // Translate raw SQLite constraint errors into user-readable messages
+            if (msg.includes('NOT NULL constraint') || msg.includes('messages_crdt')) {
+                return {
+                    error: constraintErrorMsg('Schedule', input.id, 'actual_schedules_get'),
+                    success: false,
+                };
+            }
+            throw err;
+        }
+    },
+};
+export default tool;

package/dist/src/tools/schedules_get.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({});
+const tool = {
+    name: 'actual_schedules_get',
+    description: `List all schedules in Actual Budget. Schedules automate recurring transactions (e.g. monthly rent, weekly grocery runs). Each schedule has a date rule (one-off or RecurConfig), optional payee/account/amount, and a next_date field showing when it fires next.`,
+    inputSchema: InputSchema,
+    call: async (_args, _meta) => {
+        const schedules = await adapter.getSchedules();
+        return { schedules, count: Array.isArray(schedules) ? schedules.length : 0 };
+    },
+};
+export default tool;

package/dist/src/tools/schedules_update.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+import { UUID_PATTERN } from '../lib/constants.js';
+const InputSchema = z.object({
+    id: z.string().regex(UUID_PATTERN, 'Invalid UUID format')
+        .describe('UUID of the schedule to update (from actual_schedules_get)'),
+    name: z.string().optional()
+        .describe('New display name for the schedule'),
+    payee: z.string().regex(UUID_PATTERN, 'Invalid UUID format').nullable().optional()
+        .describe('New payee UUID, or null to clear'),
+    account: z.string().regex(UUID_PATTERN, 'Invalid UUID format').nullable().optional()
+        .describe('New account UUID, or null to clear'),
+    amount: z.number().int().optional()
+        .describe('New amount in cents. Negative = expense, positive = income'),
+    amountOp: z.enum(['is', 'isapprox', 'isbetween']).optional()
+        .describe('How to match the amount'),
+    date: z.union([
+        z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+        z.object({}).passthrough(),
+    ]).optional()
+        .describe('New date string (YYYY-MM-DD) or RecurConfig object'),
+    posts_transaction: z.boolean().optional()
+        .describe('Whether Actual auto-posts a transaction on each occurrence'),
+    completed: z.boolean().optional()
+        .describe('Mark the schedule as completed (true) or reactivate it (false)'),
+    resetNextDate: z.boolean().optional().default(false)
+        .describe('When true, recalculates next_date based on the updated date/recurrence config. Set to true whenever you change the date field.'),
+});
+const tool = {
+    name: 'actual_schedules_update',
+    description: `Update an existing schedule in Actual Budget. Supply the schedule's UUID and only the fields you want to change. Set resetNextDate: true when changing the date or recurrence config to force recalculation of next_date.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        const { id, resetNextDate, ...fields } = input;
+        await adapter.updateSchedule(id, fields, resetNextDate ?? false);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/server_get_version.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({}).strict();
+const tool = {
+    name: 'actual_server_get_version',
+    description: `Get the version of the Actual Budget server.
+
+Returns the version string of the connected Actual Budget server instance.
+This is the self-hosted Actual Budget server version, not the MCP server version.
+
+Use 'actual_server_info' for MCP server details (Node.js, tool count, uptime).
+Use this tool to check the Actual Budget server version for compatibility or diagnostics.
+
+Returns:
+- { version: string } on success
+- { error: string } if the version cannot be retrieved`,
+    inputSchema: InputSchema,
+    call: async (_args) => {
+        return await adapter.getServerVersion();
+    },
+};
+export default tool;

package/dist/src/tools/server_info.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import actualToolsManager from '../actualToolsManager.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Read version from environment variable (set during Docker build) or package.json
+let packageInfo;
+try {
+    const packagePath = join(__dirname, '../../../package.json');
+    const packageJson = readFileSync(packagePath, 'utf-8');
+    packageInfo = JSON.parse(packageJson);
+    // Use VERSION environment variable if available (set by Docker build or CI/CD)
+    // This includes development metadata like: 0.2.4-dev-abc1234
+    if (process.env.VERSION && process.env.VERSION !== 'unknown') {
+        packageInfo.version = process.env.VERSION;
+    }
+    else {
+        // Fallback: Try to append git commit hash for local development builds
+        try {
+            const { execSync } = require('child_process');
+            const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8', cwd: join(__dirname, '../../..') }).trim();
+            const commitHash = execSync('git rev-parse --short HEAD', { encoding: 'utf8', cwd: join(__dirname, '../../..') }).trim();
+            if (branch === 'develop' || branch === 'development' || branch !== 'main') {
+                packageInfo.version = `${packageInfo.version}-dev-${commitHash}`;
+            }
+        }
+        catch (gitErr) {
+            // Git not available or not in a git repo, use package.json version as-is
+        }
+    }
+}
+catch (error) {
+    packageInfo = { version: 'unknown', name: 'actual-mcp-server', description: 'MCP server for Actual Budget' };
+}
+const InputSchema = z.object({}).strict();
+const tool = {
+    name: 'actual_server_info',
+    description: `Get MCP server version and system information.
+
+Returns:
+- Server version
+- Server name
+- Node.js version
+- MCP SDK version
+- Actual Budget API version
+- Total tools available
+- Uptime
+
+Use this to check server status, verify version compatibility, or debug issues.`,
+    inputSchema: InputSchema,
+    call: async (_args, _meta) => {
+        const uptime = process.uptime();
+        const uptimeFormatted = `${Math.floor(uptime / 3600)}h ${Math.floor((uptime % 3600) / 60)}m ${Math.floor(uptime % 60)}s`;
+        return {
+            server: {
+                name: packageInfo.name,
+                version: packageInfo.version,
+                description: packageInfo.description,
+                transport: process.env.MCP_STDIO_MODE === 'true' ? 'stdio' : 'http',
+            },
+            runtime: {
+                node: process.version,
+                platform: process.platform,
+                arch: process.arch,
+            },
+            dependencies: {
+                mcpSdk: packageInfo.dependencies?.['@modelcontextprotocol/sdk'] ?? 'unknown',
+                actualApi: packageInfo.dependencies?.['@actual-app/api'] ?? 'unknown',
+            },
+            status: {
+                uptime: uptimeFormatted,
+                uptimeSeconds: Math.floor(uptime),
+                memoryUsage: {
+                    heapUsed: Math.round(process.memoryUsage().heapUsed / 1024 / 1024) + ' MB',
+                    heapTotal: Math.round(process.memoryUsage().heapTotal / 1024 / 1024) + ' MB',
+                },
+            },
+            tools: {
+                total: actualToolsManager.getToolNames().length,
+            },
+        };
+    },
+};
+export default tool;

package/dist/src/tools/session_close.js

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { connectionPool } from '../lib/ActualConnectionPool.js';
+import { shutdownActualForSession } from '../actualConnection.js';
+const InputSchema = z.object({
+    sessionId: z.string().optional().describe('Session ID to close (partial match). If not provided, closes the oldest idle session.'),
+});
+const tool = {
+    name: 'actual_session_close',
+    description: 'Close an idle MCP session to free up connection slots. Useful when you get "Max concurrent sessions reached" errors. Only closes sessions other than the current one.',
+    inputSchema: InputSchema,
+    call: async (args, meta) => {
+        const input = InputSchema.parse(args || {});
+        const stats = connectionPool.getStats();
+        if (stats.totalSessions === 0) {
+            return {
+                success: false,
+                message: 'No sessions to close',
+                currentSessions: stats.totalSessions,
+                maxConcurrent: stats.maxConcurrent,
+            };
+        }
+        // Get current session ID from request context to prevent closing own session
+        const { requestContext } = await import('../server/httpServer.js');
+        const context = requestContext.getStore();
+        const currentSessionId = context?.sessionId;
+        // Find session to close
+        let targetSessionId = null;
+        if (input.sessionId) {
+            // Find session by partial match
+            const matchingSessions = stats.sessions.filter(s => s.sessionId.toLowerCase().includes(input.sessionId.toLowerCase()));
+            if (matchingSessions.length === 0) {
+                return {
+                    success: false,
+                    message: `No session found matching "${input.sessionId}"`,
+                    availableSessions: stats.sessions.map(s => s.sessionId),
+                };
+            }
+            if (matchingSessions.length > 1) {
+                return {
+                    success: false,
+                    message: `Multiple sessions match "${input.sessionId}". Please be more specific.`,
+                    matchingSessions: matchingSessions.map(s => s.sessionId),
+                };
+            }
+            targetSessionId = matchingSessions[0].sessionId;
+        }
+        else {
+            // Close the oldest idle session (not current session)
+            const sortedSessions = [...stats.sessions]
+                .filter(s => !currentSessionId || !s.sessionId.includes(currentSessionId))
+                .sort((a, b) => b.idleMinutes - a.idleMinutes);
+            if (sortedSessions.length === 0) {
+                return {
+                    success: false,
+                    message: 'No other sessions to close (only your current session is active)',
+                    currentSessions: stats.totalSessions,
+                };
+            }
+            targetSessionId = sortedSessions[0].sessionId;
+        }
+        // Don't allow closing current session
+        if (currentSessionId && targetSessionId.includes(currentSessionId)) {
+            return {
+                success: false,
+                message: 'Cannot close your current session. Please specify a different session.',
+                currentSessionId,
+            };
+        }
+        // Close the session
+        try {
+            // Verify session exists in connection pool
+            const connectionMap = connectionPool.connections;
+            if (!connectionMap.has(targetSessionId)) {
+                return {
+                    success: false,
+                    message: `Session ${targetSessionId} not found in connection pool`,
+                    availableSessions: Array.from(connectionMap.keys()),
+                };
+            }
+            await shutdownActualForSession(targetSessionId);
+            const newStats = connectionPool.getStats();
+            return {
+                success: true,
+                message: `Session ${targetSessionId} closed successfully`,
+                closedSession: targetSessionId,
+                remainingSessions: newStats.totalSessions,
+                maxConcurrent: newStats.maxConcurrent,
+                availableSlots: newStats.maxConcurrent - newStats.activeSessions,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                message: `Failed to close session: ${err.message}`,
+                error: String(err),
+            };
+        }
+    },
+};
+export default tool;

package/dist/src/tools/session_list.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { connectionPool } from '../lib/ActualConnectionPool.js';
+const InputSchema = z.object({});
+const tool = {
+    name: 'actual_session_list',
+    description: 'List all active MCP sessions with their activity status. Useful for diagnosing connection issues or seeing which sessions can be closed.',
+    inputSchema: InputSchema,
+    call: async (_args) => {
+        const stats = connectionPool.getStats();
+        return {
+            totalSessions: stats.totalSessions,
+            activeSessions: stats.activeSessions,
+            maxConcurrent: stats.maxConcurrent,
+            availableSlots: stats.maxConcurrent - stats.activeSessions,
+            sessions: stats.sessions.map(s => ({
+                sessionId: s.sessionId,
+                lastActivity: s.lastActivity,
+                idleMinutes: s.idleMinutes,
+                status: s.idleMinutes > 5 ? 'idle' : 'active',
+            })),
+        };
+    },
+};
+export default tool;

package/dist/src/tools/transactions_create.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+const InputSchema = z.object({
+    account: CommonSchemas.accountId,
+    date: CommonSchemas.date,
+    amount: CommonSchemas.amountCents,
+    payee: CommonSchemas.payeeId.optional(),
+    payee_name: z.string().optional().describe('Payee name (alternative to payee ID)'),
+    notes: CommonSchemas.notes,
+    category: CommonSchemas.categoryId.optional(),
+    cleared: CommonSchemas.cleared,
+    imported_id: z.string().optional().describe('Original imported transaction ID'),
+});
+const tool = {
+    name: 'actual_transactions_create',
+    description: 'Create a new transaction in Actual Budget. Amount should be in cents (negative for expenses, positive for income).',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        try {
+            // Use addTransactions - it reliably creates transactions.
+            // Note: API may return "ok" string instead of a UUID depending on server version.
+            // "ok" is a valid success indicator — the transaction WAS created.
+            const result = await adapter.addTransactions(input);
+            if (!result || result.length === 0) {
+                return {
+                    success: false,
+                    error: 'Failed to create transaction — no result returned from API. Use actual_accounts_list to verify the account ID.',
+                    id: null,
+                };
+            }
+            // The API sometimes returns a UUID and sometimes "ok" depending on server version.
+            // Both are success — "ok" means created but no ID available from this API version.
+            const maybeId = result[0] && result[0] !== 'ok' && result[0].length > 10
+                ? result[0]
+                : null;
+            return { success: true, id: maybeId };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            if (msg.toLowerCase().includes('not found') && msg.toLowerCase().includes('account')) {
+                // Return structured error (not throw) so callers receive { success: false, error }
+                return { success: false, error: msg, id: null };
+            }
+            throw new Error(`Failed to create transaction: ${msg}`);
+        }
+    },
+};
+export default tool;

package/dist/src/tools/transactions_delete.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    id: z.string().describe('Transaction ID to delete'),
+});
+const tool = {
+    name: 'actual_transactions_delete',
+    description: 'Delete a transaction from Actual Budget by its ID. ' +
+        'Note: if the transaction does not exist, the call will still return { success: true } ' +
+        'because the Actual Budget API does not distinguish between a successful delete and a no-op. ' +
+        'Use actual_transactions_filter to verify the transaction exists before deleting. ' +
+        'This permanently removes the transaction and updates account balances accordingly. This operation cannot be undone.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        await adapter.deleteTransaction(input.id);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/transactions_filter.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    accountId: z.string().nullable().optional().describe('Filter by specific account ID'),
+    startDate: z.string().nullable().optional().describe('Start date (YYYY-MM-DD format)'),
+    endDate: z.string().nullable().optional().describe('End date (YYYY-MM-DD format)'),
+    minAmount: z.number().nullable().optional().describe('Minimum transaction amount in cents (negative for expenses)'),
+    maxAmount: z.number().nullable().optional().describe('Maximum transaction amount in cents'),
+    categoryId: z.string().nullable().optional().describe('Filter by category ID'),
+    payeeId: z.string().nullable().optional().describe('Filter by payee ID'),
+    notes: z.string().nullable().optional().describe('Search in transaction notes (case-insensitive)'),
+    cleared: z.boolean().nullable().optional().describe('Filter by cleared status'),
+    reconciled: z.boolean().nullable().optional().describe('Filter by reconciled status'),
+});
+const tool = {
+    name: 'actual_transactions_filter',
+    description: 'Get transactions with advanced filtering. Supports filtering by amount range, category, payee, notes, and status. Returns filtered transactions matching all specified criteria.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Convert null to undefined for adapter (LibreChat sends null, adapter expects undefined)
+        const accountId = input.accountId ?? undefined;
+        const startDate = input.startDate ?? undefined;
+        const endDate = input.endDate ?? undefined;
+        // Get base transactions
+        const transactions = await adapter.getTransactions(accountId, startDate, endDate);
+        if (!Array.isArray(transactions)) {
+            return { result: [] };
+        }
+        // Exclude off-budget accounts (issue #81) — their transactions cannot have
+        // categories set; any update is silently discarded by Actual Budget.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await adapter.getAccounts();
+        const offBudgetIds = new Set(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (Array.isArray(accounts) ? accounts : [])
+            .filter((acc) => acc?.offbudget === true)
+            .map((acc) => acc.id));
+        // Apply filters
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let filtered = transactions.filter((t) => !offBudgetIds.has(t?.account));
+        // Filter by amount range
+        if (input.minAmount !== undefined) {
+            filtered = filtered.filter((t) => (t.amount || 0) >= input.minAmount);
+        }
+        if (input.maxAmount !== undefined) {
+            filtered = filtered.filter((t) => (t.amount || 0) <= input.maxAmount);
+        }
+        // Filter by category
+        if (input.categoryId) {
+            filtered = filtered.filter((t) => t.category === input.categoryId);
+        }
+        // Filter by payee
+        if (input.payeeId) {
+            filtered = filtered.filter((t) => t.payee === input.payeeId);
+        }
+        // Filter by notes (case-insensitive search)
+        if (input.notes) {
+            const searchTerm = input.notes.toLowerCase();
+            filtered = filtered.filter((t) => t.notes && t.notes.toLowerCase().includes(searchTerm));
+        }
+        // Filter by cleared status
+        if (input.cleared !== undefined) {
+            filtered = filtered.filter((t) => t.cleared === input.cleared);
+        }
+        // Filter by reconciled status
+        if (input.reconciled !== undefined) {
+            filtered = filtered.filter((t) => t.reconciled === input.reconciled);
+        }
+        return { result: filtered };
+    },
+};
+export default tool;

package/dist/src/tools/transactions_get.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+import { notFoundMsg } from '../lib/errors.js';
+const InputSchema = z.object({ accountId: z.string().optional(), startDate: z.string().optional(), endDate: z.string().optional() });
+const tool = {
+    name: 'actual_transactions_get',
+    description: "Get all transactions for a specific account within a date range. Returns transaction details including date, amount (cents), payee, category, notes, and cleared status. Dates in YYYY-MM-DD format. Perfect for account reconciliation and spending analysis.",
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Pre-flight: verify account exists when accountId is provided (BUG-7)
+        if (input.accountId) {
+            const accounts = await adapter.getAccounts();
+            const accountExists = accounts.some((a) => a.id === input.accountId);
+            if (!accountExists) {
+                return { error: notFoundMsg('Account', input.accountId, 'actual_accounts_list') };
+            }
+        }
+        const result = await adapter.getTransactions(input.accountId, input.startDate, input.endDate);
+        return { result };
+    },
+};
+export default tool;

package/dist/src/tools/transactions_import.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+// Allow either an object with accountId and txs, or raw tx array/object — keep validation light
+// NOTE: Wrapped in z.object() for LibreChat compatibility (requires type: "object")
+const InputSchema = z.object({
+    accountId: z.string().optional(),
+    txs: z.unknown(),
+});
+const tool = {
+    name: 'actual_transactions_import',
+    description: "Bulk import transactions with automatic reconciliation and duplicate detection. Matches against existing transactions using imported_id to prevent duplicates. Ideal for importing bank statements, CSV files, or syncing from external sources. Automatically applies budget rules.",
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const parsed = InputSchema.parse(args || {});
+        const accountId = parsed.accountId;
+        const txs = parsed.txs;
+        const result = await adapter.importTransactions(accountId, txs);
+        return { result };
+    },
+};
+export default tool;

package/dist/src/tools/transactions_search_by_amount.js

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    minAmount: z.number().optional().describe('Minimum amount in cents (use negative for expenses, e.g., -10000 for $-100.00). For expenses, use negative values (e.g., -5000 for -$50.00)'),
+    maxAmount: z.number().optional().describe('Maximum amount in cents (e.g., 10000 for $100.00). For expenses, use negative values (e.g., -5000 for -$50.00)'),
+    absoluteAmount: z.number().optional().describe('Optional: Search by absolute value (magnitude) in cents, ignoring sign. E.g., 5000 will match both +$50.00 (income) and -$50.00 (expense). If specified, minAmount/maxAmount are ignored.'),
+    startDate: z.string().optional().describe('Optional: Start date in YYYY-MM-DD format'),
+    endDate: z.string().optional().describe('Optional: End date in YYYY-MM-DD format'),
+    accountId: z.string().optional().describe('Optional: Filter by specific account ID'),
+    categoryName: z.string().optional().describe('Optional: Filter by category name'),
+    limit: z.number().optional().default(100).describe('Optional: Maximum number of transactions to return (default: 100)'),
+});
+const tool = {
+    name: 'actual_transactions_search_by_amount',
+    description: 'Search transactions by amount. Supports two modes: (1) Signed amount range using minAmount/maxAmount (expenses are negative, e.g., -5000 for -$50), or (2) Absolute value using absoluteAmount to find any transaction with that magnitude regardless of sign (e.g., absoluteAmount=5000 matches both +$50 income and -$50 expense). When user says "amount 50", use absoluteAmount=5000 to match both income and expenses.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Validate accountId exists if provided
+        if (input.accountId) {
+            const accounts = await adapter.getAccounts();
+            const accountExists = accounts.some((acc) => acc.id === input.accountId);
+            if (!accountExists) {
+                // Check if user provided account name instead of UUID
+                const accountByName = accounts.find((acc) => acc.name && acc.name.toLowerCase() === input.accountId.toLowerCase());
+                if (accountByName) {
+                    return {
+                        transactions: [],
+                        count: 0,
+                        totalAmount: 0,
+                        amountRange: {
+                            min: input.minAmount,
+                            max: input.maxAmount,
+                        },
+                        error: `Account '${input.accountId}' appears to be a name, not an ID. Use account UUID '${accountByName.id}' instead.`,
+                    };
+                }
+                return {
+                    transactions: [],
+                    count: 0,
+                    totalAmount: 0,
+                    amountRange: {
+                        min: input.minAmount,
+                        max: input.maxAmount,
+                    },
+                    error: `Account '${input.accountId}' not found. Did you mean to use account UUID instead of name? Use actual_accounts_list to get valid account UUIDs.`,
+                };
+            }
+        }
+        // Get base transactions (filtered by account and date range if provided)
+        const allTransactions = await adapter.getTransactions(input.accountId, input.startDate, input.endDate);
+        if (!Array.isArray(allTransactions)) {
+            return {
+                transactions: [],
+                count: 0,
+                totalAmount: 0,
+                amountRange: {
+                    min: input.minAmount,
+                    max: input.maxAmount,
+                },
+            };
+        }
+        // Apply JavaScript filters
+        let filtered = allTransactions;
+        // Filter by absolute amount (if specified, this takes precedence)
+        if (input.absoluteAmount !== undefined) {
+            const targetAbs = Math.abs(input.absoluteAmount);
+            filtered = filtered.filter((t) => Math.abs(t.amount || 0) === targetAbs);
+        }
+        else {
+            // Filter by signed amount range
+            if (input.minAmount !== undefined) {
+                filtered = filtered.filter((t) => (t.amount || 0) >= input.minAmount);
+            }
+            if (input.maxAmount !== undefined) {
+                filtered = filtered.filter((t) => (t.amount || 0) <= input.maxAmount);
+            }
+        }
+        // Filter by category name (need to lookup category ID)
+        if (input.categoryName) {
+            const categories = await adapter.getCategories();
+            const category = categories.find((c) => c.name && c.name.toLowerCase() === input.categoryName.toLowerCase());
+            if (category) {
+                filtered = filtered.filter((t) => t.category === category.id);
+            }
+            else {
+                // Category not found - return empty
+                return {
+                    transactions: [],
+                    count: 0,
+                    totalAmount: 0,
+                    amountRange: {
+                        min: input.minAmount,
+                        max: input.maxAmount,
+                    },
+                    error: `Category "${input.categoryName}" not found`,
+                };
+            }
+        }
+        // Sort by amount descending and apply limit
+        filtered.sort((a, b) => {
+            const amountA = a.amount || 0;
+            const amountB = b.amount || 0;
+            return amountB - amountA;
+        });
+        const limited = filtered.slice(0, input.limit || 100);
+        // Enrich transactions with account names
+        const accounts = await adapter.getAccounts();
+        const accountMap = new Map(accounts.map((acc) => [acc.id, acc.name]));
+        const enrichedTransactions = limited.map((t) => ({
+            ...t,
+            accountName: accountMap.get(t.account) || t.account,
+        }));
+        // Calculate summary stats
+        const totalAmount = limited.reduce((sum, t) => sum + (t.amount || 0), 0);
+        return {
+            transactions: enrichedTransactions,
+            count: enrichedTransactions.length,
+            totalAmount,
+            amountRange: input.absoluteAmount !== undefined
+                ? { absolute: input.absoluteAmount }
+                : { min: input.minAmount, max: input.maxAmount },
+        };
+    },
+};
+export default tool;