actual-mcp-server 0.19.3 → 0.20.0

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.3 | **Tool Count:** 77 (verified LibreChat-compatible)
+**Version:** 0.20.0 | **Tool Count:** 77 (verified LibreChat-compatible)
 
 ## Sponsor
 

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

@@ -45,13 +45,44 @@ function _splitInList(valuesStr) {
 //      a double-quoted element hiding a single quote (`"x' UNION SELECT 1 --"`) is well formed by (1)
 //      yet its inner `'` would terminate upstream's wrapper. Checking the stripped value closes that.
 // A legitimate `'groceries'`, `'Smith, John'`, `"cash"`, `100` or `-5.5` passes both.
+/** A single-quoted literal whose internal quotes are SQL-ESCAPED by doubling.
+ *  `'McDonald''s'` matches; `'McDonald's'` (a lone quote) does not. */
+const SQL_ESCAPED_SINGLE_QUOTED = /^'(?:[^']|'')*'$/;
 function _isSafeInListElement(raw) {
     const t = raw.trim();
-    const wellFormed = /^'[^']*'$/.test(t) || /^"[^"]*"$/.test(t) || /^-?\d+(?:\.\d+)?$/.test(t);
+    // #433: a single-quoted element may now carry DOUBLED internal quotes. That is
+    // safe for the reason #421 made the original rule, read the other way round:
+    // upstream compiles $oneof by inlining each value verbatim as `'${String(id)}'`
+    // (aql/compiler.ts, verified against the installed source), so a LONE quote
+    // terminates that wrapper and smuggles trailing SQL, while a DOUBLED quote is
+    // exactly the escape SQL defines and produces a balanced literal.
+    if (SQL_ESCAPED_SINGLE_QUOTED.test(t))
+        return true;
+    const wellFormed = /^"[^"]*"$/.test(t) || /^-?\d+(?:\.\d+)?$/.test(t);
     if (!wellFormed)
         return false;
+    // A double-quoted element must still carry no single quote at all: upstream
+    // re-wraps it in SINGLE quotes, so an internal one would break out exactly as
+    // before. This is the #421 injection witness shape.
     return !_stripWhereQuotes(t).includes("'");
 }
+/** Coercion for IN-list elements ONLY.
+ *
+ *  Deliberately separate from `_coerceWhereValue`, which serves `=`, `!=`, `<`
+ *  and friends. Those operands travel a different compile path, and this doubling
+ *  is correct ONLY because $oneof inlines its values into SQL text verbatim. A
+ *  shared coercion would apply SQL escaping to an operand that may never reach
+ *  raw SQL, which would silently match nothing.
+ *
+ *  The doubling is PRESERVED rather than unescaped, so upstream's `'${id}'` wrap
+ *  yields `'McDonald''s'`, which SQLite reads as `McDonald's`. */
+function _coerceInListValue(s) {
+    const t = s.trim();
+    if (SQL_ESCAPED_SINGLE_QUOTED.test(t) && t.includes("''")) {
+        return t.slice(1, -1); // keep the doubling; upstream supplies the outer quotes
+    }
+    return _coerceWhereValue(s);
+}
 // Coerce a SQL value literal to a number when it looks numeric, else keep the
 // (unquoted) string. Used for IN lists and comparison operands. Empty stays a
 // string so an empty literal is not silently turned into 0.
@@ -162,10 +193,12 @@ export function parseWhereClause(query, whereClause, tableName) {
                 for (const raw of rawValues) {
                     if (!_isSafeInListElement(raw)) {
                         throw new Error(`Invalid value in IN list for column "${field}": ${JSON.stringify(raw.trim())}. ` +
-                            `Each value must be a number or a quoted string with no embedded quote.`);
+                            `Each value must be a number, a double-quoted string with no single quote, ` +
+                            `or a single-quoted string whose internal quotes are SQL-escaped by doubling ` +
+                            `(for example 'McDonald''s').`);
                     }
                 }
-                query = query.filter({ [field]: { $oneof: rawValues.map(_coerceWhereValue) } });
+                query = query.filter({ [field]: { $oneof: rawValues.map(_coerceInListValue) } });
             }
             continue;
         }

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

@@ -0,0 +1,83 @@
+/**
+ * #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;
+}
+/** Resolve any installed package's real version, or null. Same contract as the
+ *  constant below: SILENT, never throws, and null is a normal state. #445 made
+ *  this take a name so `actual_server_info` can report the resolved MCP SDK
+ *  version too without duplicating the walk. */
+export function resolveInstalledVersion(pkgName, entry = pkgName) {
+    try {
+        const require = createRequire(import.meta.url);
+        // `entry` exists because a bare package name is NOT always resolvable. The MCP
+        // SDK exports no root path, so require.resolve('@modelcontextprotocol/sdk')
+        // throws MODULE_NOT_FOUND while '@modelcontextprotocol/sdk/server/index.js'
+        // resolves fine. That is the same class of trap as @actual-app/api not
+        // exporting its own package.json, and it matters more than it looks: with the
+        // omit-on-failure contract, an unresolvable name looks exactly like a package
+        // that is legitimately absent, so the caller passes a subpath it knows exists
+        // rather than letting the field silently disappear.
+        return readVersionFromTree(dirname(require.resolve(entry)), pkgName);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveInstalledApiVersion() {
+    return resolveInstalledVersion(PACKAGE);
+}
+/** 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,12 +703,43 @@ advertisedUrl) {
             if (e2 && typeof e2.stack === 'string')
                 logger.error(e2.stack);
             if (!res.headersSent) {
-                res.status(500).json({ jsonrpc: '2.0', id: payload?.id ?? null, error: { code: -32603, message: String(err) } });
+                // #446: the client gets a STABLE message plus a correlation id, never the
+                // raw error. `String(err)` here could carry a stack, raw SQL from
+                // SyncError.meta.query, an EACCES path with the OS username, or the
+                // configured upstream URL. The detail is already logged above with the
+                // request id stamped by requestContext (#221), so an operator joins the two
+                // by that id instead of reading it off the wire.
+                //
+                // The id is best effort: this catch can fire OUTSIDE requestContext.run
+                // (an error thrown while establishing the context), in which case there is
+                // nothing to correlate and the field is omitted rather than invented.
+                const requestId = requestContext.getStore()?.requestId;
+                logger.error(`[HTTP] Unhandled POST error${requestId ? ` (requestId=${requestId})` : ''}`);
+                res.status(500).json({
+                    jsonrpc: '2.0',
+                    id: payload?.id ?? null,
+                    error: {
+                        code: -32603,
+                        message: 'Internal error. The server logged the cause; quote the requestId when reporting it.',
+                        ...(requestId ? { data: { requestId } } : {}),
+                    },
+                });
             }
         }
     });
     // GET for SSE connect (reuse transport)
     app.get(httpPath, async (req, res) => {
+        // #447: the SAME gate the POST route uses. Until now this route never called
+        // it outside the OIDC branch, so in the default static-bearer posture a GET on
+        // the MCP path was unauthenticated while a POST on the identical path was not.
+        // That inconsistency is what forced #438 to withhold the session-init cause
+        // here: the cause sentences are configuration hints, and putting them on an
+        // unauthenticated route would widen what a caller without a token can learn.
+        // authenticateRequest writes its own 401 and returns false, so this is the
+        // whole change.
+        if (!authenticateRequest(req, res)) {
+            return;
+        }
         const sessionId = req.headers['mcp-session-id'];
         if (!sessionId) {
             res.status(400).json({ jsonrpc: '2.0', error: { code: -32000, message: 'No session id' }, id: null });
@@ -549,7 +748,39 @@ advertisedUrl) {
         connectionPool.touch(sessionId); // Refresh the pool's idle clock (#167)
         const transport = transports.get(sessionId);
         if (!transport) {
-            res.status(400).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Transport not ready' }, id: null });
+            // #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 + #447: the cause IS reported here now. It was withheld while this
+            // route was unauthenticated in the default static-bearer posture, because
+            // the cause sentences are configuration hints. #447 gated the route with the
+            // same authenticateRequest the POST route uses, so the reason for withholding
+            // is gone. Same closed enum, same fixed sentences, this route's own status
+            // and code. try/catch is still load bearing: this route has no error handling
+            // of its own 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.
+            let knownFailure;
+            try {
+                knownFailure = peekInitFailure(sessionId);
+            }
+            catch {
+                knownFailure = undefined;
+            }
+            if (knownFailure) {
+                logger.warn(`[SESSION] GET on session ${sessionId} whose init failed (${knownFailure.cause}); reporting the cause`);
+            }
+            res.status(400).json({
+                jsonrpc: '2.0',
+                error: knownFailure
+                    ? { code: -32000, message: knownFailure.sentence, data: { cause: knownFailure.cause, sessionInitFailed: true } }
+                    : { code: -32000, message: 'Transport not ready' },
+                id: null,
+            });
             return;
         }
         await transport.handleRequest(req, res);
@@ -652,6 +883,7 @@ advertisedUrl) {
         }
         transports.clear();
         sessionInitPromises.clear();
+        sessionInitFailures.clear(); // #438
         // Also shut down the shared/pooled connections
         await shutdownActual();
     };

package/dist/src/tools/server_info.js

@@ -3,6 +3,11 @@ import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import actualToolsManager from '../actualToolsManager.js';
+import { INSTALLED_API_VERSION, resolveInstalledVersion } from '../lib/installed-api-version.js';
+/** Resolved once at module load, not per call: the walk does blocking file reads
+ *  and this tool can be called in a loop. The SDK exports no root path, so the
+ *  resolvable subpath is passed explicitly (#445). */
+const MCP_SDK_RESOLVED = resolveInstalledVersion('@modelcontextprotocol/sdk', '@modelcontextprotocol/sdk/server/index.js');
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Read version from environment variable (set during Docker build) or package.json
@@ -65,9 +70,21 @@ Use this to check server status, verify version compatibility, or debug issues.`
                 platform: process.platform,
                 arch: process.arch,
             },
+            // #445: report BOTH the declared range and what is actually installed. They
+            // answer different questions ("what does this build allow" versus "what is it
+            // running"), and #427 needed the second: a caret range reports identically for
+            // every version inside it, which is exactly the ambiguity that made a server
+            // and api version skew hard to diagnose.
+            //
+            // The resolved fields are OMITTED when they cannot be determined, never set to
+            // a sentinel: absence means "could not resolve" and no consumer has to
+            // special-case a magic string. The declared fields keep their existing
+            // behaviour and value, so nothing that reads them today breaks.
             dependencies: {
                 mcpSdk: packageInfo.dependencies?.['@modelcontextprotocol/sdk'] ?? 'unknown',
                 actualApi: packageInfo.dependencies?.['@actual-app/api'] ?? 'unknown',
+                ...(MCP_SDK_RESOLVED ? { mcpSdkResolved: MCP_SDK_RESOLVED } : {}),
+                ...(INSTALLED_API_VERSION ? { actualApiResolved: INSTALLED_API_VERSION } : {}),
             },
             status: {
                 uptime: uptimeFormatted,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.19.3",
+  "version": "0.20.0",
   "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",
@@ -78,7 +78,7 @@
     "mcp-auth": "^0.2.0",
     "winston": "^3.18.3",
     "winston-daily-rotate-file": "^5.0.0",
-    "zod": "^4.4.3"
+    "zod": "^4.5.4"
   },
   "optionalDependencies": {
     "prom-client": "*"
@@ -86,8 +86,8 @@
   "devDependencies": {
     "@playwright/test": "^1.60.0",
     "@types/express": "^5.0.3",
-    "@types/node": "^26.1.0",
-    "knip": "^6.32.0",
+    "@types/node": "^26.4.1",
+    "knip": "^6.34.0",
     "node-fetch": "^3.3.2",
     "tsconfig-paths": "^4.2.0",
     "typescript": "^7.0.2"