actual-mcp-server 0.6.44 → 0.6.45

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.45 | **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.45",
     "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/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/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/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.45",
   "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/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",