actual-mcp-server 0.16.13 → 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.13 | **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';
@@ -295,13 +295,16 @@ export function _shouldKeepSingletonAlive(activeSessions, forceFullShutdown) {
  * 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.

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/package.json

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