actual-mcp-server 0.16.13 → 0.17.0

package/README.md

@@ -24,13 +24,13 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 ┌─────────────┐   MCP/HTTP    ┌──────────────────┐   Actual API   ┌──────────────┐
 │  LibreChat  │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  LobeChat   │               │  Server          │               │   Budget     │
-│  (remote)   │               │  (74 tools)      │               │   Server     │
+│  (remote)   │               │  (75 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 
 ┌─────────────┐   MCP/stdio   ┌──────────────────┐   Actual API   ┌──────────────┐
 │  Claude     │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  Desktop    │               │  Server          │               │   Budget     │
-│  (local)    │               │  (74 tools)      │               │   Server     │
+│  (local)    │               │  (75 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 ```
 
@@ -38,14 +38,14 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 
 Most Actual Budget MCP implementations are simple stdio bridges designed for single-user, local use with Claude Desktop. This project goes further:
 
-- **74 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
+- **75 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
 - **HTTP and stdio transport.** Runs as a real remote server for LibreChat/LobeChat (`--http`), or as a direct local process for Claude Desktop (`--stdio`). No Docker or HTTP server is needed for local use.
 - **6 exclusive ActualQL-powered tools.** Search and summarise transactions by month, amount, category, or payee using Actual Budget's native query engine. Aggregated results, no raw data dumped into the AI context window.
 - **Multi-budget switching at runtime.** Configure multiple budget files and let the AI switch between them mid-conversation with `actual_budgets_switch`. Works on both transports: HTTP keys the active budget to the MCP session, and stdio (Claude Desktop, Claude Code, Cursor) gets a synthetic per-process session so a switch is scoped to that process rather than shared globally (#348).
 - **Multi-user ready with OIDC.** Secure every session with JWKS-validated JWTs and per-user budget ACLs. No shared tokens required.
-- **Production-grade reliability.** Connection pooling (up to 15 concurrent sessions), automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
+- **Production-grade reliability on both transports.** HTTP connection pooling (up to 15 concurrent sessions), and a long-lived stdio process that logs in ONCE and reuses that connection for every tool call instead of re-authenticating per call, so Claude Desktop and Claude Code stay fast and a burst of calls no longer risks a per-call login storm against the upstream limiter. Automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
 
-> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 74 tools tested end-to-end. Any MCP-compatible client should work.
+> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 75 tools tested end-to-end. Any MCP-compatible client should work.
 
 ---
 
@@ -178,7 +178,7 @@ Add to `claude_desktop_config.json` (see [docs/guides/MCP_CLIENTS_SETUP.md](docs
 }
 ```
 
-> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 74 tools are available.
+> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 75 tools are available.
 >
 > **`MCP_BRIDGE_DATA_DIR` should be an absolute path.** Without one, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.
 
@@ -304,7 +304,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 ## Available Tools
 
-**74 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
+**75 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
 
 ### Accounts (7)
 
@@ -318,7 +318,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_accounts_reopen` | Reopen closed account. An id that is not an account is refused rather than creating one |
 | `actual_accounts_get_balance` | Get account balance at a date |
 
-### Transactions (14)
+### Transactions (15)
 
 **Standard (6)**
 
@@ -340,10 +340,11 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_transactions_uncategorized` | Summary of uncategorized transactions (totalCount, totalAmount, per-account breakdown); pass `includeTransactions:true` for paginated rows |
 | `actual_transactions_update_batch` | Apply many transaction updates in ONE call (`updates: [{ id, fields }]`); returns per-item success and failure counts |
 
-**Exclusive ActualQL-powered (6)**, unique to this MCP server
+**Exclusive ActualQL-powered (7)**, unique to this MCP server
 
 | Tool | Description |
 |------|-------------|
+| `actual_transactions_aggregate` | Deterministic integer-cent totals grouped by month, category, category group, payee, or account; transfers excluded via `transfer_id` and split children counted once |
 | `actual_transactions_search_by_month` | Search by month using `$month` transform |
 | `actual_transactions_search_by_amount` | Find by amount range |
 | `actual_transactions_search_by_category` | Search by category name |
@@ -591,7 +592,7 @@ stdio is the simplest way to connect Claude Desktop directly to Actual Budget. T
 - No auth token. Process ownership is the security boundary.
 - All logs go to stderr so they never corrupt the JSON-RPC framing on stdout
 - The process exits when stdin closes (Claude Desktop shutting down)
-- All 74 tools are available, identical to HTTP mode
+- All 75 tools are available, identical to HTTP mode
 
 **Start manually to verify:**
 
@@ -690,7 +691,7 @@ See [AI Client Setup, OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-m
 | Command | What It Tests | Requires Live Server |
 |---------|---------------|---------------------|
 | `npm run build` | TypeScript compilation | No |
-| `npm run test:unit-js` | 74-tool smoke, schema validation, auth ACL | No |
+| `npm run test:unit-js` | 75-tool smoke, schema validation, auth ACL | No |
 | `npm run test:adapter` | Adapter, retry logic, concurrency | No |
 | `npm run test:e2e` | MCP protocol compliance (Playwright) | No |
 | `npm run test:e2e:docker:full` | Full stack integration | Yes (Docker) |
@@ -775,7 +776,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.16.13 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.17.0 | **Tool Count:** 75 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/actualToolsManager.js

@@ -48,6 +48,7 @@ const IMPLEMENTED_TOOLS = [
     'actual_schedules_delete',
     'actual_schedules_get',
     'actual_schedules_update',
+    'actual_transactions_aggregate',
     'actual_transactions_create',
     'actual_transactions_delete',
     'actual_transactions_filter',

package/dist/src/lib/actual-adapter/auth-retry.js

@@ -5,6 +5,7 @@
 // getAuthRetryCounts() for getConcurrencyState, and wraps api.init() with
 // withAuthRetry. Linked issue: #127.
 import { DEFAULT_RETRY_ATTEMPTS, MAX_RETRY_DELAY_MS } from '../constants.js';
+import { isRateLimitError } from '../retry.js';
 import logger from '../../logger.js';
 let authRetryCount = 0; // monotonic, observability
 let authRetryFailureCount = 0; // increments only when retry budget exhausted
@@ -25,7 +26,13 @@ const AUTH_RETRY_BASE_BACKOFF_MS = 5000;
 export function isRetryableAuthError(err) {
     if (!(err instanceof Error))
         return false;
-    return (err.message.includes('Authentication failed: too-many-requests') ||
+    // #422: reconcile with the pool-drop rate-limit matcher by UNION, never a
+    // substitution. `isRateLimitError` matches BOTH the hyphenated `too-many-requests`
+    // code AND the spaced express default `Too many requests, ...` the current server
+    // returns, so this now retries a login throttle in either form (the spaced form
+    // was previously missed). The `network-failure` branch is preserved verbatim so
+    // withAuthRetry's login self-heal is not narrowed.
+    return (isRateLimitError(err) ||
         err.message.includes('Authentication failed: network-failure'));
 }
 /**

package/dist/src/lib/actual-adapter/filter-ids.js

@@ -31,6 +31,10 @@ import { UUID_PATTERN } from '../constants.js';
 export const FILTER_ID_ENTITIES = {
     account: { entity: 'Account', listTool: 'actual_accounts_list' },
     category: { entity: 'Category', listTool: 'actual_categories_get' },
+    // #424: category_group joins so the aggregate tool's categoryGroupIds filter resolves a NAME the
+    // same way the other three do. Without it a group name would fall through resolveFilterId's rows
+    // resolver to the payee listing and match nothing (a wrong answer, not an error).
+    category_group: { entity: 'Category group', listTool: 'actual_category_groups_get' },
     payee: { entity: 'Payee', listTool: 'actual_payees_get' },
 };
 /**

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

@@ -10,7 +10,7 @@ const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, import
  } = api;
 import { EventEmitter } from 'events';
 import observability from '../observability.js';
-import { retry, isRetryableError } from './retry.js';
+import { retry, isRetryableError, isRateLimitError } from './retry.js';
 import { withOpTimeout } from './opTimeout.js';
 import { NotFoundRefusal, OutOfRangeRefusal, constraintErrorMsg } from './errors.js';
 import { findMatchingRule } from './rule-matching.js';
@@ -295,13 +295,16 @@ export function _shouldKeepSingletonAlive(activeSessions, forceFullShutdown) {
  * actually corrupted but the error pattern doesn't match, the next call's op
  * will surface the same root cause and we'll catch it then.
  */
-// Whether an error is infrastructure-level (drop the pooled connection so the
-// next call re-inits cleanly). This is the SAME class as "retryable", so it
-// delegates to isRetryableError (#177): the pool-drop decision and the retry
-// decision share one pattern list and cannot drift. A consistency test pins
-// this equivalence.
+// Whether an error is infrastructure-level (drop the pooled connection / tear
+// down the stdio singleton so the next call re-inits cleanly). This DERIVES from
+// isRetryableError (#177: one authored pattern source, pool-drop and retry cannot
+// drift), with ONE deliberate subtraction (#422): a rate-limit is transient but
+// does NOT corrupt the connection, so it must not drop it. Re-logging-in during a
+// throttle adds a fresh login to an already-full window, cascading into a relogin
+// storm (observed over stdio in #383). Retry still backs a rate-limit off; drop
+// does not. A consistency test pins this exact relationship.
 function _shouldDropPoolOnError(err) {
-    return isRetryableError(err);
+    return isRetryableError(err) && !isRateLimitError(err);
 }
 /**
  * Enforce per-request budget ACL before any pool branching or lock acquisition.
@@ -1656,7 +1659,8 @@ export async function resolveFilterId(kind, value, opts) {
     const rows = opts?.rows
         ?? (kind === 'account' ? await getAccounts()
             : kind === 'category' ? await getCategories()
-                : await getPayees());
+                : kind === 'category_group' ? (await getCategoryGroups())
+                    : await getPayees());
     if (isEntityId(value)) {
         // Only reachable under verifyExists. A well-formed id that names nothing is a not-found,
         // not a name to resolve.
@@ -2817,6 +2821,37 @@ export async function runQuery(queryString) {
         throw new Error(`Query execution failed: ${errorMsg}`);
     }
 }
+/**
+ * #424: one read snapshot for the deterministic financial-analysis tools. Runs a fixed set of
+ * ActualQL reads inside ONE withActualApi session (not N+1): the in-range transactions with splits
+ * GROUPED (so a split reduces to its children exactly once), plus the account/category/group/payee
+ * listings the tool needs to resolve filters and label groups. The account-flow tool (#425) extends
+ * this with transfer counterparts and opening/closing balances.
+ *
+ * Original query shapes by @maxvanweenen (PR #399).
+ */
+export async function getFinancialAnalysisSnapshot(params) {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.financialAnalysis.snapshot').catch(() => { });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { q } = (await import('@actual-app/api'));
+        const queryData = async (query) => {
+            const response = await withConcurrency(() => retry(() => rawRunQuery(query), { retries: 2, backoffMs: 200 }));
+            if (Array.isArray(response))
+                return response;
+            return Array.isArray(response?.data) ? response.data : [];
+        };
+        const transactions = await queryData(q('transactions')
+            .options({ splits: 'grouped' })
+            .filter({ $and: [{ date: { $gte: params.startDate } }, { date: { $lte: params.endDate } }] })
+            .select('*'));
+        const accounts = await queryData(q('accounts').select(['id', 'name', 'offbudget', 'closed']));
+        const categories = await queryData(q('categories').select(['id', 'name', 'is_income', 'group']));
+        const categoryGroups = await queryData(q('category_groups').options({ categories: 'none' }).select(['id', 'name', 'is_income']));
+        const payees = await queryData(q('payees').select(['id', 'name', 'transfer_acct']));
+        return { transactions, accounts, categories, categoryGroups, payees };
+    });
+}
 // WHERE-clause translation extracted to ./actual-adapter/query.ts (#166).
 // Imported for internal use by runQuery and re-exported (unit-tested directly).
 import { parseWhereClause } from './actual-adapter/query.js';
@@ -3345,6 +3380,7 @@ export async function getPreferences() {
 export default {
     getAccounts,
     resolveFilterId,
+    getFinancialAnalysisSnapshot,
     getAccountsWithBalances,
     addTransactions,
     importTransactions,

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

@@ -0,0 +1,214 @@
+// Deterministic financial-analysis primitives: pure functions that turn a snapshot of Actual
+// Budget rows into aggregated, integer-cent totals, so the accounting is computed in server code
+// rather than re-derived by an LLM.
+//
+// Original implementation by @maxvanweenen (PR #399, https://github.com/agigante80/actual-mcp-server/pull/399),
+// requested in #398. This file is the aggregate slice (the `actual_transactions_aggregate` tool,
+// #424); the account-flow and recurring-expense functions land with their own tools (#425, #426).
+//
+// PURE by design: no api session, no module state, so every branch is unit-testable against fixed
+// rows. The adapter owns the impure half (fetching the snapshot) in `getFinancialAnalysisSnapshot`.
+const zeroAggregate = () => ({
+    expenseOutflow: 0,
+    credits: 0,
+    netExpense: 0,
+    income: 0,
+    uncategorizedInflows: 0,
+    adjustments: 0,
+    transferInflow: 0,
+    transferOutflow: 0,
+    transactionCount: 0,
+    transferCount: 0,
+});
+function bool(value) {
+    return value === true || value === 1;
+}
+// Money is integer cents everywhere. A non-integer amount is a data-shape error, not something to
+// round, so it throws rather than silently corrupting a total.
+function integer(value, field) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+        throw new Error(`${field} must be a safe integer number of cents.`);
+    }
+    return value;
+}
+export function buildMaps(snapshot) {
+    return {
+        accounts: new Map(snapshot.accounts.map(account => [account.id, account])),
+        categories: new Map(snapshot.categories.map(category => [category.id, category])),
+        categoryGroups: new Map(snapshot.categoryGroups.map(group => [group.id, group])),
+        payees: new Map(snapshot.payees.map(payee => [payee.id, payee])),
+        transactions: new Map([...snapshot.transactions, ...(snapshot.transferCounterparts ?? [])].flatMap(transaction => [
+            transaction,
+            ...(transaction.subtransactions ?? []),
+        ]).map(transaction => [transaction.id, transaction])),
+    };
+}
+/**
+ * Convert Actual's grouped split representation into posting rows. A normal transaction appears
+ * once. A split contributes its CHILDREN and never its parent, so a split is counted exactly once.
+ * A `seen` set dedups a child that arrives both grouped and top-level, in either order.
+ */
+export function postingRows(transactions) {
+    const rows = [];
+    const seen = new Set();
+    for (const transaction of transactions) {
+        if (transaction.is_parent === true || (transaction.subtransactions?.length ?? 0) > 0) {
+            for (const child of transaction.subtransactions ?? []) {
+                if (seen.has(child.id))
+                    continue;
+                seen.add(child.id);
+                rows.push({
+                    ...child,
+                    account: child.account ?? transaction.account,
+                    date: child.date ?? transaction.date,
+                    payee: child.payee ?? transaction.payee,
+                    parent_id: child.parent_id ?? transaction.id,
+                    is_child: true,
+                });
+            }
+            continue;
+        }
+        if (transaction.parent_id != null || transaction.is_child === true) {
+            if (!seen.has(transaction.id)) {
+                seen.add(transaction.id);
+                rows.push(transaction);
+            }
+            continue;
+        }
+        if (!seen.has(transaction.id)) {
+            seen.add(transaction.id);
+            rows.push(transaction);
+        }
+    }
+    return rows;
+}
+/**
+ * Classify a posting row. A TRANSFER is detected from `transfer_id` FIRST, before any category or
+ * income logic, so a transfer is never spending or income regardless of how it is categorized. That
+ * is the exact fragility #398 identified in the existing summary tools.
+ */
+export function classifyExternal(transaction, category) {
+    if (transaction.transfer_id != null)
+        return 'transfer';
+    if (transaction.starting_balance_flag === true)
+        return 'adjustment';
+    const amount = integer(transaction.amount, `Transaction ${transaction.id} amount`);
+    if (category && bool(category.is_income))
+        return 'income';
+    if (amount < 0)
+        return 'expense';
+    if (amount > 0 && category)
+        return 'credit';
+    if (amount > 0)
+        return 'uncategorized-inflow';
+    return 'expense';
+}
+function groupingFields(transaction, dimensions, maps) {
+    const category = transaction.category ? maps.categories.get(transaction.category) : undefined;
+    const categoryGroup = category?.group ? maps.categoryGroups.get(category.group) : undefined;
+    const payee = transaction.payee ? maps.payees.get(transaction.payee) : undefined;
+    const account = maps.accounts.get(transaction.account);
+    const fields = {};
+    for (const dimension of dimensions) {
+        if (dimension === 'month')
+            fields.month = transaction.date.slice(0, 7);
+        if (dimension === 'category') {
+            fields.categoryId = category?.id ?? null;
+            fields.categoryName = category?.name ?? 'Uncategorized';
+        }
+        if (dimension === 'category_group') {
+            fields.categoryGroupId = categoryGroup?.id ?? null;
+            fields.categoryGroupName = categoryGroup?.name ?? 'Uncategorized';
+        }
+        if (dimension === 'payee') {
+            fields.payeeId = payee?.id ?? null;
+            fields.payeeName = payee?.name ?? 'Unknown payee';
+        }
+        if (dimension === 'account') {
+            fields.accountId = transaction.account;
+            fields.accountName = account?.name ?? transaction.account;
+        }
+    }
+    return fields;
+}
+function matchesFilters(transaction, input, maps) {
+    if (transaction.date < input.startDate || transaction.date > input.endDate)
+        return false;
+    if (input.accountIds && !input.accountIds.includes(transaction.account))
+        return false;
+    if (input.categoryIds && (!transaction.category || !input.categoryIds.includes(transaction.category)))
+        return false;
+    if (input.payeeIds && (!transaction.payee || !input.payeeIds.includes(transaction.payee)))
+        return false;
+    if (input.categoryGroupIds) {
+        const groupId = transaction.category ? maps.categories.get(transaction.category)?.group : undefined;
+        if (!groupId || !input.categoryGroupIds.includes(groupId))
+            return false;
+    }
+    return true;
+}
+function addAggregate(target, source) {
+    target.expenseOutflow += source.expenseOutflow;
+    target.credits += source.credits;
+    target.income += source.income;
+    target.uncategorizedInflows += source.uncategorizedInflows;
+    target.adjustments += source.adjustments;
+    target.transferInflow += source.transferInflow;
+    target.transferOutflow += source.transferOutflow;
+    target.transactionCount += source.transactionCount;
+    target.transferCount += source.transferCount;
+    target.netExpense = target.expenseOutflow - target.credits;
+}
+/**
+ * Group posting rows over an inclusive date range into integer-cent totals. Transfers are excluded
+ * by default (kept in their own inflow/outflow fields when `excludeTransfers` is false); income is
+ * excluded unless `includeIncome`. Deliberately groups IN PROCESS rather than via a `.groupBy`
+ * query, because a grouped query would flatten splits back to inline and reintroduce double-count.
+ */
+export function aggregateTransactions(snapshot, input) {
+    const maps = buildMaps(snapshot);
+    const grouped = new Map();
+    for (const transaction of postingRows(snapshot.transactions)) {
+        if (!matchesFilters(transaction, input, maps))
+            continue;
+        const category = transaction.category ? maps.categories.get(transaction.category) : undefined;
+        const classification = classifyExternal(transaction, category);
+        if (classification === 'income' && !input.includeIncome)
+            continue;
+        if (classification === 'transfer' && input.excludeTransfers)
+            continue;
+        const dimensions = groupingFields(transaction, input.groupBy, maps);
+        const key = JSON.stringify(dimensions);
+        const entry = grouped.get(key) ?? { dimensions, values: zeroAggregate() };
+        const amount = integer(transaction.amount, `Transaction ${transaction.id} amount`);
+        if (classification === 'expense')
+            entry.values.expenseOutflow += Math.abs(amount);
+        if (classification === 'credit')
+            entry.values.credits += amount;
+        if (classification === 'income')
+            entry.values.income += amount;
+        if (classification === 'uncategorized-inflow')
+            entry.values.uncategorizedInflows += amount;
+        if (classification === 'adjustment')
+            entry.values.adjustments += amount;
+        if (classification === 'transfer') {
+            if (amount >= 0)
+                entry.values.transferInflow += amount;
+            else
+                entry.values.transferOutflow += Math.abs(amount);
+            entry.values.transferCount += 1;
+        }
+        else {
+            entry.values.transactionCount += 1;
+        }
+        entry.values.netExpense = entry.values.expenseOutflow - entry.values.credits;
+        grouped.set(key, entry);
+    }
+    const groups = [...grouped.values()]
+        .sort((a, b) => JSON.stringify(a.dimensions).localeCompare(JSON.stringify(b.dimensions)))
+        .map(entry => ({ ...entry.dimensions, ...entry.values }));
+    const totals = zeroAggregate();
+    for (const entry of grouped.values())
+        addAggregate(totals, entry.values);
+    return { dateRange: { startDate: input.startDate, endDate: input.endDate }, groups, totals };
+}

package/dist/src/lib/retry.js

@@ -5,9 +5,18 @@ const log = ModuleLoggers.RETRY;
  * Error-message fragments that mark a TRANSIENT / infrastructure-level failure:
  * the kind a retry can actually recover from, and the kind worth dropping a
  * pooled connection over. Single source of truth for #177: the adapter's
- * `_shouldDropPoolOnError` delegates to `isRetryableError`, so the retry
+ * `_shouldDropPoolOnError` derives from `isRetryableError`, so the retry
  * decision and the pool-drop decision cannot drift apart.
  *
+ * #422 is the ONE deliberate divergence: a rate-limit ("too-many-requests") is
+ * transient and worth backing off, but it does NOT corrupt the connection, so
+ * `_shouldDropPoolOnError` subtracts it (`isRetryableError && !isRateLimitError`).
+ * Re-initing during a throttle adds a fresh login to an already-full window,
+ * which is itself rejected, cascading into a relogin storm (observed over stdio
+ * in #383). Retry stays unified with this list; only drop carves the one case
+ * out. That is #177's spirit (one authored pattern source) preserved, not a
+ * second divergent list.
+ *
  * Anything NOT matching here (domain/validation errors such as "is required",
  * "not found", "does not exist", Zod failures, and any unknown error) is
  * terminal: it fails the same way on every attempt, so it must NOT be retried.
@@ -38,6 +47,34 @@ export function isRetryableError(err) {
     const msg = err.message || '';
     return TRANSIENT_ERROR_PATTERNS.some(p => msg.includes(p));
 }
+/**
+ * The rate-limit signal, in BOTH forms it reaches us (#422). `@actual-app/api`
+ * throws `Authentication failed: ${result.error}`, interpolating the server's
+ * raw string, so the exact shape is server-dependent:
+ *   - the hyphenated code `too-many-requests` (referenced by the auth-retry
+ *     comments, some Actual builds), and
+ *   - the spaced express-rate-limit default `Too many requests, please try
+ *     again later.` (what the E2E stack's server actually returns, #383).
+ * The `[\s-]?` arms match both; `rate[\s-]?limit` covers "rate limit" phrasing.
+ *
+ * Shared by `_shouldDropPoolOnError` (to NOT drop a throttled-but-live
+ * connection) and by `isRetryableAuthError` (to retry a login throttle). A
+ * non-Error rejection is not a rate-limit.
+ *
+ * Checks both `.message` AND `.code`: a login throttle carries it in the message
+ * (`Authentication failed: Too many requests...`), but a SYNC throttle surfaces
+ * as `Error("We had an unknown problem opening ...")` with the rate-limit only in
+ * `.code` (observed in the #383 write path). Matching just the message would miss
+ * that shape.
+ */
+export const RATE_LIMIT_PATTERN = /too[\s-]?many[\s-]?requests|rate[\s-]?limit/i;
+export function isRateLimitError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const code = err.code;
+    const codeStr = typeof code === 'string' ? code : '';
+    return RATE_LIMIT_PATTERN.test(err.message || '') || RATE_LIMIT_PATTERN.test(codeStr);
+}
 export async function retry(fn, opts) {
     const retries = opts?.retries ?? DEFAULT_RETRY_ATTEMPTS;
     const backoffMs = opts?.backoffMs ?? DEFAULT_RETRY_BACKOFF_MS;

package/dist/src/lib/tool-annotations.js

@@ -77,6 +77,7 @@ const READ_ONLY = new Set([
     'actual_server_info',
     'actual_session_list',
     'actual_tags_list',
+    'actual_transactions_aggregate',
     'actual_transactions_filter',
     'actual_transactions_get',
     'actual_transactions_search_by_amount',

package/dist/src/tools/index.js

@@ -49,6 +49,7 @@ export { default as schedules_delete } from './schedules_delete.js';
 export { default as schedules_get } from './schedules_get.js';
 export { default as schedules_update } from './schedules_update.js';
 export { default as server_info } from './server_info.js';
+export { default as transactions_aggregate } from './transactions_aggregate.js';
 export { default as transactions_create } from './transactions_create.js';
 export { default as transactions_delete } from './transactions_delete.js';
 export { default as transactions_filter } from './transactions_filter.js';

package/dist/src/tools/transactions_aggregate.js

@@ -0,0 +1,87 @@
+// #424: deterministic, read-only aggregation of posted transactions.
+//
+// Original implementation by @maxvanweenen (PR #399), requested in #398. The accounting lives in
+// src/lib/financial-analysis.ts; this file is the tool surface plus the #388 filter-id resolution.
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+import adapter from '../lib/actual-adapter.js';
+import { aggregateTransactions, } from '../lib/financial-analysis.js';
+const GroupDimensionSchema = z.enum(['month', 'category', 'category_group', 'payee', 'account']);
+// The optional id filters are BARE strings, not CommonSchemas ids, on purpose (#388): a NAME is
+// resolved to its id by adapter.resolveFilterId rather than rejected with a bare ZodError, so the
+// caller learns the id. Tightening these to CommonSchemas would delete that accommodation.
+const IdArray = z.array(z.string().min(1)).min(1).max(100);
+const InputSchema = z.object({
+    startDate: CommonSchemas.date,
+    endDate: CommonSchemas.date,
+    groupBy: z.union([GroupDimensionSchema, z.array(GroupDimensionSchema).min(1).max(5)]),
+    accountIds: IdArray.optional(),
+    categoryIds: IdArray.optional(),
+    categoryGroupIds: IdArray.optional(),
+    payeeIds: IdArray.optional(),
+    includeIncome: z.boolean().optional().default(false),
+    excludeTransfers: z.boolean().optional().default(true),
+}).strict().superRefine((input, ctx) => {
+    if (input.startDate > input.endDate) {
+        ctx.addIssue({ code: 'custom', path: ['endDate'], message: 'endDate must be on or after startDate' });
+    }
+});
+// Resolve every element of an optional id filter through the #388 chokepoint, reusing the listing
+// the snapshot already fetched (so no extra listing read per element, no N+1). A well-formed known
+// id passes through unchanged; a NAME throws a refusal carrying the resolved id; an unknown
+// well-formed id throws NotFoundRefusal.
+async function resolveIds(ids, kind, rows) {
+    if (!ids)
+        return undefined;
+    const resolved = [];
+    for (const id of ids) {
+        resolved.push(await adapter.resolveFilterId(kind, id, { verifyExists: true, rows }));
+    }
+    return resolved;
+}
+export default createTool({
+    name: 'actual_transactions_aggregate',
+    description: [
+        'Deterministically aggregate posted transactions over an inclusive date range using integer cents.',
+        'Split parents are excluded and split children are counted once.',
+        'Transfers are identified only by transfer_id and never count as spending or income.',
+        'Positive non-income-category transactions are credits; positive uncategorized transactions are reported separately as uncategorizedInflows.',
+        'groupBy accepts one dimension or an array of month, category, category_group, payee, and account.',
+        'includeIncome defaults to false. excludeTransfers defaults to true; when false, transfers stay in separate transferInflow and transferOutflow fields.',
+        'Amounts are in cents: $100.00 = 10000. Dates are YYYY-MM-DD.',
+    ].join(' '),
+    schema: InputSchema,
+    handler: async (input) => {
+        const snapshot = await adapter.getFinancialAnalysisSnapshot({
+            startDate: input.startDate,
+            endDate: input.endDate,
+        });
+        const accountIds = await resolveIds(input.accountIds, 'account', snapshot.accounts);
+        const categoryIds = await resolveIds(input.categoryIds, 'category', snapshot.categories);
+        const categoryGroupIds = await resolveIds(input.categoryGroupIds, 'category_group', snapshot.categoryGroups);
+        const payeeIds = await resolveIds(input.payeeIds, 'payee', snapshot.payees);
+        const groupBy = (Array.isArray(input.groupBy) ? [...new Set(input.groupBy)] : [input.groupBy]);
+        return aggregateTransactions(snapshot, {
+            startDate: input.startDate,
+            endDate: input.endDate,
+            groupBy,
+            accountIds,
+            categoryIds,
+            categoryGroupIds,
+            payeeIds,
+            includeIncome: input.includeIncome,
+            excludeTransfers: input.excludeTransfers,
+        });
+    },
+    examples: [
+        {
+            description: 'Total spending per category for a month, transfers excluded',
+            input: { startDate: '2025-01-01', endDate: '2025-01-31', groupBy: 'category', includeIncome: false, excludeTransfers: true },
+        },
+        {
+            description: 'Spending and income per month, transfers kept separate',
+            input: { startDate: '2025-01-01', endDate: '2025-03-31', groupBy: 'month', includeIncome: true, excludeTransfers: false },
+        },
+    ],
+});

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.16.13",
+  "version": "0.17.0",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
   },
-  "description": "MCP server with 74 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+  "description": "MCP server with 75 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
   "homepage": "https://github.com/agigante80/actual-mcp-server#readme",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_hold_for_next_month.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/transactions_update_splits.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/stdio_budget_switch.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/playwright_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budgets_import_syncid.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/transactions_aggregate.test.js && node tests/unit/generated_tools.smoke.test.js &&node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_hold_for_next_month.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/transactions_update_splits.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/stdio_budget_switch.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/playwright_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budgets_import_syncid.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js",
     "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
     "test:e2e": "npx playwright test",
     "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",