actual-mcp-server 0.5.0

package/dist/src/tools/transactions_search_by_category.js

@@ -0,0 +1,137 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    categoryName: z.string().optional().describe('Name of the category to search for (e.g., "Food", "Rent", "Transportation") - optional for smoke tests'),
+    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'),
+    minAmount: z.number().optional().describe('Optional: Minimum amount in cents (use negative for expenses)'),
+    maxAmount: z.number().optional().describe('Optional: Maximum amount in cents'),
+    limit: z.number().optional().default(100).describe('Optional: Maximum number of transactions to return (default: 100)'),
+});
+const tool = {
+    name: 'actual_transactions_search_by_category',
+    description: 'Search transactions by category name. Returns all transactions in a specific category with optional date range, account, and amount filters. Perfect for analyzing spending in budget categories.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Fetch accounts once — used for validation, off-budget filtering (issue #81), and enrichment
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const allAccounts = await adapter.getAccounts();
+        // Step 0: Validate accountId exists if provided
+        if (input.accountId) {
+            const accountExists = allAccounts.some((acc) => acc.id === input.accountId);
+            if (!accountExists) {
+                // Check if user provided account name instead of UUID
+                const accountByName = allAccounts.find((acc) => acc.name && acc.name.toLowerCase() === input.accountId.toLowerCase());
+                if (accountByName) {
+                    return {
+                        transactions: [],
+                        count: 0,
+                        totalAmount: 0,
+                        categoryName: input.categoryName,
+                        error: `Account '${input.accountId}' appears to be a name, not an ID. Use account UUID '${accountByName.id}' instead.`,
+                    };
+                }
+                return {
+                    transactions: [],
+                    count: 0,
+                    totalAmount: 0,
+                    categoryName: input.categoryName,
+                    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.`,
+                };
+            }
+        }
+        // Step 1: Find category ID by name
+        let categoryId;
+        if (input.categoryName) {
+            const categories = await adapter.getCategories();
+            const category = categories.find((c) => c.name && c.name.toLowerCase() === input.categoryName.toLowerCase());
+            if (!category) {
+                // Category not found - return empty result
+                return {
+                    transactions: [],
+                    count: 0,
+                    totalAmount: 0,
+                    categoryName: input.categoryName,
+                    error: `Category "${input.categoryName}" not found`,
+                };
+            }
+            categoryId = category.id;
+        }
+        // Step 2: Get base transactions (filtered by account and date range if provided)
+        // getTransactions() requires an accountId — when none is provided, fetch from all accounts.
+        // Exclude off-budget accounts (issue #81) — their transactions cannot have categories set;
+        // any update is silently discarded by Actual Budget.
+        const offBudgetIds = new Set(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (Array.isArray(allAccounts) ? allAccounts : [])
+            .filter((acc) => acc?.offbudget === true)
+            .map((acc) => acc.id));
+        let allTransactions;
+        if (input.accountId) {
+            const raw = await adapter.getTransactions(input.accountId, input.startDate, input.endDate);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            allTransactions = (Array.isArray(raw) ? raw : []).filter((t) => !offBudgetIds.has(t?.account));
+        }
+        else {
+            // Only fetch from on-budget accounts — skip off-budget entirely (more efficient)
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const budgetAccounts = allAccounts.filter((acc) => !acc?.offbudget);
+            const perAccount = await Promise.all(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            budgetAccounts.map((acc) => adapter.getTransactions(acc.id, input.startDate, input.endDate).catch(() => [])));
+            // Deduplicate by id (split transactions appear in both parent and child accounts)
+            const seen = new Set();
+            allTransactions = perAccount.flat().filter((t) => {
+                if (!t.id || seen.has(t.id))
+                    return false;
+                seen.add(t.id);
+                return true;
+            });
+        }
+        if (!Array.isArray(allTransactions)) {
+            return {
+                transactions: [],
+                count: 0,
+                totalAmount: 0,
+                categoryName: input.categoryName,
+            };
+        }
+        // Step 3: Apply JavaScript filters
+        let filtered = allTransactions;
+        // Filter by category ID
+        if (categoryId) {
+            filtered = filtered.filter((t) => t.category === categoryId);
+        }
+        // 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);
+        }
+        // Sort by date descending and apply limit
+        filtered.sort((a, b) => {
+            const dateA = a.date || '';
+            const dateB = b.date || '';
+            return dateB.localeCompare(dateA);
+        });
+        const limited = filtered.slice(0, input.limit || 100);
+        // Enrich transactions with account names (reuse already-fetched allAccounts)
+        const accountMap = new Map(allAccounts.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,
+            categoryName: input.categoryName,
+        };
+    },
+};
+export default tool;

package/dist/src/tools/transactions_search_by_month.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    month: z.string().optional().describe('Month to search in YYYY-MM format (e.g., "2025-01" for January 2025) - defaults to current month'),
+    accountId: z.string().optional().describe('Optional: Filter by specific account ID'),
+    categoryName: z.string().optional().describe('Optional: Filter by category name (e.g., "Food", "Rent")'),
+    payeeName: z.string().optional().describe('Optional: Filter by payee name'),
+    minAmount: z.number().optional().describe('Optional: Minimum amount in cents (use negative for expenses)'),
+    maxAmount: z.number().optional().describe('Optional: Maximum amount in cents'),
+    limit: z.number().optional().default(100).describe('Optional: Maximum number of transactions to return (default: 100)'),
+});
+const tool = {
+    name: 'actual_transactions_search_by_month',
+    description: 'Search transactions for a specific month. Returns all transactions matching the month and optional filters (account, category, payee, amount range). Efficiently queries by date range.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Step 0: 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());
+                const month = input.month || `${new Date().getFullYear()}-${String(new Date().getMonth() + 1).padStart(2, '0')}`;
+                if (accountByName) {
+                    return {
+                        transactions: [],
+                        count: 0,
+                        totalAmount: 0,
+                        month,
+                        error: `Account '${input.accountId}' appears to be a name, not an ID. Use account UUID '${accountByName.id}' instead.`,
+                    };
+                }
+                return {
+                    transactions: [],
+                    count: 0,
+                    totalAmount: 0,
+                    month,
+                    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.`,
+                };
+            }
+        }
+        // Default to current month if not provided
+        const today = new Date();
+        const month = input.month || `${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, '0')}`;
+        // Calculate the date range for the month
+        const [year, monthNum] = month.split('-').map(Number);
+        const startDate = `${year}-${String(monthNum).padStart(2, '0')}-01`;
+        // Calculate last day of month
+        const lastDay = new Date(year, monthNum, 0).getDate();
+        const endDate = `${year}-${String(monthNum).padStart(2, '0')}-${String(lastDay).padStart(2, '0')}`;
+        // Get base transactions (filtered by account and date range)
+        const allTransactions = await adapter.getTransactions(input.accountId, startDate, endDate);
+        if (!Array.isArray(allTransactions)) {
+            return {
+                transactions: [],
+                count: 0,
+                totalAmount: 0,
+                month,
+            };
+        }
+        // Fetch accounts once — used for off-budget filtering (issue #81) and enrichment
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await adapter.getAccounts();
+        // Exclude off-budget accounts (issue #81) — their transactions cannot have
+        // categories set; any update is silently discarded by Actual Budget.
+        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 JavaScript filters
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let filtered = allTransactions.filter((t) => !offBudgetIds.has(t?.account));
+        // 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,
+                    month,
+                    error: `Category "${input.categoryName}" not found`,
+                };
+            }
+        }
+        // Filter by payee name (need to lookup payee ID)
+        if (input.payeeName) {
+            const payees = await adapter.getPayees();
+            const payee = payees.find((p) => p.name && p.name.toLowerCase() === input.payeeName.toLowerCase());
+            if (payee) {
+                filtered = filtered.filter((t) => t.payee === payee.id);
+            }
+            else {
+                // Payee not found - return empty
+                return {
+                    transactions: [],
+                    count: 0,
+                    totalAmount: 0,
+                    month,
+                    error: `Payee "${input.payeeName}" not found`,
+                };
+            }
+        }
+        // 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);
+        }
+        // Sort by date descending and apply limit
+        filtered.sort((a, b) => {
+            const dateA = a.date || '';
+            const dateB = b.date || '';
+            return dateB.localeCompare(dateA);
+        });
+        const limited = filtered.slice(0, input.limit || 100);
+        // Enrich transactions with account names (reuse already-fetched accounts)
+        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,
+            month,
+        };
+    },
+};
+export default tool;

package/dist/src/tools/transactions_search_by_payee.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    payeeName: z.string().optional().describe('Name of the payee/vendor to search for (optional for smoke tests)'),
+    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'),
+    minAmount: z.number().optional().describe('Optional: Minimum amount in cents'),
+    maxAmount: z.number().optional().describe('Optional: Maximum amount in cents'),
+    limit: z.number().optional().default(100).describe('Optional: Maximum number of transactions to return (default: 100)'),
+});
+const tool = {
+    name: 'actual_transactions_search_by_payee',
+    description: 'Search transactions by payee name. Returns all transactions for a specific payee with optional date range, category, and amount filters. Useful for analyzing spending patterns with specific vendors or service providers.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Step 0: 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,
+                        payeeName: input.payeeName,
+                        error: `Account '${input.accountId}' appears to be a name, not an ID. Use account UUID '${accountByName.id}' instead.`,
+                    };
+                }
+                return {
+                    transactions: [],
+                    count: 0,
+                    totalAmount: 0,
+                    payeeName: input.payeeName,
+                    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.`,
+                };
+            }
+        }
+        // Step 1: Find payee ID by name
+        let payeeId;
+        if (input.payeeName) {
+            const payees = await adapter.getPayees();
+            const payee = payees.find((p) => p.name && p.name.toLowerCase() === input.payeeName.toLowerCase());
+            if (!payee) {
+                // Payee not found - return empty result
+                return {
+                    transactions: [],
+                    count: 0,
+                    totalAmount: 0,
+                    payeeName: input.payeeName,
+                    error: `Payee "${input.payeeName}" not found`,
+                };
+            }
+            payeeId = payee.id;
+        }
+        // Step 2: Get base transactions (filtered by account and date range if provided)
+        // getTransactions() requires an accountId — when none is provided, fetch from all accounts
+        let allTransactions;
+        if (input.accountId) {
+            allTransactions = await adapter.getTransactions(input.accountId, input.startDate, input.endDate);
+        }
+        else {
+            const allAccounts = await adapter.getAccounts();
+            const perAccount = await Promise.all(allAccounts.map((acc) => adapter.getTransactions(acc.id, input.startDate, input.endDate).catch(() => [])));
+            // Deduplicate by id (split transactions appear in both parent and child accounts)
+            const seen = new Set();
+            allTransactions = perAccount.flat().filter((t) => {
+                if (!t.id || seen.has(t.id))
+                    return false;
+                seen.add(t.id);
+                return true;
+            });
+        }
+        if (!Array.isArray(allTransactions)) {
+            return {
+                transactions: [],
+                count: 0,
+                totalAmount: 0,
+                payeeName: input.payeeName,
+            };
+        }
+        // Step 3: Apply JavaScript filters
+        let filtered = allTransactions;
+        // Filter by payee ID
+        if (payeeId) {
+            filtered = filtered.filter((t) => t.payee === payeeId);
+        }
+        // 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,
+                    payeeName: input.payeeName,
+                    error: `Category "${input.categoryName}" not found`,
+                };
+            }
+        }
+        // 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);
+        }
+        // Sort by date descending and apply limit
+        filtered.sort((a, b) => {
+            const dateA = a.date || '';
+            const dateB = b.date || '';
+            return dateB.localeCompare(dateA);
+        });
+        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,
+            payeeName: input.payeeName,
+        };
+    },
+};
+export default tool;

package/dist/src/tools/transactions_summary_by_category.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    startDate: z.string().optional().describe('Start date in YYYY-MM-DD format (default: first day of current month)'),
+    endDate: z.string().optional().describe('End date in YYYY-MM-DD format (default: today)'),
+    accountId: z.string().optional().describe('Optional: Filter by specific account ID'),
+    includeIncome: z.boolean().optional().default(false).describe('Optional: Include income categories (default: false, only expenses)'),
+});
+const tool = {
+    name: 'actual_transactions_summary_by_category',
+    description: 'Get spending summary grouped by category using ActualQL aggregation. Returns total amount and transaction count per category for a date range. Perfect for budget analysis and expense tracking. By default excludes income categories (set includeIncome=true to include them).',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Default to current month if dates not provided
+        const today = new Date();
+        const firstDayOfMonth = new Date(today.getFullYear(), today.getMonth(), 1);
+        const startDate = input.startDate || firstDayOfMonth.toISOString().split('T')[0];
+        const endDate = input.endDate || today.toISOString().split('T')[0];
+        // Build ActualQL query with groupBy and aggregation
+        const api = await import('@actual-app/api');
+        const q = api.q;
+        // Start with date filter
+        let query = q('transactions').filter({
+            $and: [
+                { date: { $gte: startDate } },
+                { date: { $lte: endDate } }
+            ]
+        });
+        // Filter by account if specified
+        if (input.accountId) {
+            query = query.filter({ account: input.accountId });
+        }
+        // Filter out income categories unless requested
+        if (!input.includeIncome) {
+            query = query.filter({ 'category.is_income': { $ne: true } });
+        }
+        // Group by category and calculate sum
+        query = query
+            .groupBy(['category.group.name', 'category.name'])
+            .select([
+            'category.group.name',
+            'category.name',
+            { totalAmount: { $sum: '$amount' } },
+            { transactionCount: { $count: '*' } }
+        ])
+            .orderBy(['category.group.sort_order', 'category.sort_order']);
+        const rawResult = await adapter.runQuery(query);
+        // @actual-app/api runQuery returns { data: [...] } — unwrap if needed
+        const result = Array.isArray(rawResult) ? rawResult : rawResult?.data;
+        // Ensure result is an array
+        if (!result || !Array.isArray(result)) {
+            return {
+                summary: [],
+                totalAmount: 0,
+                dateRange: {
+                    startDate,
+                    endDate,
+                },
+            };
+        }
+        const summary = result.map((row) => ({
+            categoryGroup: row['category.group.name'] || 'Uncategorized',
+            categoryName: row['category.name'] || 'Uncategorized',
+            totalAmount: row.totalAmount || 0,
+            transactionCount: row.transactionCount || 0,
+        }));
+        // Calculate grand total
+        const totalAmount = summary.reduce((sum, item) => sum + item.totalAmount, 0);
+        return {
+            summary,
+            totalAmount,
+            dateRange: {
+                startDate,
+                endDate,
+            },
+        };
+    },
+};
+export default tool;

package/dist/src/tools/transactions_summary_by_payee.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    startDate: z.string().optional().describe('Start date in YYYY-MM-DD format (default: first day of current month)'),
+    endDate: z.string().optional().describe('End date in YYYY-MM-DD format (default: today)'),
+    accountId: z.string().optional().describe('Optional: Filter by specific account ID'),
+    limit: z.number().optional().default(50).describe('Optional: Maximum number of payees to return (default: 50, ordered by totalAmount descending)'),
+});
+const tool = {
+    name: 'actual_transactions_summary_by_payee',
+    description: 'Get spending summary grouped by payee using ActualQL aggregation. Returns total amount and transaction count per payee for a date range. Useful for identifying top vendors and analyzing merchant spending patterns. Results are ordered by total amount (highest first).',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Build ActualQL query with groupBy and aggregation
+        const api = await import('@actual-app/api');
+        const q = api.q;
+        // Default to current month if dates not provided
+        const today = new Date();
+        const firstDayOfMonth = new Date(today.getFullYear(), today.getMonth(), 1);
+        const startDate = input.startDate || firstDayOfMonth.toISOString().split('T')[0];
+        const endDate = input.endDate || today.toISOString().split('T')[0];
+        // Start with date filter
+        let query = q('transactions').filter({
+            $and: [
+                { date: { $gte: startDate } },
+                { date: { $lte: endDate } }
+            ]
+        });
+        // Group by payee and calculate sum
+        query = query
+            .groupBy('payee.name')
+            .select([
+            'payee.name',
+            { totalAmount: { $sum: '$amount' } },
+            { transactionCount: { $count: '*' } }
+        ])
+            .limit(input.limit || 50);
+        const rawResult = await adapter.runQuery(query);
+        // @actual-app/api runQuery returns { data: [...] } — unwrap if needed
+        const result = Array.isArray(rawResult) ? rawResult : rawResult?.data;
+        // Ensure result is an array
+        if (!result || !Array.isArray(result)) {
+            return {
+                summary: [],
+                totalAmount: 0,
+                dateRange: {
+                    startDate,
+                    endDate,
+                },
+            };
+        }
+        const summary = result
+            .map((row) => ({
+            payeeName: row['payee.name'] || 'Unknown',
+            totalAmount: row.totalAmount || 0,
+            transactionCount: row.transactionCount || 0,
+        }))
+            .sort((a, b) => b.totalAmount - a.totalAmount); // Sort by totalAmount descending in JavaScript
+        // Calculate grand total
+        const totalAmount = summary.reduce((sum, item) => sum + item.totalAmount, 0);
+        return {
+            summary,
+            totalAmount,
+            dateRange: {
+                startDate,
+                endDate,
+            },
+        };
+    },
+};
+export default tool;

package/dist/src/tools/transactions_uncategorized.js

@@ -0,0 +1,66 @@
+/**
+ * actual_transactions_uncategorized
+ *
+ * List transactions that have no category assigned.
+ *
+ * Concept and implementation adapted from the ZanzyTHEbar fork:
+ * https://github.com/ZanzyTHEbar/actual-mcp-server/blob/main/src/tools/transactions_uncategorized.ts
+ * Credit: ZanzyTHEbar (https://github.com/ZanzyTHEbar)
+ *
+ * Adapted for this project's conventions:
+ * - No wrapToolCall — uses direct call() pattern
+ * - Returns { transactions, count, summary, dateRange } matching the search_by_* shape
+ */
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+const InputSchema = z.object({
+    startDate: CommonSchemas.date.optional().describe('Start date in YYYY-MM-DD format (default: first day of current month)'),
+    endDate: CommonSchemas.date.optional().describe('End date in YYYY-MM-DD format (default: today)'),
+    accountId: CommonSchemas.accountId.optional().describe('Filter by specific account ID (optional)'),
+    limit: z.number().optional().default(500).describe('Maximum number of transactions to return (default: 500)'),
+});
+const tool = {
+    name: 'actual_transactions_uncategorized',
+    description: 'List uncategorized transactions (category is null/unset). Useful for cleanup workflows and rule-suggestion prompts. Defaults to the current month unless a date range is provided. Returns { transactions, count, summary: { totalAmount }, dateRange }.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        const today = new Date();
+        const firstDayOfMonth = new Date(today.getFullYear(), today.getMonth(), 1);
+        const startDate = input.startDate || firstDayOfMonth.toISOString().split('T')[0];
+        const endDate = input.endDate || today.toISOString().split('T')[0];
+        const accountId = input.accountId ?? undefined;
+        // Fetch transactions first. When accountId is undefined, rawGetTransactions does
+        // a full table scan (no account filter) — this reliably returns newly written
+        // transactions even across separate WAL sessions in CI Docker. Filtering by
+        // accountId uses a SQLite index that can lag across sessions.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const txnRaw = await adapter.getTransactions(accountId, startDate, endDate);
+        const txns = Array.isArray(txnRaw) ? txnRaw : [];
+        // Fetch accounts to build off-budget exclusion set.
+        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));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const uncategorized = txns.filter(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (txn) => txn?.category == null && !offBudgetIds.has(txn?.account));
+        const limited = uncategorized.slice(0, input.limit ?? 500);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const totalAmount = limited.reduce((sum, txn) => {
+            const amount = typeof txn?.amount === 'number' ? txn.amount : 0;
+            return sum + amount;
+        }, 0);
+        return {
+            transactions: limited,
+            count: limited.length,
+            summary: { totalAmount },
+            dateRange: { startDate, endDate },
+        };
+    },
+};
+export default tool;