actual-mcp-server 0.18.0 → 0.19.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)   │               │  (76 tools)      │               │   Server     │
+│  (remote)   │               │  (77 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 
 ┌─────────────┐   MCP/stdio   ┌──────────────────┐   Actual API   ┌──────────────┐
 │  Claude     │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  Desktop    │               │  Server          │               │   Budget     │
-│  (local)    │               │  (76 tools)      │               │   Server     │
+│  (local)    │               │  (77 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:
 
-- **76 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.
+- **77 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 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 76 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 77 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 76 tools are available.
+> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 77 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
 
-**76 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
+**77 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
 
 ### Accounts (8)
 
@@ -319,7 +319,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_accounts_get_balance` | Get account balance at a date |
 | `actual_account_flow_summary` | Explain the exact balance change across a set of accounts over a date range: external income, expense outflow, credits, uncategorized inflows, and transfers into, out of, or within the selection, with an exact reconciliation |
 
-### Transactions (15)
+### Transactions (16)
 
 **Standard (6)**
 
@@ -341,7 +341,7 @@ 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 (7)**, unique to this MCP server
+**Exclusive ActualQL-powered (8)**, unique to this MCP server
 
 | Tool | Description |
 |------|-------------|
@@ -352,6 +352,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_transactions_search_by_payee` | Find by payee/vendor |
 | `actual_transactions_summary_by_category` | Spending summary grouped by category |
 | `actual_transactions_summary_by_payee` | Top vendors with totals and counts |
+| `actual_recurring_expenses_summary` | Detect recurring charges (subscriptions, bills) from posted history: cadence (with date-drift and month-end tolerance), latest amount, price changes, occurrences, annualized cost, and active or inactive state |
 
 ### Transfers (1)
 
@@ -593,7 +594,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 76 tools are available, identical to HTTP mode
+- All 77 tools are available, identical to HTTP mode
 
 **Start manually to verify:**
 
@@ -692,7 +693,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` | 76-tool smoke, schema validation, auth ACL | No |
+| `npm run test:unit-js` | 77-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) |
@@ -777,7 +778,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.18.0 | **Tool Count:** 76 (verified LibreChat-compatible)
+**Version:** 0.19.0 | **Tool Count:** 77 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/actualToolsManager.js

@@ -5,6 +5,7 @@ import { formatZodError } from './lib/zod-error-format.js';
 // Adding the tool name here is considered fully implemented.
 const IMPLEMENTED_TOOLS = [
     'actual_account_flow_summary',
+    'actual_recurring_expenses_summary',
     'actual_accounts_close',
     'actual_accounts_create',
     'actual_accounts_delete',

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

@@ -328,3 +328,254 @@ export function summarizeAccountFlow(snapshot, input) {
         },
     };
 }
+function paymentEvents(snapshot, input, maps) {
+    const selected = input.accountIds ? new Set(input.accountIds) : null;
+    const events = [];
+    for (const transaction of snapshot.transactions) {
+        if (transaction.date < input.startDate || transaction.date > input.endDate)
+            continue;
+        if (selected && !selected.has(transaction.account))
+            continue;
+        const postings = transaction.is_parent === true || (transaction.subtransactions?.length ?? 0) > 0
+            ? postingRows([transaction])
+            : [transaction];
+        let amount = 0;
+        let payeeId = transaction.payee ?? null;
+        for (const posting of postings) {
+            if (posting.transfer_id != null) {
+                continue;
+            }
+            if (posting.starting_balance_flag === true)
+                continue;
+            const category = posting.category ? maps.categories.get(posting.category) : undefined;
+            if (category && bool(category.is_income))
+                continue;
+            const postingAmount = integer(posting.amount, `Transaction ${posting.id} amount`);
+            if (postingAmount < 0)
+                amount += Math.abs(postingAmount);
+            payeeId = payeeId ?? posting.payee ?? null;
+        }
+        if (amount <= 0 || !payeeId)
+            continue;
+        events.push({ id: transaction.id, date: transaction.date, amount, payeeId, accountId: transaction.account });
+    }
+    return events.sort((a, b) => a.date.localeCompare(b.date) || a.id.localeCompare(b.id));
+}
+function utcDate(value) {
+    return new Date(`${value}T00:00:00Z`);
+}
+function daysBetween(a, b) {
+    return Math.round((utcDate(b).getTime() - utcDate(a).getTime()) / 86_400_000);
+}
+function isLastDayOfMonth(value) {
+    const date = utcDate(value);
+    const next = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 1));
+    return date.getUTCDate() === new Date(next.getTime() - 86_400_000).getUTCDate();
+}
+function monthsBetween(a, b) {
+    const left = utcDate(a);
+    const right = utcDate(b);
+    return (right.getUTCFullYear() - left.getUTCFullYear()) * 12 + right.getUTCMonth() - left.getUTCMonth();
+}
+function intervalMatches(a, b, frequency) {
+    const days = daysBetween(a, b);
+    if (frequency === 'weekly')
+        return days >= 5 && days <= 9;
+    if (frequency === 'biweekly')
+        return days >= 12 && days <= 16;
+    if (frequency === 'monthly') {
+        if (monthsBetween(a, b) !== 1)
+            return false;
+        const dayDiff = Math.abs(utcDate(a).getUTCDate() - utcDate(b).getUTCDate());
+        return dayDiff <= 7 || (isLastDayOfMonth(a) && isLastDayOfMonth(b));
+    }
+    if (frequency === 'quarterly')
+        return monthsBetween(a, b) === 3 && Math.abs(utcDate(a).getUTCDate() - utcDate(b).getUTCDate()) <= 10;
+    if (frequency === 'yearly')
+        return monthsBetween(a, b) === 12 && Math.abs(utcDate(a).getUTCDate() - utcDate(b).getUTCDate()) <= 15;
+    return false;
+}
+function detectFrequency(events) {
+    if (events.length < 2)
+        return { frequency: 'other', regularity: 0 };
+    const candidates = ['weekly', 'biweekly', 'monthly', 'quarterly', 'yearly'];
+    let best = { frequency: 'other', regularity: 0 };
+    for (const frequency of candidates) {
+        let matches = 0;
+        for (let i = 1; i < events.length; i += 1) {
+            if (intervalMatches(events[i - 1].date, events[i].date, frequency))
+                matches += 1;
+        }
+        const regularity = matches / (events.length - 1);
+        if (regularity > best.regularity)
+            best = { frequency, regularity };
+    }
+    return best.regularity >= 0.6 ? best : { frequency: 'other', regularity: best.regularity };
+}
+function amountClose(a, b) {
+    return Math.abs(a - b) <= Math.max(100, Math.round(Math.max(a, b) * 0.05));
+}
+function initialAmountLanes(events) {
+    const lanes = [];
+    for (const event of events) {
+        const lane = lanes.find(candidate => amountClose(candidate[candidate.length - 1].amount, event.amount));
+        if (lane)
+            lane.push(event);
+        else
+            lanes.push([event]);
+    }
+    return lanes;
+}
+function mergePriceLanes(lanes) {
+    const result = lanes.map(lane => [...lane].sort((a, b) => a.date.localeCompare(b.date)));
+    let changed = true;
+    while (changed) {
+        changed = false;
+        outer: for (let i = 0; i < result.length; i += 1) {
+            for (let j = i + 1; j < result.length; j += 1) {
+                const a = result[i];
+                const b = result[j];
+                const aBeforeB = a[a.length - 1].date < b[0].date;
+                const bBeforeA = b[b.length - 1].date < a[0].date;
+                if (!aBeforeB && !bBeforeA)
+                    continue;
+                const combined = [...a, ...b].sort((x, y) => x.date.localeCompare(y.date));
+                const detected = detectFrequency(combined);
+                if (detected.frequency !== 'other' && detected.regularity >= 0.75) {
+                    result[i] = combined;
+                    result.splice(j, 1);
+                    changed = true;
+                    break outer;
+                }
+            }
+        }
+    }
+    return result;
+}
+function addFrequency(dateValue, frequency) {
+    if (frequency === 'other')
+        return undefined;
+    const date = utcDate(dateValue);
+    if (frequency === 'weekly')
+        date.setUTCDate(date.getUTCDate() + 7);
+    if (frequency === 'biweekly')
+        date.setUTCDate(date.getUTCDate() + 14);
+    if (frequency === 'monthly' || frequency === 'quarterly' || frequency === 'yearly') {
+        const months = frequency === 'monthly' ? 1 : frequency === 'quarterly' ? 3 : 12;
+        const originalDay = date.getUTCDate();
+        const wasMonthEnd = isLastDayOfMonth(dateValue);
+        date.setUTCDate(1);
+        date.setUTCMonth(date.getUTCMonth() + months);
+        const lastDay = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 0)).getUTCDate();
+        date.setUTCDate(wasMonthEnd ? lastDay : Math.min(originalDay, lastDay));
+    }
+    return date.toISOString().slice(0, 10);
+}
+function establishedAmounts(events) {
+    const runs = [];
+    for (const event of events) {
+        const current = runs[runs.length - 1];
+        // The wider amount tolerance belongs to series matching, not price history.
+        // Once events are known to be one series, preserve exact posted prices so a
+        // small increase cannot be hidden inside a historical median.
+        if (current && current[current.length - 1] === event.amount)
+            current.push(event.amount);
+        else
+            runs.push([event.amount]);
+    }
+    const median = (values) => [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)];
+    return {
+        latest: median(runs[runs.length - 1]),
+        previous: runs.length > 1 ? median(runs[runs.length - 2]) : undefined,
+    };
+}
+function annualize(amount, frequency) {
+    const multiplier = {
+        weekly: 52,
+        biweekly: 26,
+        monthly: 12,
+        quarterly: 4,
+        yearly: 1,
+    };
+    const value = multiplier[frequency];
+    return value === undefined ? undefined : integer(amount * value, 'Annualized amount');
+}
+function inactiveAt(endDate, expectedNextDate, frequency) {
+    if (!expectedNextDate)
+        return true;
+    const secondMiss = addFrequency(expectedNextDate, frequency);
+    return secondMiss !== undefined && endDate >= secondMiss;
+}
+export function summarizeRecurringExpenses(snapshot, input) {
+    const maps = buildMaps(snapshot);
+    const byPayeeAccount = new Map();
+    for (const event of paymentEvents(snapshot, input, maps)) {
+        const key = `${event.payeeId}:${event.accountId}`;
+        const values = byPayeeAccount.get(key) ?? [];
+        values.push(event);
+        byPayeeAccount.set(key, values);
+    }
+    const detected = [];
+    for (const events of byPayeeAccount.values()) {
+        for (const lane of mergePriceLanes(initialAmountLanes(events))) {
+            const cadence = detectFrequency(lane);
+            if (cadence.frequency === 'other')
+                continue;
+            const needed = cadence.frequency === 'yearly' ? Math.min(2, input.minOccurrences) : input.minOccurrences;
+            if (lane.length < needed)
+                continue;
+            detected.push({ events: lane, ...cadence });
+        }
+    }
+    const series = detected.flatMap(item => {
+        const first = item.events[0];
+        const last = item.events[item.events.length - 1];
+        const expectedNextDate = addFrequency(last.date, item.frequency);
+        const inactive = inactiveAt(input.endDate, expectedNextDate, item.frequency);
+        if (inactive && !input.includeInactive)
+            return [];
+        const amounts = establishedAmounts(item.events);
+        const annualizedAmount = annualize(amounts.latest, item.frequency);
+        if (annualizedAmount === undefined)
+            return [];
+        const confidence = item.regularity >= 0.9 && item.events.length >= 4
+            ? 'high'
+            : item.regularity >= 0.7
+                ? 'medium'
+                : 'low';
+        const previousAmount = amounts.previous;
+        const priceChange = previousAmount !== undefined && previousAmount !== amounts.latest
+            ? {
+                previousAmount,
+                currentAmount: amounts.latest,
+                absoluteChange: amounts.latest - previousAmount,
+                percentageChange: Math.round(((amounts.latest - previousAmount) / previousAmount) * 10_000) / 100,
+            }
+            : undefined;
+        return [{
+                payeeId: first.payeeId,
+                payeeName: maps.payees.get(first.payeeId)?.name ?? first.payeeId,
+                accountId: first.accountId,
+                accountName: maps.accounts.get(first.accountId)?.name ?? first.accountId,
+                frequency: item.frequency,
+                occurrenceCount: item.events.length,
+                latestAmount: amounts.latest,
+                ...(previousAmount !== undefined ? { previousAmount } : {}),
+                annualizedAmount,
+                firstObservedDate: first.date,
+                lastObservedDate: last.date,
+                expectedNextDate,
+                ...(priceChange ? { priceChange } : {}),
+                confidence,
+                confidenceScore: Math.round(item.regularity * 100),
+                active: !inactive,
+            }];
+    }).sort((a, b) => a.payeeName.localeCompare(b.payeeName) || b.latestAmount - a.latestAmount);
+    return {
+        dateRange: { startDate: input.startDate, endDate: input.endDate },
+        series,
+        totalAnnualizedRecurringExpenses: series
+            .filter(item => item.active)
+            .reduce((total, item) => total + item.annualizedAmount, 0),
+    };
+}

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

@@ -56,6 +56,7 @@ const OPEN_WORLD = new Set(['actual_bank_sync']);
  */
 const READ_ONLY = new Set([
     'actual_account_flow_summary',
+    'actual_recurring_expenses_summary',
     'actual_accounts_get_balance',
     'actual_accounts_list',
     'actual_budgets_get_all',

package/dist/src/tools/index.js

@@ -1,6 +1,7 @@
 // Auto-generated index for all tool modules
 export { default as entities_search } from './entities_search.js';
 export { default as account_flow_summary } from './account_flow_summary.js';
+export { default as recurring_expenses_summary } from './recurring_expenses_summary.js';
 export { default as accounts_close } from './accounts_close.js';
 export { default as accounts_create } from './accounts_create.js';
 export { default as accounts_delete } from './accounts_delete.js';

package/dist/src/tools/recurring_expenses_summary.js

@@ -0,0 +1,82 @@
+// #426: deterministic, read-only recurring-expense detection.
+//
+// Original heuristic by @maxvanweenen (PR #399), the third tool from #398. The detection lives in
+// src/lib/financial-analysis.ts (summarizeRecurringExpenses); this file is the tool surface plus the
+// #388 filter-id resolution. The heuristic core is ported verbatim; only the id-filter surface is
+// adapted to this server's resolveFilterId convention (a NAME resolves or is refused with its id),
+// matching the two sibling tools rather than PR #399's strict-UUID plus manual existence check.
+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 { summarizeRecurringExpenses } from '../lib/financial-analysis.js';
+// Compute the inclusive start date for a "last N months" lookback, clamping the day to the target
+// month's length (so a 31-day anchor lands on the last valid day) and then stepping one day forward
+// so the window is a whole number of months ending at endDate.
+function startFromMonths(endDate, months) {
+    const end = new Date(`${endDate}T00:00:00Z`);
+    const originalDay = end.getUTCDate();
+    end.setUTCDate(1);
+    end.setUTCMonth(end.getUTCMonth() - months);
+    const lastDay = new Date(Date.UTC(end.getUTCFullYear(), end.getUTCMonth() + 1, 0)).getUTCDate();
+    end.setUTCDate(Math.min(originalDay, lastDay));
+    end.setUTCDate(end.getUTCDate() + 1);
+    return end.toISOString().slice(0, 10);
+}
+// Bare-string ids (#388): a NAME resolves via adapter.resolveFilterId rather than being rejected.
+const InputSchema = z.object({
+    startDate: CommonSchemas.date.optional(),
+    endDate: CommonSchemas.date.optional(),
+    months: z.number().int().min(1).max(60).optional(),
+    accountIds: z.array(z.string().min(1)).min(1).max(100).optional(),
+    minOccurrences: z.number().int().min(2).max(100).default(3),
+    includeInactive: z.boolean().default(false),
+}).strict().superRefine((input, ctx) => {
+    if (input.startDate && input.months) {
+        ctx.addIssue({ code: 'custom', path: ['months'], message: 'Use startDate or months, not both' });
+    }
+    if (input.startDate && input.endDate && input.startDate > input.endDate) {
+        ctx.addIssue({ code: 'custom', path: ['endDate'], message: 'endDate must be on or after startDate' });
+    }
+});
+export default createTool({
+    name: 'actual_recurring_expenses_summary',
+    description: [
+        'Detect recurring expenses (subscriptions, bills) from posted transaction history, without relying on schedules.',
+        'Transfers, income, starting balances, and split-parent duplicates are excluded; a transfer is never recurring.',
+        'Date drift and month-end clamping are tolerated, distinct amount lanes for one payee stay separate, and a later contiguous lane is treated as a price change with the exact new latestAmount preserved.',
+        'A series that has gone quiet is inactive after a two-miss rule; includeInactive controls whether it appears.',
+        'Annualized amounts use exact integer multipliers: weekly 52, biweekly 26, monthly 12, quarterly 4, yearly 1.',
+        'Defaults to an 18-month lookback, three occurrences, and active series only. Amounts are in cents; dates are YYYY-MM-DD.',
+    ].join(' '),
+    schema: InputSchema,
+    handler: async (input) => {
+        const endDate = input.endDate ?? new Date().toISOString().slice(0, 10);
+        const startDate = input.startDate ?? startFromMonths(endDate, input.months ?? 18);
+        // Recurring detection reads only the transaction stream and listings, no balance queries, so the
+        // snapshot is fetched without balanceAccountIds. One withActualApi read session, no N+1.
+        const snapshot = await adapter.getFinancialAnalysisSnapshot({ startDate, endDate });
+        let accountIds;
+        if (input.accountIds) {
+            accountIds = [];
+            for (const id of input.accountIds) {
+                // A NAME throws NotFoundRefusal carrying the resolved id; a well-formed id is verified against
+                // the listing we already hold, so a correct call reads no extra listing.
+                accountIds.push(await adapter.resolveFilterId('account', id, { verifyExists: true, rows: snapshot.accounts }));
+            }
+        }
+        return summarizeRecurringExpenses(snapshot, {
+            startDate,
+            endDate,
+            accountIds,
+            minOccurrences: input.minOccurrences,
+            includeInactive: input.includeInactive,
+        });
+    },
+    examples: [
+        {
+            description: 'What am I paying for every month, over the last year',
+            input: { months: 12, minOccurrences: 3, includeInactive: false },
+        },
+    ],
+});

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
   },
-  "description": "MCP server with 76 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 77 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/transactions_aggregate.test.js && node tests/unit/account_flow_summary.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/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.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",