actual-mcp-server 0.6.44 → 0.6.48

package/README.md

@@ -751,4 +751,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.44 | **Tool Count:** 71 (verified LibreChat-compatible)
+**Version:** 0.6.48 | **Tool Count:** 71 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.44",
+    "version": "0.6.48",
     "engines": {
         "node": ">=20.0.0",
         "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
         "verify-tools": "npm run build && node scripts/verify-tools.js",
         "check:coverage": "node scripts/list-actual-api-methods.mjs",
         "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-        "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/check_coverage.test.js",
+        "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js",
         "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
         "test:e2e": "npx playwright test",
         "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",

package/dist/src/actualToolsManager.js

@@ -1,5 +1,6 @@
 import logger from './logger.js';
 import { z } from 'zod';
+import { formatZodError } from './lib/zod-error-format.js';
 // ✅ List of tools already implemented in this class.
 // Adding the tool name here is considered fully implemented.
 const IMPLEMENTED_TOOLS = [
@@ -169,14 +170,10 @@ class ActualToolsManager {
             return safe;
         }
         catch (err) {
-            // Format Zod validation errors more clearly
+            // Format Zod validation errors into one actionable, consistent message (#206).
+            // Duck-type on `.issues` so any structurally-compatible ZodError is handled.
             if (err && typeof err === 'object' && 'issues' in err) {
-                const zodError = err;
-                const issues = zodError.issues.map(issue => {
-                    const path = issue.path.join('.');
-                    return `${path}: ${issue.message}`;
-                }).join(', ');
-                const formattedMsg = `Validation error: ${issues}`;
+                const formattedMsg = formatZodError(err, tool.inputSchema);
                 logger.error(`[TOOL ERROR] ${name}: ${formattedMsg}`);
                 throw new Error(formattedMsg);
             }

package/dist/src/lib/loggerFactory.js

@@ -26,15 +26,19 @@ import logger from '../logger.js';
  */
 export function createModuleLogger(moduleName) {
     const prefix = `[${moduleName}]`;
+    // `module` is attached as a structured field (promoted to a top-level field by the
+    // logger format, #219) while the `[MODULE]` prefix is kept in the message for the
+    // pretty/dev output. `module` is spread LAST so it stays authoritative and a caller's
+    // metadata cannot accidentally overwrite it.
     return {
         info: (message, meta) => {
-            logger.info(`${prefix} ${message}`, meta);
+            logger.info(`${prefix} ${message}`, { ...meta, module: moduleName });
         },
         debug: (message, meta) => {
-            logger.debug(`${prefix} ${message}`, meta);
+            logger.debug(`${prefix} ${message}`, { ...meta, module: moduleName });
         },
         warn: (message, meta) => {
-            logger.warn(`${prefix} ${message}`, meta);
+            logger.warn(`${prefix} ${message}`, { ...meta, module: moduleName });
         },
         error: (message, error, meta) => {
             if (error) {
@@ -42,10 +46,11 @@ export function createModuleLogger(moduleName) {
                     error: error.message,
                     stack: error.stack,
                     ...meta,
+                    module: moduleName,
                 });
             }
             else {
-                logger.error(`${prefix} ${message}`, meta);
+                logger.error(`${prefix} ${message}`, { ...meta, module: moduleName });
             }
         },
     };

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

@@ -41,7 +41,7 @@ export const categoryIdSchema = z
 export const categoryGroupIdSchema = z
     .string()
     .regex(UUID_PATTERN, 'Invalid category group ID format (expected UUID)')
-    .describe('Category group UUID');
+    .describe('Category group UUID; list with actual_category_groups_get');
 /**
  * Payee UUID validation
  * Used for: transactions, payee management, rules

package/dist/src/lib/zod-error-format.js

@@ -0,0 +1,150 @@
+const MAX_KEY_LEN = 64;
+/** Strip control characters and cap length so a hostile key cannot flood or inject. */
+function sanitizeKey(key) {
+    let k = typeof key === 'string' ? key : String(key);
+    // eslint-disable-next-line no-control-regex
+    k = k.replace(/[\u0000-\u001f\u007f]/g, '');
+    if (k.length > MAX_KEY_LEN)
+        k = `${k.slice(0, MAX_KEY_LEN)}...`;
+    return k;
+}
+// ---- leaf-schema `.describe()` hint resolution (best-effort, never throws) ----
+function unwrap(schema) {
+    // Strip only true single-child wrappers (optional / nullable / default / readonly /
+    // catch / brand), which in Zod v4 all expose their child at `_def.innerType`. We do
+    // NOT use `.unwrap()`: ZodArray also has `.unwrap()` (returning its element), which
+    // would descend past the array before the caller resolves the element by path index.
+    let s = schema;
+    let guard = 0;
+    while (s && guard++ < 12) {
+        const inner = s?._def?.innerType;
+        if (inner && inner !== s) {
+            s = inner;
+            continue;
+        }
+        break;
+    }
+    return s;
+}
+function shapeOf(schema) {
+    try {
+        const direct = schema?.shape;
+        if (direct)
+            return typeof direct === 'function' ? direct() : direct;
+        const def = schema?._def?.shape;
+        if (def)
+            return typeof def === 'function' ? def() : def;
+    }
+    catch { /* ignore */ }
+    return undefined;
+}
+function elementOf(schema) {
+    return schema?.element ?? schema?._def?.element ?? schema?._def?.type;
+}
+function leafAt(schema, path) {
+    let cur = schema;
+    for (const seg of path) {
+        cur = unwrap(cur);
+        if (typeof seg === 'number' || /^\d+$/.test(String(seg))) {
+            cur = elementOf(cur);
+        }
+        else {
+            const shape = shapeOf(cur);
+            cur = shape ? shape[String(seg)] : undefined;
+        }
+        if (!cur)
+            return undefined;
+    }
+    return unwrap(cur);
+}
+function hintAt(schema, path) {
+    if (!schema)
+        return undefined;
+    try {
+        const leaf = leafAt(schema, path);
+        const d = leaf?.description;
+        return typeof d === 'string' && d.length > 0 ? d : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---- per-issue rendering ----
+function unitFor(origin, count) {
+    const plural = count === 1 ? '' : 's';
+    if (origin === 'string')
+        return ` character${plural}`;
+    if (origin === 'array' || origin === 'set')
+        return ` item${plural}`;
+    return '';
+}
+function describeIssue(issue, schema) {
+    const path = Array.isArray(issue?.path) ? issue.path : [];
+    const pathStr = path.join('.');
+    const hint = hintAt(schema, path);
+    const withHint = (s) => (hint ? `${s} (${hint})` : s);
+    // Pass an already-actionable message through, prefixed with the field path when there is
+    // one (an empty path, e.g. a root-level issue, must not produce a leading ": ").
+    const withPath = (m) => (pathStr ? `${pathStr}: ${m}` : m);
+    const msg = typeof issue?.message === 'string' ? issue.message : 'invalid input';
+    switch (issue?.code) {
+        case 'invalid_type': {
+            // Zod v4's DEFAULT message looks like "Invalid input: expected X, received Y"
+            // ("received undefined" means the field was missing). We reformat only when we can
+            // read that "received <word>" token: that confirms it is the default message, not a
+            // custom one that merely happens to start with the same words. Anything else (a custom
+            // .int()/.refine() message) passes through unchanged. NOTE: this prefix is English and
+            // Zod-version-specific; the exact-string unit tests act as a canary if Zod changes it.
+            const received = msg.startsWith('Invalid input: expected') ? /received (\w+)/.exec(msg)?.[1] : undefined;
+            if (received === 'undefined')
+                return withHint(`${pathStr} is required`);
+            if (received)
+                return withHint(`${pathStr}: expected ${issue.expected}, received ${received}`);
+            return withPath(msg);
+        }
+        case 'invalid_value':
+            // enum / literal: list the allowed options
+            return Array.isArray(issue.values) ? withPath(`allowed values: ${issue.values.join(', ')}`) : withPath(msg);
+        case 'invalid_format':
+            // regex / custom string formats already carry an actionable message
+            return withPath(msg);
+        case 'too_big': {
+            if (!msg.startsWith('Too big:'))
+                return withPath(msg); // custom message
+            const cmp = issue.inclusive === false ? 'less than' : 'at most';
+            return withPath(`must be ${cmp} ${issue.maximum}${unitFor(issue.origin, issue.maximum)}`);
+        }
+        case 'too_small': {
+            if (!msg.startsWith('Too small:'))
+                return withPath(msg); // custom message
+            const cmp = issue.inclusive === false ? 'more than' : 'at least';
+            return withPath(`must be ${cmp} ${issue.minimum}${unitFor(issue.origin, issue.minimum)}`);
+        }
+        case 'unrecognized_keys': {
+            // path is empty for this issue: do NOT emit a leading "<path>: " (the old bug).
+            const keys = (Array.isArray(issue.keys) ? issue.keys : [])
+                .map(sanitizeKey)
+                .filter((k) => k.length > 0)
+                .join(', ');
+            // keys can be empty if every offending key sanitised away (all control chars).
+            return keys ? `unexpected field(s): ${keys}` : 'unexpected field(s) present';
+        }
+        default:
+            return withPath(msg);
+    }
+}
+/**
+ * Format a ZodError into one actionable `Validation error: ...` string.
+ *
+ * @param error  the ZodError (duck-typed on `.issues`, so a structurally-compatible
+ *               error from any Zod build is accepted).
+ * @param schema optional tool input schema, used to resolve `.describe()` hints for
+ *               the failing fields. Omit it and messages still format, just without hints.
+ */
+export function formatZodError(error, schema) {
+    const issues = Array.isArray(error?.issues) ? error.issues : [];
+    if (issues.length === 0)
+        return 'Validation error: invalid input';
+    const parts = issues.map((issue) => describeIssue(issue, schema));
+    return `Validation error: ${parts.join(', ')}`;
+}

package/dist/src/logger.js

@@ -2,6 +2,10 @@ import winston from 'winston';
 import DailyRotateFile from 'winston-daily-rotate-file';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { randomUUID } from 'crypto';
+// requestContext only imports async_hooks, so this is safe to import from the early-loaded
+// logger module (no circular import).
+import { requestContext } from './lib/requestContext.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // env-configurable
@@ -14,7 +18,6 @@ const LOG_DIR = process.env.MCP_BRIDGE_LOG_DIR
 const DATE_PATTERN = process.env.MCP_BRIDGE_ROTATE_DATEPATTERN || 'YYYY-MM-DD';
 const MAX_SIZE = process.env.MCP_BRIDGE_MAX_LOG_SIZE || '20m';
 const MAX_FILES = process.env.MCP_BRIDGE_MAX_FILES || '14d';
-const DEFAULT_LEVEL = process.env.MCP_BRIDGE_LOG_LEVEL || 'debug';
 function safeStringify(obj, maxLen = 2000) {
     try {
         const seen = new WeakSet();
@@ -39,6 +42,228 @@ function safeStringify(obj, maxLen = 2000) {
         }
     }
 }
+/**
+ * Resolve the output format, level, and service name from the environment.
+ *
+ * Format precedence is deterministic: an explicit `LOG_FORMAT` ("json" | "pretty")
+ * wins; otherwise `NODE_ENV==='production'` selects JSON; otherwise pretty. The
+ * non-production default is therefore the human-readable text format, so existing
+ * log-text-scraping tests keep passing and JSON is an explicit opt-in or prod-only.
+ */
+export function resolveLogConfig(env = process.env) {
+    const fmt = String(env.LOG_FORMAT || '').toLowerCase();
+    const isProd = env.NODE_ENV === 'production';
+    const useJson = fmt === 'json' ? true : fmt === 'pretty' ? false : isProd;
+    const level = env.MCP_BRIDGE_LOG_LEVEL || (isProd ? 'info' : 'debug');
+    const service = env.MCP_SERVICE_NAME || 'actual-mcp-server';
+    return { useJson, level, service };
+}
+const { useJson: USE_JSON, level: DEFAULT_LEVEL, service: SERVICE } = resolveLogConfig(process.env);
+// Fields that stay at the top level of a record; everything else is user metadata.
+// `sessionId`/`requestId` are reserved correlation fields (#221), so they render top-level
+// rather than nested under `context`.
+const STANDARD_KEYS = new Set([
+    'level', 'message', 'timestamp', 'service', 'module', 'stack', 'ms', 'sessionId', 'requestId',
+]);
+// Promote a `service` field onto every record.
+const addService = winston.format((info) => {
+    info.service = SERVICE;
+    return info;
+});
+/**
+ * Resolve a request correlation id: reuse a non-empty inbound `X-Correlation-ID`, else
+ * generate one. Exported so the HTTP layer and tests share the exact decision (#221).
+ *
+ * The inbound value is CLIENT-CONTROLLED and is stamped on every log line for the request,
+ * so it is sanitised first: control characters are stripped (prevents log-line forging in
+ * non-JSON consumers) and the length is capped (prevents per-line bloat from a hostile
+ * header). If nothing usable remains, a UUID is generated.
+ */
+const MAX_REQUEST_ID_LEN = 128;
+export function resolveRequestId(inbound) {
+    let id = typeof inbound === 'string' ? inbound.trim() : '';
+    if (id) {
+        // eslint-disable-next-line no-control-regex
+        id = id.replace(/[\u0000-\u001f\u007f]/g, '').slice(0, MAX_REQUEST_ID_LEN);
+    }
+    return id.length > 0 ? id : randomUUID();
+}
+// Stamp the active request's correlation ids onto every record (#221). Reads the
+// AsyncLocalStorage store; the context-derived id is authoritative, so it OVERWRITES any
+// caller-supplied `sessionId` metadata. When there is no active store (startup, CLI, stdio
+// without a request wrapper) it is a no-op and never throws. Must run after splat() (which
+// reverts top-level field additions made before it), so it is placed alongside addService.
+const addCorrelation = winston.format((info) => {
+    const store = requestContext.getStore();
+    if (store?.sessionId)
+        info.sessionId = store.sessionId;
+    if (store?.requestId)
+        info.requestId = store.requestId;
+    return info;
+});
+// Collect non-standard fields into a single `context` object so JSON records have a
+// stable shape ({ timestamp, level, service, module, message, stack?, context? }).
+// winston hands the SAME info object to every transport's format, so this must be
+// idempotent: a record passing through more than one transport (e.g. STORE_LOGS=true
+// gives two file transports plus the console) must not re-nest `context` into
+// `context.context`. Excluding the `context` key from the move makes a second pass a
+// no-op, and any already-present context is merged rather than wrapped.
+const nestContext = winston.format((info) => {
+    const ctx = {};
+    for (const key of Object.keys(info)) {
+        if (!STANDARD_KEYS.has(key) && key !== 'context') {
+            ctx[key] = info[key];
+            delete info[key];
+        }
+    }
+    if (Object.keys(ctx).length > 0) {
+        const existing = info.context;
+        info.context =
+            existing && typeof existing === 'object' ? { ...existing, ...ctx } : ctx;
+    }
+    return info;
+});
+// ---------------------------------------------------------------------------
+// Secret / PII redaction (#220)
+//
+// Runs inside buildLogFormat (per-transport), specifically AFTER winston.format.splat():
+// splat() rebuilds the record from the original args and reverts top-level field mutations
+// made before it (nested objects survive only because they are shared refs), so redaction
+// placed before splat would silently fail to mask a top-level secret like `note`. Running
+// it per-transport in the SAME pipeline that serializes (before nestContext, which moves
+// fields under `context`) is the placement that actually reaches the output. It is
+// idempotent (masking and value-scrub both go to a constant), so the STORE_LOGS
+// multi-transport fan-out is safe. The live `note`/header tests pin this ordering: moving
+// redactSecrets before splat makes them fail.
+//
+// Two mechanisms: a key-name denylist for structured fields at any depth, and a finite
+// scrub of the actual configured secret VALUES (which catches a secret carried as a value
+// under a benign key, or inside a stringified message).
+// ---------------------------------------------------------------------------
+const REDACTED = '[REDACTED]';
+const SENSITIVE_KEYS = new Set([
+    'authorization', 'proxy-authorization', 'token', 'password', 'encryptionpassword',
+    'cookie', 'set-cookie', 'secret', 'apikey', 'api_key', 'x-api-key',
+    'access_token', 'refresh_token', 'client_secret',
+]);
+/** A metadata key is sensitive if its lowercased name is denylisted or ends in a secret suffix. */
+export function isSensitiveKey(key) {
+    const low = key.toLowerCase();
+    if (SENSITIVE_KEYS.has(low))
+        return true;
+    return (low.endsWith('password') ||
+        low.endsWith('secret') ||
+        low.endsWith('token') ||
+        low.includes('authorization') ||
+        low.includes('cookie'));
+}
+/** The actual configured secret values, so a secret echoed as a VALUE is also masked. */
+export function collectSecretValues(env = process.env) {
+    const out = [];
+    for (const [k, v] of Object.entries(env)) {
+        // length guard avoids masking short/common values that could collide with benign log
+        // text (a short secret is still masked by KEY name when under a sensitive field; only
+        // the free-text VALUE scrub is skipped for it).
+        if (typeof v === 'string' && v.length >= 8 && /(PASSWORD|SECRET|AUTHORIZATION|_TOKEN)$/.test(k)) {
+            out.push(v);
+        }
+    }
+    return out;
+}
+function scrubSecretValues(s, secrets) {
+    let out = s;
+    for (const sec of secrets) {
+        if (sec && out.includes(sec))
+            out = out.split(sec).join(REDACTED);
+    }
+    return out;
+}
+const MAX_REDACT_DEPTH = 8;
+const MAX_REDACT_NODES = 2000;
+/**
+ * Return a redacted version of a value. NESTED objects/arrays are COPIED (copy-on-write),
+ * never mutated, so redacting a log record cannot corrupt a live caller object (e.g.
+ * `req.headers` passed by reference). Depth/node caps and a cycle guard bound pathological
+ * or cyclic structures.
+ */
+function redactValue(val, secrets, depth, seen, counter) {
+    if (val && typeof val === 'object') {
+        if (depth > MAX_REDACT_DEPTH || counter.n > MAX_REDACT_NODES)
+            return '[Truncated]';
+        if (seen.has(val))
+            return '[Circular]';
+        seen.add(val);
+        if (Array.isArray(val))
+            return val.map((v) => redactValue(v, secrets, depth + 1, seen, counter));
+        const copy = {};
+        for (const key of Object.keys(val)) {
+            counter.n++;
+            copy[key] = isSensitiveKey(key)
+                ? REDACTED
+                : redactValue(val[key], secrets, depth + 1, seen, counter);
+        }
+        return copy;
+    }
+    if (typeof val === 'string' && secrets.length > 0)
+        return scrubSecretValues(val, secrets);
+    return val;
+}
+/**
+ * Mask sensitive keys and scrub known-secret values. The TOP-LEVEL record is mutated in
+ * place (winston hands the transport its own copy, and the winston Symbol keys must be
+ * preserved), but every NESTED object is replaced with a redacted copy so a shared live
+ * object (a request's headers) is never altered. Masking to a constant is idempotent.
+ */
+export function redactRecord(record, secrets = []) {
+    if (!record || typeof record !== 'object')
+        return record;
+    const seen = new WeakSet();
+    const counter = { n: 0 };
+    const rec = record;
+    for (const key of Object.keys(rec)) {
+        rec[key] = isSensitiveKey(key) ? REDACTED : redactValue(rec[key], secrets, 1, seen, counter);
+    }
+    return record;
+}
+const SECRET_VALUES = collectSecretValues(process.env);
+const redactSecrets = winston.format((info) => redactRecord(info, SECRET_VALUES));
+/**
+ * Build the winston format. Reuses winston's own building blocks
+ * (`format.errors` + `format.splat` + `format.json`) rather than a hand-rolled
+ * serializer, so the metadata that loggerFactory already attaches flows through.
+ * The previous printf referenced only `{ timestamp, level, message }`, which is
+ * why metadata (including error stacks) was silently dropped.
+ */
+export function buildLogFormat(useJson, colorize = !!process.stdout.isTTY) {
+    if (useJson) {
+        return winston.format.combine(winston.format.timestamp(), // ISO 8601 UTC
+        winston.format.errors({ stack: true }), winston.format.splat(), 
+        // #220: redact AFTER splat. splat() rebuilds the record from the original args and
+        // reverts top-level field mutations made before it (nested objects survive as shared
+        // refs), so redaction must run after splat to actually mask top-level secrets.
+        redactSecrets(), addCorrelation(), // #221: stamp sessionId/requestId (after splat, like addService)
+        addService(), nestContext(), winston.format.json());
+    }
+    // Colorize only for an interactive terminal, so piped output and log files do not get
+    // ANSI escape codes (also keeps the format deterministic and unit-testable).
+    return winston.format.combine(winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss.SSS' }), winston.format.errors({ stack: true }), winston.format.splat(), redactSecrets(), // #220: after splat (see note in the json branch)
+    addCorrelation(), // #221: stamp sessionId/requestId
+    ...(colorize ? [winston.format.colorize()] : []), winston.format.printf((info) => {
+        const rec = info;
+        let line = `${rec.timestamp} ${rec.level}: ${rec.message}`;
+        if (rec.stack)
+            line += `\n${rec.stack}`;
+        // Append any remaining metadata for dev readability (it is no longer dropped).
+        const extra = {};
+        for (const key of Object.keys(rec)) {
+            if (!STANDARD_KEYS.has(key))
+                extra[key] = rec[key];
+        }
+        if (Object.keys(extra).length > 0)
+            line += ` ${safeStringify(extra, 1000)}`;
+        return line;
+    }));
+}
 const transports = [];
 // file transports when enabled (capture debug+)
 if (STORE_LOGS) {
@@ -50,22 +275,23 @@ if (STORE_LOGS) {
         zippedArchive: true,
         maxSize: MAX_SIZE,
         maxFiles: MAX_FILES,
-        format: winston.format.combine(winston.format.timestamp(), winston.format.printf(({ timestamp, level, message }) => `${timestamp} ${level}: ${message}`)),
+        // Files must never get ANSI colour, regardless of whether stdout is a TTY.
+        format: buildLogFormat(USE_JSON, false),
     });
     // debug transport collects debug+ messages into debug-%DATE%.log
     transports.push(createDailyRotateTransport('debug'));
     // errors into error-%DATE%.log
     transports.push(createDailyRotateTransport('error'));
 }
-// single console transport for terminal output (use same level)
-// In stdio mode all output must go to stderr — writing to stdout corrupts JSON-RPC framing.
+// single console transport for terminal output (use same level).
+// In stdio mode all output must go to stderr. Writing to stdout corrupts JSON-RPC framing.
 // MCP_STDIO_MODE is set by src/index.ts before this module is first imported.
 transports.push(new winston.transports.Console({
     level: DEFAULT_LEVEL,
     ...(process.env.MCP_STDIO_MODE === 'true'
         ? { stderrLevels: ['error', 'warn', 'info', 'verbose', 'debug', 'silly', 'http'] }
         : {}),
-    format: winston.format.combine(winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss.SSS' }), winston.format.colorize(), winston.format.printf(({ timestamp, level, message }) => `${timestamp} ${level}: ${message}`)),
+    format: buildLogFormat(USE_JSON),
 }));
 const logger = winston.createLogger({
     level: DEFAULT_LEVEL,
@@ -73,15 +299,17 @@ const logger = winston.createLogger({
     exitOnError: false,
 });
 export function logTransportWithDirection(direction, clientIp, req, data) {
-    const meta = {
+    // Log STRUCTURED meta (not a pre-stringified blob) so the redaction format (#220) can
+    // mask sensitive header keys (Authorization, Cookie) and known-secret values in the
+    // payload before anything is written.
+    logger.debug('transport message', {
         direction,
         clientIp,
         method: req.method,
         url: req.originalUrl,
         headers: req.headers,
         payload: safeStringify(data, 2000),
-    };
-    logger.debug(safeStringify(meta, 4000));
+    });
 }
 // --- Wire debug module into winston and route console.* to winston only ---
 // NOTE: avoid writing to both original console and winston to prevent duplicates.
@@ -121,7 +349,7 @@ export function logTransportWithDirection(direction, clientIp, req, data) {
         }
     }
     catch {
-        // debug module not available or failed to patch — ignore
+        // debug module not available or failed to patch, ignore
     }
 })();
 export default logger;

package/dist/src/server/httpServer.js

@@ -3,7 +3,7 @@ import { randomUUID, timingSafeEqual } from 'node:crypto';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import logger from '../logger.js';
+import logger, { resolveRequestId } from '../logger.js';
 import { getLocalIp } from '../utils.js';
 import actualToolsManager from '../actualToolsManager.js';
 import { getConnectionState, connectToActualForSession, shutdownActualForSession, shutdownActual, canAcceptNewSession } from '../actualConnection.js';
@@ -389,7 +389,8 @@ bindHost = 'localhost', advertisedUrl) {
                     // Run in AsyncLocalStorage context so tools can access sessionId
                     // and the adapter can enforce per-request budget ACL (#156).
                     const allowedBudgetsInit = req.allowedBudgets;
-                    await requestContext.run({ sessionId: undefined, allowedBudgets: allowedBudgetsInit, principal: resolvePrincipal(req) }, async () => {
+                    const requestId = resolveRequestId(req.get('x-correlation-id'));
+                    await requestContext.run({ sessionId: undefined, requestId, allowedBudgets: allowedBudgetsInit, principal: resolvePrincipal(req) }, async () => {
                         await transport.handleRequest(req, res, req.body);
                     });
                 }
@@ -483,7 +484,8 @@ bindHost = 'localhost', advertisedUrl) {
             // Run in AsyncLocalStorage context so tools and the adapter can access
             // sessionId (pool branch, #134) and allowedBudgets (ACL enforcement, #156).
             const allowedBudgets = req.allowedBudgets;
-            await requestContext.run({ sessionId, allowedBudgets, principal: resolvePrincipal(req) }, async () => {
+            const requestId = resolveRequestId(req.get('x-correlation-id'));
+            await requestContext.run({ sessionId, requestId, allowedBudgets, principal: resolvePrincipal(req) }, async () => {
                 await transport.handleRequest(req, res, req.body);
             });
         }

package/dist/src/tools/accounts_update.js

@@ -28,25 +28,18 @@ Example: Update account name and offbudget status:
 }`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
-        try {
-            const input = InputSchema.parse(args || {});
-            if (!input.fields || Object.keys(input.fields).length === 0) {
-                throw new Error('No fields provided to update. Include at least one field: name, offbudget, or closed.');
-            }
-            await adapter.updateAccount(input.id, input.fields);
-            return {
-                success: true,
-                accountId: input.id,
-                updatedFields: Object.keys(input.fields),
-            };
-        }
-        catch (error) {
-            if (error instanceof z.ZodError) {
-                const fieldErrors = error.issues.map((e) => `${e.path.join('.')}: ${e.message}`).join('; ');
-                throw new Error(`Invalid account update data: ${fieldErrors}`);
-            }
-            throw error;
+        // Zod validation errors are formatted centrally by actualToolsManager (#206);
+        // this tool only adds its domain guard for an empty update.
+        const input = InputSchema.parse(args || {});
+        if (!input.fields || Object.keys(input.fields).length === 0) {
+            throw new Error('No fields provided to update. Include at least one field: name, offbudget, or closed.');
         }
+        await adapter.updateAccount(input.id, input.fields);
+        return {
+            success: true,
+            accountId: input.id,
+            updatedFields: Object.keys(input.fields),
+        };
     },
 };
 export default tool;

package/dist/src/tools/categories_create.js

@@ -11,29 +11,8 @@ const tool = {
     description: "Create a category. REQUIRED: group_id (category group UUID). Use actual_category_groups_get to find available groups. Optional: is_income (boolean, defaults to false for expense categories).",
     inputSchema: InputSchema,
     call: async (args, _meta) => {
-        // Validate input with helpful error messages
-        let input;
-        try {
-            input = InputSchema.parse(args || {});
-        }
-        catch (error) {
-            if (error instanceof z.ZodError) {
-                const issues = error.issues.map(issue => {
-                    if (issue.path.includes('group_id')) {
-                        return `Invalid group_id: ${issue.message}. Use actual_category_groups_get to find valid category group UUIDs.`;
-                    }
-                    if (issue.path.includes('name')) {
-                        return `Invalid name: ${issue.message}`;
-                    }
-                    if (issue.path.includes('is_income')) {
-                        return `Invalid is_income: ${issue.message}. Must be true or false.`;
-                    }
-                    return `${issue.path.join('.')}: ${issue.message}`;
-                });
-                throw new Error(`Validation failed:\n${issues.join('\n')}`);
-            }
-            throw error;
-        }
+        // Zod validation errors are formatted centrally by actualToolsManager (#206).
+        const input = InputSchema.parse(args || {});
         try {
             // Input already has correct field names (group_id, is_income)
             // Convert null to false (LibreChat sometimes sends null instead of undefined)

package/dist/src/tools/payees_update.js

@@ -35,25 +35,18 @@ Example: Mark payee as transfer account:
 }`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
-        try {
-            const input = InputSchema.parse(args || {});
-            if (!input.fields || Object.keys(input.fields).length === 0) {
-                throw new Error('No fields provided to update. Include at least one field: name or transfer_acct.');
-            }
-            await adapter.updatePayee(input.id, input.fields);
-            return {
-                success: true,
-                payeeId: input.id,
-                updatedFields: Object.keys(input.fields),
-            };
-        }
-        catch (error) {
-            if (error instanceof z.ZodError) {
-                const fieldErrors = error.issues.map((e) => `${e.path.join('.')}: ${e.message}`).join('; ');
-                throw new Error(`Invalid payee update data: ${fieldErrors}`);
-            }
-            throw error;
+        // Zod validation errors are formatted centrally by actualToolsManager (#206);
+        // this tool only adds its domain guard for an empty update.
+        const input = InputSchema.parse(args || {});
+        if (!input.fields || Object.keys(input.fields).length === 0) {
+            throw new Error('No fields provided to update. Include at least one field: name or transfer_acct.');
         }
+        await adapter.updatePayee(input.id, input.fields);
+        return {
+            success: true,
+            payeeId: input.id,
+            updatedFields: Object.keys(input.fields),
+        };
     },
 };
 export default tool;

package/dist/src/tools/rules_create.js

@@ -55,75 +55,67 @@ Action operators: 'set', 'set-split-amount', 'link-schedule', 'append-notes'.
 Example: {stage: "post", conditionsOp: "and", conditions: [{field: "imported_payee", op: "contains", value: "Amazon"}], actions: [{op: "set", field: "category", value: "category-uuid"}]}`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
-        try {
-            const input = InputSchema.parse(args || {});
-            // Validate that actions with op="set" have a field
-            for (const action of input.actions) {
-                if (action.op === 'set' && !action.field) {
-                    throw new Error('Action with op="set" requires a "field" property (e.g., "category", "payee", "notes", "cleared")');
-                }
-                // Validate action field values for ID-type fields
-                if (action.op === 'set' && action.field) {
-                    // Check if using category field with text value instead of ID
-                    if (action.field === 'category' && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
-                        throw new Error(`Action field "category" expects a category ID (UUID), but got text value "${action.value}". ` +
-                            `Use the category UUID from your budget data. You can list categories to find the correct UUID.`);
-                    }
-                    // Check if using payee field with text value instead of ID
-                    if (action.field === 'payee' && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
-                        throw new Error(`Action field "payee" expects a payee ID (UUID), but got text value "${action.value}". ` +
-                            `Use the payee UUID from your budget data. You can list payees to find the correct UUID.`);
-                    }
-                    // Check if using account field with text value instead of ID
-                    if (action.field === 'account' && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
-                        throw new Error(`Action field "account" expects an account ID (UUID), but got text value "${action.value}". ` +
-                            `Use the account UUID from your budget data. You can list accounts to find the correct UUID.`);
-                    }
-                }
-                // Validate append-notes and prepend-notes have string values
-                if ((action.op === 'append-notes' || action.op === 'prepend-notes') && typeof action.value !== 'string') {
-                    throw new Error(`Action "${action.op}" requires a string value, but got ${typeof action.value}. ` +
-                        `Example: {op: "${action.op}", value: "text to ${action.op === 'append-notes' ? 'append' : 'prepend'}"}`);
-                }
+        // Zod validation errors are formatted centrally by actualToolsManager (#206).
+        const input = InputSchema.parse(args || {});
+        // Validate that actions with op="set" have a field
+        for (const action of input.actions) {
+            if (action.op === 'set' && !action.field) {
+                throw new Error('Action with op="set" requires a "field" property (e.g., "category", "payee", "notes", "cleared")');
             }
-            // Validate field usage to guide users toward correct field selection
-            for (const condition of input.conditions) {
-                const fieldInfo = FIELD_OPERATORS[condition.field];
-                // Validate operator is compatible with field type
-                if (fieldInfo && !fieldInfo.operators.includes(condition.op)) {
-                    throw new Error(`Invalid operator "${condition.op}" for field "${condition.field}". ` +
-                        `Field "${condition.field}" is a ${fieldInfo.type} field and only supports: ${fieldInfo.operators.join(', ')}. ` +
-                        `Please use one of these operators instead.`);
+            // Validate action field values for ID-type fields
+            if (action.op === 'set' && action.field) {
+                // Check if using category field with text value instead of ID
+                if (action.field === 'category' && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
+                    throw new Error(`Action field "category" expects a category ID (UUID), but got text value "${action.value}". ` +
+                        `Use the category UUID from your budget data. You can list categories to find the correct UUID.`);
                 }
                 // Check if using payee field with text value instead of ID
-                if (condition.field === 'payee' && typeof condition.value === 'string' && !condition.value.match(/^[0-9a-f-]{36}$/i)) {
-                    throw new Error(`Field "payee" expects a payee ID (UUID), but got text value "${condition.value}". ` +
-                        `To match payee names with text, use "imported_payee" field instead. ` +
-                        `Example: {field: "imported_payee", op: "contains", value: "${condition.value}"}`);
-                }
-                // Similar validation for account and category
-                if (['account', 'category'].includes(condition.field) && typeof condition.value === 'string' && !condition.value.match(/^[0-9a-f-]{36}$/i)) {
-                    throw new Error(`Field "${condition.field}" expects an ID (UUID), but got text value "${condition.value}". ` +
-                        `Use the ${condition.field} UUID from your budget data. List ${condition.field === 'account' ? 'accounts' : 'categories'} to find the correct UUID.`);
+                if (action.field === 'payee' && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
+                    throw new Error(`Action field "payee" expects a payee ID (UUID), but got text value "${action.value}". ` +
+                        `Use the payee UUID from your budget data. You can list payees to find the correct UUID.`);
                 }
-                // Validate oneOf/notOneOf operators expect array values
-                if (['oneOf', 'notOneOf'].includes(condition.op) && !Array.isArray(condition.value)) {
-                    throw new Error(`Operator "${condition.op}" expects an array of values, but got ${typeof condition.value}. ` +
-                        `Example: {field: "${condition.field}", op: "${condition.op}", value: ["uuid-1", "uuid-2"]}`);
+                // Check if using account field with text value instead of ID
+                if (action.field === 'account' && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
+                    throw new Error(`Action field "account" expects an account ID (UUID), but got text value "${action.value}". ` +
+                        `Use the account UUID from your budget data. You can list accounts to find the correct UUID.`);
                 }
             }
-            // No automatic translation - require explicit field names
-            const ruleData = JSON.parse(JSON.stringify(input)); // deep clone
-            const ruleId = await adapter.createRule(ruleData);
-            return { id: ruleId, success: true };
+            // Validate append-notes and prepend-notes have string values
+            if ((action.op === 'append-notes' || action.op === 'prepend-notes') && typeof action.value !== 'string') {
+                throw new Error(`Action "${action.op}" requires a string value, but got ${typeof action.value}. ` +
+                    `Example: {op: "${action.op}", value: "text to ${action.op === 'append-notes' ? 'append' : 'prepend'}"}`);
+            }
         }
-        catch (error) {
-            if (error instanceof z.ZodError) {
-                const fieldErrors = error.issues.map((e) => `${e.path.join('.')}: ${e.message}`).join('; ');
-                throw new Error(`Invalid rule data: ${fieldErrors}`);
+        // Validate field usage to guide users toward correct field selection
+        for (const condition of input.conditions) {
+            const fieldInfo = FIELD_OPERATORS[condition.field];
+            // Validate operator is compatible with field type
+            if (fieldInfo && !fieldInfo.operators.includes(condition.op)) {
+                throw new Error(`Invalid operator "${condition.op}" for field "${condition.field}". ` +
+                    `Field "${condition.field}" is a ${fieldInfo.type} field and only supports: ${fieldInfo.operators.join(', ')}. ` +
+                    `Please use one of these operators instead.`);
+            }
+            // Check if using payee field with text value instead of ID
+            if (condition.field === 'payee' && typeof condition.value === 'string' && !condition.value.match(/^[0-9a-f-]{36}$/i)) {
+                throw new Error(`Field "payee" expects a payee ID (UUID), but got text value "${condition.value}". ` +
+                    `To match payee names with text, use "imported_payee" field instead. ` +
+                    `Example: {field: "imported_payee", op: "contains", value: "${condition.value}"}`);
+            }
+            // Similar validation for account and category
+            if (['account', 'category'].includes(condition.field) && typeof condition.value === 'string' && !condition.value.match(/^[0-9a-f-]{36}$/i)) {
+                throw new Error(`Field "${condition.field}" expects an ID (UUID), but got text value "${condition.value}". ` +
+                    `Use the ${condition.field} UUID from your budget data. List ${condition.field === 'account' ? 'accounts' : 'categories'} to find the correct UUID.`);
+            }
+            // Validate oneOf/notOneOf operators expect array values
+            if (['oneOf', 'notOneOf'].includes(condition.op) && !Array.isArray(condition.value)) {
+                throw new Error(`Operator "${condition.op}" expects an array of values, but got ${typeof condition.value}. ` +
+                    `Example: {field: "${condition.field}", op: "${condition.op}", value: ["uuid-1", "uuid-2"]}`);
             }
-            throw error;
         }
+        // No automatic translation - require explicit field names
+        const ruleData = JSON.parse(JSON.stringify(input)); // deep clone
+        const ruleId = await adapter.createRule(ruleData);
+        return { id: ruleId, success: true };
     },
 };
 export default tool;

package/dist/src/tools/rules_create_or_update.js

@@ -115,89 +115,81 @@ IMPORTANT Field Types:
 Returns: { id, created: boolean } — created=true if new rule was created, false if existing rule was updated.`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
-        try {
-            const input = InputSchema.parse(args || {});
-            // ── Validate conditions ──
-            for (const condition of input.conditions) {
-                const fieldInfo = FIELD_OPERATORS[condition.field];
-                if (fieldInfo && !fieldInfo.operators.includes(condition.op)) {
-                    throw new Error(`Invalid operator "${condition.op}" for field "${condition.field}". ` +
-                        `Field "${condition.field}" is a ${fieldInfo.type} field and only supports: ${fieldInfo.operators.join(', ')}.`);
-                }
-                if (condition.field === 'payee' && typeof condition.value === 'string' && !condition.value.match(/^[0-9a-f-]{36}$/i)) {
-                    throw new Error(`Field "payee" expects a UUID, but got "${condition.value}". ` +
-                        `Use "imported_payee" for text matching instead.`);
-                }
-                if (['account', 'category'].includes(condition.field) && typeof condition.value === 'string' && !condition.value.match(/^[0-9a-f-]{36}$/i)) {
-                    throw new Error(`Field "${condition.field}" expects a UUID, but got text "${condition.value}".`);
-                }
-                if (['oneOf', 'notOneOf'].includes(condition.op) && !Array.isArray(condition.value)) {
-                    throw new Error(`Operator "${condition.op}" expects an array of values.`);
-                }
+        // Zod validation errors are formatted centrally by actualToolsManager (#206).
+        const input = InputSchema.parse(args || {});
+        // ── Validate conditions ──
+        for (const condition of input.conditions) {
+            const fieldInfo = FIELD_OPERATORS[condition.field];
+            if (fieldInfo && !fieldInfo.operators.includes(condition.op)) {
+                throw new Error(`Invalid operator "${condition.op}" for field "${condition.field}". ` +
+                    `Field "${condition.field}" is a ${fieldInfo.type} field and only supports: ${fieldInfo.operators.join(', ')}.`);
             }
-            // ── Validate actions ──
-            for (const action of input.actions) {
-                if (action.op === 'set' && !action.field) {
-                    throw new Error('Action with op="set" requires a "field" property.');
-                }
-                if (action.op === 'set' && action.field) {
-                    for (const idField of ['category', 'payee', 'account']) {
-                        if (action.field === idField && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
-                            throw new Error(`Action field "${idField}" expects a UUID, but got "${action.value}".`);
-                        }
+            if (condition.field === 'payee' && typeof condition.value === 'string' && !condition.value.match(/^[0-9a-f-]{36}$/i)) {
+                throw new Error(`Field "payee" expects a UUID, but got "${condition.value}". ` +
+                    `Use "imported_payee" for text matching instead.`);
+            }
+            if (['account', 'category'].includes(condition.field) && typeof condition.value === 'string' && !condition.value.match(/^[0-9a-f-]{36}$/i)) {
+                throw new Error(`Field "${condition.field}" expects a UUID, but got text "${condition.value}".`);
+            }
+            if (['oneOf', 'notOneOf'].includes(condition.op) && !Array.isArray(condition.value)) {
+                throw new Error(`Operator "${condition.op}" expects an array of values.`);
+            }
+        }
+        // ── Validate actions ──
+        for (const action of input.actions) {
+            if (action.op === 'set' && !action.field) {
+                throw new Error('Action with op="set" requires a "field" property.');
+            }
+            if (action.op === 'set' && action.field) {
+                for (const idField of ['category', 'payee', 'account']) {
+                    if (action.field === idField && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
+                        throw new Error(`Action field "${idField}" expects a UUID, but got "${action.value}".`);
                     }
                 }
-                if (['append-notes', 'prepend-notes'].includes(action.op) && typeof action.value !== 'string') {
-                    throw new Error(`Action "${action.op}" requires a string value.`);
+            }
+            if (['append-notes', 'prepend-notes'].includes(action.op) && typeof action.value !== 'string') {
+                throw new Error(`Action "${action.op}" requires a string value.`);
+            }
+        }
+        // Fetch existing rules and either update (matched) or create (no match) inside
+        // ONE withWriteSession cycle so the read and the write share a single lock
+        // acquisition (#142).
+        return await adapter.withWriteSession(async () => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const existingRules = await rawGetRules();
+            let matchedRule = null;
+            for (const rule of existingRules) {
+                const r = rule;
+                if (!r.id || typeof r.id !== 'string')
+                    continue;
+                const existingConditions = Array.isArray(r.conditions) ? r.conditions : [];
+                const existingConditionsOp = r.conditionsOp || 'and';
+                if (conditionsMatch(existingConditions, existingConditionsOp, input.conditions, input.conditionsOp)) {
+                    matchedRule = r;
+                    break;
                 }
             }
-            // Fetch existing rules and either update (matched) or create (no match) inside
-            // ONE withWriteSession cycle so the read and the write share a single lock
-            // acquisition (#142).
-            return await adapter.withWriteSession(async () => {
+            const ruleData = JSON.parse(JSON.stringify(input)); // deep clone for API call
+            if (matchedRule) {
+                // UPDATE existing rule. The Actual Budget API expects the FULL merged rule
+                // object passed as a single argument (matches adapter.updateRule's behaviour).
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                const existingRules = await rawGetRules();
-                let matchedRule = null;
-                for (const rule of existingRules) {
-                    const r = rule;
-                    if (!r.id || typeof r.id !== 'string')
-                        continue;
-                    const existingConditions = Array.isArray(r.conditions) ? r.conditions : [];
-                    const existingConditionsOp = r.conditionsOp || 'and';
-                    if (conditionsMatch(existingConditions, existingConditionsOp, input.conditions, input.conditionsOp)) {
-                        matchedRule = r;
-                        break;
-                    }
-                }
-                const ruleData = JSON.parse(JSON.stringify(input)); // deep clone for API call
-                if (matchedRule) {
-                    // UPDATE existing rule. The Actual Budget API expects the FULL merged rule
-                    // object passed as a single argument (matches adapter.updateRule's behaviour).
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    const merged = {
-                        id: matchedRule.id,
-                        stage: ruleData.stage ?? matchedRule.stage,
-                        conditionsOp: ruleData.conditionsOp ?? matchedRule.conditionsOp,
-                        conditions: ruleData.conditions ?? matchedRule.conditions ?? [],
-                        actions: ruleData.actions ?? matchedRule.actions ?? [],
-                    };
-                    await rawUpdateRule(merged);
-                    return { id: matchedRule.id, created: false };
-                }
-                else {
-                    // CREATE new rule
-                    const rawId = await rawCreateRule(ruleData);
-                    return { id: normalizeToId(rawId), created: true };
-                }
-            });
-        }
-        catch (error) {
-            if (error instanceof z.ZodError) {
-                const fieldErrors = error.issues.map((e) => `${e.path.join('.')}: ${e.message}`).join('; ');
-                throw new Error(`Invalid rule data: ${fieldErrors}`);
+                const merged = {
+                    id: matchedRule.id,
+                    stage: ruleData.stage ?? matchedRule.stage,
+                    conditionsOp: ruleData.conditionsOp ?? matchedRule.conditionsOp,
+                    conditions: ruleData.conditions ?? matchedRule.conditions ?? [],
+                    actions: ruleData.actions ?? matchedRule.actions ?? [],
+                };
+                await rawUpdateRule(merged);
+                return { id: matchedRule.id, created: false };
             }
-            throw error;
-        }
+            else {
+                // CREATE new rule
+                const rawId = await rawCreateRule(ruleData);
+                return { id: normalizeToId(rawId), created: true };
+            }
+        });
     },
 };
 export default tool;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.44",
+  "version": "0.6.48",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/check_coverage.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/entities_search.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js",
     "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
     "test:e2e": "npx playwright test",
     "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",