actual-mcp-server 0.5.0

package/dist/src/tools/query_run.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    query: z.string().min(1).describe('ActualQL query string to execute'),
+});
+const tool = {
+    name: 'actual_query_run',
+    description: `Execute SQL queries for advanced financial data analysis.
+
+**RECOMMENDED: Use SQL syntax** - Most reliable and well-tested format.
+
+SQL SYNTAX (Preferred):
+  SELECT [fields] FROM [table] WHERE [conditions] ORDER BY [field] DESC LIMIT [n]
+  
+  Examples:
+  • "SELECT * FROM transactions ORDER BY date DESC LIMIT 5"
+  • "SELECT id, date, amount, payee.name FROM transactions WHERE amount < 0 LIMIT 10"
+  • "SELECT id, date, amount, category.name FROM transactions WHERE date >= '2025-01-01'"
+
+IMPORTANT - Field Names:
+  • Use payee.name (NOT payee_name) for payee names
+  • Use category.name (NOT category_name) for category names
+  • Use account.name (NOT account_name) for account names
+  • Amounts are in cents: $100.00 = 10000
+
+Available Tables:
+  • transactions: id, date, amount, notes, cleared, account, payee, category
+    - Join with: payee.name, category.name, account.name
+  • accounts: id, name, type, closed, offbudget
+  • categories: id, name, group, is_income
+  • payees: id, name
+  • category_groups: id, name, is_income
+
+Common Queries:
+  • Last 5 transactions: "SELECT * FROM transactions ORDER BY date DESC LIMIT 5"
+  • By category: "SELECT id, date, amount, payee.name FROM transactions WHERE category.name = 'Food' LIMIT 10"
+  • Expenses: "SELECT id, date, amount, payee.name FROM transactions WHERE amount < 0 ORDER BY date DESC LIMIT 10"
+  • Date range: "SELECT * FROM transactions WHERE date >= '2025-01-01' AND date <= '2025-12-31'"
+
+Alternative Formats:
+  • Simple table name: "transactions" (returns all records)
+  • ActualQL objects: Not recommended, use SQL instead
+
+For details: https://actualbudget.org/docs/api/actual-ql/`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        try {
+            const input = InputSchema.parse(args || {});
+            // Detect and reject GraphQL-like syntax with nested objects
+            if (input.query.trim().startsWith('query ') && input.query.includes('{') && input.query.includes('}')) {
+                throw new Error(`GraphQL syntax is not fully supported. Please use SQL instead.\n\nExample: SELECT id, date, amount, payee.name, category.name FROM transactions ORDER BY date DESC LIMIT 5\n\nYour query attempted: ${input.query.substring(0, 100)}...`);
+            }
+            const result = await adapter.runQuery(input.query);
+            return { result };
+        }
+        catch (error) {
+            // Provide helpful error messages
+            const errorMessage = error?.message || String(error);
+            // Check if error is about payee_name, category_name, account_name
+            if (errorMessage.includes('payee_name') || errorMessage.includes('category_name') || errorMessage.includes('account_name')) {
+                throw new Error(`Field name error: Use dot notation for joins.\n• Use payee.name (NOT payee_name)\n• Use category.name (NOT category_name)\n• Use account.name (NOT account_name)\n\nExample: SELECT id, date, amount, payee.name FROM transactions LIMIT 5\n\nOriginal error: ${errorMessage}`);
+            }
+            if (errorMessage.includes('does not exist in the schema')) {
+                throw new Error(`Invalid table or field name. Available tables: transactions, accounts, categories, payees, category_groups, schedules, rules. Use dot notation for joins (e.g., category.name). Original error: ${errorMessage}`);
+            }
+            else if (errorMessage.includes('ActualQL query builder not available')) {
+                throw new Error('ActualQL query builder is not available. The Actual Budget API may not be properly initialized.');
+            }
+            else if (errorMessage.includes('parse') || errorMessage.includes('syntax')) {
+                throw new Error(`Query syntax error: ${errorMessage}\n\nRecommended: Use SQL syntax\nExample: SELECT * FROM transactions ORDER BY date DESC LIMIT 5\n\nSee tool description for more examples.`);
+            }
+            else {
+                throw new Error(`Query execution failed: ${errorMessage}`);
+            }
+        }
+    },
+};
+export default tool;

package/dist/src/tools/rules_create.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+// Define the schema for rule conditions and actions
+const ConditionSchema = z.object({
+    field: z.string().describe('Field to match (e.g., "payee", "notes", "amount", "category")'),
+    op: z.string().describe('Operation (e.g., "is", "contains", "isapprox", "gte", "lte")'),
+    value: z.union([z.string(), z.number()]).describe('Value to match against'),
+    type: z.string().optional().describe('Type of condition (e.g., "string", "number", "id")'),
+});
+const ActionSchema = z.object({
+    op: z.string()
+        .default('set')
+        .describe('Operation to perform. Options: "set" (default, assign value to field), "set-split-amount" (split transaction), "link-schedule" (link to scheduled transaction), "prepend-notes" (add text before notes), "append-notes" (add text after notes)'),
+    field: z.string()
+        .optional()
+        .describe('Field to modify - required for "set" operation. Options: "category" (transaction category), "payee" (transaction payee), "notes" (transaction notes), "cleared" (cleared status), "account" (move to different account)'),
+    value: z.union([z.string(), z.number(), z.boolean(), z.object({}).passthrough()])
+        .describe('Value to assign. Use category/payee/account UUID for "id" types, text for "string" types, number for amounts'),
+    type: z.string()
+        .optional()
+        .describe('Value type hint. Options: "id" (UUID for category/payee/account), "string" (text value), "number" (numeric value), "boolean" (true/false)'),
+    options: z.object({}).passthrough().optional().describe('Additional options for the action'),
+});
+// Operator validation map
+const FIELD_OPERATORS = {
+    'imported_payee': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
+    'payee': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
+    'account': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
+    'category': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
+    'notes': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
+    'description': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
+    'amount': { type: 'number', operators: ['is', 'gte', 'lte', 'gt', 'lt', 'isapprox'] },
+    'date': { type: 'date', operators: ['is', 'gte', 'lte', 'gt', 'lt'] },
+};
+const InputSchema = z.object({
+    stage: z.enum(['pre', 'post']).optional().default('pre').describe('When to apply the rule - "pre" (before transactions sync) or "post" (after transactions sync)'),
+    conditionsOp: z.enum(['and', 'or']).optional().default('and').describe('How to combine multiple conditions'),
+    conditions: z.array(ConditionSchema).describe('Array of conditions that must be met for the rule to apply'),
+    actions: z.array(ActionSchema).describe('Array of actions to perform when conditions are met'),
+});
+const tool = {
+    name: 'actual_rules_create',
+    description: `Create a new budget rule with conditions and actions.
+
+IMPORTANT Field Types:
+- "imported_payee" (string) - for text matching payee names. Supports: contains, matches, doesNotContain, is, isNot
+- "payee" (ID) - for exact payee ID matching. Supports: is, isNot, oneOf, notOneOf
+- "account", "category" (ID) - for account/category IDs. Supports: is, isNot, oneOf, notOneOf
+- "notes", "description" (string) - for text matching. Supports: contains, matches, doesNotContain, is, isNot
+- "amount", "date" (number/date) - supports: is, gte, lte, gt, lt
+
+Stage options: 'pre' or 'post'.
+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'}"}`);
+                }
+            }
+            // 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"]}`);
+                }
+            }
+            // 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 };
+        }
+        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}`);
+            }
+            throw error;
+        }
+    },
+};
+export default tool;

package/dist/src/tools/rules_create_or_update.js

@@ -0,0 +1,191 @@
+/**
+ * actual_rules_create_or_update
+ *
+ * Idempotent rule upsert: create a rule if none with matching conditions exists,
+ * or update the existing one in place. Prevents duplicate rules when an AI client
+ * retries or regenerates the same rule creation request.
+ *
+ * Matching logic: a rule is considered a "match" when it has the same set of
+ * (field, op, value) triples AND the same conditionsOp ("and"/"or"). Order of
+ * conditions in the array is irrelevant — the comparison is set-based.
+ *
+ * Concept and implementation adapted from the ZanzyTHEbar fork:
+ * https://github.com/ZanzyTHEbar/actual-mcp-server/blob/main/src/tools/rules_create_or_update.ts
+ * Credit: ZanzyTHEbar (https://github.com/ZanzyTHEbar)
+ *
+ * Adapted for this project's conventions:
+ * - No wrapToolCall — uses direct call() pattern
+ * - Reuses exact same ConditionSchema / ActionSchema / FIELD_OPERATORS as rules_create.ts
+ */
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+// Mirrors the same schemas used in rules_create.ts
+const ConditionSchema = z.object({
+    field: z.string().describe('Field to match (e.g., "payee", "notes", "amount", "category", "imported_payee")'),
+    op: z.string().describe('Operation (e.g., "is", "contains", "isapprox", "gte", "lte")'),
+    value: z.union([z.string(), z.number()]).describe('Value to match against'),
+    type: z.string().optional().describe('Type of condition (e.g., "string", "number", "id")'),
+});
+const ActionSchema = z.object({
+    op: z.string()
+        .default('set')
+        .describe('Operation to perform. Options: "set" (default), "set-split-amount", "link-schedule", "prepend-notes", "append-notes"'),
+    field: z.string()
+        .optional()
+        .describe('Field to modify — required for "set" op. Options: "category", "payee", "notes", "cleared", "account"'),
+    value: z.union([z.string(), z.number(), z.boolean(), z.object({}).passthrough()])
+        .describe('Value to assign. Use UUIDs for id-type fields, text for strings, numbers for amounts'),
+    type: z.string()
+        .optional()
+        .describe('Value type hint: "id", "string", "number", "boolean"'),
+    options: z.object({}).passthrough().optional().describe('Additional options for the action'),
+});
+// Same operator validation map as rules_create.ts
+const FIELD_OPERATORS = {
+    'imported_payee': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
+    'payee': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
+    'account': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
+    'category': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
+    'notes': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
+    'description': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
+    'amount': { type: 'number', operators: ['is', 'gte', 'lte', 'gt', 'lt', 'isapprox'] },
+    'date': { type: 'date', operators: ['is', 'gte', 'lte', 'gt', 'lt'] },
+};
+const InputSchema = z.object({
+    stage: z.enum(['pre', 'post']).optional().default('pre').describe('When to apply the rule — "pre" or "post"'),
+    conditionsOp: z.enum(['and', 'or']).optional().default('and').describe('How to combine multiple conditions'),
+    conditions: z.array(ConditionSchema).describe('Array of conditions that must be met'),
+    actions: z.array(ActionSchema).describe('Array of actions to perform when conditions match'),
+});
+/**
+ * Normalize a single object for stable JSON comparison by sorting its keys
+ * and stripping undefined values.
+ */
+function canonicalize(obj) {
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        if (obj[key] !== undefined)
+            sorted[key] = obj[key];
+    }
+    return JSON.stringify(sorted);
+}
+/**
+ * Return true when two rules have semantically equivalent conditions.
+ * Matching is set-based on (field, op, value) triples — order is irrelevant.
+ */
+function conditionsMatch(existingConditions, existingConditionsOp, newConditions, newConditionsOp) {
+    if ((existingConditionsOp || 'and') !== newConditionsOp)
+        return false;
+    if (!Array.isArray(existingConditions))
+        return false;
+    if (existingConditions.length !== newConditions.length)
+        return false;
+    const existingSet = new Set(existingConditions.map((c) => {
+        const cond = c;
+        return canonicalize({ field: cond.field, op: cond.op, value: cond.value });
+    }));
+    const newSet = new Set(newConditions.map((c) => canonicalize({ field: c.field, op: c.op, value: c.value })));
+    if (existingSet.size !== newSet.size)
+        return false;
+    for (const item of newSet) {
+        if (!existingSet.has(item))
+            return false;
+    }
+    return true;
+}
+const tool = {
+    name: 'actual_rules_create_or_update',
+    description: `Create a rule if no matching rule exists, or update the existing rule if one with the same conditions already exists. Prevents duplicate rules.
+
+Matching logic: a rule is considered a "match" when it has the same set of conditions (field + op + value triples) and the same conditionsOp ("and"/"or"). Condition order is irrelevant.
+
+When a match is found: the rule's actions (and stage) are REPLACED with the new values.
+When no match exists: a new rule is created.
+
+IMPORTANT Field Types:
+- "imported_payee" (string) — text matching. Supports: contains, matches, doesNotContain, is, isNot
+- "payee" (ID) — exact payee UUID. Supports: is, isNot, oneOf, notOneOf
+- "account", "category" (ID) — UUID matching. Supports: is, isNot, oneOf, notOneOf
+- "notes", "description" (string) — text matching. Supports: contains, matches, doesNotContain, is, isNot
+- "amount", "date" (number/date) — supports: is, gte, lte, gt, lt
+
+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.`);
+                }
+            }
+            // ── 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.`);
+                }
+            }
+            // ── Fetch existing rules and look for a match ──
+            const existingRules = await adapter.getRules();
+            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 ──
+                await adapter.updateRule(matchedRule.id, {
+                    stage: ruleData.stage,
+                    conditionsOp: ruleData.conditionsOp,
+                    conditions: ruleData.conditions,
+                    actions: ruleData.actions,
+                });
+                return { id: matchedRule.id, created: false };
+            }
+            else {
+                // ── CREATE new rule ──
+                const ruleId = await adapter.createRule(ruleData);
+                return { id: ruleId, 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}`);
+            }
+            throw error;
+        }
+    },
+};
+export default tool;

package/dist/src/tools/rules_delete.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+import { notFoundMsg } from '../lib/errors.js';
+const InputSchema = z.object({
+    id: z.string().describe('Rule ID to delete'),
+});
+const tool = {
+    name: 'actual_rules_delete',
+    description: `Delete a budget rule from Actual Budget. The rule will no longer be applied to new or existing transactions. This operation cannot be undone.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Pre-flight: verify rule exists (BUG-9)
+        const allRules = await adapter.getRules();
+        const ruleExists = allRules.some((r) => r.id === input.id);
+        if (!ruleExists) {
+            return {
+                error: notFoundMsg('Rule', input.id, 'actual_rules_get'),
+                success: false,
+            };
+        }
+        await adapter.deleteRule(input.id);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/rules_get.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({});
+const tool = {
+    name: 'actual_rules_get',
+    description: `List all budget rules in Actual Budget. Rules automate transaction categorization and other budget operations based on conditions. Each rule has conditions (e.g., payee matches "Amazon") and actions (e.g., set category to "Shopping").`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const rules = await adapter.getRules();
+        return { rules };
+    },
+};
+export default tool;

package/dist/src/tools/rules_update.js

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+// Define the schema for rule conditions and actions (same as create)
+const ConditionSchema = z.object({
+    field: z.string().describe('Field to match (e.g., "payee", "notes", "amount", "category")'),
+    op: z.string().describe('Operation (e.g., "is", "contains", "isapprox", "gte", "lte")'),
+    value: z.union([z.string(), z.number()]).describe('Value to match against'),
+    type: z.string().optional().describe('Type of condition (e.g., "string", "number", "id")'),
+});
+const ActionSchema = z.object({
+    op: z.string().describe('Operation to perform (e.g., "set", "set-split-amount", "link-schedule", "prepend-notes", "append-notes")'),
+    field: z.string().optional().describe('Field to set (e.g., "category", "payee", "notes", "cleared") - required for "set" operation'),
+    value: z.union([z.string(), z.number(), z.boolean(), z.object({}).passthrough()]).describe('Value to set or use in operation'),
+    type: z.string().optional().describe('Type of action (e.g., "id", "string", "number", "boolean")'),
+    options: z.object({}).passthrough().optional().describe('Additional options for the action'),
+});
+// Operator validation map
+const FIELD_OPERATORS = {
+    'imported_payee': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
+    'payee': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
+    'account': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
+    'category': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
+    'notes': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
+    'description': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
+    'amount': { type: 'number', operators: ['is', 'gte', 'lte', 'gt', 'lt', 'isapprox'] },
+    'date': { type: 'date', operators: ['is', 'gte', 'lte', 'gt', 'lt'] },
+};
+const InputSchema = z.object({
+    id: z.string().describe('Rule ID to update'),
+    fields: z.object({
+        stage: z.enum(['pre', 'post']).optional().describe('When to apply the rule - "pre" (before transactions sync) or "post" (after transactions sync)'),
+        conditionsOp: z.enum(['and', 'or']).optional().describe('How to combine multiple conditions'),
+        conditions: z.array(ConditionSchema).optional().describe('New array of conditions'),
+        actions: z.array(ActionSchema).optional().describe('New array of actions'),
+    }).describe('Fields to update'),
+});
+const tool = {
+    name: 'actual_rules_update',
+    description: `Update an existing budget rule by ID. Only provide the fields you want to change.
+
+IMPORTANT Field Types:
+- "imported_payee" (string) - for text matching payee names. Supports: contains, matches, doesNotContain, is, isNot
+- "payee" (ID) - for exact payee ID matching. Supports: is, isNot, oneOf, notOneOf
+- "account", "category" (ID) - for account/category IDs. Supports: is, isNot, oneOf, notOneOf
+- "notes", "description" (string) - for text matching. Supports: contains, matches, doesNotContain, is, isNot
+- "amount", "date" (number/date) - supports: is, gte, lte, gt, lt
+
+Stage options: 'pre' or 'post'.
+Action operators: 'set', 'set-split-amount', 'link-schedule', 'append-notes'.
+
+Do not include the rule ID in the fields object - it is provided separately.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Validate action field values
+        if (input.fields.actions) {
+            for (const action of input.fields.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'}"}`);
+                }
+            }
+        }
+        // Validate field usage to guide users toward correct field selection
+        if (input.fields.conditions) {
+            for (const condition of input.fields.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"]}`);
+                }
+            }
+        }
+        // No automatic translation - require explicit field names
+        const fields = JSON.parse(JSON.stringify(input.fields)); // deep clone
+        await adapter.updateRule(input.id, fields);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/schedules_create.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+import { UUID_PATTERN } from '../lib/constants.js';
+const RecurConfigSchema = z.object({
+    frequency: z.enum(['daily', 'weekly', 'monthly', 'yearly'])
+        .describe('How often the schedule repeats'),
+    start: z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
+        .describe('Start date in YYYY-MM-DD format'),
+    endMode: z.enum(['never', 'after_n_occurrences', 'on_date'])
+        .describe('When the schedule stops: never, after N occurrences, or on a specific date'),
+    interval: z.number().int().positive().optional()
+        .describe('Every N periods. Default: 1 (every period)'),
+    skipWeekend: z.boolean().optional()
+        .describe('If true, occurrence is moved when it falls on a weekend'),
+    weekendSolveMode: z.enum(['before', 'after']).optional()
+        .describe('Move to Friday before or Monday after the weekend. Requires skipWeekend: true'),
+    endOccurrences: z.number().int().positive().optional()
+        .describe('Number of occurrences before stopping. Required when endMode is after_n_occurrences'),
+    endDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional()
+        .describe('Date (YYYY-MM-DD) after which the schedule stops. Required when endMode is on_date'),
+});
+const InputSchema = z.object({
+    name: z.string().optional()
+        .describe('Unique display name for the schedule'),
+    payee: z.string().regex(UUID_PATTERN, 'Invalid UUID format').optional()
+        .describe('Payee UUID (from actual_payees_get)'),
+    account: z.string().regex(UUID_PATTERN, 'Invalid UUID format').optional()
+        .describe('Account UUID (from actual_accounts_list). If omitted the schedule is not tied to an account'),
+    amount: z.number().int().optional()
+        .describe('Amount in cents. Negative = expense (e.g. -5000 = -$50.00), positive = income'),
+    amountOp: z.enum(['is', 'isapprox', 'isbetween']).optional().default('is')
+        .describe('How to match the amount. "isbetween" requires amount to be an object { num1, num2 }'),
+    date: z.union([
+        z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
+            .describe('YYYY-MM-DD — one-off schedule on this specific date'),
+        RecurConfigSchema
+            .describe('RecurConfig object — recurring schedule'),
+    ]).describe('Date string for one-off or RecurConfig object for recurring. Required.'),
+    posts_transaction: z.boolean().optional().default(false)
+        .describe('When true, Actual automatically posts a transaction on each occurrence'),
+});
+const tool = {
+    name: 'actual_schedules_create',
+    description: `Create a new schedule in Actual Budget. Schedules can be one-off (supply a YYYY-MM-DD date string) or recurring (supply a RecurConfig object with frequency, start, and endMode). Amounts are in cents — negative for expenses, positive for income.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        const { date, ...rest } = input;
+        const schedule = { ...rest, date };
+        const id = await adapter.createSchedule(schedule);
+        return { id };
+    },
+};
+export default tool;