actual-mcp-server 0.20.0 → 0.22.0

package/dist/src/lib/query-validator.js

@@ -5,12 +5,92 @@
  * to prevent server crashes from invalid table/field references.
  */
 import { getTableFields, getTableNames, isValidTable, isValidField, isValidJoinPath, } from './actual-schema.js';
+/**
+ * Blank the CONTENTS of quoted literals, keeping the quotes.
+ *
+ * #450 round 2: every extractor below scans for keywords (`FROM`, `JOIN`, `GROUP BY`,
+ * `ORDER BY`, `LIMIT`) and must not see one that lives inside a string value. Word boundaries
+ * fixed the column-name instance of that; they cannot fix the literal instance, which is both
+ * the same defect and far more reachable. Measured on v0.21.0, before this:
+ *
+ *   WHERE notes LIKE '%limit%' AND catgeory = 'groceries'   ACCEPTED, typo never validated
+ *   WHERE notes = 'order by z' AND made_up_col = 'x'        ACCEPTED
+ *   SELECT 'a from b', made_up_col FROM transactions        rejected as Table "b" does not exist
+ *   WHERE notes = 'join secrets'                            rejected as Table "secrets" does not exist
+ *
+ * The last two are FALSE REJECTIONS of legitimate queries, so this is not only a bypass fix.
+ *
+ * `validateQueryShape` has done exactly this since #162 for the same reason; extracting it
+ * here means the shape gate and the schema validator can never disagree about what is a
+ * literal. Lengths change, so never map an index from the blanked copy back onto the raw SQL.
+ * Nothing here does: the extractors read identifiers, which never live inside a literal.
+ */
+function blankStringLiterals(sql) {
+    // ONE left-to-right pass. The two obvious shortcuts are both wrong, and both were shipped
+    // and caught in review of the first attempt at this:
+    //
+    //   1. TWO INDEPENDENT REGEX PASSES (single quotes, then double quotes) let one pass match
+    //      ACROSS the other's literals. `WHERE notes = "it's" AND made_up_col = "don't"` had its
+    //      middle blanked by the single-quote pass, deleting `made_up_col` before the extractor
+    //      could see it. An apostrophe in a note search is ordinary input, not an edge case.
+    //   2. TREATING `\` AS AN ESCAPE. SQL escapes a quote by DOUBLING it, not with a backslash,
+    //      so in `'a\'` the literal ENDS at the second quote. Reading it as escaped swallowed the
+    //      rest of the clause, which both hid an unknown column from this validator and let
+    //      `'a\' ; DELETE FROM accounts; --'` past the #162 stacked-statement gate.
+    //
+    // So: whichever quote opens first wins, and it closes on the next matching quote unless that
+    // quote is doubled. Quotes are kept, contents are dropped.
+    let out = '';
+    let i = 0;
+    while (i < sql.length) {
+        const ch = sql[i];
+        if (ch !== "'" && ch !== '"') {
+            out += ch;
+            i++;
+            continue;
+        }
+        const quote = ch;
+        const quoteStart = i;
+        out += quote;
+        i++;
+        while (i < sql.length) {
+            if (sql[i] === quote) {
+                if (sql[i + 1] === quote) {
+                    i += 2; // a doubled quote is an escaped quote: still inside the literal
+                    continue;
+                }
+                break; // closing quote
+            }
+            i++; // literal content: dropped
+        }
+        if (i < sql.length) {
+            out += quote;
+            i++;
+        }
+        else {
+            // UNTERMINATED literal (no closing quote). The tail must stay VISIBLE, and this branch is
+            // the one that matters most: dropping it made `validateQueryShape` fail OPEN. Verified on
+            // the built module while it did:
+            //   WHERE notes = 'x ; DROP TABLE accounts     was rejected, became ACCEPTED
+            //   WHERE notes = 'x AND DELETE FROM accounts  was rejected, became ACCEPTED
+            // The regex this scanner replaced never matched an unterminated literal, so the tail
+            // stayed visible and the #162 gate still saw the stacked statement and the write keyword.
+            // Moving a security gate in the fail-open direction to tidy up a scanner is a bad trade,
+            // so the remainder is emitted RAW, exactly as the old behaviour left it.
+            out += sql.slice(quoteStart + 1);
+        }
+    }
+    return out;
+}
 /**
  * Extract table name from SQL query
  * Handles: FROM table, FROM table1, table2, JOIN table
  */
 function extractTableNames(sql) {
     const tables = new Set();
+    // #450: literals blanked first, so `WHERE notes = 'join secrets'` no longer reports
+    // `Table "secrets" does not exist` for a perfectly legitimate query.
+    sql = blankStringLiterals(sql);
     const normalized = sql.toUpperCase();
     // Extract FROM clause tables - handle queries without WHERE/ORDER/LIMIT
     const fromMatch = normalized.match(/FROM\s+(\w+)/i);
@@ -31,11 +111,19 @@ function extractTableNames(sql) {
 function extractSelectFields(sql) {
     const fields = [];
     // Handle SELECT *
+    // #450: see blankStringLiterals. A literal beginning with `from` truncated the clause and
+    // reported the literal's own words as a missing table.
+    sql = blankStringLiterals(sql);
     if (/SELECT\s+\*/i.test(sql)) {
         return [{ field: '*' }];
     }
-    // Extract SELECT clause
-    const selectMatch = sql.match(/SELECT\s+(.*?)\s+FROM/is);
+    // Extract SELECT clause.
+    // #450: `FROM` carries a trailing word boundary. Without it the lazy match terminates at the
+    // letters `from` inside any identifier, so `SELECT made_up_col AS from_x FROM accounts`
+    // truncated the clause to `made_up_col AS`, which fails the `^\w+$` test below and therefore
+    // extracted ZERO fields, skipping the allowlist loop entirely. Same defect class as the WHERE
+    // terminator below, reachable through an alias rather than a column name.
+    const selectMatch = sql.match(/SELECT\s+(.*?)\s+FROM\b/is);
     if (!selectMatch)
         return fields;
     const selectClause = selectMatch[1];
@@ -63,7 +151,22 @@ function extractSelectFields(sql) {
  */
 function extractWhereFields(sql) {
     const fields = [];
-    const whereMatch = sql.match(/WHERE\s+(.*?)(?:GROUP|ORDER|LIMIT|;|$)/is);
+    // #450: every keyword terminator carries word boundaries. Without them the lazy match cuts the
+    // clause at the first occurrence of the LETTERS `GROUP`, `ORDER` or `LIMIT` anywhere, including
+    // inside a column name, and every field after that point escaped schema validation silently.
+    // Reachable with columns this project's own schema defines: `sort_order` and `balance_limit`
+    // (accounts), `account_group_id` (accounts), and `group` (categories), which IS the keyword.
+    // The terminator anchors on the FULL two-word clause (`GROUP BY`, `ORDER BY`) rather than the bare
+    // keyword, because `group` is itself a column on `categories`: with word boundaries alone,
+    // `WHERE group = "x" AND bogus = "y"` still truncated to the empty string, since the column name
+    // and the keyword are the same token. `LIMIT` stays a single word because it is one in SQL too,
+    // and it is safe: no schema column is named exactly `limit`, and `balance_limit` has no word
+    // boundary before its `limit` (the preceding `_` is a word character).
+    // #450: literals blanked BEFORE the terminator match. Word boundaries alone left the whole
+    // bypass reachable through a string value, which is the likelier route by far: a search for
+    // notes containing the word "limit" truncated the clause and let every later field through.
+    sql = blankStringLiterals(sql);
+    const whereMatch = sql.match(/WHERE\s+(.*?)(?:\bGROUP\s+BY\b|\bORDER\s+BY\b|\bLIMIT\b|;|$)/is);
     if (!whereMatch)
         return fields;
     const whereClause = whereMatch[1];
@@ -248,9 +351,7 @@ export function formatValidationErrors(result) {
 export function validateQueryShape(query) {
     // Blank out single- and double-quoted literals (keep the quotes so positions
     // are roughly preserved, but drop their contents).
-    const stripped = query
-        .replace(/'(?:[^'\\]|\\.)*'/g, "''")
-        .replace(/"(?:[^"\\]|\\.)*"/g, '""');
+    const stripped = blankStringLiterals(query);
     // Stacked statements: a semicolon followed by more non-whitespace.
     if (/;\s*\S/.test(stripped)) {
         throw new Error('actual_query_run does not allow stacked statements (multiple statements separated by ";").');

package/dist/src/lib/schemas/common.js

@@ -3,7 +3,7 @@
  *
  * Common validation schemas used across MCP tools for Actual Budget.
  * These schemas provide consistent validation, better error messages,
- * and reduce duplication across the 77 tool definitions.
+ * and reduce duplication across the 81 tool definitions.
  */
 import { z } from 'zod';
 import { MAX_NAME_LENGTH, MAX_NOTES_LENGTH, DATE_PATTERN, MONTH_PATTERN, UUID_PATTERN } from '../constants.js';
@@ -62,6 +62,14 @@ export const ruleIdSchema = z
  * Tag UUID validation
  * Used for: tag management operations (update, delete)
  */
+/**
+ * Account group UUID validation (#429)
+ * Used for: account group management operations (update, delete)
+ */
+export const accountGroupIdSchema = z
+    .string()
+    .regex(UUID_PATTERN, 'Invalid account group ID format (expected UUID)')
+    .describe('Account group UUID');
 export const tagIdSchema = z
     .string()
     .regex(UUID_PATTERN, 'Invalid tag ID format (expected UUID)')
@@ -225,6 +233,7 @@ export const CommonSchemas = {
     categoryGroupId: categoryGroupIdSchema,
     payeeId: payeeIdSchema,
     ruleId: ruleIdSchema,
+    accountGroupId: accountGroupIdSchema,
     tagId: tagIdSchema,
     scheduleId: scheduleIdSchema,
     // Dates

package/dist/src/lib/server-version-guard.js

@@ -77,10 +77,12 @@ export function checkServerVersion(running, range = SUPPORTED_ACTUAL_SERVER_RANG
     // api patches, so comparing patches would be pure false-positive volume. It is
     // silent when equal and silent when the server is behind.
     //
-    // Scope, stated because it is narrower than it looks: this fires only when ops
-    // still SUCCEED, since the caller runs after a completed operation. A server so
-    // far ahead that budget download already fails never reaches it, and that case
-    // is #438's (surface the real session-init error) rather than this one's.
+    // Scope: this USED to fire only when ops still SUCCEEDED, because the only caller ran after a
+    // completed operation, so a server far enough ahead that the budget download already failed
+    // never reached it. #453 removed that limit by adding a call site BEFORE the download in
+    // loadBudgetTracked, which is the case this branch most wanted to reach. The verdict is
+    // unchanged; only WHEN it can be asked changed. #438 still owns surfacing the real error
+    // AFTER a failure; this warns before one.
     const bundled = parseVersion(bundledApi ?? '');
     if (bundled && (have[0] > bundled[0] || (have[0] === bundled[0] && have[1] > bundled[1]))) {
         return {
@@ -97,7 +99,11 @@ export function checkServerVersion(running, range = SUPPORTED_ACTUAL_SERVER_RANG
 // ---------------------------------------------------------------------------
 // Per-process once-guard.
 // ---------------------------------------------------------------------------
-let checked = false;
+let checked = false; // a version WAS read and judged: never check again
+let inFlight = false; // a check is running right now: a concurrent caller must not duplicate it
+let attempts = 0; // failed attempts, so an unreachable /info cannot be probed forever
+/** Failed probes tolerated before the check gives up for the process. */
+const MAX_PROBE_ATTEMPTS = 3;
 /**
  * Run the compatibility check at most once per process. Call this from inside a successful
  * `withActualApi` operation (while the connection is live), passing a function that reads the
@@ -114,15 +120,28 @@ export async function checkServerVersionOnce(readVersion, log,
 // the process-global api mutex. Tests pass an explicit literal so no in-chain
 // assertion depends on what is installed (#321).
 bundledApi = INSTALLED_API_VERSION) {
-    if (checked)
+    if (checked || inFlight || attempts >= MAX_PROBE_ATTEMPTS)
         return;
-    checked = true; // set synchronously, before any await, so a concurrent op cannot double-fire
+    // #453 review: the latch used to be set here, synchronously, before the await. That was right
+    // while this ran only AFTER a successful operation. Once the probe moved BEFORE the first
+    // download it became the most failure-prone moment available (a slow or unreachable /info, or
+    // the op timeout firing), and a single failure then disabled the warning for the LIFETIME of
+    // the process, including #276's surviving post-op call site. The deployment that silenced it
+    // is precisely the one the guard exists for.
+    //
+    // So: `inFlight` keeps the concurrency property the synchronous latch was actually providing,
+    // `checked` is now set only once a version was really read and judged, and `attempts` bounds
+    // the retries so an unreachable server costs at most MAX_PROBE_ATTEMPTS extra /info calls per
+    // process rather than one per budget load.
+    inFlight = true;
     try {
         const result = await readVersion();
         if (!result || 'error' in result || typeof result.version !== 'string') {
+            attempts++;
             log.debug('[server-version] could not read the Actual server version; skipping the compatibility check');
             return;
         }
+        checked = true; // a real answer: this is the one and only judgement
         const verdict = checkServerVersion(result.version, SUPPORTED_ACTUAL_SERVER_RANGE, bundledApi);
         if (!verdict.ok && verdict.message) {
             log.warn(verdict.message);
@@ -130,10 +149,16 @@ bundledApi = INSTALLED_API_VERSION) {
     }
     catch {
         // Advisory only: a failure to check must never surface as an error or affect the op.
+        attempts++;
         log.debug('[server-version] compatibility check threw; ignored');
     }
+    finally {
+        inFlight = false;
+    }
 }
 /** Test-only: reset the once-guard between cases. */
 export function _resetForTests() {
     checked = false;
+    inFlight = false;
+    attempts = 0;
 }

package/dist/src/lib/tool-annotations.js

@@ -55,6 +55,7 @@ const OPEN_WORLD = new Set(['actual_bank_sync']);
  *   actual_session_close   closes a pooled connection: server state, not budget data.
  */
 const READ_ONLY = new Set([
+    'actual_account_groups_list',
     'actual_account_flow_summary',
     'actual_recurring_expenses_summary',
     'actual_accounts_get_balance',
@@ -99,6 +100,7 @@ const READ_ONLY = new Set([
  * and in #357), so a close can be a delete.
  */
 const DESTRUCTIVE = new Set([
+    'actual_account_groups_delete',
     'actual_accounts_close',
     'actual_accounts_delete',
     // Upstream `reconcileTransactions` overwrites fields on transactions that ALREADY exist
@@ -151,6 +153,8 @@ const DESTRUCTIVE = new Set([
  * not, because on the split path it deletes and recreates child rows.
  */
 const ADDITIVE = new Set([
+    'actual_account_groups_create',
+    'actual_account_groups_update',
     'actual_accounts_create',
     'actual_accounts_reopen',
     'actual_accounts_update',

package/dist/src/server/httpServer.js

@@ -25,97 +25,11 @@ import * as fs from 'node:fs';
 // `requestContext` from this module.
 import { requestContext } from '../lib/requestContext.js';
 import { buildToolListEntries } from '../lib/tool-list-entry.js';
-const INIT_FAILURE_SENTENCES = {
-    schema_too_new: "The Actual server's database schema is newer than the @actual-app/api this build bundles. Upgrade actual-mcp-server, or hold the server upgrade until its dependency update ships.",
-    auth_failed: 'Authentication against the Actual server failed. Check ACTUAL_PASSWORD and the budget password.',
-    // Deliberately not asserting permanence: ECONNRESET and ETIMEDOUT are classed
-    // TRANSIENT by isRetryableError, so this can be a blip rather than misconfiguration.
-    network_unreachable: 'The Actual server could not be reached, which may be transient. If it persists, check ACTUAL_SERVER_URL and that the server is running.',
-    budget_not_found: 'The configured budget was not found on the Actual server. Check ACTUAL_BUDGET_SYNC_ID.',
-    out_of_sync: 'The local budget copy is out of sync with the Actual server and could not be reconciled.',
-    encryption_error: "The budget's end-to-end encryption password is wrong or missing.",
-    clock_drift: "The host clock differs too far from the Actual server's. Fix the system time.",
-    // A filesystem permission error, WITHOUT claiming which path: the classifier
-    // sees only the errno, and EACCES can come from the data directory, TLS
-    // material, or a socket during api.init.
-    permission_denied: 'The server was denied filesystem access while initialising. Check the data directory mount and its ownership first, then any TLS material.',
-    timeout: 'Initialising the Actual connection ran out of time, which may be transient.',
-    unknown: 'The Actual connection for this session could not be initialised. See the server log for the cause.',
-};
-/** Actual's own reason strings, from `withErrorCode` and SyncError, to our enum.
- *  `out-of-sync-migrations` maps to schema_too_new, NOT out_of_sync: `invalid-schema`
- *  is absent from budgetLoader's KNOWN_LOAD_REASONS, so migrations is the only route
- *  by which a too-new schema surfaces on the post-condition path, and upstream's own
- *  sentence for it is "This budget cannot be loaded with this version of the app." */
-const REASON_TO_CAUSE = {
-    'invalid-schema': 'schema_too_new',
-    'out-of-sync-migrations': 'schema_too_new',
-    'out-of-sync': 'out_of_sync',
-    'out-of-sync-data': 'out_of_sync',
-    'budget-not-found': 'budget_not_found',
-    'clock-drift': 'clock_drift',
-    'encrypt-failure': 'encryption_error',
-    'decrypt-failure': 'encryption_error',
-    'missing-key': 'encryption_error',
-};
-/** Node fs/net codes. A DIFFERENT namespace from Actual's reasons, deliberately
- *  kept in its own table so the two can never be conflated. */
-const SYSTEM_CODE_TO_CAUSE = {
-    EACCES: 'permission_denied',
-    EPERM: 'permission_denied',
-    EROFS: 'permission_denied',
-    ECONNREFUSED: 'network_unreachable',
-    ENOTFOUND: 'network_unreachable',
-    ECONNRESET: 'network_unreachable',
-    EHOSTUNREACH: 'network_unreachable',
-    ETIMEDOUT: 'timeout',
-};
-export function classifyInitFailure(err) {
-    const done = (cause) => ({ cause, sentence: INIT_FAILURE_SENTENCES[cause] });
-    try {
-        const e = err;
-        // `.code` FIRST: upstream's api/download-budget and api/load-budget never let a
-        // SyncError escape, they throw a plain Error carrying .code via withErrorCode.
-        const code = typeof e?.code === 'string' ? e.code : undefined;
-        if (code && REASON_TO_CAUSE[code])
-            return done(REASON_TO_CAUSE[code]);
-        if (code && SYSTEM_CODE_TO_CAUSE[code])
-            return done(SYSTEM_CODE_TO_CAUSE[code]);
-        // `.reason` only as a defensive fallback, for a SyncError that reaches us by
-        // some path that does not go through those two handlers.
-        const reason = typeof e?.reason === 'string' ? e.reason : undefined;
-        if (reason && REASON_TO_CAUSE[reason])
-            return done(REASON_TO_CAUSE[reason]);
-        const message = typeof e?.message === 'string' ? e.message : '';
-        // Our OWN synthesized post-condition error (#396) embeds the upstream reason
-        // in prose. On a resync of an existing local copy this is the shape that
-        // actually arrives for the schema and migration classes, so a classifier that
-        // handled only the upstream shapes would answer `unknown` for exactly the
-        // failures this ticket is about.
-        const embedded = /Upstream reason: \[([a-z-]+)\]/.exec(message)?.[1];
-        if (embedded && REASON_TO_CAUSE[embedded])
-            return done(REASON_TO_CAUSE[embedded]);
-        // Last resort, message shapes. `network-failure` is tested BEFORE the auth
-        // wording because upstream reports an unreachable server as
-        // "Authentication failed: network-failure", where the actionable half is the
-        // network, not the credentials.
-        if (/network-failure|ECONNREFUSED|ENOTFOUND/i.test(message))
-            return done('network_unreachable');
-        if (/timed out|ETIMEDOUT/i.test(message))
-            return done('timeout');
-        if (/Authentication failed|invalid-password|Invalid password/i.test(message))
-            return done('auth_failed');
-        if (/invalid-schema/i.test(message))
-            return done('schema_too_new');
-        return done('unknown');
-    }
-    catch {
-        // TOTAL by construction: a classifier that throws would land on the outer POST
-        // catch and egress as raw String(err), defeating this contract through the one
-        // line deliberately left to #446.
-        return done('unknown');
-    }
-}
+// #438 / #452: the init-failure classifier now lives in src/lib/init-failure.ts so BOTH
+// transports can reach it (stdio could not, which was the whole of #452). Re-exported here
+// unchanged so existing importers and tests are unaffected.
+import { classifyInitFailure } from '../lib/init-failure.js';
+export { classifyInitFailure };
 export { requestContext };
 // Resolve the authenticated principal for the per-principal budget preference
 // (#189). OIDC: the verified JWT subject. Static-bearer: a single shared

package/dist/src/server/stdioServer.js

@@ -7,6 +7,83 @@ import logger from '../logger.js';
 import actualToolsManager from '../actualToolsManager.js';
 import { requestContext } from '../lib/requestContext.js';
 import { buildToolListEntries } from '../lib/tool-list-entry.js';
+import { classifyInitFailure, isInitFailure } from '../lib/init-failure.js';
+/**
+ * The stdio `tools/call` handler, built as a named factory so #452's error mapping can be driven
+ * by a unit test with a stubbed connection, instead of only by starting a real process against a
+ * real server. `startStdioServer` registers exactly this.
+ */
+export function createStdioCallToolHandler(mcp, stdioSessionId) {
+    return async (request) => {
+        const req = request;
+        const params = req?.params ?? {};
+        const rawName = params.name;
+        const args = params.arguments;
+        if (typeof rawName !== 'string') {
+            throw new Error('Tool name must be a string');
+        }
+        logger.debug(`[STDIO] tools/call ${rawName}`);
+        // Wrap the DISPATCH, not server.connect(). The transport invokes this handler
+        // from an I/O event, which is outside any scope established around connect(),
+        // so an AsyncLocalStorage context opened there would not be visible here.
+        // Everything downstream is awaited inside this callback, so it propagates.
+        //
+        // Only `sessionId` is placed in the store, deliberately:
+        //   - 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, 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.
+        try {
+            const result = await requestContext.run({ sessionId: stdioSessionId, transport: 'stdio' }, () => mcp.executeTool(rawName, args ?? {}));
+            return {
+                content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
+            };
+        }
+        catch (err) {
+            // #452: give a FAILED CONNECTION the same named causes an HTTP client gets. Until this,
+            // stdio let the raw upstream sentence through, and for the #427 case that sentence
+            // ("Make sure you are using the latest version") names the wrong component: the user has
+            // already upgraded Actual, and the thing to upgrade is actual-mcp-server.
+            //
+            // GATED ON THE BRAND, never on the message. This catch sees EVERY tool error, and the
+            // classifier's last-resort branches match prose: a #270 op timeout would read as `timeout`
+            // and a #422 rate-limit as `auth_failed`, replacing a true message with a false one. Only an
+            // error marked by initActualApiForOperation is classified here. See src/lib/init-failure.ts.
+            if (isInitFailure(err)) {
+                const { cause, sentence } = classifyInitFailure(err);
+                if (cause !== 'unknown') {
+                    // stderr only: stdout is JSON-RPC framing (scripts/stdio-framing-check.mjs).
+                    logger.warn('[STDIO] tool call failed while establishing the Actual connection', {
+                        tool: rawName,
+                        cause,
+                    });
+                    // An MCP tool error, not a thrown exception, so the client renders the sentence as the
+                    // tool's result. The upstream string is deliberately dropped rather than appended: a
+                    // stdio tool error is handed to a cloud model, and #438's fixed-sentence contract exists
+                    // so no upstream stack, SQL, filesystem path or server URL has to be scrubbed correctly.
+                    // The raw error is still in the stderr log above the operator's own terminal.
+                    return { isError: true, content: [{ type: 'text', text: sentence }] };
+                }
+            }
+            throw err;
+        }
+    };
+}
 export async function startStdioServer(mcp, capabilities, implementedTools, serverDescription, serverInstructions, toolSchemas, version) {
     const toolsList = Array.isArray(implementedTools) ? implementedTools : [];
     // #348: a synthetic session identity for this stdio process.
@@ -45,45 +122,7 @@ export async function startStdioServer(mcp, capabilities, implementedTools, serv
         return { tools };
     });
     // Call tool handler — delegates to ActualMCPConnection.executeTool()
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const req = request;
-        const params = req?.params ?? {};
-        const rawName = params.name;
-        const args = params.arguments;
-        if (typeof rawName !== 'string') {
-            throw new Error('Tool name must be a string');
-        }
-        logger.debug(`[STDIO] tools/call ${rawName}`);
-        // Wrap the DISPATCH, not server.connect(). The transport invokes this handler
-        // from an I/O event, which is outside any scope established around connect(),
-        // so an AsyncLocalStorage context opened there would not be visible here.
-        // Everything downstream is awaited inside this callback, so it propagates.
-        //
-        // Only `sessionId` is placed in the store, deliberately:
-        //   - 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, 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.
-        const result = await requestContext.run({ sessionId: stdioSessionId, transport: 'stdio' }, () => mcp.executeTool(rawName, args ?? {}));
-        return {
-            content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
-        };
-    });
+    server.setRequestHandler(CallToolRequestSchema, createStdioCallToolHandler(mcp, stdioSessionId));
     const transport = new StdioServerTransport();
     // server.connect() calls transport.start() internally — do NOT call transport.start() manually
     await server.connect(transport);

package/dist/src/tools/account_groups_create.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+/** #429: create a custom account group (Actual 26.9.0+). */
+export default createTool({
+    name: 'actual_account_groups_create',
+    description: 'Create a custom account group for organising accounts in the sidebar. ' +
+        'Returns the id of the new group. Assigning accounts to it is a separate step: ' +
+        'set the account\'s account_group_id with actual_accounts_update. ' +
+        'Requires an Actual server on 26.9.0 or newer.',
+    schema: z.object({
+        name: z.string().min(1).describe('Display name for the group, for example "Savings" or "Joint accounts"'),
+        sort_order: z
+            .number()
+            .optional()
+            .describe('Optional ordering position in the sidebar. Lower sorts first; omit to let Actual place it.'),
+    }),
+    handler: async (input) => {
+        const id = await adapter.createAccountGroup(input);
+        return { id, name: input.name };
+    },
+    examples: [
+        { description: 'Create a group for savings accounts', input: { name: 'Savings' } },
+        { description: 'Create a group pinned to the top of the sidebar', input: { name: 'Daily spending', sort_order: 0 } },
+    ],
+});

package/dist/src/tools/account_groups_delete.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+import adapter from '../lib/actual-adapter.js';
+/** #429: delete a custom account group (Actual 26.9.0+). */
+export default createTool({
+    name: 'actual_account_groups_delete',
+    description: 'Delete a custom account group. The accounts in it are NOT deleted: they become ungrouped. ' +
+        'Note that upstream clears those member references best-effort under sync, so a concurrent ' +
+        'assignment on another device can survive the delete; treat any account still pointing at a ' +
+        'missing group as ungrouped. Refuses with a not-found error, writing nothing, when the group ' +
+        'does not exist. Requires an Actual server on 26.9.0 or newer.',
+    schema: z.object({
+        id: CommonSchemas.accountGroupId.describe('Id of the account group to delete (actual_account_groups_list lists them)'),
+    }),
+    handler: async (input) => {
+        await adapter.deleteAccountGroup(input.id);
+        return { success: true, id: input.id };
+    },
+    examples: [
+        { description: 'Delete a group, leaving its accounts ungrouped', input: { id: '00000000-0000-0000-0000-000000000000' } },
+    ],
+});

package/dist/src/tools/account_groups_list.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+/**
+ * #429: list the custom account groups (Actual 26.9.0+).
+ *
+ * Read the grouping semantics before relying on a group id: upstream clears member
+ * references on a best-effort basis under CRDT sync, so an account whose
+ * `account_group_id` points at a group that is missing here is UNGROUPED, not an error.
+ */
+export default createTool({
+    name: 'actual_account_groups_list',
+    description: 'List the custom account groups used to organise accounts in the sidebar. ' +
+        'Returns each group with its id, name and sort order. An account whose account_group_id ' +
+        'does not appear here is ungrouped: upstream clears member references best-effort under ' +
+        'sync, so a dangling reference is expected and is not an error. Requires an Actual server ' +
+        'on 26.9.0 or newer, which is where account groups were introduced.',
+    schema: z.object({}),
+    handler: async () => {
+        return await adapter.getAccountGroups();
+    },
+    examples: [{ description: 'List every account group', input: {} }],
+});

package/dist/src/tools/account_groups_update.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+import adapter from '../lib/actual-adapter.js';
+/** #429: rename or reorder a custom account group (Actual 26.9.0+). */
+export default createTool({
+    name: 'actual_account_groups_update',
+    description: 'Rename a custom account group or change its sidebar position. ' +
+        'Does not change which accounts belong to it: use actual_accounts_update to move an ' +
+        'account between groups. Refuses with a not-found error, writing nothing, when the group ' +
+        'does not exist. Requires an Actual server on 26.9.0 or newer.',
+    schema: z.object({
+        id: CommonSchemas.accountGroupId.describe('Id of the account group to update (actual_account_groups_list lists them)'),
+        name: z.string().min(1).optional().describe('New display name'),
+        sort_order: z.number().optional().describe('New ordering position in the sidebar; lower sorts first'),
+    }),
+    handler: async (input) => {
+        const { id, ...fields } = input;
+        await adapter.updateAccountGroup(id, fields);
+        return { success: true, id, updated: Object.keys(fields) };
+    },
+    examples: [
+        { description: 'Rename a group', input: { id: '00000000-0000-0000-0000-000000000000', name: 'Long-term savings' } },
+    ],
+});

package/dist/src/tools/index.js

@@ -6,6 +6,10 @@ export { default as accounts_close } from './accounts_close.js';
 export { default as accounts_create } from './accounts_create.js';
 export { default as accounts_delete } from './accounts_delete.js';
 export { default as accounts_get_balance } from './accounts_get_balance.js';
+export { default as account_groups_list } from './account_groups_list.js';
+export { default as account_groups_create } from './account_groups_create.js';
+export { default as account_groups_update } from './account_groups_update.js';
+export { default as account_groups_delete } from './account_groups_delete.js';
 export { default as accounts_list } from './accounts_list.js';
 export { default as accounts_reopen } from './accounts_reopen.js';
 export { default as accounts_update } from './accounts_update.js';