actual-mcp-server 0.16.12 → 0.16.13

package/README.md

@@ -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.13 | **Tool Count:** 74 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/lib/actual-adapter.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
@@ -397,17 +426,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 +517,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 +657,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 +1035,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 +1139,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 +1201,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 +1227,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 +1259,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/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.13",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"