actual-mcp-server 0.6.0 → 0.6.2

package/README.md

@@ -730,4 +730,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.0 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.2 | **Tool Count:** 63 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.0",
+    "version": "0.6.2",
     "engines": {
         "node": ">=20.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/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/transactions_uncategorized.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/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.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",
         "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",

package/dist/src/index.js

@@ -34,7 +34,14 @@ process.on('unhandledRejection', (reason, promise) => {
         reasonStr.includes('Rate limit exceeded') ||
         reasonStr.includes('Failed syncing account') ||
         reasonStr.includes('GoCardless') ||
-        reasonStr.includes('SimpleFIN')) {
+        reasonStr.includes('SimpleFIN') ||
+        // Actual API auth failures (network-failure, too-many-requests, invalid-password,
+        // etc.) can escape as unhandled rejections from session-init code paths that
+        // create a deferred Promise but only conditionally await it (see #132). The
+        // primary fix lives in httpServer.ts (.catch on initPromise); this allow-list
+        // entry is defence-in-depth so any future deferred-promise leak in the same
+        // family also fails non-fatally.
+        reasonStr.includes('Authentication failed:')) {
         console.error('⚠️  Known Actual API domain error escaped to unhandledRejection:');
         console.error('⚠️  ' + reasonStr);
         console.error('⚠️  Server will continue running. The caller received an error response.');

package/dist/src/lib/ActualConnectionPool.js

@@ -16,6 +16,7 @@ import config from '../config.js';
 import path from 'path';
 import os from 'os';
 import fs from 'fs';
+import { setApiInitialized } from './apiState.js';
 const DEFAULT_DATA_DIR = path.resolve(os.homedir() || '.', '.actual');
 class ActualConnectionPool {
     connections = new Map();
@@ -118,6 +119,9 @@ class ActualConnectionPool {
                 serverURL: SERVER_URL,
                 password: PASSWORD,
             });
+            // Mark the singleton as live so the adapter's pool-cooperation branch
+            // (withActualApi in actual-adapter.ts) can safely skip its per-op init.
+            setApiInitialized(true);
             logger.info(`[ConnectionPool] Downloading budget for session: ${sessionId}`);
             if (BUDGET_PASSWORD) {
                 const apiWithOptions = api;
@@ -149,6 +153,8 @@ class ActualConnectionPool {
             catch (cleanupErr) {
                 logger.debug(`[ConnectionPool] Error during cleanup (ignoring): ${cleanupErr}`);
             }
+            // Singleton is back to torn-down state regardless of cleanup outcome.
+            setApiInitialized(false);
             // Ensure this session is not in the connections map
             this.connections.delete(sessionId);
             throw err;
@@ -177,6 +183,7 @@ class ActualConnectionPool {
                 serverURL: SERVER_URL,
                 password: PASSWORD,
             });
+            setApiInitialized(true);
             if (BUDGET_PASSWORD) {
                 const apiWithOptions = api;
                 await apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD });
@@ -194,6 +201,7 @@ class ActualConnectionPool {
         }
         catch (err) {
             logger.error('[ConnectionPool] Failed to initialize shared connection:', err);
+            setApiInitialized(false);
             throw err;
         }
     }
@@ -213,12 +221,15 @@ class ActualConnectionPool {
             }
             conn.initialized = false;
             this.connections.delete(sessionId);
+            setApiInitialized(false);
             // NOTE: We do NOT delete the data directory because it's shared across all sessions
             // Deleting it would cause data loss for other active sessions
             logger.info(`[ConnectionPool] Connection shutdown complete for session: ${sessionId}`);
         }
         catch (err) {
             logger.error(`[ConnectionPool] Error shutting down connection for session ${sessionId}:`, err);
+            // Even on error, the singleton is in an unknown state — don't reuse.
+            setApiInitialized(false);
         }
     }
     /**
@@ -236,10 +247,12 @@ class ActualConnectionPool {
             }
             this.sharedConnection.initialized = false;
             this.sharedConnection = null;
+            setApiInitialized(false);
             logger.info('[ConnectionPool] Shared connection shutdown complete');
         }
         catch (err) {
             logger.error('[ConnectionPool] Error shutting down shared connection:', err);
+            setApiInitialized(false);
         }
     }
     /**
@@ -265,12 +278,21 @@ class ActualConnectionPool {
         this.sharedConnection = null;
     }
     /**
-     * Start periodic cleanup of idle connections
+     * Start periodic cleanup of idle connections.
+     *
+     * The interval is `unref()`d so it does not keep the Node event loop alive
+     * on its own. Without this, importing the pool from a one-shot script
+     * (e.g. unit test, `--test-actual-connection`) would prevent natural
+     * process exit. The interval still fires while the server runs because
+     * other handles (HTTP listener, stdio transport, etc.) keep the loop alive.
      */
     startCleanupTimer() {
         this.cleanupInterval = setInterval(() => {
             this.cleanupIdleConnections();
         }, this.CLEANUP_INTERVAL);
+        if (typeof this.cleanupInterval.unref === 'function') {
+            this.cleanupInterval.unref();
+        }
     }
     /**
      * Clean up idle connections that haven't been used recently

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

@@ -15,6 +15,9 @@ import retry from './retry.js';
 import logger from '../logger.js';
 import config from '../config.js';
 import { parseBudgetRegistry } from './budget-registry.js';
+import { requestContext } from './requestContext.js';
+import { connectionPool } from './ActualConnectionPool.js';
+import { isApiInitialized, setApiInitialized } from './apiState.js';
 /**
  * Budget registry — all budgets configured via ACTUAL_* and BUDGET_n_* env vars.
  * Built once at startup; used by every withActualApi call.
@@ -53,12 +56,118 @@ function withApiLock(fn) {
     _apiSessionLock = new Promise(resolve => { release = resolve; });
     return prevLock.then(() => fn()).finally(() => release());
 }
+// ----------------------------------------------------------------------------
+// Per-session pool cooperation — issue #134
+// ----------------------------------------------------------------------------
+// Pre-#134, every adapter call did api.init() + op + api.shutdown(). With many
+// tool calls in quick succession this produced a burst of upstream logins and
+// tripped Actual's auth rate-limiter (#127's root cause).
+//
+// Post-#134, when an MCP session has already initialised a per-session
+// connection via ActualConnectionPool (httpServer.ts wires this on session
+// open), withActualApi reuses that connection: no init, no shutdown. Writes
+// commit via api.sync() (the same pattern processWriteQueue already uses).
+// The pool tears down once at session close.
+//
+// Fallback: when there is no sessionId in AsyncLocalStorage (e.g. startup
+// health checks, internal calls outside any MCP session, stdio transport
+// callers that don't run inside requestContext.run), or when there is a
+// sessionId but the pool has no initialised connection for it, withActualApi
+// falls back to the legacy init+shutdown path so non-MCP callers keep working.
+let connectionReuseCount = 0;
+// The "is the @actual-app/api singleton currently live?" flag lives in
+// src/lib/apiState.ts so both this module and ActualConnectionPool can
+// update it without a circular import. The pool's hasConnection() returns
+// true based on its own per-session record; this flag is the second guard
+// — the singleton's actual state. Both must agree before reuse is safe.
+function _resolveSessionId() {
+    return requestContext.getStore()?.sessionId;
+}
+function _hasPooledConnection(sessionId) {
+    if (!sessionId)
+        return false;
+    if (!isApiInitialized())
+        return false; // singleton was shut down by some other path
+    return connectionPool.hasConnection(sessionId);
+}
 /**
- * Helper to init and shutdown Actual API around each operation
- * This is CRITICAL for data persistence - shutdown() must be called after every operation
- * Based on the pattern from https://github.com/s-stefanov/actual-mcp
+ * Decide whether an error from the wrapped operation suggests the api
+ * singleton is in a corrupted state and the pool's session connection should
+ * be released so the next call re-inits cleanly.
+ *
+ * **Drop on**: infrastructure-level errors that imply the api singleton, the
+ * upstream connection, or process-level resources are no longer usable.
+ *
+ * **Keep on**: user-input validation errors, domain errors ("not found",
+ * "does not exist"), Zod schema failures — these don't corrupt the api
+ * singleton, so dropping the pool would discard a perfectly good connection
+ * and force every retry through the legacy init+shutdown path (which is
+ * exactly the auth-burst pattern #134 is trying to eliminate).
+ *
+ * Default: keep. We err on the side of preserving pool reuse — if the api is
+ * actually corrupted but the error pattern doesn't match, the next call's op
+ * will surface the same root cause and we'll catch it then.
  */
-async function withActualApi(operation) {
+function _shouldDropPoolOnError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const msg = err.message || '';
+    return (msg.includes('Authentication failed') ||
+        msg.includes('ECONNRESET') ||
+        msg.includes('ECONNREFUSED') ||
+        msg.includes('socket hang up') ||
+        msg.includes('ETIMEDOUT') ||
+        msg.includes('out of memory') ||
+        msg.includes('ENOMEM'));
+}
+/**
+ * Helper to run an operation with the Actual API ready, deciding the lifecycle
+ * mode automatically:
+ *
+ *   - **Pooled mode** (preferred): when an MCP session is in the AsyncLocalStorage
+ *     context AND the connection pool has an initialised connection for it.
+ *     The operation runs against the existing connection. No init, no shutdown.
+ *     If the operation throws, the pool's connection for that session is
+ *     released so the next call gets a fresh init.
+ *
+ *   - **Legacy mode** (fallback): the original per-op init → op → shutdown
+ *     cycle. Used when there is no sessionId in context, or the pool has no
+ *     connection for the sessionId. Preserves the original tombstone /
+ *     persistence semantics for non-MCP callers.
+ *
+ * In either mode `withApiLock` serialises against concurrent callers because
+ * `@actual-app/api` is a process-wide singleton.
+ */
+export async function withActualApi(operation) {
+    const sessionId = _resolveSessionId();
+    if (_hasPooledConnection(sessionId)) {
+        // Pooled mode: skip init+shutdown.
+        return withApiLock(async () => {
+            try {
+                connectionReuseCount++;
+                logger.debug(`[ADAPTER] Reusing pool connection for session ${sessionId} (reuses=${connectionReuseCount})`);
+                return await operation();
+            }
+            catch (err) {
+                // Only drop the pool connection on errors that suggest the api
+                // singleton itself is in a bad state. User-input validation /
+                // domain errors leave the connection fine and dropping it would
+                // re-introduce the auth-burst pattern #134 is fixing.
+                if (_shouldDropPoolOnError(err)) {
+                    logger.warn(`[ADAPTER] Releasing pool connection for session ${sessionId} after infrastructure-level error`);
+                    try {
+                        await connectionPool.shutdownConnection(sessionId);
+                    }
+                    catch (_e) { /* swallow */ }
+                }
+                throw err;
+            }
+        });
+    }
+    if (sessionId) {
+        logger.warn(`[ADAPTER] Pool miss for session ${sessionId}; falling back to per-op init`);
+    }
+    // Legacy mode: init+shutdown around every operation.
     return withApiLock(async () => {
         try {
             await initActualApiForOperation();
@@ -69,20 +178,225 @@ async function withActualApi(operation) {
         }
     });
 }
+/**
+ * Variant of `withActualApi` for write operations. Identical to `withActualApi`
+ * except that, in pooled mode, it explicitly calls `api.sync()` after the
+ * operation succeeds so writes propagate to the upstream Actual server (and so
+ * tombstones for deletes propagate). In legacy mode the existing
+ * `shutdownActualApi()` already handles the persistence flush — no extra sync
+ * call needed there.
+ *
+ * Pattern source: `processWriteQueue` already uses `api.sync()` between writes
+ * within a batch (without shutdown), so this is the same proven approach
+ * generalised to single-write call sites.
+ */
+export async function withActualApiWrite(operation) {
+    const sessionId = _resolveSessionId();
+    if (_hasPooledConnection(sessionId)) {
+        return withApiLock(async () => {
+            try {
+                connectionReuseCount++;
+                logger.debug(`[ADAPTER] Reusing pool connection for write session ${sessionId} (reuses=${connectionReuseCount})`);
+                const result = await operation();
+                // Propagate the write to the server so other clients (and our next
+                // read) see it. Pre-#134 this happened implicitly via api.shutdown().
+                try {
+                    const apiAny = api;
+                    if (typeof apiAny.sync === 'function') {
+                        await apiAny.sync();
+                    }
+                }
+                catch (syncErr) {
+                    // Sync failure on a write IS infrastructure-level — drop the pool
+                    // connection so the next call re-inits, then surface the error.
+                    logger.error(`[ADAPTER] api.sync() failed after write in session ${sessionId}; releasing pool connection`);
+                    try {
+                        await connectionPool.shutdownConnection(sessionId);
+                    }
+                    catch (_e) { /* swallow */ }
+                    throw syncErr;
+                }
+                return result;
+            }
+            catch (err) {
+                // Same policy as withActualApi: only drop the pool on errors that
+                // suggest the api singleton is corrupted. User-input / domain errors
+                // leave the connection fine.
+                if (_shouldDropPoolOnError(err)) {
+                    logger.warn(`[ADAPTER] Releasing pool connection for write session ${sessionId} after infrastructure-level error`);
+                    try {
+                        await connectionPool.shutdownConnection(sessionId);
+                    }
+                    catch (_e) { /* swallow */ }
+                }
+                throw err;
+            }
+        });
+    }
+    if (sessionId) {
+        logger.warn(`[ADAPTER] Pool miss for session ${sessionId}; falling back to per-op init (write)`);
+    }
+    return withApiLock(async () => {
+        try {
+            await initActualApiForOperation();
+            return await operation();
+        }
+        finally {
+            await shutdownActualApi();
+        }
+    });
+}
+/**
+ * Test-only: reset the connection-reuse counter. NOT exported via the package
+ * public surface — only used by unit tests.
+ */
+export function _resetConnectionReuseCounterForTests() {
+    connectionReuseCount = 0;
+}
+/**
+ * Test-only: directly set the api-initialised flag. Lets unit tests exercise
+ * the pool-cooperation branch without driving a real api.init() against the
+ * upstream. NOT exported via the package public surface.
+ */
+export function _setApiInitializedForTests(value) {
+    setApiInitialized(value);
+}
+/**
+ * Test-only: short-circuit `initActualApiForOperation` and `shutdownActualApi`
+ * so the legacy fallback path can run without making network calls against a
+ * real upstream Actual server. Used by unit tests that want to verify the
+ * branch decision in `withActualApi` (pool vs legacy) without hanging on the
+ * real api.init network handshake.
+ *
+ * NOT exported via the package public surface.
+ */
+let _skipApiInitForTests = false;
+export function _setSkipApiInitForTests(value) {
+    _skipApiInitForTests = value;
+}
+// ----------------------------------------------------------------------------
+// Auth-rate-limit retry — issue #127
+// ----------------------------------------------------------------------------
+// The Actual Budget server returns "Authentication failed: too-many-requests"
+// when many MCP sessions log in in quick succession (e.g. a burst of E2E
+// tests). Without a retry-with-backoff at the adapter layer, the very first
+// burst spike fails through to the test runner and cascades into the bearer
+// MCP container's session-init crash (see #132).
+//
+// We retry only on errors known to be transient at the auth layer
+// (too-many-requests, network-failure). invalid-password and other terminal
+// errors propagate immediately so callers see the real cause.
+//
+// The retry budget is bounded so a rate-limited init cannot indefinitely
+// hold the API mutex (withApiLock) and starve other operations.
+// ----------------------------------------------------------------------------
+let authRetryCount = 0; // monotonic, observability
+let authRetryFailureCount = 0; // increments only when retry budget exhausted
+// The auth-rate-limit path uses a deliberately LARGER backoff than the generic
+// retry helper because Actual Budget's auth rate-limiter operates on a multi-
+// second sliding window, not a per-request burst. The generic 200ms base
+// would exhaust within 1.4s — well inside the upstream's window.
+//
+// Empirically (2026-05-06, #127):
+//   - 200ms base = 1.4s total: too short, every retry hits the throttle.
+//   - 2000ms base = 14s total: insufficient under heavy auth pressure
+//     (e.g. 10 rapid logins before a tool call still throttle 14s+).
+//   - 5000ms base = 5s + 10s + 10s = 25s total (each step capped by
+//     MAX_RETRY_DELAY_MS): clears the rate-limit window in light-pressure
+//     scenarios (3 rapid logins) without holding the API mutex unreasonably
+//     long.
+//
+// Beyond 25s, blocking the API mutex starts to harm tail latency for
+// unrelated tool calls. The proper long-term fix for sustained-pressure
+// scenarios is session reuse (avoid init+shutdown per op) — out of scope for
+// this ticket; tracked as a follow-up.
+const AUTH_RETRY_BASE_BACKOFF_MS = 5000;
+export function isRetryableAuthError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return (err.message.includes('Authentication failed: too-many-requests') ||
+        err.message.includes('Authentication failed: network-failure'));
+}
+/**
+ * Wrap an operation with retry-on-rate-limit. Used to wrap api.init() so
+ * transient too-many-requests errors are absorbed transparently. The retry
+ * budget is capped at DEFAULT_RETRY_ATTEMPTS (3) attempts and total wallclock
+ * is bounded by MAX_RETRY_DELAY_MS via exponential backoff.
+ *
+ * Test-friendly: opts.maxRetries / opts.baseBackoffMs override the defaults
+ * so unit tests can run fast.
+ *
+ * Log hygiene: this function never logs the upstream URL, password, or any
+ * config-derived value — only the error class and the Actual error code
+ * (extracted from the message) plus the attempt counter.
+ */
+export async function withAuthRetry(operation, opts) {
+    const maxRetries = opts?.maxRetries ?? DEFAULT_RETRY_ATTEMPTS;
+    const baseBackoffMs = opts?.baseBackoffMs ?? AUTH_RETRY_BASE_BACKOFF_MS;
+    let attempt = 0;
+    while (true) {
+        try {
+            return await operation();
+        }
+        catch (err) {
+            if (!isRetryableAuthError(err))
+                throw err;
+            attempt++;
+            if (attempt > maxRetries) {
+                // Budget exhausted: log + bump failure counter, but do NOT bump
+                // authRetryCount — that counter measures successful retry-and-sleep
+                // cycles, not failed final attempts.
+                authRetryFailureCount++;
+                const code = (err instanceof Error ? err.message.match(/Authentication failed: (\S+)/)?.[1] : null) || 'unknown';
+                logger.error(`[ADAPTER] Auth retry exhausted after ${maxRetries} retries (last code: ${code})`);
+                throw err;
+            }
+            // We're going to retry — count it and sleep with exponential backoff.
+            authRetryCount++;
+            const delay = Math.min(baseBackoffMs * Math.pow(2, attempt - 1), MAX_RETRY_DELAY_MS);
+            const code = (err instanceof Error ? err.message.match(/Authentication failed: (\S+)/)?.[1] : null) || 'unknown';
+            logger.debug(`[ADAPTER] Auth retry ${attempt}/${maxRetries} (code: ${code}) after ${delay}ms`);
+            await new Promise(r => setTimeout(r, delay));
+        }
+    }
+}
+/**
+ * Test-only: reset the auth retry observability counters. NOT exported via
+ * the package public surface — only used by unit tests.
+ */
+export function _resetAuthRetryCountersForTests() {
+    authRetryCount = 0;
+    authRetryFailureCount = 0;
+}
 /**
  * Initialize Actual API - based on s-stefanov/actual-mcp pattern
  * This calls api.init() and api.downloadBudget() for each operation
  */
 async function initActualApiForOperation() {
+    if (_skipApiInitForTests) {
+        setApiInitialized(true);
+        return;
+    }
+    // If the api singleton is already live (e.g. the connection pool initialised
+    // it at MCP session open), don't redundantly call api.init() again — that
+    // would trigger an extra upstream login and reintroduce the auth-burst
+    // pattern #134 is fixing. The pool keeps the singleton alive across writes;
+    // we just join in.
+    if (isApiInitialized()) {
+        logger.debug('[ADAPTER] api already initialised; skipping redundant init');
+        return;
+    }
     try {
         const budget = getActiveBudgetConfig();
         const DATA_DIR = config.MCP_BRIDGE_DATA_DIR;
         logger.debug(`[ADAPTER] Initializing Actual API for operation (budget: "${budget.name}", server: ${budget.serverUrl})`);
-        await api.init({
+        // Wrap api.init in auth-rate-limit retry so a transient too-many-requests
+        // doesn't surface to the caller (and doesn't trigger #132's crash path).
+        await withAuthRetry(() => api.init({
             dataDir: DATA_DIR,
             serverURL: budget.serverUrl,
             password: budget.password || '',
-        });
+        }));
         logger.debug('[ADAPTER] Downloading budget');
         if (budget.encryptionPassword) {
             const apiWithOptions = api;
@@ -91,6 +405,7 @@ async function initActualApiForOperation() {
         else {
             await api.downloadBudget(budget.syncId);
         }
+        setApiInitialized(true);
         logger.debug('[ADAPTER] Actual API initialized for operation');
     }
     catch (err) {
@@ -99,6 +414,38 @@ async function initActualApiForOperation() {
     }
 }
 async function shutdownActualApi() {
+    if (_skipApiInitForTests) {
+        setApiInitialized(false);
+        return;
+    }
+    // If the connection pool currently has any active per-session connections,
+    // those sessions own the api singleton's lifecycle — tearing it down here
+    // would invalidate every active session's pool entry and force the next
+    // tool call back through legacy init+shutdown (the very pattern #134 is
+    // eliminating). Instead, just sync (the persistence guarantee that
+    // shutdown was previously providing implicitly) and leave the singleton
+    // alive for the pool to manage.
+    try {
+        const stats = connectionPool.getStats();
+        if (stats.activeSessions > 0) {
+            try {
+                const apiAny = api;
+                if (typeof apiAny.sync === 'function') {
+                    await apiAny.sync();
+                    logger.debug('[ADAPTER] api.sync() instead of shutdown (pool has active sessions)');
+                }
+            }
+            catch (syncErr) {
+                logger.error('[ADAPTER] sync-without-shutdown failed:', syncErr);
+                // Don't propagate — shutdown was best-effort anyway.
+            }
+            return;
+        }
+    }
+    catch (statsErr) {
+        // Pool not available (e.g. early startup) — fall through to legacy shutdown.
+        logger.debug('[ADAPTER] could not read pool stats; defaulting to full shutdown:', statsErr);
+    }
     try {
         const maybeApi = api;
         if (typeof maybeApi.shutdown === 'function') {
@@ -109,8 +456,14 @@ async function shutdownActualApi() {
     catch (err) {
         logger.error('[ADAPTER] Error during Actual API shutdown:', err);
     }
+    finally {
+        // Always reset the flag — even if shutdown threw, the api singleton is
+        // no longer in a known-good state, so pool reuse must NOT be attempted
+        // until something explicitly re-inits.
+        setApiInitialized(false);
+    }
 }
-import { BANK_SYNC_SETTLE_MS, DEFAULT_CONCURRENCY_LIMIT, WRITE_SESSION_DELAY_MS } from './constants.js';
+import { BANK_SYNC_SETTLE_MS, DEFAULT_CONCURRENCY_LIMIT, DEFAULT_RETRY_ATTEMPTS, MAX_RETRY_DELAY_MS, WRITE_SESSION_DELAY_MS } from './constants.js';
 /**
  * Very small concurrency limiter for adapter calls. This prevents bursts from
  * overloading the actual server. It's intentionally tiny and in-memory; replace
@@ -247,7 +600,24 @@ function withConcurrency(fn) {
 }
 // Expose some helpers for testing concurrency
 export function getConcurrencyState() {
-    return { running, queueLength: queue.length, maxConcurrency: MAX_CONCURRENCY };
+    return {
+        running,
+        queueLength: queue.length,
+        maxConcurrency: MAX_CONCURRENCY,
+        // Auth-retry observability — issue #127. authRetries is monotonic over the
+        // process lifetime; authRetryFailures only increments when retry budget
+        // exhausted. A jump in authRetries without a matching jump in
+        // authRetryFailures means the retry-with-backoff is absorbing rate-limit
+        // pressure (healthy). Both jumping = upstream genuinely overloaded.
+        authRetries: authRetryCount,
+        authRetryFailures: authRetryFailureCount,
+        // Pool-cooperation observability — issue #134. connectionReuses increments
+        // every time withActualApi reused an existing per-session pool connection
+        // instead of running its own init+shutdown cycle. Pre-#134 this was
+        // structurally always 0; post-#134 it should grow at least linearly with
+        // tool-call volume on healthy MCP sessions.
+        connectionReuses: connectionReuseCount,
+    };
 }
 /**
  * Sync local changes to the Actual Budget server.
@@ -385,7 +755,8 @@ export async function importTransactions(accountId, txs) {
 }
 export async function createTransfer(params) {
     observability.incrementToolCall('actual.transfers.create').catch(() => { });
-    return queueWriteOperation(async () => {
+    // ── Phase 1: validate + write ─────────────────────────────────────────────
+    const writeResult = await queueWriteOperation(async () => {
         if (params.from_account === params.to_account) {
             return { success: false, error: 'from_account and to_account must be different accounts.' };
         }
@@ -411,16 +782,30 @@ export async function createTransfer(params) {
             payee: transferPayee.id,
             ...(params.notes !== undefined && { notes: params.notes }),
         };
-        const result = await withConcurrency(() => retry(() => rawAddTransactions(params.from_account, [sourceTx], { runTransfers: true }), { retries: 2, backoffMs: 200 }));
-        let from_id = null;
-        if (Array.isArray(result) && result.length > 0 && typeof result[0] === 'string' && result[0] !== 'ok') {
-            from_id = result[0];
-        }
-        else if (result && typeof result === 'object' && 'id' in result) {
-            from_id = result.id;
-        }
-        return { success: true, from_id, to_id: null };
+        await withConcurrency(() => retry(() => rawAddTransactions(params.from_account, [sourceTx], { runTransfers: true }), { retries: 2, backoffMs: 200 }));
+        return { success: true };
     });
+    if (!writeResult.success)
+        return writeResult;
+    // ── Phase 2: read-back in a fresh session (after write has synced) ────────
+    // A new withActualApi session downloads the budget from the server, which
+    // reflects the synced write, guaranteeing transfer_id is fully committed.
+    try {
+        return await withActualApi(async () => {
+            const txns = await withConcurrency(() => retry(() => rawGetTransactions(params.from_account, params.date, params.date), { retries: 2, backoffMs: 200 }));
+            // Find the most recently created transfer matching our amount.
+            // imported_id is not synced via Actual Budget CRDT, so we sort by
+            // sort_order descending and take the newest matching transfer instead.
+            const tx = (txns ?? [])
+                .filter((t) => t.amount === -Math.abs(params.amount) && t.transfer_id != null)
+                .sort((a, b) => (b.sort_order ?? 0) - (a.sort_order ?? 0))[0];
+            return { success: true, from_id: tx?.id ?? null, to_id: tx?.transfer_id ?? null };
+        });
+    }
+    catch {
+        // Transfer was created; IDs just can't be retrieved right now.
+        return { success: true, from_id: null, to_id: null };
+    }
 }
 export async function getTransactions(accountId, startDate, endDate) {
     return withActualApi(async () => {

package/dist/src/lib/apiState.js

@@ -0,0 +1,26 @@
+/**
+ * Shared module-level state for the @actual-app/api singleton's "live" flag.
+ *
+ * @actual-app/api is a process-wide singleton that gets `init()`d and
+ * `shutdown()`d by multiple paths in this codebase: the connection pool's
+ * per-session init (`ActualConnectionPool.getConnection`), the adapter's
+ * legacy per-op cycle (`initActualApiForOperation` / `shutdownActualApi`),
+ * and the write queue (`processWriteQueue`).
+ *
+ * The adapter's pool-cooperation logic (`withActualApi` in actual-adapter.ts)
+ * needs to know whether the singleton is currently live so it can safely
+ * skip the per-op init when the pool already has a connection. This module
+ * exposes a tiny shared flag that all init/shutdown paths update, so any
+ * caller can probe the truth without having to know about every path.
+ *
+ * Lives in src/lib/ rather than inside actual-adapter.ts so the connection
+ * pool can update it without creating a circular import (the pool is itself
+ * imported by the adapter).
+ */
+let _apiInitialized = false;
+export function isApiInitialized() {
+    return _apiInitialized;
+}
+export function setApiInitialized(value) {
+    _apiInitialized = value;
+}

package/dist/src/lib/requestContext.js

@@ -0,0 +1,17 @@
+import { AsyncLocalStorage } from 'async_hooks';
+/**
+ * Per-request AsyncLocalStorage. Carries the active MCP sessionId across
+ * async boundaries so adapter / tool code can identify which session is
+ * making the call without threading an argument through every layer.
+ *
+ * Producer: src/server/httpServer.ts wraps each `transport.handleRequest()`
+ * call in `requestContext.run({ sessionId }, …)`.
+ *
+ * Consumer: src/lib/actual-adapter.ts uses `requestContext.getStore()?.sessionId`
+ * to decide whether the session has an initialised pool connection it can
+ * reuse (eliminating the per-op login burst — see #134).
+ *
+ * Lives in src/lib/ rather than src/server/ to avoid the circular import that
+ * would otherwise exist between httpServer.ts and actual-adapter.ts.
+ */
+export const requestContext = new AsyncLocalStorage();

package/dist/src/server/httpServer.js

@@ -1,5 +1,3 @@
-// src/server/httpServer.ts
-import { AsyncLocalStorage } from 'async_hooks';
 import express from 'express';
 import { randomUUID } from 'crypto';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -16,8 +14,12 @@ import { createMcpAuth } from '../auth/setup.js';
 import { budgetAclMiddleware } from '../auth/budget-acl.js';
 import * as https from 'node:https';
 import * as fs from 'node:fs';
-// AsyncLocalStorage for request context (sessionId accessible to tools)
-export const requestContext = new AsyncLocalStorage();
+// AsyncLocalStorage for request context — moved to src/lib/requestContext.ts
+// so adapter code can import it without a circular dependency on httpServer.
+// Re-exported here for backward compatibility with any callers that imported
+// `requestContext` from this module.
+import { requestContext } from '../lib/requestContext.js';
+export { requestContext };
 export async function startHttpServer(mcp, port, httpPath, capabilities, // was passed by index.ts
 implementedTools, // was passed by index.ts
 serverDescription, // was passed by index.ts
@@ -313,6 +315,13 @@ bindHost = 'localhost', advertisedUrl) {
                     resolveInit = resolve;
                     rejectInit = reject;
                 });
+                // Always-on safety net: if no concurrent code path is awaiting initPromise
+                // when rejectInit fires (e.g. session init fails before any tools/call
+                // arrives), the rejection would otherwise hit process.on('unhandledRejection')
+                // and exit the server. The original error is already logged inside the
+                // onsessioninitialized catch block below — we deliberately do NOT re-log here
+                // to avoid duplicate noise and any risk of leaking credentials.
+                initPromise.catch(() => { });
                 const transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: () => randomUUID(),
                     enableJsonResponse: true,

package/dist/src/tools/transactions_uncategorized.js

@@ -13,7 +13,7 @@ import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import { CommonSchemas } from '../lib/schemas/common.js';
 const InputSchema = z.object({
-    startDate: CommonSchemas.date.optional().describe('Start date in YYYY-MM-DD format (default: first day of current month)'),
+    startDate: CommonSchemas.date.optional().describe('Start date in YYYY-MM-DD format (default: all-time)'),
     endDate: CommonSchemas.date.optional().describe('End date in YYYY-MM-DD format (default: today)'),
     accountId: CommonSchemas.accountId.optional().describe('Filter to a specific account ID (optional)'),
     includeTransactions: z.boolean().optional().default(false).describe('When true, include paginated transaction rows in the response (default: false)'),
@@ -37,14 +37,14 @@ const tool = {
         'Use limit (default 50, max 1000) and offset for pagination.',
         'Excludes: transfers, split-transaction parents, opening balance entries, off-budget accounts, and closed accounts.',
         'When accountId is provided, all fields are scoped to that account.',
+        'Default date range is all-time (2000-01-01 to today); pass startDate/endDate to narrow.',
         'Note: the legacy summary.totalAmount field has been removed — totalAmount is now at the top level.',
     ].join(' '),
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
         const today = new Date();
-        const firstDayOfMonth = new Date(today.getFullYear(), today.getMonth(), 1);
-        const startDate = input.startDate || firstDayOfMonth.toISOString().split('T')[0];
+        const startDate = input.startDate || '2000-01-01';
         const endDate = input.endDate || today.toISOString().split('T')[0];
         const accountId = input.accountId ?? undefined;
         // Full table scan when no accountId — reliably returns newly written transactions

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "engines": {
     "node": ">=20.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/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/transactions_uncategorized.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/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.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",
     "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",