actual-mcp-server 0.5.0

package/dist/src/tools/budgets_resetHold.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    month: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/, 'month must be in YYYY-MM format').describe('Budget month in YYYY-MM format'),
+});
+const tool = {
+    name: 'actual_budgets_resetHold',
+    description: `Reset the budget hold for a month, releasing any amount previously held for next month via holdBudgetForNextMonth.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        await adapter.resetBudgetHold(input.month);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/budgets_setAmount.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({ month: z.string().min(1), categoryId: z.string().min(1), amount: z.number() });
+const tool = {
+    name: 'actual_budgets_setAmount',
+    description: "Set the budgeted amount for a specific category in a given month. Amount in cents (e.g., 50000 = $500). Use this to allocate money to spending categories for budget planning.",
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        try {
+            const result = await adapter.setBudgetAmount(input.month, input.categoryId, input.amount);
+            return { result };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            // The pre-flight in adapter.setBudgetAmount throws:
+            //   Category "${categoryId}" not found. Use actual_categories_get to list available categories.
+            // That string always contains BOTH "not found" AND "category", so && is the correct operator.
+            if (msg.toLowerCase().includes('not found') && msg.toLowerCase().includes('category')) {
+                return { success: false, error: msg };
+            }
+            throw new Error(`Failed to set budget amount: ${msg}`);
+        }
+    },
+};
+export default tool;

package/dist/src/tools/budgets_setCarryover.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    month: z.string().describe('Budget month in YYYY-MM format'),
+    categoryId: z.string().describe('Category ID'),
+    flag: z.boolean().describe('Whether to carry over unused budget to next month (true) or not (false)'),
+});
+const tool = {
+    name: 'actual_budgets_setCarryover',
+    description: `Set carryover behavior for a category in a specific month. When enabled (true), leftover budget or overspending automatically rolls into the next month's available balance. When disabled (false), each month starts fresh with no carryover - useful for fixed monthly expenses. Essential for flexible budget management.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        await adapter.setBudgetCarryover(input.month, input.categoryId, input.flag);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/budgets_switch.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    budgetName: z.string().min(1, 'budgetName must not be empty').describe('The name of the budget to switch to, as configured via BUDGET_n_NAME environment variables. ' +
+        'Use actual_budgets_list_available to see all available budget names. ' +
+        'Partial / case-insensitive match is supported (e.g. "office" matches "Office Budget").'),
+});
+const tool = {
+    name: 'actual_budgets_switch',
+    description: 'Switch to a different pre-configured budget for all subsequent operations. ' +
+        'Each budget can target a different Actual Budget server, sync ID, and encryption password. ' +
+        'Call actual_budgets_list_available first to see the available budget names. ' +
+        'The switch is instant and takes effect immediately — no server restart required.',
+    inputSchema: InputSchema,
+    call: async (args) => {
+        const { budgetName } = InputSchema.parse(args);
+        const result = await Promise.resolve(adapter.switchBudget(budgetName));
+        return {
+            success: true,
+            budgetName: result.name,
+            budgetId: result.syncId,
+            serverUrl: result.serverUrl,
+            message: `Switched to budget '${result.name}' (${result.syncId}) on ${result.serverUrl}. All subsequent operations now target this budget.`,
+        };
+    },
+};
+export default tool;

package/dist/src/tools/budgets_transfer.js

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    month: z.string().describe('Month in YYYY-MM format'),
+    fromCategoryId: z.string().describe('Source category ID to transfer from'),
+    toCategoryId: z.string().describe('Target category ID to transfer to'),
+    amount: z.number().describe('Amount to transfer in cents (positive integer)'),
+});
+const tool = {
+    name: 'actual_budgets_transfer',
+    description: 'Transfer budget amount between categories. Decreases the source category budget and increases the target category budget by the specified amount for the given month.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        if (input.amount <= 0) {
+            throw new Error('Transfer amount must be positive');
+        }
+        if (input.fromCategoryId === input.toCategoryId) {
+            throw new Error('Source and target categories must be different');
+        }
+        // Get current budget for both categories
+        const budgetMonth = await adapter.getBudgetMonth(input.month);
+        if (!budgetMonth || !budgetMonth.categoryGroups) {
+            throw new Error(`Budget not found for month ${input.month}`);
+        }
+        // Flatten categories from all groups
+        const allCategories = budgetMonth.categoryGroups.flatMap((group) => group.categories || []);
+        const fromBudget = allCategories.find((c) => c.id === input.fromCategoryId);
+        const toBudget = allCategories.find((c) => c.id === input.toCategoryId);
+        if (!fromBudget) {
+            throw new Error(`Source category ${input.fromCategoryId} not found in budget`);
+        }
+        if (!toBudget) {
+            throw new Error(`Target category ${input.toCategoryId} not found in budget`);
+        }
+        const currentFromAmount = fromBudget.budgeted || 0;
+        const currentToAmount = toBudget.budgeted || 0;
+        // Check if source has enough budget
+        if (currentFromAmount < input.amount) {
+            throw new Error(`Insufficient budget in source category. Available: ${currentFromAmount}, Requested: ${input.amount}`);
+        }
+        // Perform the transfer - use adapter.setBudgetAmount directly (already queued)
+        // Note: Don't use batchBudgetUpdates as it creates a nested queue deadlock
+        await adapter.setBudgetAmount(input.month, input.fromCategoryId, currentFromAmount - input.amount);
+        await adapter.setBudgetAmount(input.month, input.toCategoryId, currentToAmount + input.amount);
+        return {
+            result: {
+                success: true,
+                transferred: input.amount,
+                fromCategory: {
+                    id: input.fromCategoryId,
+                    previousAmount: currentFromAmount,
+                    newAmount: currentFromAmount - input.amount,
+                },
+                toCategory: {
+                    id: input.toCategoryId,
+                    previousAmount: currentToAmount,
+                    newAmount: currentToAmount + input.amount,
+                },
+            },
+        };
+    },
+};
+export default tool;

package/dist/src/tools/categories_create.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+const InputSchema = z.object({
+    name: CommonSchemas.name,
+    group_id: CommonSchemas.categoryGroupId,
+    is_income: z.boolean().nullable().optional(),
+}).passthrough(); // Allow other fields to pass through
+const tool = {
+    name: 'actual_categories_create',
+    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;
+        }
+        try {
+            // Input already has correct field names (group_id, is_income)
+            // Convert null to false (LibreChat sometimes sends null instead of undefined)
+            const normalizedInput = {
+                name: input.name,
+                group_id: input.group_id,
+                is_income: input.is_income ?? false,
+            };
+            const result = await adapter.createCategory(normalizedInput);
+            return {
+                success: true,
+                categoryId: result,
+                message: `Category "${input.name}" created successfully`
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Provide helpful error messages for common issues
+            if (errorMessage.includes('groupId is required') || errorMessage.includes('group_id')) {
+                throw new Error(`Failed to create category: Invalid or missing group_id. Use actual_category_groups_get to get available category groups first.`);
+            }
+            if (errorMessage.includes('already exists') || errorMessage.includes('duplicate')) {
+                throw new Error(`Failed to create category: A category named "${input.name}" already exists in this group.`);
+            }
+            throw new Error(`Failed to create category: ${errorMessage}`);
+        }
+    },
+};
+export default tool;

package/dist/src/tools/categories_delete.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    id: z.string().describe('Category ID to delete'),
+});
+const tool = {
+    name: 'actual_categories_delete',
+    description: 'Delete a category from Actual Budget. Transactions using this category will need to be recategorized. This operation cannot be undone.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        await adapter.deleteCategory(input.id);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/categories_get.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({});
+const tool = {
+    name: 'actual_categories_get',
+    description: 'List all budget categories organized by category groups. Categories are spending/income buckets (e.g., Groceries, Rent, Salary) used for budgeting and transaction categorization. Returns both grouped view and flat list with category IDs, names, and group assignments.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        InputSchema.parse(args || {});
+        const result = await adapter.getCategories();
+        return { result };
+    },
+};
+export default tool;

package/dist/src/tools/categories_update.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    id: z.string().describe('Category ID to update'),
+    fields: z.object({
+        name: z.string().optional().describe('New category name'),
+        group_id: z.string().optional().describe('Category group ID to move this category to'),
+        is_income: z.boolean().optional().describe('Whether this is an income category'),
+        hidden: z.boolean().optional().describe('Whether this category is hidden'),
+    }).describe('Fields to update'),
+});
+const tool = {
+    name: 'actual_categories_update',
+    description: 'Update an existing category in Actual Budget. You can rename the category, move it to a different group, or change its properties.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        await adapter.updateCategory(input.id, input.fields);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/category_groups_create.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    name: z.string().min(1).describe('Category group name'),
+    is_income: z.boolean().optional().describe('Whether this is an income category group (default: false)'),
+    hidden: z.boolean().optional().describe('Whether this group is hidden (default: false)'),
+});
+const tool = {
+    name: 'actual_category_groups_create',
+    description: `Create a new category group in Actual Budget. Category groups help organize categories into logical sections (e.g., "Fixed Expenses", "Variable Expenses", "Savings Goals"). After creating a group, you can move categories into it.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        const groupId = await adapter.createCategoryGroup(input);
+        return { id: groupId, success: true };
+    },
+};
+export default tool;

package/dist/src/tools/category_groups_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('Category group ID to delete'),
+});
+const tool = {
+    name: 'actual_category_groups_delete',
+    description: `Delete a category group from Actual Budget. Note: Categories within the group will be moved to a default group or ungrouped. This operation cannot be undone.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Pre-flight: verify category group exists (BUG-10)
+        const groups = await adapter.getCategoryGroups();
+        const groupExists = groups.some((g) => g.id === input.id);
+        if (!groupExists) {
+            return {
+                error: notFoundMsg('Category group', input.id, 'actual_category_groups_get'),
+                success: false,
+            };
+        }
+        await adapter.deleteCategoryGroup(input.id);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/category_groups_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_category_groups_get',
+    description: `List all category groups in Actual Budget. Category groups organize related categories together (e.g., "Monthly Bills" group contains "Rent", "Utilities", "Internet" categories). Each group has an ID, name, and optional properties.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const groups = await adapter.getCategoryGroups();
+        return { groups };
+    },
+};
+export default tool;

package/dist/src/tools/category_groups_update.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    id: z.string().describe('Category group ID to update'),
+    fields: z.object({
+        name: z.string().optional().describe('New group name'),
+        is_income: z.boolean().optional().describe('Whether this is an income category group'),
+        hidden: z.boolean().optional().describe('Whether this group is hidden'),
+    }).describe('Fields to update'),
+});
+const tool = {
+    name: 'actual_category_groups_update',
+    description: `Update an existing category group in Actual Budget. You can rename the group, change whether it's an income group, or hide/show it.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        await adapter.updateCategoryGroup(input.id, input.fields);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/get_id_by_name.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const ALLOWED_TYPES = ['accounts', 'schedules', 'categories', 'payees'];
+const InputSchema = z.object({
+    type: z
+        .enum(ALLOWED_TYPES)
+        .describe("Entity type to look up. One of: 'accounts', 'schedules', 'categories', 'payees'"),
+    name: z
+        .string()
+        .min(1, 'Name cannot be empty')
+        .describe('Exact name of the entity to resolve to an ID'),
+});
+const tool = {
+    name: 'actual_get_id_by_name',
+    description: `Resolve an entity name to its UUID.
+
+Looks up the UUID for any Account, Payee, Category, or Schedule by their display name.
+This is useful when you know the human-readable name but need the ID for other API calls.
+
+Allowed types: 'accounts', 'schedules', 'categories', 'payees'
+
+Returns the UUID string for the matching entity.
+
+Examples:
+- Find the ID for an account named "Checking Account"
+- Find the ID for a category named "Groceries"
+- Find the ID for a payee named "Amazon"
+- Find the ID for a schedule named "Rent"`,
+    inputSchema: InputSchema,
+    call: async (args) => {
+        const input = InputSchema.parse(args);
+        const id = await adapter.getIDByName(input.type, input.name);
+        return { id, type: input.type, name: input.name };
+    },
+};
+export default tool;

package/dist/src/tools/index.js

@@ -0,0 +1,63 @@
+// Auto-generated index for all tool modules
+export { default as accounts_close } from './accounts_close.js';
+export { default as accounts_create } from './accounts_create.js';
+export { default as accounts_delete } from './accounts_delete.js';
+export { default as accounts_get_balance } from './accounts_get_balance.js';
+export { default as accounts_list } from './accounts_list.js';
+export { default as accounts_reopen } from './accounts_reopen.js';
+export { default as accounts_update } from './accounts_update.js';
+export { default as bank_sync } from './bank_sync.js';
+export { default as budget_updates_batch } from './budget_updates_batch.js';
+export { default as budgets_get_all } from './budgets_get_all.js';
+export { default as budgets_list_available } from './budgets_list_available.js';
+export { default as budgets_switch } from './budgets_switch.js';
+export { default as budgets_getMonth } from './budgets_getMonth.js';
+export { default as budgets_getMonths } from './budgets_getMonths.js';
+export { default as budgets_holdForNextMonth } from './budgets_holdForNextMonth.js';
+export { default as budgets_resetHold } from './budgets_resetHold.js';
+export { default as budgets_setAmount } from './budgets_setAmount.js';
+export { default as budgets_setCarryover } from './budgets_setCarryover.js';
+export { default as budgets_transfer } from './budgets_transfer.js';
+export { default as categories_create } from './categories_create.js';
+export { default as categories_delete } from './categories_delete.js';
+export { default as categories_get } from './categories_get.js';
+export { default as categories_update } from './categories_update.js';
+export { default as category_groups_create } from './category_groups_create.js';
+export { default as category_groups_delete } from './category_groups_delete.js';
+export { default as category_groups_get } from './category_groups_get.js';
+export { default as category_groups_update } from './category_groups_update.js';
+export { default as payee_rules_get } from './payee_rules_get.js';
+export { default as payees_create } from './payees_create.js';
+export { default as payees_delete } from './payees_delete.js';
+export { default as payees_get } from './payees_get.js';
+export { default as payees_merge } from './payees_merge.js';
+export { default as payees_update } from './payees_update.js';
+export { default as get_id_by_name } from './get_id_by_name.js';
+export { default as server_get_version } from './server_get_version.js';
+export { default as query_run } from './query_run.js';
+export { default as rules_create } from './rules_create.js';
+export { default as rules_create_or_update } from './rules_create_or_update.js';
+export { default as rules_delete } from './rules_delete.js';
+export { default as rules_get } from './rules_get.js';
+export { default as rules_update } from './rules_update.js';
+export { default as schedules_create } from './schedules_create.js';
+export { default as schedules_delete } from './schedules_delete.js';
+export { default as schedules_get } from './schedules_get.js';
+export { default as schedules_update } from './schedules_update.js';
+export { default as server_info } from './server_info.js';
+export { default as transactions_create } from './transactions_create.js';
+export { default as transactions_delete } from './transactions_delete.js';
+export { default as transactions_filter } from './transactions_filter.js';
+export { default as transactions_get } from './transactions_get.js';
+export { default as transactions_import } from './transactions_import.js';
+export { default as transactions_search_by_amount } from './transactions_search_by_amount.js';
+export { default as transactions_search_by_category } from './transactions_search_by_category.js';
+export { default as transactions_search_by_month } from './transactions_search_by_month.js';
+export { default as transactions_search_by_payee } from './transactions_search_by_payee.js';
+export { default as transactions_summary_by_category } from './transactions_summary_by_category.js';
+export { default as transactions_summary_by_payee } from './transactions_summary_by_payee.js';
+export { default as transactions_uncategorized } from './transactions_uncategorized.js';
+export { default as transactions_update } from './transactions_update.js';
+export { default as transactions_update_batch } from './transactions_update_batch.js';
+export { default as session_close } from './session_close.js';
+export { default as session_list } from './session_list.js';

package/dist/src/tools/payee_rules_get.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+import { notFoundMsg } from '../lib/errors.js';
+const InputSchema = z.object({
+    payeeId: z.string().describe('ID of the payee to get rules for'),
+});
+const tool = {
+    name: 'actual_payee_rules_get',
+    description: `Get all payee rules associated with a specific payee. Returns PayeeRule objects that show how transactions with this payee are automatically processed (conditions and actions).`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Pre-flight: verify payee exists and get its name (BUG-3)
+        const payees = await adapter.getPayees();
+        const payee = payees.find((p) => p.id === input.payeeId);
+        if (!payee) {
+            return {
+                error: notFoundMsg('Payee', input.payeeId, 'actual_payees_get'),
+                rules: [],
+                count: 0,
+            };
+        }
+        const rules = await adapter.getPayeeRules(input.payeeId);
+        return { rules, count: rules.length, payeeName: payee.name };
+    },
+};
+export default tool;

package/dist/src/tools/payees_create.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+import adapter from '../lib/actual-adapter.js';
+export default createTool({
+    name: 'actual_payees_create',
+    description: 'Create a new payee in Actual Budget',
+    schema: z.object({
+        name: CommonSchemas.name,
+        notes: CommonSchemas.notes
+    }),
+    handler: async (input) => {
+        return await adapter.createPayee(input);
+    },
+    examples: [
+        {
+            description: 'Create a payee for a grocery store',
+            input: { name: 'Whole Foods' },
+        },
+        {
+            description: 'Create a payee with notes',
+            input: { name: 'Electric Company', notes: 'Monthly utility payment' },
+        },
+    ],
+});

package/dist/src/tools/payees_delete.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    id: z.string().describe('Payee ID to delete'),
+});
+const tool = {
+    name: 'actual_payees_delete',
+    description: 'Delete a payee from Actual Budget. Transactions using this payee will have it removed. This operation cannot be undone.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        await adapter.deletePayee(input.id);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/payees_get.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({});
+const tool = {
+    name: 'actual_payees_get',
+    description: "List all payees in Actual Budget. Payees represent merchants, service providers, individuals, or other entities you transact with. Returns payee ID, name, and optional transfer account information for internal transfers.",
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        InputSchema.parse(args || {});
+        const result = await adapter.getPayees();
+        return { result };
+    },
+};
+export default tool;

package/dist/src/tools/payees_merge.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    targetId: z.string().describe('ID of the target payee to merge into (this payee will be retained)'),
+    mergeIds: z.array(z.string()).describe('Array of payee IDs to merge into the target payee (these will be consolidated)'),
+});
+const tool = {
+    name: 'actual_payees_merge',
+    description: `Merge one or more payees into a target payee. This consolidates duplicate payees by merging the specified payees into the target, retaining the name of the target payee. All transactions from merged payees will be reassigned to the target payee.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        await adapter.mergePayees(input.targetId, input.mergeIds);
+        return { success: true, message: `Successfully merged ${input.mergeIds.length} payee(s) into target payee` };
+    },
+};
+export default tool;

package/dist/src/tools/payees_update.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { CommonSchemas } from '../lib/schemas/common.js';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    id: CommonSchemas.payeeId,
+    fields: z.object({
+        name: CommonSchemas.name.optional(),
+        transfer_acct: CommonSchemas.accountId.optional().describe('Transfer account if payee represents account transfer'),
+        category: CommonSchemas.categoryId.optional().nullable().describe('Default category ID for this payee (null to clear)'),
+    }).strict().optional().describe('Fields to update - only recognized fields allowed'),
+});
+const tool = {
+    name: 'actual_payees_update',
+    description: `Update an existing payee in Actual Budget.
+
+Updatable fields:
+- name: Payee name (1-255 chars)
+- transfer_acct: Transfer account ID if this payee represents an account transfer (optional)
+- category: Default category ID to auto-assign to transactions from this payee (optional, null to clear)
+
+Example: Update payee name:
+{
+  "id": "<payee-uuid>",
+  "fields": {
+    "name": "Grocery Store"
+  }
+}
+
+Example: Mark payee as transfer account:
+{
+  "id": "<payee-uuid>",
+  "fields": {
+    "transfer_acct": "<account-uuid>"
+  }
+}`,
+    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;
+        }
+    },
+};
+export default tool;