actual-mcp-server 0.16.11 → 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.11 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.16.13 | **Tool Count:** 74 (verified LibreChat-compatible)
 
 ## Sponsor
 

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

@@ -3,6 +3,7 @@
 // calls and string parsing, with no module state or side effects. parseWhereClause
 // is re-exported from actual-adapter.ts and is unit-tested directly. The #178
 // operator support (LIKE / NOT LIKE / IS NULL, throw-on-unsupported) lives here.
+import { getFieldType } from '../actual-schema.js';
 // Strip a single pair of surrounding quotes from a SQL value literal.
 function _stripWhereQuotes(s) {
     return s.trim().replace(/^['"]|['"]$/g, '');
@@ -17,7 +18,38 @@ function _coerceWhereValue(s) {
     const n = Number(v);
     return isNaN(n) ? v : n;
 }
-export function parseWhereClause(query, whereClause) {
+// #420: coerce a SQL literal to a real JavaScript boolean, for a column the schema types as
+// boolean. ActualQL requires a genuine JS boolean here: its compiler only tags a value as
+// `boolean` from `typeof value === 'boolean'`, and `castInput` has no string-to-boolean or
+// integer-to-boolean branch, so `"true"` and `1` are both rejected with the exact errors #420
+// reports.
+//
+// Accepts `true`/`false` case-insensitively AND `1`/`0`. The integer form is accepted on purpose:
+// the tool advertises SQL, and every mainstream engine (SQLite, which is Actual's own store, plus
+// MySQL/MariaDB/SQL Server/Postgres) treats `1`/`0` as booleans. Refusing it would make this tool
+// stricter than the database it models. A value that is neither throws, naming the column and the
+// value, because a bad boolean literal is a caller mistake we can describe precisely.
+function _coerceBoolean(field, s) {
+    const v = _stripWhereQuotes(s).toLowerCase();
+    if (v === 'true' || v === '1')
+        return true;
+    if (v === 'false' || v === '0')
+        return false;
+    throw new Error(`Invalid boolean value for column "${field}": ${JSON.stringify(_stripWhereQuotes(s))}. ` +
+        `Use true or false (1 or 0 are also accepted).`);
+}
+// Whether the schema types `field` (a plain or joined column) as boolean, given the base table.
+// An unknown field is NOT boolean, so its value is left untouched: this is what keeps a string
+// comparison like `notes = 'true'` a string, and the query validator handles the unknown-field
+// case separately.
+function _isBooleanField(tableName, field) {
+    return tableName !== undefined && getFieldType(tableName, field) === 'boolean';
+}
+// `tableName` is the FROM table, used to look up column types so boolean literals can be coerced
+// (#420). It is optional only so the many existing unit tests that assert non-boolean behaviour
+// need not all pass it; the production call site in actual-adapter.ts always does. When it is
+// absent, no field resolves as boolean and the pre-#420 behaviour is exactly preserved.
+export function parseWhereClause(query, whereClause, tableName) {
     // OR is not supported. Detect it up front and fail loudly. Without this guard
     // a clause like `amount = 100 OR amount < 0` is left as a single fragment by
     // the AND-splitter, and the comparison regex's greedy value capture swallows
@@ -68,8 +100,20 @@ export function parseWhereClause(query, whereClause) {
         const inMatch = trimmedCondition.match(/^([\w.]+)\s+IN\s+\((.+)\)$/i);
         if (inMatch) {
             const [, field, valuesStr] = inMatch;
-            const values = valuesStr.split(',').map(_coerceWhereValue);
-            query = query.filter({ [field]: { $oneof: values } });
+            const rawValues = valuesStr.split(',');
+            if (_isBooleanField(tableName, field)) {
+                // #420: `$oneof` STRINGIFIES every element (upstream `compiler.ts` emits
+                // `'${String(id)}'`), so `is_parent IN (true, false)` would compile to
+                // `IN ('true','false')` against a 0/1 column and silently match nothing, which is worse
+                // than the loud error we produce today. Expand to `$or` of equalities instead: each inner
+                // equality then routes through `castInput(..., 'boolean')` and works. `$or` is a real
+                // ActualQL condition key (compiler.ts handles `field === '$or'` via `compileOr`).
+                const orConditions = rawValues.map((v) => ({ [field]: _coerceBoolean(field, v) }));
+                query = query.filter({ $or: orConditions });
+            }
+            else {
+                query = query.filter({ [field]: { $oneof: rawValues.map(_coerceWhereValue) } });
+            }
             continue;
         }
         // Comparison operators: field >= value, field = value, etc.
@@ -86,7 +130,12 @@ export function parseWhereClause(query, whereClause) {
                 '!=': '$ne',
             };
             const actualOp = operatorMap[operator];
-            const finalValue = _coerceWhereValue(valueStr);
+            // #420: on a boolean column the literal must reach ActualQL as a real JS boolean, not the
+            // string "true" or the number 1. Only = and != are meaningful for a boolean; the ordering
+            // operators are left to their normal path, where ActualQL will reject them for a boolean as
+            // it does today, rather than us inventing an ordering the column does not have.
+            const isBool = _isBooleanField(tableName, field) && (actualOp === '$eq' || actualOp === '$ne');
+            const finalValue = isBool ? _coerceBoolean(field, valueStr) : _coerceWhereValue(valueStr);
             if (actualOp === '$eq') {
                 // Simple equality can use the direct field: value shorthand.
                 query = query.filter({ [field]: finalValue });

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 });
@@ -2659,9 +2747,10 @@ export async function runQuery(queryString) {
                             });
                             query = query.select(fieldList);
                         }
-                        // Apply WHERE conditions
+                        // Apply WHERE conditions. tableName is passed so parseWhereClause can resolve column
+                        // types and coerce boolean literals to real booleans (#420).
                         if (whereClause) {
-                            query = parseWhereClause(query, whereClause);
+                            query = parseWhereClause(query, whereClause, tableName);
                         }
                         // Apply ORDER BY
                         if (orderField) {

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

@@ -211,3 +211,25 @@ export function isValidField(tableName, fieldName) {
 export function isValidJoinPath(path) {
     return path in JOIN_PATHS;
 }
+/**
+ * Resolve a WHERE field to its declared type, for the given base table.
+ *
+ * Handles both a plain column (`is_parent`, resolved against `tableName`) and a joined field
+ * (`category.hidden`, resolved through JOIN_PATHS to the target table's column). Returns the
+ * `type` string from the schema, or `undefined` when the field is not known.
+ *
+ * #420: used to decide whether a WHERE literal must be coerced to a real boolean. It is
+ * deliberately conservative: an unknown field returns `undefined` and the caller then leaves the
+ * value untouched, so this can never turn a valid string comparison into a boolean by accident.
+ * The query validator (`query-validator.ts`) is what rejects an unknown field; this only reports a
+ * type when it is certain of one.
+ */
+export function getFieldType(tableName, field) {
+    if (field.includes('.')) {
+        const join = JOIN_PATHS[field];
+        if (!join)
+            return undefined;
+        return ACTUAL_SCHEMA[join.table]?.[join.field]?.type;
+    }
+    return ACTUAL_SCHEMA[tableName]?.[field]?.type;
+}

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/dist/src/tools/query_run.js

@@ -24,6 +24,11 @@ Supported WHERE operators:
   • LIKE / NOT LIKE for pattern search (case-insensitive, accent-insensitive; use % as wildcard)
     e.g. "WHERE imported_payee LIKE '%amazon%'" to find raw bank-sync payee strings
   • IS NULL / IS NOT NULL e.g. "WHERE imported_payee IS NULL" to find unmerged rows
+  • Boolean columns take true / false (case-insensitive; 1 / 0 also accepted)
+    e.g. "WHERE cleared = false" for uncleared, "WHERE reconciled = true",
+    "WHERE category.hidden = true", "WHERE account.closed = true"
+    Note: transactions are returned in split-INLINE mode, so "WHERE is_parent = true" returns
+    nothing (parent rows are hidden); use "is_parent = false" to exclude split children.
   • Combine conditions with AND. OR, REGEXP, NOT IN, and parenthesised groups are not yet
     supported and will return an error (the query is never silently run unfiltered).
 

package/package.json

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