actual-mcp-server 0.8.4 → 0.8.10

package/README.md

@@ -134,6 +134,8 @@ docker compose --profile dev up -d          # dev mode with hot-reload
 
 ### Option C: npm (HTTP server)
 
+> **Requires Node.js 22+.** npm and npx do not enforce this, so check with `node --version` first. On an older Node the server refuses to start and tells you so. Note that `npx` runs whichever `node` is first on your `PATH`, which is not always the one you installed most recently.
+
 ```bash
 # Quick start via npx (no clone needed):
 ACTUAL_SERVER_URL=http://localhost:5006 \
@@ -720,4 +722,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.8.4 | **Tool Count:** 71 (verified LibreChat-compatible)
+**Version:** 0.8.10 | **Tool Count:** 71 (verified LibreChat-compatible)

package/bin/actual-mcp-server.js

@@ -1,3 +1,10 @@
 #!/usr/bin/env node
-// Entry point for npx actual-mcp-server — delegates to the compiled dist.
-import '../dist/src/index.js';
+// Entry point for npx actual-mcp-server. Delegates to the compiled dist.
+//
+// #275: the version guard is a STATIC import so it evaluates before this module's
+// body, and the dist server is a DYNAMIC import so its module graph is never loaded
+// on an interpreter that cannot run it. Reversing either would put us back to the
+// cryptic ERR_IMPORT_ASSERTION_TYPE_MISSING on Node 18.
+import '../dist/src/lib/node-version-guard.js';
+
+await import('../dist/src/index.js');

package/dist/src/index.js

@@ -1,5 +1,38 @@
+// #275: MUST be the first import. ES modules evaluate their imports depth-first in
+// source order, so this arms the Node floor check before zod, before the rejection
+// allowlist, and before the handlers below. `npm start` and the documented
+// `node dist/src/index.js --stdio` reach this file without going through bin/, so the
+// guard cannot live in bin/ alone. Importing the named export does not change that:
+// the module's top-level `enforceNodeVersion()` still fires here, exactly once.
+import { findRootPackageJson } from './lib/node-version-guard.js';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import { isKnownBenignRejection } from './lib/rejection-allowlist.js';
+/**
+ * #277: the single version reader for this module.
+ *
+ * This used to be a dynamic JSON import of `../package.json` carrying an import
+ * attribute, which from the compiled `dist/src/index.js` resolved to `dist/package.json`:
+ * a mirror that tsc emitted precisely BECAUSE of this import (rootDir is "."), and that
+ * went stale between a version bump and the next build. `src/tools/server_info.ts` reads
+ * the ROOT manifest, so the two disagreed. Removing the import removes the mirror too.
+ *
+ * `findRootPackageJson` walks up to the outermost package.json named actual-mcp-server,
+ * skipping that mirror. It never throws (it swallows unreadable and malformed files), so
+ * the try/catch is belt-and-braces around a future change rather than a live path.
+ * Removing the import attributes also removes the last instance of the construct that
+ * crashed on Node 18 in #275.
+ */
+function readRootVersion() {
+    try {
+        const manifest = findRootPackageJson(dirname(fileURLToPath(import.meta.url)));
+        return manifest?.version ?? process.env.VERSION ?? 'unknown';
+    }
+    catch {
+        return process.env.VERSION ?? 'unknown';
+    }
+}
 // Add global error handlers
 process.on('unhandledRejection', (reason, promise) => {
     console.error('=== UNHANDLED REJECTION ===');
@@ -9,6 +42,15 @@ process.on('unhandledRejection', (reason, promise) => {
         console.error('Stack:', reason.stack);
     }
     console.error('===========================');
+    // #275 backstop. The guard above catches both entry points, but a consumer that
+    // imports this package as a library reaches neither. Import attributes are the one
+    // construct here that fails on an under-floor Node, and it fails asynchronously,
+    // so name the real cause rather than letting the reader chase a packaging bug.
+    if (reason?.code === 'ERR_IMPORT_ASSERTION_TYPE_MISSING') {
+        console.error(`⚠️  This almost certainly means Node ${process.version} is too old.`);
+        console.error('⚠️  actual-mcp-server requires the Node version in package.json "engines".');
+        console.error('⚠️  Import attributes (`with { type: "json" }`) need Node 22 or newer.');
+    }
     if (isKnownBenignRejection(reason)) {
         console.error('⚠️  Known Actual API domain error escaped to unhandledRejection:');
         console.error('⚠️  ' + String(reason));
@@ -81,8 +123,7 @@ if (!argsEarly.includes('--http') &&
 }
 if (argsEarly.includes('--help') || argsEarly.includes('-h') ||
     argsEarly.includes('--version') || argsEarly.includes('-v')) {
-    const pkg = await import('../package.json', { with: { type: 'json' } });
-    const version = pkg.default.version;
+    const version = readRootVersion();
     if (argsEarly.includes('--version') || argsEarly.includes('-v')) {
         console.log(version);
     }
@@ -135,11 +176,10 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
     const logger = loggerModule.default;
     const { getLocalIp } = utilsModule;
     const actualToolsManager = actualToolsManagerModule.default;
-    // Load version from environment (Docker build-time) or package.json (local dev)
+    // Load version from environment (Docker build-time) or the ROOT package.json (local dev)
     let VERSION = process.env.VERSION;
     if (!VERSION || VERSION === 'unknown') {
-        const packageJson = await import('../package.json', { with: { type: 'json' } });
-        VERSION = packageJson.default.version;
+        VERSION = readRootVersion();
         // Append git commit hash for development builds
         try {
             const { execSync } = await import('child_process');

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

@@ -12,6 +12,7 @@ import { retry, isRetryableError } from './retry.js';
 import { withOpTimeout } from './opTimeout.js';
 import { notFoundMsg } from './errors.js';
 import logger from '../logger.js';
+import { checkServerVersionOnce } from './server-version-guard.js';
 import config from '../config.js';
 import { parseBudgetRegistry } from './budget-registry.js';
 import { getPreferredBudgetSyncId, setPreferredBudgetSyncId, pickAllowedPreferredBudget } from './budget-preference-store.js';
@@ -229,11 +230,21 @@ function _enforceBudgetAcl(toolName) {
  * In either mode `withApiLock` serialises against concurrent callers because
  * `@actual-app/api` is a process-wide singleton.
  */
-export async function withActualApi(operation) {
+export async function withActualApi(rawOperation) {
     // ACL enforcement BEFORE pool branching or lock acquisition (#156).
     // Denial here means the lock is never acquired and no upstream resource is
     // touched.
     _enforceBudgetAcl();
+    // #276: on the FIRST successful op, warn (once) if the Actual server version is outside
+    // the range this build supports. It runs inside the op while the connection is live and
+    // reuses it via rawGetServerVersion (NOT the withActualApi-wrapped getServerVersion, which
+    // would re-enter the lock). The once-guard flips its flag synchronously, so this never
+    // repeats per session or op. It is advisory: it never throws and never blocks the op.
+    const operation = async () => {
+        const result = await rawOperation();
+        await checkServerVersionOnce(() => rawGetServerVersion(), logger);
+        return result;
+    };
     const sessionId = _resolveSessionId();
     if (_hasPooledConnection(sessionId)) {
         // Pooled mode: skip init+shutdown.
@@ -519,8 +530,35 @@ let writeSessionTimeout = null;
 // Counter for diagnostic: writes that reused an existing pool connection
 // (skipped the per-op init). Surfaces in getConcurrencyState(). See #158.
 let writeConnectionReuseCount = 0;
+// #278: one batch dispatch per processWriteQueue run. Exposed to tests so the debounce
+// COALESCING property (N same-tick writes -> ONE batch, one init/sync cycle) is pinned.
+// A fix that drained on every enqueue would close the deadlock and silently turn one
+// batch into N; nothing else in the suite would notice.
+let writeQueueBatchCount = 0;
+/**
+ * #278: the ONLY place a write-queue drain is scheduled.
+ *
+ * The callback nulls `writeSessionTimeout` BEFORE draining. That ordering is the whole
+ * fix. Previously a timer that fired while a drain was in flight hit the early return in
+ * `processWriteQueue` without clearing its own handle, leaving a dead-but-non-null value
+ * behind. The drain's `finally` then skipped its re-drain because it tested
+ * `writeSessionTimeout === null`, so an operation enqueued mid-drain was never dispatched
+ * and its promise never settled. `withOpTimeout` (#270) could not catch it: that bounds
+ * execution, and the operation never started.
+ */
+function scheduleWriteQueueDrain() {
+    if (writeSessionTimeout)
+        clearTimeout(writeSessionTimeout);
+    writeSessionTimeout = setTimeout(() => {
+        writeSessionTimeout = null;
+        processWriteQueue();
+    }, WRITE_SESSION_DELAY_MS);
+}
 async function processWriteQueue() {
-    // Atomically check and set processing flag to prevent race conditions
+    // Atomically check and set processing flag to prevent race conditions.
+    // Safe to return without touching writeSessionTimeout: a fired timer has already
+    // nulled it (scheduleWriteQueueDrain), and the finally below always reschedules
+    // whenever the queue is non-empty.
     if (isProcessingWrites || writeQueue.length === 0)
         return;
     isProcessingWrites = true;
@@ -530,6 +568,15 @@ async function processWriteQueue() {
         writeSessionTimeout = null;
     }
     const batch = writeQueue.splice(0, writeQueue.length); // Take all current items
+    // #278: these entries are now DISPATCHED, so their residency bound no longer applies.
+    // Clearing here, before any await, means the timer can never fire on an in-flight op.
+    for (const entry of batch) {
+        if (entry.residencyTimer) {
+            clearTimeout(entry.residencyTimer);
+            entry.residencyTimer = undefined;
+        }
+    }
+    writeQueueBatchCount++;
     // Pool-cooperation decision (#158): use the first queued op's captured
     // sessionId as the batch's sessionId. In practice all ops batched together
     // came from the same setTimeout window and same request, so they share
@@ -636,12 +683,13 @@ async function processWriteQueue() {
     }
     finally {
         isProcessingWrites = false;
-        // Process any new operations that were queued while we were processing
-        if (writeQueue.length > 0 && writeSessionTimeout === null) {
-            writeSessionTimeout = setTimeout(() => {
-                processWriteQueue();
-            }, WRITE_SESSION_DELAY_MS);
-        }
+        // #278: ALWAYS re-drain a non-empty queue. The old `&& writeSessionTimeout === null`
+        // guard was the lost wakeup: a timer that fired mid-drain left a dead handle here,
+        // so operations queued during the drain were stranded until an unrelated later write
+        // happened to schedule a fresh timer. No busy loop: this only fires when work exists,
+        // and the drain splices the entire queue.
+        if (writeQueue.length > 0)
+            scheduleWriteQueueDrain();
     }
 }
 function queueWriteOperation(operation) {
@@ -653,17 +701,40 @@ function queueWriteOperation(operation) {
     // decision in processWriteQueue would always miss. See #158.
     const sessionId = _resolveSessionId();
     return new Promise((resolve, reject) => {
-        writeQueue.push({ operation, resolve, reject, sessionId });
-        // Clear existing timeout
-        if (writeSessionTimeout) {
-            clearTimeout(writeSessionTimeout);
+        const entry = { operation, resolve, reject, sessionId };
+        // #278: bound queue RESIDENCY, not just execution. #270's withOpTimeout bounds an
+        // operation that is RUNNING; it cannot bound one that never starts. Reuse the same
+        // knob so there is one timeout concept: ACTUAL_OP_TIMEOUT_MS, with <= 0 meaning
+        // disabled (matching withOpTimeout). Worst case for a single call is therefore
+        // residency + execution = 2 * ACTUAL_OP_TIMEOUT_MS; residency is normally under
+        // WRITE_SESSION_DELAY_MS (100ms).
+        const residencyLimitMs = config.ACTUAL_OP_TIMEOUT_MS;
+        if (Number.isFinite(residencyLimitMs) && residencyLimitMs > 0) {
+            entry.residencyTimer = setTimeout(() => {
+                const index = writeQueue.indexOf(entry);
+                if (index === -1)
+                    return; // already dispatched; the timer was cleared, this is belt and braces
+                writeQueue.splice(index, 1);
+                logger.error(`[WRITE QUEUE] Operation was not dispatched within ${residencyLimitMs}ms; rejecting it (#278)`);
+                // Deliberately does NOT contain the substring "timed out". TRANSIENT_ERROR_PATTERNS
+                // in ./retry.ts matches that substring, and _shouldDropPoolOnError delegates to
+                // isRetryableError. An operation that was never dispatched never touched upstream,
+                // so classifying it as an infrastructure failure would tear down a healthy pooled
+                // connection on a false signal. This error is terminal by design.
+                reject(new Error(`Write operation was not dispatched within ${residencyLimitMs}ms ` +
+                    '(write-queue stall, ACTUAL_OP_TIMEOUT_MS). The operation never ran and no data was modified.'));
+            }, residencyLimitMs);
+            // A pending residency timer must never hold the stdio process open at shutdown.
+            entry.residencyTimer.unref?.();
         }
-        // Set new timeout to process queue
-        writeSessionTimeout = setTimeout(() => {
-            processWriteQueue();
-        }, WRITE_SESSION_DELAY_MS);
+        writeQueue.push(entry);
+        scheduleWriteQueueDrain();
     });
 }
+/** #278 test hook: batches dispatched by processWriteQueue. Pins the coalescing property. */
+export function _getWriteQueueBatchCountForTests() {
+    return writeQueueBatchCount;
+}
 /**
  * Run a read+write atomic sequence inside a SINGLE write-queue session.
  *

package/dist/src/lib/constants.js

@@ -81,3 +81,21 @@ export const MONTH_PATTERN = /^\d{4}-\d{2}$/;
  * UUID pattern for ID validation
  */
 export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * #276: the Actual Budget SERVER version range this build's `@actual-app/api` is known
+ * to work with. HAND-MAINTAINED: `@actual-app/api` v26 exposes no supported-server range
+ * (verified: getServerVersion just proxies the server's build.version), so there is no
+ * upstream fact to derive this from and no #275-style drift guard is possible.
+ *
+ * UPDATE THIS when bumping `@actual-app/api`: set `minVersion` to the oldest server the new
+ * client supports, and `testedMaxMajor` to the newest server major it has been tested
+ * against. The check is ADVISORY only (the real compatibility contract is the migration
+ * check `@actual-app/api` runs at downloadBudget), so a wrong value here can at most produce
+ * a spurious or missing warning, never a broken deployment.
+ */
+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". */
+    testedMaxMajor: 26,
+};

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

@@ -0,0 +1,153 @@
+/**
+ * #275: fail fast, and legibly, on an unsupported Node.
+ *
+ * npm and npx do not enforce `engines` (`engine-strict` defaults to false), so the
+ * package installs and launches happily on Node 18. There it dies with
+ * `ERR_IMPORT_ASSERTION_TYPE_MISSING`, because Node 18 predates the `with` import
+ * attribute spelling used by the dynamic `import('../package.json', { with: ... })`
+ * calls in index.ts. That is a link-time error on a dynamic import, not a syntax
+ * error, so it escapes to `unhandledRejection` AFTER the stdio transport has already
+ * announced itself. The client sees a connected server with zero tools and blames
+ * its own config.
+ *
+ * This module runs the check on import, before anything else is evaluated.
+ *
+ * CONSTRAINTS, enforced by tests/unit/node_version_guard.test.js:
+ *
+ *  1. Zero dependencies beyond `node:fs`, `node:path`, `node:url`. It has to run on
+ *     the very interpreter it is about to reject, so it cannot import anything that
+ *     might fail to parse or resolve there.
+ *  2. No import attributes. Reading the floor via `import(pkg, { with: ... })` would
+ *     be the exact construct that breaks on the Node we are guarding against, so the
+ *     floor is read with `readFileSync` + `JSON.parse`, which works everywhere.
+ *  3. The floor is never hardcoded. It comes from `engines.node` in the root
+ *     package.json, so bumping the floor needs no change here.
+ *
+ * On the root package.json: a `dist/package.json` mirror can sit between this module and
+ * the real root. `tsc` emitted one for as long as any source file imported
+ * `../package.json` (rootDir is "." and resolveJsonModule is on), and in a dev tree it
+ * went stale. #277 removed those imports, so a clean build no longer produces it, but a
+ * dist/ tree built by an older version still can. Reading it would reintroduce the class
+ * of bug this guard exists to prevent, so we walk up looking for the package.json that
+ * identifies itself as this package, rather than trusting a fixed relative depth.
+ */
+import { existsSync, readFileSync, writeSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The package.json we trust. The dist mirror carries the same name, so the walk also bounds by depth. */
+const PACKAGE_NAME = 'actual-mcp-server';
+/** How far up to look. From dist/src/lib/ the root is 3 levels up; 5 leaves headroom for an outDir change. */
+const MAX_WALK_LEVELS = 5;
+/** `'v18.19.1'` and `'18.19.1'` both yield `18`. Returns NaN when unparseable. */
+export function parseMajor(version) {
+    if (typeof version !== 'string')
+        return NaN;
+    const match = /^v?(\d+)\./.exec(version.trim());
+    return match ? Number(match[1]) : NaN;
+}
+/** `'>=22.0.0'` yields `22`. Returns NaN when unparseable, which callers treat as "fail open". */
+export function requiredMajor(range) {
+    if (typeof range !== 'string')
+        return NaN;
+    const match = /(\d+)/.exec(range.trim());
+    return match ? Number(match[1]) : NaN;
+}
+/**
+ * Pure. No I/O, no process access, so the truth table is unit-testable without spawning.
+ *
+ * Fails OPEN on anything it cannot parse. A guard that bricks a valid install because
+ * `engines.node` was written in a spelling we did not anticipate would be worse than
+ * the bug it is fixing.
+ */
+export function checkNodeVersion(running, range) {
+    const have = parseMajor(running);
+    const need = requiredMajor(range);
+    if (Number.isNaN(have) || Number.isNaN(need))
+        return { ok: true };
+    if (have >= need)
+        return { ok: true };
+    return {
+        ok: false,
+        message: `actual-mcp-server requires Node ${range}, but is running on ${running}.\n` +
+            '\n' +
+            "If you launched this through npx or the installed launcher, its '#!/usr/bin/env node'\n" +
+            'shebang re-resolves node from PATH. Pointing your MCP client at a newer npx, or at an\n' +
+            'absolute path to the launcher, therefore does NOT change which interpreter runs. Fix\n' +
+            'PATH, or invoke a supported node binary directly:\n' +
+            '\n' +
+            '  /path/to/node-22/bin/node $(which actual-mcp-server) --stdio\n' +
+            '\n' +
+            'Without this check the server would start, announce itself to your client, and\n' +
+            'then die with ERR_IMPORT_ASSERTION_TYPE_MISSING, leaving a connected session\n' +
+            'that exposes zero tools.',
+    };
+}
+/**
+ * Walk up from `startDir` for the package.json whose `name` is this package.
+ * Depth-independent, so it resolves identically from `bin/` and from `dist/src/lib/`.
+ * Returns null when not found, or when the file is unreadable or not valid JSON.
+ *
+ * Takes the OUTERMOST match, not the first one. This matters when a `dist/package.json`
+ * mirror is present (see above): it also carries `name: "actual-mcp-server"` and an
+ * `engines` block, and is structurally identical to the root apart from a possibly stale
+ * `version`. A first-match-wins walk from `dist/src/lib/` would therefore stop at the
+ * mirror, which is precisely the stale read this guard must avoid. The root always sits
+ * above the mirror, so the last match on the way up is the right one.
+ *
+ * The walk stops at a `node_modules` boundary so that an installed copy resolves to
+ * its own manifest and can never climb into a consuming project that happens to
+ * share the name.
+ */
+export function findRootPackageJson(startDir) {
+    let dir = startDir;
+    let outermost = null;
+    for (let level = 0; level <= MAX_WALK_LEVELS; level++) {
+        try {
+            const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+            if (manifest && manifest.name === PACKAGE_NAME && manifest.engines)
+                outermost = manifest;
+        }
+        catch {
+            // No package.json here, or it is unreadable or malformed. Keep walking.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        // `dir` is the installed package root; above it lies the consumer's tree.
+        if (outermost && parent.endsWith(`${sep}node_modules`))
+            break;
+        // Having found a manifest, stop as soon as the chain of package.json files breaks.
+        // Without this the walk climbs out of the repository, and an ancestor directory
+        // that happens to hold a package.json named actual-mcp-server (a checkout nested
+        // inside another checkout of itself) would override the real root.
+        if (outermost && !existsSync(join(parent, 'package.json')))
+            break;
+        dir = parent;
+    }
+    return outermost;
+}
+/**
+ * Read the floor and enforce it. Writes to stderr ONLY: stdout is reserved for stdio
+ * JSON-RPC framing, and a stray byte there corrupts the client's message stream.
+ *
+ * Uses `writeSync(2, ...)` rather than `process.stderr.write(...)`. Node's stderr is
+ * ASYNCHRONOUS when it is a pipe on POSIX, which is precisely how an MCP client
+ * captures it, so a `process.stderr.write()` immediately followed by `process.exit()`
+ * can be torn down before the buffer flushes. A guard whose message gets dropped
+ * leaves the user staring at the same silent failure it was written to explain.
+ *
+ * Exported for the tests. Called on import (below) so a bare
+ * `import './lib/node-version-guard.js'` is enough to arm it.
+ */
+export function enforceNodeVersion(runningVersion = process.version) {
+    const manifest = findRootPackageJson(dirname(fileURLToPath(import.meta.url)));
+    const range = manifest?.engines?.node;
+    if (!range)
+        return; // Fail open: cannot find the floor, so do not invent one.
+    const verdict = checkNodeVersion(runningVersion, range);
+    if (verdict.ok)
+        return;
+    writeSync(2, `\n${verdict.message}\n\n`);
+    process.exit(1);
+}
+enforceNodeVersion();

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

@@ -0,0 +1,105 @@
+/**
+ * #276: warn (once) when the Actual Budget SERVER version is outside the range this build's
+ * `@actual-app/api` is known to work with.
+ *
+ * Reporting already existed (actual_server_get_version, actual_server_info) but nothing
+ * enforced or even flagged compatibility. This adds an ADVISORY startup-ish warning: the
+ * real compatibility contract is the migration check `@actual-app/api` runs at
+ * downloadBudget, so this warning never fails startup and never blocks an operation.
+ *
+ * Design (mirrors src/lib/node-version-guard.ts):
+ *  - The comparator is PURE (no I/O, no logging), so its truth table is unit-testable.
+ *  - It FAILS OPEN: an unparseable version produces no warning. A spurious warning on a
+ *    healthy deployment would be worse than staying quiet.
+ *  - The firing is a per-PROCESS once-guard: the flag is flipped SYNCHRONOUSLY before any
+ *    await, so the check runs exactly once no matter how many ops or sessions occur, and it
+ *    reuses the connection the triggering op already established (no extra auth burst,
+ *    avoiding the #127/#134 class). There is NO boot-time probe: index.ts deliberately has
+ *    no startup connection, and a naive boot call would double-init then be torn down by
+ *    shutdownActualApi.
+ */
+import { SUPPORTED_ACTUAL_SERVER_RANGE } from './constants.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')
+        return null;
+    const m = /^v?(\d+)\.(\d+)(?:\.(\d+))?/.exec(v.trim());
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)];
+}
+/** a < b as semver triples. */
+function lessThan(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i];
+    }
+    return false;
+}
+/**
+ * Pure. Compare a running server version against the supported range.
+ * 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) {
+    const have = parseVersion(running);
+    const min = parseVersion(range.minVersion);
+    if (!have || !min)
+        return { ok: true };
+    if (lessThan(have, min)) {
+        return {
+            ok: false,
+            message: `Actual Budget server ${running} is older than the minimum this build supports ` +
+                `(>= ${range.minVersion}). Some tools may misbehave. Upgrade the Actual Budget server, ` +
+                'or pin an older actual-mcp-server. This is advisory: the server, not this warning, ' +
+                'enforces compatibility at budget download.',
+        };
+    }
+    if (have[0] > range.testedMaxMajor) {
+        return {
+            ok: false,
+            message: `Actual Budget server ${running} is newer than this build was tested against ` +
+                `(tested up to major ${range.testedMaxMajor}.x). It will very likely work, but if a ` +
+                'tool behaves oddly, update actual-mcp-server. Advisory only.',
+        };
+    }
+    return { ok: true };
+}
+// ---------------------------------------------------------------------------
+// Per-process once-guard.
+// ---------------------------------------------------------------------------
+let checked = false;
+/**
+ * Run the compatibility check at most once per process. Call this from inside a successful
+ * `withActualApi` operation (while the connection is live), passing a function that reads the
+ * server version through the SAME live connection (rawGetServerVersion, not the withActualApi
+ * wrapped getServerVersion, to avoid re-entering the lock).
+ *
+ * NEVER throws. A read failure is a single `debug`; being outside the range is a single
+ * `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) {
+    if (checked)
+        return;
+    checked = true; // set synchronously, before any await, so a concurrent op cannot double-fire
+    try {
+        const result = await readVersion();
+        if (!result || 'error' in result || typeof result.version !== 'string') {
+            log.debug('[server-version] could not read the Actual server version; skipping the compatibility check');
+            return;
+        }
+        const verdict = checkServerVersion(result.version);
+        if (!verdict.ok && verdict.message) {
+            log.warn(verdict.message);
+        }
+    }
+    catch {
+        // Advisory only: a failure to check must never surface as an error or affect the op.
+        log.debug('[server-version] compatibility check threw; ignored');
+    }
+}
+/** Test-only: reset the once-guard between cases. */
+export function _resetForTests() {
+    checked = false;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.8.4",
+  "version": "0.8.10",
   "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/generated_tools.smoke.test.js && node tests/unit/schema_validation.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/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/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_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/payees_delete.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/budget_acl_enforcement.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/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/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/ci_workflow_guards.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/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/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/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_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/payees_delete.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/budget_acl_enforcement.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/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/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/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",
     "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",
@@ -42,8 +42,11 @@
     "test:integration:sanity": "MCP_TEST_LEVEL=sanity node tests/manual/index.js",
     "test:integration:smoke": "MCP_TEST_LEVEL=smoke node tests/manual/index.js",
     "test:integration:normal": "MCP_TEST_LEVEL=normal node tests/manual/index.js",
+    "test:integration:normal:stdio": "MCP_TEST_TRANSPORT=stdio MCP_TEST_LEVEL=normal node tests/manual/index.js",
     "test:integration:extended": "MCP_TEST_LEVEL=extended node tests/manual/index.js",
+    "test:integration:extended:stdio": "MCP_TEST_TRANSPORT=stdio MCP_TEST_LEVEL=extended node tests/manual/index.js",
     "test:integration:full": "MCP_TEST_LEVEL=full node tests/manual/index.js",
+    "test:integration:full:stdio": "MCP_TEST_TRANSPORT=stdio MCP_TEST_LEVEL=full node tests/manual/index.js",
     "test:integration:cleanup": "MCP_TEST_LEVEL=cleanup node tests/manual/index.js",
     "deploy:full": "bash scripts/deploy-and-test.sh full",
     "deploy:smoke": "bash scripts/deploy-and-test.sh smoke",
@@ -57,6 +60,7 @@
     "release:patch": "npm run version:bump -- patch",
     "tool-count": "node scripts/tool-count.mjs",
     "config-drift": "npm run build && node scripts/config-drift.mjs",
+    "node-version-drift": "node scripts/node-version-drift.mjs",
     "knip": "knip"
   },
   "dependencies": {

package/dist/package.json

@@ -1,101 +0,0 @@
-{
-    "name": "actual-mcp-server",
-    "displayName": "Actual MCP Server",
-    "version": "0.8.4",
-    "engines": {
-        "node": ">=22.0.0",
-        "npm": ">=10.0.0"
-    },
-    "description": "MCP server with 71 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
-    "homepage": "https://github.com/agigante80/actual-mcp-server#readme",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/agigante80/actual-mcp-server"
-    },
-    "main": "dist/src/index.js",
-    "bin": {
-        "actual-mcp-server": "./bin/actual-mcp-server.js"
-    },
-    "files": [
-        "bin/",
-        "dist/",
-        "README.md",
-        "LICENSE"
-    ],
-    "type": "module",
-    "scripts": {
-        "build": "tsc",
-        "dev": "npm run build && node scripts/register-tsconfig-paths.js -- --debug",
-        "start": "node dist/src/index.js",
-        "verify-tools": "npm run build && node scripts/verify-tools.js",
-        "check:coverage": "node scripts/list-actual-api-methods.mjs",
-        "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-        "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/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/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/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_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/payees_delete.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/budget_acl_enforcement.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/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/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/ci_workflow_guards.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",
-        "test:e2e:docker:smoke": "./tests/e2e/run-docker-e2e.sh smoke",
-        "test:e2e:docker:full": "./tests/e2e/run-docker-e2e.sh full",
-        "test:all": "npm run test:adapter && npm run test:unit-js && npm run test:e2e:docker:smoke",
-        "test:mcp-client": "npm run build && MCP_ALLOW_UNAUTHENTICATED=true node scripts/register-tsconfig-paths.js -- --http --test-mcp-client",
-        "test:integration": "MCP_TEST_LEVEL=sanity node tests/manual/index.js",
-        "test:integration:sanity": "MCP_TEST_LEVEL=sanity node tests/manual/index.js",
-        "test:integration:smoke": "MCP_TEST_LEVEL=smoke node tests/manual/index.js",
-        "test:integration:normal": "MCP_TEST_LEVEL=normal node tests/manual/index.js",
-        "test:integration:extended": "MCP_TEST_LEVEL=extended node tests/manual/index.js",
-        "test:integration:full": "MCP_TEST_LEVEL=full node tests/manual/index.js",
-        "test:integration:cleanup": "MCP_TEST_LEVEL=cleanup node tests/manual/index.js",
-        "deploy:full": "bash scripts/deploy-and-test.sh full",
-        "deploy:smoke": "bash scripts/deploy-and-test.sh smoke",
-        "docs:sync": "node scripts/version-bump.js sync",
-        "version:current": "cat VERSION",
-        "version:dev": "node scripts/version-dev.js",
-        "version:bump": "node scripts/version-bump.js",
-        "version:check": "node scripts/version-check.js",
-        "release:major": "npm run version:bump -- major",
-        "release:minor": "npm run version:bump -- minor",
-        "release:patch": "npm run version:bump -- patch",
-        "tool-count": "node scripts/tool-count.mjs",
-        "config-drift": "npm run build && node scripts/config-drift.mjs",
-        "knip": "knip"
-    },
-    "dependencies": {
-        "@actual-app/api": "^26.7.0",
-        "@modelcontextprotocol/sdk": "^1.29.0",
-        "debug": "^4.4.3",
-        "dotenv": "^17.4.2",
-        "express": "^5.2.1",
-        "fuse.js": "^7.4.2",
-        "jose": "^6.2.3",
-        "mcp-auth": "^0.2.0",
-        "winston": "^3.18.3",
-        "winston-daily-rotate-file": "^5.0.0",
-        "zod": "^4.4.3"
-    },
-    "optionalDependencies": {
-        "prom-client": "*"
-    },
-    "devDependencies": {
-        "@playwright/test": "^1.60.0",
-        "@types/express": "^5.0.3",
-        "@types/node": "^26.1.0",
-        "knip": "^6.16.1",
-        "node-fetch": "^3.3.2",
-        "tsconfig-paths": "^4.2.0",
-        "typescript": "^6.0.3"
-    },
-    "license": "MIT",
-    "keywords": [
-        "mcp",
-        "model-context-protocol",
-        "actual-budget",
-        "actual-finance",
-        "librechat",
-        "claude-desktop",
-        "cursor",
-        "budget",
-        "finance",
-        "ai"
-    ],
-    "author": "agigante80"
-}

package/dist/src/tests/observability.smoke.test.js

@@ -1,18 +0,0 @@
-import { incrementToolCall, getMetricsText } from '../observability.js';
-export default async function runObservabilitySmoke() {
-    console.log('Running observability smoke test');
-    // Should not throw even if prom-client isn't installed
-    await incrementToolCall('test.tool');
-    const metrics = await getMetricsText();
-    if (metrics !== null && typeof metrics !== 'string') {
-        throw new Error('getMetricsText returned unexpected type');
-    }
-    console.log('✅ Observability smoke test passed');
-}
-const mainUrl = typeof process !== 'undefined' && process.argv && process.argv[1] ? `file://${process.argv[1]}` : '';
-if (import.meta.url === mainUrl) {
-    runObservabilitySmoke().catch(err => {
-        console.error('Observability smoke test failed:', err);
-        process.exit(1);
-    });
-}