actual-mcp-server 0.19.2 → 0.19.4

package/README.md

@@ -60,8 +60,12 @@ Most Actual Budget MCP implementations are simple stdio bridges designed for sin
 - [Testing](#testing)
 - [Documentation](#documentation)
 - [Contributing](#contributing)
+- [Architecture](#architecture)
 - [License](#license)
+- [Acknowledgments](#acknowledgments)
 - [Disclaimer](#disclaimer)
+- [Support](#support)
+- [Sponsor](#sponsor)
 
 ---
 
@@ -458,10 +462,6 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 `actual_session_list` · `actual_session_close`
 
-### Not Yet Implemented
-
-- Scheduled/recurring transactions (`getSchedules`, `createSchedule`, `updateSchedule`, `deleteSchedule`)
-
 ---
 
 ## Configuration
@@ -773,12 +773,11 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ## Support
 
-- **[GitHub Issues](https://github.com/agigante80/actual-mcp-server/issues)**: bug reports and feature requests
-- **[GitHub Discussions](https://github.com/agigante80/actual-mcp-server/discussions)**: questions and ideas
+- **[GitHub Issues](https://github.com/agigante80/actual-mcp-server/issues)**: bug reports, feature requests, questions and ideas
 
 ---
 
-**Version:** 0.19.2 | **Tool Count:** 77 (verified LibreChat-compatible)
+**Version:** 0.19.4 | **Tool Count:** 77 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/lib/constants.js

@@ -96,6 +96,12 @@ export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0
 export const SUPPORTED_ACTUAL_SERVER_RANGE = {
     /** Oldest server version this client supports. Below this: "too old" warning. */
     minVersion: '25.0.0',
-    /** Newest server MAJOR tested against `@actual-app/api` v26. Above this: "newer than tested". */
+    /** Newest server MAJOR tested against `@actual-app/api` v26. Above this: "newer than tested".
+     *  #439: now deliberately REDUNDANT with the derived upper bound (the installed
+     *  api version), which subsumes it whenever this constant holds the installed
+     *  major, the only value it is meant to hold. Retained as the hand-maintained
+     *  fallback for when the installed version cannot be resolved. Deleting it and
+     *  deriving the bound entirely is defensible and removes the drift class, but it
+     *  changes a shared constant, so it belongs in its own ticket. */
     testedMaxMajor: 26,
 };

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/lib/installed-api-version.js

@@ -0,0 +1,68 @@
+/**
+ * #439: resolve the version of `@actual-app/api` this process actually has
+ * installed, as opposed to the range `package.json` declares.
+ *
+ * WHY NOT the obvious routes, all verified rather than assumed:
+ *  - `require.resolve('@actual-app/api/package.json')` throws
+ *    ERR_PACKAGE_PATH_NOT_EXPORTED: the package does not export that subpath.
+ *  - The module's own `VERSION` export is `undefined`, and the bundle carries an
+ *    unrelated third-party `VERSION` string, so reading it could silently yield a
+ *    wrong version.
+ *  - `package.json` holds a CARET RANGE, so the installed version is unknowable
+ *    at our build time and cannot be baked in.
+ * So: resolve the entry point, then walk up to the nearest `package.json` whose
+ * `name` matches, mirroring the shape of node-version-guard.ts.
+ *
+ * THIS MODULE IS SILENT. It emits nothing: no `console.*`, no logger import, no
+ * direct stdout or stderr write. At module load there is no injected logger, and
+ * on stdio stdout is reserved for JSON-RPC framing, so a stray write would
+ * corrupt the protocol with nothing to catch it. A failure returns null.
+ *
+ * The `try/catch` and the memoisation both live HERE rather than in the caller,
+ * so every consumer imports a value that cannot throw. That matters beyond the
+ * adapter: #445 will make `src/tools/server_info.ts` a second consumer, and that
+ * file is reachable from `src/tools/index.ts` into `actualToolsManager`, where an
+ * uncaught resolution throw would break TOOL REGISTRATION rather than merely the
+ * adapter. Resolving once at load also keeps a blocking `readFileSync` out of the
+ * per-operation path, which runs inside the process-global api mutex.
+ */
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const PACKAGE = '@actual-app/api';
+/** Exported for tests: an injectable start directory over a synthetic fixture
+ *  tree, so the walk-up logic is covered without touching the live node_modules
+ *  (an in-chain test may never depend on what happens to be installed, #321). */
+export function readVersionFromTree(startDir, pkgName = PACKAGE) {
+    let dir = startDir;
+    // Bounded walk: stop at the filesystem root, and never above a node_modules
+    // boundary, so a nested copy resolves to ITS manifest rather than a parent's.
+    for (let hops = 0; hops < 32; hops++) {
+        try {
+            const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+            if (manifest?.name === pkgName && typeof manifest.version === 'string')
+                return manifest.version;
+        }
+        catch {
+            // No manifest at this level, or unreadable. Keep walking.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+function resolveInstalledApiVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        return readVersionFromTree(dirname(require.resolve(PACKAGE)));
+    }
+    catch {
+        return null;
+    }
+}
+/** The installed version, or null when it cannot be determined. Resolved ONCE at
+ *  module load. Null is a normal state, not an error: every consumer must stay
+ *  silent on it rather than reporting a sentinel. */
+export const INSTALLED_API_VERSION = resolveInstalledApiVersion();

package/dist/src/lib/schemas/common.js

@@ -3,7 +3,7 @@
  *
  * Common validation schemas used across MCP tools for Actual Budget.
  * These schemas provide consistent validation, better error messages,
- * and reduce duplication across the 43 tool definitions.
+ * and reduce duplication across the 77 tool definitions.
  */
 import { z } from 'zod';
 import { MAX_NAME_LENGTH, MAX_NOTES_LENGTH, DATE_PATTERN, MONTH_PATTERN, UUID_PATTERN } from '../constants.js';

package/dist/src/lib/server-version-guard.js

@@ -19,6 +19,7 @@
  *    shutdownActualApi.
  */
 import { SUPPORTED_ACTUAL_SERVER_RANGE } from './constants.js';
+import { INSTALLED_API_VERSION } from './installed-api-version.js';
 /** Parse `26.7.0` (or `v26.7.0`) into `[26, 7, 0]`. Returns null when unparseable. */
 export function parseVersion(v) {
     if (typeof v !== 'string')
@@ -41,7 +42,7 @@ function lessThan(a, b) {
  * FAILS OPEN on anything unparseable (returns ok:true, no message), so a version string we
  * did not anticipate never produces a false warning.
  */
-export function checkServerVersion(running, range = SUPPORTED_ACTUAL_SERVER_RANGE) {
+export function checkServerVersion(running, range = SUPPORTED_ACTUAL_SERVER_RANGE, bundledApi = INSTALLED_API_VERSION) {
     const have = parseVersion(running);
     const min = parseVersion(range.minVersion);
     if (!have || !min)
@@ -63,6 +64,34 @@ export function checkServerVersion(running, range = SUPPORTED_ACTUAL_SERVER_RANG
                 'tool behaves oddly, update actual-mcp-server. Advisory only.',
         };
     }
+    // #439: the server is ahead of the `@actual-app/api` this build bundles.
+    //
+    // LAST in the chain deliberately (DECISION 3). Server 27.0.0 against bundled
+    // 26.9.0 satisfies this AND the testedMaxMajor branch above, and the verdict is
+    // single-valued, so the precedence is decided here rather than discovered by
+    // whoever reads the message. The existing branch keeps priority and its
+    // assertion stays green unchanged.
+    //
+    // MAJOR.MINOR ONLY (DECISION 2). Actual ships schema changes in MINOR releases
+    // (26.9.0 added account_group_id), while server patches ship independently of
+    // api patches, so comparing patches would be pure false-positive volume. It is
+    // silent when equal and silent when the server is behind.
+    //
+    // Scope, stated because it is narrower than it looks: this fires only when ops
+    // still SUCCEED, since the caller runs after a completed operation. A server so
+    // far ahead that budget download already fails never reaches it, and that case
+    // is #438's (surface the real session-init error) rather than this one's.
+    const bundled = parseVersion(bundledApi ?? '');
+    if (bundled && (have[0] > bundled[0] || (have[0] === bundled[0] && have[1] > bundled[1]))) {
+        return {
+            ok: false,
+            message: `Actual Budget server ${running} is newer than the @actual-app/api ${bundledApi} ` +
+                'this build bundles. Actual ships schema changes in minor releases, so a budget ' +
+                'download can fail with an invalid-schema error once one lands. Upgrade ' +
+                'actual-mcp-server, or hold the server upgrade until its dependency update has ' +
+                'shipped. Advisory only.',
+        };
+    }
     return { ok: true };
 }
 // ---------------------------------------------------------------------------
@@ -79,7 +108,12 @@ let checked = false;
  * `warn`; being in range is silent. The `log` argument is the module logger so all output
  * goes through the redaction-protected logger (never console.*), keeping stdio framing intact.
  */
-export async function checkServerVersionOnce(readVersion, log) {
+export async function checkServerVersionOnce(readVersion, log, 
+// #439: injected as a VALUE, not a function, and defaulted here rather than
+// resolved per call. A per-call resolver would do blocking readFileSync inside
+// the process-global api mutex. Tests pass an explicit literal so no in-chain
+// assertion depends on what is installed (#321).
+bundledApi = INSTALLED_API_VERSION) {
     if (checked)
         return;
     checked = true; // set synchronously, before any await, so a concurrent op cannot double-fire
@@ -89,7 +123,7 @@ export async function checkServerVersionOnce(readVersion, log) {
             log.debug('[server-version] could not read the Actual server version; skipping the compatibility check');
             return;
         }
-        const verdict = checkServerVersion(result.version);
+        const verdict = checkServerVersion(result.version, SUPPORTED_ACTUAL_SERVER_RANGE, bundledApi);
         if (!verdict.ok && verdict.message) {
             log.warn(verdict.message);
         }

package/dist/src/server/httpServer.js

@@ -25,6 +25,97 @@ import * as fs from 'node:fs';
 // `requestContext` from this module.
 import { requestContext } from '../lib/requestContext.js';
 import { buildToolListEntries } from '../lib/tool-list-entry.js';
+const INIT_FAILURE_SENTENCES = {
+    schema_too_new: "The Actual server's database schema is newer than the @actual-app/api this build bundles. Upgrade actual-mcp-server, or hold the server upgrade until its dependency update ships.",
+    auth_failed: 'Authentication against the Actual server failed. Check ACTUAL_PASSWORD and the budget password.',
+    // Deliberately not asserting permanence: ECONNRESET and ETIMEDOUT are classed
+    // TRANSIENT by isRetryableError, so this can be a blip rather than misconfiguration.
+    network_unreachable: 'The Actual server could not be reached, which may be transient. If it persists, check ACTUAL_SERVER_URL and that the server is running.',
+    budget_not_found: 'The configured budget was not found on the Actual server. Check ACTUAL_BUDGET_SYNC_ID.',
+    out_of_sync: 'The local budget copy is out of sync with the Actual server and could not be reconciled.',
+    encryption_error: "The budget's end-to-end encryption password is wrong or missing.",
+    clock_drift: "The host clock differs too far from the Actual server's. Fix the system time.",
+    // A filesystem permission error, WITHOUT claiming which path: the classifier
+    // sees only the errno, and EACCES can come from the data directory, TLS
+    // material, or a socket during api.init.
+    permission_denied: 'The server was denied filesystem access while initialising. Check the data directory mount and its ownership first, then any TLS material.',
+    timeout: 'Initialising the Actual connection ran out of time, which may be transient.',
+    unknown: 'The Actual connection for this session could not be initialised. See the server log for the cause.',
+};
+/** Actual's own reason strings, from `withErrorCode` and SyncError, to our enum.
+ *  `out-of-sync-migrations` maps to schema_too_new, NOT out_of_sync: `invalid-schema`
+ *  is absent from budgetLoader's KNOWN_LOAD_REASONS, so migrations is the only route
+ *  by which a too-new schema surfaces on the post-condition path, and upstream's own
+ *  sentence for it is "This budget cannot be loaded with this version of the app." */
+const REASON_TO_CAUSE = {
+    'invalid-schema': 'schema_too_new',
+    'out-of-sync-migrations': 'schema_too_new',
+    'out-of-sync': 'out_of_sync',
+    'out-of-sync-data': 'out_of_sync',
+    'budget-not-found': 'budget_not_found',
+    'clock-drift': 'clock_drift',
+    'encrypt-failure': 'encryption_error',
+    'decrypt-failure': 'encryption_error',
+    'missing-key': 'encryption_error',
+};
+/** Node fs/net codes. A DIFFERENT namespace from Actual's reasons, deliberately
+ *  kept in its own table so the two can never be conflated. */
+const SYSTEM_CODE_TO_CAUSE = {
+    EACCES: 'permission_denied',
+    EPERM: 'permission_denied',
+    EROFS: 'permission_denied',
+    ECONNREFUSED: 'network_unreachable',
+    ENOTFOUND: 'network_unreachable',
+    ECONNRESET: 'network_unreachable',
+    EHOSTUNREACH: 'network_unreachable',
+    ETIMEDOUT: 'timeout',
+};
+export function classifyInitFailure(err) {
+    const done = (cause) => ({ cause, sentence: INIT_FAILURE_SENTENCES[cause] });
+    try {
+        const e = err;
+        // `.code` FIRST: upstream's api/download-budget and api/load-budget never let a
+        // SyncError escape, they throw a plain Error carrying .code via withErrorCode.
+        const code = typeof e?.code === 'string' ? e.code : undefined;
+        if (code && REASON_TO_CAUSE[code])
+            return done(REASON_TO_CAUSE[code]);
+        if (code && SYSTEM_CODE_TO_CAUSE[code])
+            return done(SYSTEM_CODE_TO_CAUSE[code]);
+        // `.reason` only as a defensive fallback, for a SyncError that reaches us by
+        // some path that does not go through those two handlers.
+        const reason = typeof e?.reason === 'string' ? e.reason : undefined;
+        if (reason && REASON_TO_CAUSE[reason])
+            return done(REASON_TO_CAUSE[reason]);
+        const message = typeof e?.message === 'string' ? e.message : '';
+        // Our OWN synthesized post-condition error (#396) embeds the upstream reason
+        // in prose. On a resync of an existing local copy this is the shape that
+        // actually arrives for the schema and migration classes, so a classifier that
+        // handled only the upstream shapes would answer `unknown` for exactly the
+        // failures this ticket is about.
+        const embedded = /Upstream reason: \[([a-z-]+)\]/.exec(message)?.[1];
+        if (embedded && REASON_TO_CAUSE[embedded])
+            return done(REASON_TO_CAUSE[embedded]);
+        // Last resort, message shapes. `network-failure` is tested BEFORE the auth
+        // wording because upstream reports an unreachable server as
+        // "Authentication failed: network-failure", where the actionable half is the
+        // network, not the credentials.
+        if (/network-failure|ECONNREFUSED|ENOTFOUND/i.test(message))
+            return done('network_unreachable');
+        if (/timed out|ETIMEDOUT/i.test(message))
+            return done('timeout');
+        if (/Authentication failed|invalid-password|Invalid password/i.test(message))
+            return done('auth_failed');
+        if (/invalid-schema/i.test(message))
+            return done('schema_too_new');
+        return done('unknown');
+    }
+    catch {
+        // TOTAL by construction: a classifier that throws would land on the outer POST
+        // catch and egress as raw String(err), defeating this contract through the one
+        // line deliberately left to #446.
+        return done('unknown');
+    }
+}
 export { requestContext };
 // Resolve the authenticated principal for the per-principal budget preference
 // (#189). OIDC: the verified JWT subject. Static-bearer: a single shared
@@ -175,6 +266,40 @@ advertisedUrl) {
     }
     const transports = new Map();
     const sessionInitPromises = new Map(); // Track session init completion
+    // #438: why a session is NOT in `transports`. Closure-scoped like its two
+    // siblings above, so repeated startHttpServer calls (which the unit tests make)
+    // never share state and no reset export is needed. PEEK-ONLY: no reader deletes,
+    // and the TTL is the sole reaper. Consume-on-read was rejected because two
+    // concurrent requests on one session id would race for the single record and the
+    // loser would silently get the generic 404, restoring this bug at random.
+    const INIT_FAILURE_TTL_MS = 60_000;
+    const INIT_FAILURE_MAX = 1000;
+    const sessionInitFailures = new Map();
+    const rememberInitFailure = (sid, err) => {
+        const now = Date.now();
+        for (const [k, v] of sessionInitFailures) {
+            if (now - v.at > INIT_FAILURE_TTL_MS)
+                sessionInitFailures.delete(k);
+        }
+        // FIFO once capped. A failed init creates no pool entry, so onSessionEvicted
+        // never fires for these and nothing else would ever reap them.
+        while (sessionInitFailures.size >= INIT_FAILURE_MAX) {
+            const oldest = sessionInitFailures.keys().next().value;
+            if (oldest === undefined)
+                break;
+            sessionInitFailures.delete(oldest);
+        }
+        sessionInitFailures.set(sid, { ...classifyInitFailure(err), at: now });
+    };
+    /** Peek. Never deletes. Returns undefined once the TTL has elapsed. */
+    const peekInitFailure = (sid) => {
+        const rec = sessionInitFailures.get(sid);
+        if (!rec)
+            return undefined;
+        if (Date.now() - rec.at > INIT_FAILURE_TTL_MS)
+            return undefined;
+        return { cause: rec.cause, sentence: rec.sentence };
+    };
     // safe fallback if index didn't provide implementedTools
     const toolsList = Array.isArray(implementedTools) ? implementedTools : [];
     // #379: one resolver, one builder, for all THREE tools/list paths below: the SDK handler,
@@ -429,6 +554,12 @@ advertisedUrl) {
                             logger.error(`[SESSION] Failed to initialize Actual for session ${sid}:`, err);
                             // Don't add failed sessions to transports map - they won't be usable anyway
                             // This prevents accumulation of dead sessions
+                            // #438: remember WHY. The transport is still deliberately not registered,
+                            // so the dead-session protection above is unchanged; without this the
+                            // cause is known here and discarded, and the client's next request gets
+                            // a bare "Session not found" that says nothing about a schema mismatch,
+                            // a bad password or an unreachable server.
+                            rememberInitFailure(sid, err);
                             rejectInit?.(err);
                         }
                         finally {
@@ -492,6 +623,43 @@ advertisedUrl) {
                     // Session doesn't exist (expired, server restarted, or invalid)
                     // For tools/list, return tools for LobeChat discovery (they cache session IDs)
                     // This allows LobeChat's backend to discover available tools even with expired sessions
+                    // #438: ONE lookup, at the top of this block and BEFORE the shim, so
+                    // there is a single read per request under peek semantics and a fourth
+                    // caller cannot reintroduce the mask. Wrapped in its own try/catch: a
+                    // throw here would land on the outer catch below, which returns raw
+                    // String(err) (that line's sanitisation is #446), and would defeat the
+                    // enum-only contract through the very hole left open there.
+                    let knownFailure;
+                    try {
+                        knownFailure = peekInitFailure(sessionId);
+                    }
+                    catch {
+                        knownFailure = undefined;
+                    }
+                    if (knownFailure) {
+                        // A known init failure BEATS the discovery shim for this session id:
+                        // answering 200 plus a full tool list to a session whose connection
+                        // never came up is the same masking in a friendlier costume.
+                        logger.warn(`[SESSION] Session ${sessionId} failed to initialize (${knownFailure.cause}); reporting the cause (method: ${method})`);
+                        res.status(404).json({
+                            jsonrpc: '2.0',
+                            id: payload?.id ?? null,
+                            error: {
+                                code: -32001,
+                                // The lowercase `re-initialize` token is load bearing, not styling:
+                                // tests/manual/mcp-client.js:131 matches `includes('re-initialize')`
+                                // to trigger its session reset, and that branch is checked BEFORE its
+                                // `timed out` branch. Capitalising it made a failed-init session fall
+                                // through to the timeout branch, which retries a permanently dead
+                                // session until MCP_TEST_MAX_RETRIES is exhausted.
+                                message: `${knownFailure.sentence} Please re-initialize by calling initialize without an mcp-session-id header once the cause is fixed.`,
+                                // Closed enum only. Nothing derived from the upstream error reaches
+                                // the wire, which is why no scrubber has to be correct here.
+                                data: { cause: knownFailure.cause, sessionInitFailed: true },
+                            },
+                        });
+                        return;
+                    }
                     if (method === 'tools/list') {
                         logger.debug('[LOBECHAT COMPAT] Handling tools/list with expired/invalid session - returning tools for discovery');
                         const tools = buildToolListEntries(toolsList, resolveToolMeta);
@@ -535,6 +703,10 @@ advertisedUrl) {
             if (e2 && typeof e2.stack === 'string')
                 logger.error(e2.stack);
             if (!res.headersSent) {
+                // NOTE: this returns the raw error string to the client. That pre-existing
+                // disclosure is tracked as #446 and is deliberately out of scope here. The
+                // #438 session-init path above is CONTAINED by its own try/catch and never
+                // reaches this line, so its closed-enum contract cannot leak through here.
                 res.status(500).json({ jsonrpc: '2.0', id: payload?.id ?? null, error: { code: -32603, message: String(err) } });
             }
         }
@@ -549,6 +721,36 @@ advertisedUrl) {
         connectionPool.touch(sessionId); // Refresh the pool's idle clock (#167)
         const transport = transports.get(sessionId);
         if (!transport) {
+            // #438: same cause, this route's own status and code. The classifier owns no
+            // status: each caller maps the classification onto the shape it already
+            // returns. try/catch is load bearing here because this route has NONE and the
+            // file registers no error-handling middleware, so under Express 5 an async
+            // throw reaches the default final handler, which puts err.stack in the body
+            // whenever NODE_ENV is not production (unset for a bare node run, and
+            // `development` in docker-compose).
+            // #438 REVIEW: this route is deliberately NOT given the cause. Outside the
+            // OIDC branch it never calls `authenticateRequest` (POST-only, at the single
+            // call site), so anything added here is reachable without an Authorization
+            // header, and the sentences are configuration hints. The body therefore stays
+            // the constant it has always been. The POST route, which IS authenticated,
+            // carries the whole value of this feature. Reporting here can be revisited
+            // once that route's auth posture is fixed, which is #447.
+            //
+            // The peek is kept solely for the log line: it tells an operator reading the
+            // server log why this session is dead, without putting it on an unauthenticated
+            // wire. try/catch is load bearing because this route has NO error handling and
+            // the file registers no error middleware, so under Express 5 a throw reaches the
+            // default final handler, which emits err.stack whenever NODE_ENV is not
+            // production (unset for a bare node run, `development` in docker-compose).
+            try {
+                const knownFailure = peekInitFailure(sessionId);
+                if (knownFailure) {
+                    logger.warn(`[SESSION] GET on session ${sessionId} whose init failed (${knownFailure.cause}); returning the generic body (auth posture, see the note above)`);
+                }
+            }
+            catch {
+                // never let diagnostics break the response
+            }
             res.status(400).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Transport not ready' }, id: null });
             return;
         }
@@ -652,6 +854,7 @@ advertisedUrl) {
         }
         transports.clear();
         sessionInitPromises.clear();
+        sessionInitFailures.clear(); // #438
         // Also shut down the shared/pooled connections
         await shutdownActual();
     };

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.4",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
@@ -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/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: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/httpServer_init_failure_report.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",