actual-mcp-server 0.16.11 → 0.16.12

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.12 | **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

@@ -2659,9 +2659,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/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.12",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"