actual-mcp-server 0.19.2 → 0.19.3

package/README.md

@@ -778,7 +778,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.19.2 | **Tool Count:** 77 (verified LibreChat-compatible)
+**Version:** 0.19.3 | **Tool Count:** 77 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/lib/financial-analysis.js

@@ -258,6 +258,13 @@ export function summarizeAccountFlow(snapshot, input) {
         const counterpart = transaction.transfer_id ? maps.transactions.get(transaction.transfer_id) : undefined;
         const payee = transaction.payee ? maps.payees.get(transaction.payee) : undefined;
         const counterpartAccountId = counterpart?.account ?? payee?.transfer_acct ?? null;
+        // #428: when the counterpart cannot be resolved (no counterpart row and no payee transfer_acct),
+        // counterpartSelected is false and the leg is bucketed by SIGN into intoSelection / outOfSelection.
+        // This is the deterministic rule: within-selection membership requires POSITIVE proof both legs are
+        // selected, which an unresolvable counterpart cannot give. The outcome is not silent: the
+        // transfersByAccount row below carries matchedCounterpart=false, so a caller can see the leg was
+        // classified without a resolved counterparty. netTransferEffect (line above) already counted the
+        // amount, so reconciliation stays exact regardless of the bucket.
         const counterpartSelected = counterpartAccountId ? selected.has(counterpartAccountId) : false;
         if (counterpartSelected) {
             withinSelectionTimingEffect += amount;
@@ -290,14 +297,25 @@ export function summarizeAccountFlow(snapshot, input) {
             });
         }
     }
-    // The tool handler always supplies balances (via balanceAccountIds), so difference is exact here.
-    // If a future caller omits them, both reduce to 0 and difference reads as a false "exact": #428.
-    const openingBalance = uniqueAccountIds.reduce((sum, id) => sum + integer(snapshot.openingBalances?.[id] ?? 0, `Opening balance for ${id}`), 0);
-    const closingBalance = uniqueAccountIds.reduce((sum, id) => sum + integer(snapshot.closingBalances?.[id] ?? 0, `Closing balance for ${id}`), 0);
-    const balanceChange = closingBalance - openingBalance;
+    // #428: balances are OPTIONAL on the snapshot. The tool handler always supplies them (via
+    // balanceAccountIds), so on the tool path this is true and reconciliation is exact by construction.
+    // A caller that omits either map, though, would otherwise reduce both to 0 and read difference as a
+    // false "exact" zero. The check is on the MAP being undefined (entirely unpopulated), NOT a per-id
+    // lookup: the `?? 0` per-id default is legitimate for a genuine zero-balance account.
+    const balancesAvailable = snapshot.openingBalances !== undefined && snapshot.closingBalances !== undefined;
+    const openingBalance = balancesAvailable
+        ? uniqueAccountIds.reduce((sum, id) => sum + integer(snapshot.openingBalances?.[id] ?? 0, `Opening balance for ${id}`), 0)
+        : null;
+    const closingBalance = balancesAvailable
+        ? uniqueAccountIds.reduce((sum, id) => sum + integer(snapshot.closingBalances?.[id] ?? 0, `Closing balance for ${id}`), 0)
+        : null;
+    const balanceChange = openingBalance !== null && closingBalance !== null ? closingBalance - openingBalance : null;
     const netExternalCashFlow = income - incomeReversals + credits + uncategorizedInflows - expenseOutflow;
     const totalAdjustments = startingBalance;
     const calculatedBalanceChange = netExternalCashFlow + netTransferEffect + totalAdjustments;
+    // When balances are unavailable, difference must NOT read as a reconciled value. Null it so a
+    // caller cannot mistake an unpopulated run for a reconciled one.
+    const difference = balanceChange !== null ? balanceChange - calculatedBalanceChange : null;
     return {
         dateRange: { startDate: input.startDate, endDate: input.endDate },
         accounts: uniqueAccountIds.map(id => ({ id, name: maps.accounts.get(id)?.name ?? id })),
@@ -322,9 +340,12 @@ export function summarizeAccountFlow(snapshot, input) {
         transfersByAccount: transfersByAccount.sort((a, b) => `${a.date}:${a.fromAccountId}:${a.toAccountId}`.localeCompare(`${b.date}:${b.fromAccountId}:${b.toAccountId}`)),
         adjustments: { startingBalance, total: totalAdjustments },
         reconciliation: {
+            // #428: balancesAvailable is false when the snapshot omitted the balance maps; difference and
+            // actualBalanceChange are then null so an unpopulated run cannot read as a reconciled one.
+            balancesAvailable,
             calculatedBalanceChange,
             actualBalanceChange: balanceChange,
-            difference: balanceChange - calculatedBalanceChange,
+            difference,
         },
     };
 }

package/dist/src/tools/account_flow_summary.js

@@ -24,7 +24,7 @@ export default createTool({
         'Explain the exact balance change across a selected set of accounts over an inclusive date range, in integer cents.',
         'Separates external income, expense outflow, credits, uncategorized inflows, starting-balance adjustments, and transfers into, out of, or within the selection.',
         'Transfers are detected from transfer_id and are never spending or income.',
-        'openingBalance is immediately before startDate and closingBalance is at the end of the inclusive endDate; reconciliation.difference is exact and transfersByAccount names the funding counterparties.',
+        'openingBalance is immediately before startDate and closingBalance is at the end of the inclusive endDate; reconciliation.difference is exact (reconciliation.balancesAvailable is true) and transfersByAccount names the funding counterparties.',
         'Amounts are in cents: $100.00 = 10000. Dates are YYYY-MM-DD.',
     ].join(' '),
     schema: InputSchema,

package/package.json

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