actual-mcp-server 0.16.12 → 0.16.15

package/README.md

@@ -43,7 +43,7 @@ Most Actual Budget MCP implementations are simple stdio bridges designed for sin
 - **6 exclusive ActualQL-powered tools.** Search and summarise transactions by month, amount, category, or payee using Actual Budget's native query engine. Aggregated results, no raw data dumped into the AI context window.
 - **Multi-budget switching at runtime.** Configure multiple budget files and let the AI switch between them mid-conversation with `actual_budgets_switch`. Works on both transports: HTTP keys the active budget to the MCP session, and stdio (Claude Desktop, Claude Code, Cursor) gets a synthetic per-process session so a switch is scoped to that process rather than shared globally (#348).
 - **Multi-user ready with OIDC.** Secure every session with JWKS-validated JWTs and per-user budget ACLs. No shared tokens required.
-- **Production-grade reliability.** Connection pooling (up to 15 concurrent sessions), automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
+- **Production-grade reliability on both transports.** HTTP connection pooling (up to 15 concurrent sessions), and a long-lived stdio process that logs in ONCE and reuses that connection for every tool call instead of re-authenticating per call, so Claude Desktop and Claude Code stay fast and a burst of calls no longer risks a per-call login storm against the upstream limiter. Automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
 
 > **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 74 tools tested end-to-end. Any MCP-compatible client should work.
 
@@ -775,7 +775,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.16.12 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.16.15 | **Tool Count:** 74 (verified LibreChat-compatible)
 
 ## Sponsor
 

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

@@ -5,6 +5,7 @@
 // getAuthRetryCounts() for getConcurrencyState, and wraps api.init() with
 // withAuthRetry. Linked issue: #127.
 import { DEFAULT_RETRY_ATTEMPTS, MAX_RETRY_DELAY_MS } from '../constants.js';
+import { isRateLimitError } from '../retry.js';
 import logger from '../../logger.js';
 let authRetryCount = 0; // monotonic, observability
 let authRetryFailureCount = 0; // increments only when retry budget exhausted
@@ -25,7 +26,13 @@ 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') ||
+    // #422: reconcile with the pool-drop rate-limit matcher by UNION, never a
+    // substitution. `isRateLimitError` matches BOTH the hyphenated `too-many-requests`
+    // code AND the spaced express default `Too many requests, ...` the current server
+    // returns, so this now retries a login throttle in either form (the spaced form
+    // was previously missed). The `network-failure` branch is preserved verbatim so
+    // withAuthRetry's login self-heal is not narrowed.
+    return (isRateLimitError(err) ||
         err.message.includes('Authentication failed: network-failure'));
 }
 /**

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

@@ -10,7 +10,7 @@ const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, import
  } = api;
 import { EventEmitter } from 'events';
 import observability from '../observability.js';
-import { retry, isRetryableError } from './retry.js';
+import { retry, isRetryableError, isRateLimitError } from './retry.js';
 import { withOpTimeout } from './opTimeout.js';
 import { NotFoundRefusal, OutOfRangeRefusal, constraintErrorMsg } from './errors.js';
 import { findMatchingRule } from './rule-matching.js';
@@ -248,6 +248,35 @@ function _hasPooledConnection(sessionId) {
         return false; // singleton was shut down by some other path
     return connectionPool.hasConnection(sessionId);
 }
+// #419: is this whole process a stdio server? The --stdio flag sets MCP_STDIO_MODE
+// in src/index.ts BEFORE any import, it is the RAW_ENV_ALLOWLIST-registered process
+// marker (config-registry.ts), and server_info.ts reads exactly this to report the
+// transport. A stdio process is one long-lived single-user session for its whole
+// lifetime, so keeping the api singleton alive between ops is a PROCESS fact. It is
+// deliberately NOT read from the ambient request context: the write drain calls
+// shutdownActualApi OUTSIDE the per-op requestContext.run (see processWriteQueue),
+// in a context that belongs to an unrelated enqueuer, which is the #390 trap.
+function _isStdioProcess() {
+    return process.env.MCP_STDIO_MODE === 'true';
+}
+/**
+ * #419: decide whether `shutdownActualApi` keeps the api singleton alive (sync-only)
+ * or tears it fully down (which resets `isApiInitialized`). Kept alive when another
+ * HTTP session still owns the singleton, OR when this is a stdio process and no
+ * infrastructure-level error forced a teardown.
+ *
+ * `forceFullShutdown` defeats ONLY the stdio process keep-alive, never the
+ * active-HTTP-session keep-alive: with active sessions other sessions own the
+ * singleton, so tearing it down would break them, and a stdio process always has
+ * `activeSessions === 0`, so forcing there tears down exactly its own singleton.
+ *
+ * Exported for unit tests: the branch is observable behaviour, not an internal.
+ */
+export function _shouldKeepSingletonAlive(activeSessions, forceFullShutdown) {
+    if (activeSessions > 0)
+        return true;
+    return _isStdioProcess() && !forceFullShutdown;
+}
 /**
  * Decide whether an error from the wrapped operation suggests the api
  * singleton is in a corrupted state and the pool's session connection should
@@ -266,13 +295,16 @@ function _hasPooledConnection(sessionId) {
  * 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.
  */
-// Whether an error is infrastructure-level (drop the pooled connection so the
-// next call re-inits cleanly). This is the SAME class as "retryable", so it
-// delegates to isRetryableError (#177): the pool-drop decision and the retry
-// decision share one pattern list and cannot drift. A consistency test pins
-// this equivalence.
+// Whether an error is infrastructure-level (drop the pooled connection / tear
+// down the stdio singleton so the next call re-inits cleanly). This DERIVES from
+// isRetryableError (#177: one authored pattern source, pool-drop and retry cannot
+// drift), with ONE deliberate subtraction (#422): a rate-limit is transient but
+// does NOT corrupt the connection, so it must not drop it. Re-logging-in during a
+// throttle adds a fresh login to an already-full window, cascading into a relogin
+// storm (observed over stdio in #383). Retry still backs a rate-limit off; drop
+// does not. A consistency test pins this exact relationship.
 function _shouldDropPoolOnError(err) {
-    return isRetryableError(err);
+    return isRetryableError(err) && !isRateLimitError(err);
 }
 /**
  * Enforce per-request budget ACL before any pool branching or lock acquisition.
@@ -397,17 +429,32 @@ export async function withActualApi(rawOperation) {
             }
         }, { budget: _affinityBudget() });
     }
-    if (sessionId) {
+    // #419: only warn when a real re-init will actually happen. In a stdio process
+    // the singleton is kept alive between ops, so after the first login this is warm
+    // reuse, not a costly miss; gating on !isApiInitialized() makes the line appear
+    // at most once per process rather than per call, and keeps it honest for HTTP.
+    if (sessionId && !isApiInitialized()) {
         logger.warn(`[ADAPTER] Pool miss for session ${sessionId}; falling back to per-op init`);
     }
     // Legacy mode: init+shutdown around every operation.
     return withApiLock(async () => {
+        let forceFullShutdown = false;
         try {
             await initActualApiForOperation();
             return await withOpTimeout(operation);
         }
+        catch (err) {
+            // #419: the stdio keep-alive branch leaves the singleton live; on an
+            // infrastructure-level error it may be corrupt, so force a full teardown
+            // (which resets isApiInitialized) so the next op re-inits fresh. Mirrors
+            // the pool branch's _shouldDropPoolOnError drop above. Domain/validation
+            // errors leave the singleton intact (no per-op login reintroduced).
+            if (_shouldDropPoolOnError(err))
+                forceFullShutdown = true;
+            throw err;
+        }
         finally {
-            await shutdownActualApi();
+            await shutdownActualApi({ forceFullShutdown });
         }
     }, { budget: _affinityBudget() });
 }
@@ -473,16 +520,25 @@ export async function withActualApiWrite(operation) {
             }
         }, { budget: _affinityBudget() });
     }
-    if (sessionId) {
+    // #419: see the read-path note above; warn only when a real re-init happens.
+    if (sessionId && !isApiInitialized()) {
         logger.warn(`[ADAPTER] Pool miss for session ${sessionId}; falling back to per-op init (write)`);
     }
     return withApiLock(async () => {
+        let forceFullShutdown = false;
         try {
             await initActualApiForOperation();
             return await withOpTimeout(operation);
         }
+        catch (err) {
+            // #419: force a full teardown on an infrastructure-level error so the next
+            // stdio op re-inits fresh (see the read-path catch for the rationale).
+            if (_shouldDropPoolOnError(err))
+                forceFullShutdown = true;
+            throw err;
+        }
         finally {
-            await shutdownActualApi();
+            await shutdownActualApi({ forceFullShutdown });
         }
     }, { budget: _affinityBudget() });
 }
@@ -604,39 +660,56 @@ async function initActualApiForOperation() {
         throw err;
     }
 }
-async function shutdownActualApi() {
+async function shutdownActualApi(opts) {
+    const forceFullShutdown = opts?.forceFullShutdown === true;
     if (_skipApiInitForTests) {
-        setApiInitialized(false);
+        // Honour the SAME keep-alive decision the real path makes, so unit tests can
+        // observe the stdio keep-alive and self-heal behaviour without driving a live
+        // api.init(). In every non-stdio context _shouldKeepSingletonAlive is false
+        // (activeSessions === 0, not stdio), so this stays the pre-#419 always-reset
+        // and existing tests are unaffected.
+        let activeSessions = 0;
+        try {
+            activeSessions = connectionPool.getStats().activeSessions;
+        }
+        catch { /* pool not up */ }
+        if (!_shouldKeepSingletonAlive(activeSessions, forceFullShutdown)) {
+            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.
+    // Keep the api singleton alive (sync only) when another session still owns it
+    // OR when this is a stdio process (#419): tearing it down would invalidate an
+    // active session's pool entry, or, for stdio, force a fresh upstream LOGIN on
+    // the next tool call (the #127 burst, per stdio call). Instead sync (the
+    // persistence guarantee shutdown provided implicitly) and leave it alive.
+    //
+    // #419 self-heal: forceFullShutdown, set by a legacy branch on an
+    // infrastructure-level error, defeats ONLY the stdio keep-alive so the next op
+    // re-inits fresh against a clean singleton, exactly as the always-full-shutdown
+    // legacy path used to give for free.
+    let activeSessions = 0;
     try {
-        const stats = connectionPool.getStats();
-        if (stats.activeSessions > 0) {
-            try {
-                const apiAny = api;
-                if (typeof apiAny.sync === 'function') {
-                    await withOpTimeout(() => apiAny.sync(), '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;
-        }
+        activeSessions = connectionPool.getStats().activeSessions;
     }
     catch (statsErr) {
-        // Pool not available (e.g. early startup) — fall through to legacy shutdown.
+        // 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);
     }
+    if (_shouldKeepSingletonAlive(activeSessions, forceFullShutdown)) {
+        try {
+            const apiAny = api;
+            if (typeof apiAny.sync === 'function') {
+                await withOpTimeout(() => apiAny.sync(), 'sync');
+                logger.debug('[ADAPTER] api.sync() instead of shutdown (singleton kept alive)');
+            }
+        }
+        catch (syncErr) {
+            logger.error('[ADAPTER] sync-without-shutdown failed:', syncErr);
+            // Don't propagate: shutdown was best-effort anyway.
+        }
+        return;
+    }
     try {
         const maybeApi = api;
         if (typeof maybeApi.shutdown === 'function') {
@@ -965,6 +1038,11 @@ async function processWriteQueue() {
                     // Each op keeps its own withOpTimeout (#270) and still settles individually, so one
                     // stalled or rejected operation cannot hold the api mutex or fail its siblings.
                     let stuckLoadError = null;
+                    // #419: the drain inits once and shuts down once per batch. If any op hits
+                    // an infrastructure-level error, force the batch-end shutdownActualApi to
+                    // fully tear the singleton down (self-heal) so the next stdio batch re-inits
+                    // fresh, instead of the stdio keep-alive leaving a corrupt singleton live.
+                    let drainForceFullShutdown = false;
                     // Counted so the event is logged ONCE with a total. Without this the fail-fast path sits
                     // outside the per-operation try, so it never reaches the '[WRITE QUEUE] Operation failed'
                     // line and N operations fail with no log entry anywhere. Given this whole ticket family
@@ -1064,6 +1142,10 @@ async function processWriteQueue() {
                         }
                         catch (error) {
                             logger.error('[WRITE QUEUE] Operation failed:', error);
+                            // #419: remember an infrastructure-level failure so the batch-end
+                            // shutdown self-heals (see drainForceFullShutdown above).
+                            if (_shouldDropPoolOnError(error))
+                                drainForceFullShutdown = true;
                             reject(error);
                         }
                         finally {
@@ -1122,6 +1204,11 @@ async function processWriteQueue() {
                     }
                     catch (syncError) {
                         logger.error('[WRITE QUEUE] Sync failed:', syncError);
+                        // #419: a legacy-branch infrastructure-level sync failure self-heals
+                        // too, so the next stdio batch re-inits fresh rather than reusing a
+                        // singleton whose sync just failed.
+                        if (!usePoolBranch && _shouldDropPoolOnError(syncError))
+                            drainForceFullShutdown = true;
                         // Pool branch: drop the connection on infrastructure-level sync
                         // failure so the next write re-initialises cleanly. Mirrors
                         // withActualApiWrite's policy.
@@ -1143,7 +1230,9 @@ async function processWriteQueue() {
                         // Legacy branch only: actually shut the singleton down.
                         // shutdownActualApi() itself short-circuits to sync-only if another
                         // path has active pool sessions, so this is safe under contention.
-                        await shutdownActualApi();
+                        // #419: forceFullShutdown defeats the stdio keep-alive when the batch
+                        // saw an infrastructure-level error, so the next batch re-inits fresh.
+                        await shutdownActualApi({ forceFullShutdown: drainForceFullShutdown });
                     }
                     logger.debug(`[WRITE QUEUE] Batch completed successfully`);
                 }
@@ -1173,7 +1262,9 @@ async function processWriteQueue() {
                         }
                     }
                     else {
-                        await shutdownActualApi();
+                        // #419: a fatal batch error is infrastructure-level by definition, so
+                        // force a full teardown (stdio self-heal) regardless of the per-op flag.
+                        await shutdownActualApi({ forceFullShutdown: true });
                     }
                 }
             }, { budget: batchBudget });

package/dist/src/lib/retry.js

@@ -5,9 +5,18 @@ const log = ModuleLoggers.RETRY;
  * Error-message fragments that mark a TRANSIENT / infrastructure-level failure:
  * the kind a retry can actually recover from, and the kind worth dropping a
  * pooled connection over. Single source of truth for #177: the adapter's
- * `_shouldDropPoolOnError` delegates to `isRetryableError`, so the retry
+ * `_shouldDropPoolOnError` derives from `isRetryableError`, so the retry
  * decision and the pool-drop decision cannot drift apart.
  *
+ * #422 is the ONE deliberate divergence: a rate-limit ("too-many-requests") is
+ * transient and worth backing off, but it does NOT corrupt the connection, so
+ * `_shouldDropPoolOnError` subtracts it (`isRetryableError && !isRateLimitError`).
+ * Re-initing during a throttle adds a fresh login to an already-full window,
+ * which is itself rejected, cascading into a relogin storm (observed over stdio
+ * in #383). Retry stays unified with this list; only drop carves the one case
+ * out. That is #177's spirit (one authored pattern source) preserved, not a
+ * second divergent list.
+ *
  * Anything NOT matching here (domain/validation errors such as "is required",
  * "not found", "does not exist", Zod failures, and any unknown error) is
  * terminal: it fails the same way on every attempt, so it must NOT be retried.
@@ -38,6 +47,34 @@ export function isRetryableError(err) {
     const msg = err.message || '';
     return TRANSIENT_ERROR_PATTERNS.some(p => msg.includes(p));
 }
+/**
+ * The rate-limit signal, in BOTH forms it reaches us (#422). `@actual-app/api`
+ * throws `Authentication failed: ${result.error}`, interpolating the server's
+ * raw string, so the exact shape is server-dependent:
+ *   - the hyphenated code `too-many-requests` (referenced by the auth-retry
+ *     comments, some Actual builds), and
+ *   - the spaced express-rate-limit default `Too many requests, please try
+ *     again later.` (what the E2E stack's server actually returns, #383).
+ * The `[\s-]?` arms match both; `rate[\s-]?limit` covers "rate limit" phrasing.
+ *
+ * Shared by `_shouldDropPoolOnError` (to NOT drop a throttled-but-live
+ * connection) and by `isRetryableAuthError` (to retry a login throttle). A
+ * non-Error rejection is not a rate-limit.
+ *
+ * Checks both `.message` AND `.code`: a login throttle carries it in the message
+ * (`Authentication failed: Too many requests...`), but a SYNC throttle surfaces
+ * as `Error("We had an unknown problem opening ...")` with the rate-limit only in
+ * `.code` (observed in the #383 write path). Matching just the message would miss
+ * that shape.
+ */
+export const RATE_LIMIT_PATTERN = /too[\s-]?many[\s-]?requests|rate[\s-]?limit/i;
+export function isRateLimitError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const code = err.code;
+    const codeStr = typeof code === 'string' ? code : '';
+    return RATE_LIMIT_PATTERN.test(err.message || '') || RATE_LIMIT_PATTERN.test(codeStr);
+}
 export async function retry(fn, opts) {
     const retries = opts?.retries ?? DEFAULT_RETRY_ATTEMPTS;
     const backoffMs = opts?.backoffMs ?? DEFAULT_RETRY_BACKOFF_MS;

package/dist/src/server/stdioServer.js

@@ -63,16 +63,19 @@ export async function startStdioServer(mcp, capabilities, implementedTools, serv
         //   - no `principal`, or getActiveBudgetConfig() would attempt the #189
         //     preferred-budget restore for a caller that has no authenticated
         //     identity, and the env default would stop being authoritative.
-        //   - `transport: 'stdio'` is what keeps stdio OFF the pooled path.
-        //     switchBudget's slow path calls connectionPool.getConnection(), so
-        //     WITHOUT this marker the first switch would silently move stdio onto
-        //     the pooled branch: writes would then rely on api.sync() instead of the
-        //     legacy init/shutdown cycle every existing stdio persistence behaviour
-        //     is built on, and the entry would never be touched (touch() is called
-        //     only from httpServer.ts), so it would expire after the idle timeout and
-        //     be torn down by the cleanup sweep without the api lock, possibly
-        //     mid-operation. That is a far larger change than this ticket, and it is
-        //     not one we want by accident.
+        //   - `transport: 'stdio'` is what keeps stdio OFF the pooled path, and it
+        //     stays that way after #419. switchBudget's slow path calls
+        //     connectionPool.getConnection(), so WITHOUT this marker the first switch
+        //     would silently move stdio onto the pooled branch, and the entry would
+        //     never be touched (touch() is called only from httpServer.ts), so it
+        //     would expire after the idle timeout and be torn down by the cleanup
+        //     sweep without the api lock, possibly mid-operation. That is a far larger
+        //     change than we want by accident.
+        //     #419 solved the per-call upstream login WITHOUT pooling stdio: a stdio
+        //     process keeps the api singleton alive between ops in shutdownActualApi
+        //     (see _shouldKeepSingletonAlive), so the legacy branch's init no-ops
+        //     after the first login. No pool entry is created, so there is nothing for
+        //     the sweep to evict and this comment's hazard never arises.
         //   - `allowedBudgets` is absent, so under AUTH_PROVIDER=oidc switchBudget
         //     still denies. Fail closed: a local pipe must not gain budget access an
         //     HTTP caller would need an ACL for.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.16.12",
+  "version": "0.16.15",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"