actual-mcp-server 0.5.8 → 0.6.0

package/README.md

@@ -296,7 +296,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_accounts_reopen` | Reopen closed account |
 | `actual_accounts_get_balance` | Get account balance at a date |
 
-### Transactions (12)
+### Transactions (13)
 
 **Standard (6)**
 
@@ -309,6 +309,12 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_transactions_update` | Update a transaction |
 | `actual_transactions_delete` | Delete a transaction |
 
+**Utility (1)**
+
+| Tool | Description |
+|------|-------------|
+| `actual_transactions_uncategorized` | Summary of uncategorized transactions (totalCount, totalAmount, per-account breakdown); pass `includeTransactions:true` for paginated rows |
+
 **Exclusive ActualQL-powered (6)** — unique to this MCP server
 
 | Tool | Description |
@@ -724,4 +730,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.5.8 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.0 | **Tool Count:** 63 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.5.8",
+    "version": "0.6.0",
     "engines": {
         "node": ">=20.0.0",
         "npm": ">=10.0.0"

package/dist/src/tools/transactions_uncategorized.js

@@ -1,15 +1,13 @@
 /**
  * actual_transactions_uncategorized
  *
- * List transactions that have no category assigned.
+ * Returns a summary of uncategorized transactions by default (totalCount, totalAmount,
+ * per-account breakdown). Pass includeTransactions:true to also receive a paginated
+ * transaction list with limit/offset/hasMore.
  *
  * 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';
@@ -17,12 +15,30 @@ 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)'),
+    accountId: CommonSchemas.accountId.optional().describe('Filter to a specific account ID (optional)'),
+    includeTransactions: z.boolean().optional().default(false).describe('When true, include paginated transaction rows in the response (default: false)'),
+    limit: z.number().int().min(1).max(1000).optional().default(50).describe('Max transactions per page when includeTransactions is true (default: 50, max: 1000)'),
+    offset: z.number().int().min(0).optional().default(0).describe('Pagination start index when includeTransactions is true (default: 0)'),
 });
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isUncategorized(txn, excludedAccountIds) {
+    return (txn?.category == null &&
+        txn?.transfer_id == null &&
+        txn?.is_parent !== true &&
+        txn?.starting_balance_flag !== true &&
+        !excludedAccountIds.has(txn?.account));
+}
 const tool = {
     name: 'actual_transactions_uncategorized',
-    description: 'List uncategorized transactions (category is null/unset). Excludes transfers, split-transaction parents, opening balance entries, off-budget accounts, and closed accounts — matching Actual Budget\'s own Uncategorized view. Defaults to the current month unless a date range is provided. Returns { transactions, count, summary: { totalAmount }, dateRange }.',
+    description: [
+        'Get uncategorized transactions summary and optional paginated list.',
+        'Default response: { totalCount, totalAmount, byAccount: [{accountId, accountName, count, totalAmount}], dateRange }.',
+        'Pass includeTransactions:true to also receive transactions[], count, hasMore, offset, limit.',
+        'Use limit (default 50, max 1000) and offset for pagination.',
+        'Excludes: transfers, split-transaction parents, opening balance entries, off-budget accounts, and closed accounts.',
+        'When accountId is provided, all fields are scoped to that account.',
+        'Note: the legacy summary.totalAmount field has been removed — totalAmount is now at the top level.',
+    ].join(' '),
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
@@ -31,40 +47,69 @@ const tool = {
         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.
+        // Full table scan when no accountId — reliably returns newly written transactions
+        // across separate WAL sessions in CI Docker. Filtering by accountId uses an 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 exclusion set: off-budget + closed accounts.
+        // Fetch accounts for exclusion set (off-budget + closed) and name lookup.
+        // Two separate withActualApi sessions is intentional for a read-only tool —
+        // keeps each call isolated. If latency becomes a concern, both could be merged
+        // into a single withActualApi using the raw API directly.
         const accounts = await adapter.getAccounts();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accountList = Array.isArray(accounts) ? accounts : [];
         const excludedAccountIds = new Set(
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (Array.isArray(accounts) ? accounts : [])
+        accountList
             .filter((acc) => acc?.offbudget === true || acc?.closed === true)
             .map((acc) => acc.id));
+        const accountNameMap = new Map(
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const uncategorized = txns.filter(
+        accountList.map((acc) => [acc.id, acc.name]));
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (txn) => txn?.category == null &&
-            txn?.transfer_id == null &&
-            txn?.is_parent !== true &&
-            txn?.starting_balance_flag !== true &&
-            !excludedAccountIds.has(txn?.account));
-        const limited = uncategorized.slice(0, input.limit ?? 500);
+        const uncategorized = txns.filter((txn) => isUncategorized(txn, excludedAccountIds));
+        const totalCount = uncategorized.length;
         // 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;
+        const totalAmount = uncategorized.reduce((sum, txn) => {
+            return sum + (typeof txn?.amount === 'number' ? txn.amount : 0);
         }, 0);
-        return {
-            transactions: limited,
-            count: limited.length,
-            summary: { totalAmount },
+        // Per-account breakdown — one entry per on-budget open account with ≥1 uncategorized txn
+        const byAccountMap = new Map();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        for (const txn of uncategorized) {
+            const acctId = txn?.account;
+            if (!acctId)
+                continue;
+            const entry = byAccountMap.get(acctId) ?? { count: 0, totalAmount: 0 };
+            entry.count += 1;
+            entry.totalAmount += typeof txn?.amount === 'number' ? txn.amount : 0;
+            byAccountMap.set(acctId, entry);
+        }
+        const byAccount = Array.from(byAccountMap.entries()).map(([acctId, data]) => ({
+            accountId: acctId,
+            accountName: accountNameMap.get(acctId) ?? acctId,
+            count: data.count,
+            totalAmount: data.totalAmount,
+        }));
+        const result = {
+            totalCount,
+            totalAmount,
+            byAccount,
             dateRange: { startDate, endDate },
         };
+        if (input.includeTransactions) {
+            const limit = input.limit ?? 50;
+            const offset = input.offset ?? 0;
+            const page = uncategorized.slice(offset, offset + limit);
+            result.transactions = page;
+            result.count = page.length;
+            result.hasMore = offset + page.length < totalCount;
+            result.offset = offset;
+            result.limit = limit;
+        }
+        return result;
     },
 };
 export default tool;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"