actual-mcp-server 0.5.0

package/dist/src/tests/observability.smoke.test.js

@@ -0,0 +1,18 @@
+import { incrementToolCall, getMetricsText } from '../observability.js';
+export default async function runObservabilitySmoke() {
+    console.log('Running observability smoke test');
+    // Should not throw even if prom-client isn't installed
+    await incrementToolCall('test.tool');
+    const metrics = await getMetricsText();
+    if (metrics !== null && typeof metrics !== 'string') {
+        throw new Error('getMetricsText returned unexpected type');
+    }
+    console.log('✅ Observability smoke test passed');
+}
+const mainUrl = typeof process !== 'undefined' && process.argv && process.argv[1] ? `file://${process.argv[1]}` : '';
+if (import.meta.url === mainUrl) {
+    runObservabilitySmoke().catch(err => {
+        console.error('Observability smoke test failed:', err);
+        process.exit(1);
+    });
+}

package/dist/src/tests/testMcpClient.js

@@ -0,0 +1,170 @@
+export async function testMcpClient(advertisedUrl, port, httpPath) {
+    // Try builtin fetch or fallback to node-fetch if necessary
+    const globalFetch = globalThis.fetch;
+    const fetchAny = globalFetch ?? (await import('node-fetch')).default;
+    const fetchFn = fetchAny;
+    const base = new URL(advertisedUrl);
+    // quick probe endpoint
+    const probeUrl = `${base.origin}/.well-known/oauth-protected-resource`;
+    console.info(`MCP client test: probing ${probeUrl}`);
+    const probeRes = await fetchFn(probeUrl, { method: 'GET' });
+    if (!probeRes.ok) {
+        throw new Error(`Probe GET failed: ${probeRes.status} ${probeRes.statusText}`);
+    }
+    const probeJsonRaw = await probeRes.json();
+    const probeJsonObj = probeJsonRaw && typeof probeJsonRaw === 'object' ? probeJsonRaw : undefined;
+    const resultRaw = probeJsonObj && 'result' in probeJsonObj ? probeJsonObj.result : probeJsonRaw;
+    if (!resultRaw)
+        throw new Error('Probe response missing result');
+    // validate presence and types with runtime guards
+    const resultObj = resultRaw && typeof resultRaw === 'object' ? resultRaw : undefined;
+    if (!resultObj)
+        throw new Error('Probe result is not an object');
+    const serverInstructions = resultObj['serverInstructions'];
+    if (serverInstructions && typeof serverInstructions === 'object') {
+        if (typeof serverInstructions['instructions'] !== 'string') {
+            throw new Error('serverInstructions missing or wrong type');
+        }
+    }
+    const capabilitiesVal = resultObj['capabilities'];
+    if (!capabilitiesVal || typeof capabilitiesVal !== 'object' || !('tools' in capabilitiesVal)) {
+        throw new Error('capabilities.tools missing or wrong type');
+    }
+    const toolsVal = resultObj['tools'];
+    if (!Array.isArray(toolsVal)) {
+        throw new Error('tools missing or not array');
+    }
+    console.info('Probe OK: capabilities/tools/serverInstructions present');
+    // Now do JSON-RPC initialize + tools/list using the HTTP endpoint
+    const rpcUrl = `${base.origin}${httpPath}`;
+    const initPayload = {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+            protocolVersion: '2025-06-18',
+            capabilities: {},
+            clientInfo: { name: 'actual-mcp-server-client-test', version: '0.0.1' },
+        },
+    };
+    console.info(`MCP client test: POST initialize -> ${rpcUrl}`);
+    // Server expects the client to accept both JSON responses and SSE frames
+    const commonPostHeaders = { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' };
+    const initRes = await fetchFn(rpcUrl, {
+        method: 'POST',
+        headers: commonPostHeaders,
+        body: JSON.stringify(initPayload),
+    });
+    if (!initRes.ok) {
+        throw new Error(`Initialize POST failed: ${initRes.status} ${initRes.statusText}`);
+    }
+    const initJsonRaw = await initRes.json();
+    const initJson = (initJsonRaw && typeof initJsonRaw === 'object') ? initJsonRaw : undefined;
+    if (!initJson || !('result' in initJson)) {
+        throw new Error(`Initialize response missing result: ${JSON.stringify(initJsonRaw)}`);
+    }
+    let sessionId = undefined;
+    if (initRes.headers && typeof initRes.headers === 'object') {
+        const h = initRes.headers;
+        if (typeof h.get === 'function') {
+            sessionId = h.get('mcp-session-id') ?? undefined;
+        }
+        else if ('mcp-session-id' in h) {
+            sessionId = h['mcp-session-id'];
+        }
+    }
+    if (sessionId)
+        console.info(`Received session id header: ${sessionId}`);
+    // Validate initialize result fields (capabilities/tools/serverInstructions)
+    const initResultRaw = initJson['result'];
+    const initResult = initResultRaw && typeof initResultRaw === 'object' ? initResultRaw : undefined;
+    if (!initResult || typeof initResult['capabilities'] !== 'object') {
+        throw new Error('initialize result.capabilities missing or not object');
+    }
+    // Accept either a tools array or derive tools from capabilities.tools object
+    let initTools = [];
+    if (Array.isArray(initResult['tools'])) {
+        initTools = initResult['tools'];
+    }
+    else if (initResult['capabilities'] && typeof initResult['capabilities']['tools'] === 'object') {
+        initTools = Object.keys(initResult['capabilities']['tools']);
+    }
+    else {
+        throw new Error('initialize result.tools missing or not array and capabilities.tools not present');
+    }
+    // serverInstructions may be a string, an object { instructions }, or absent.
+    const si = initResult['serverInstructions'];
+    if (!si) {
+        console.warn('Warning: serverInstructions missing from initialize result — continuing tests');
+    }
+    else if (typeof si === 'string') {
+        // ok
+    }
+    else if (typeof si === 'object' && typeof si['instructions'] === 'string') {
+        // ok
+    }
+    else {
+        console.warn('Warning: serverInstructions present but in unexpected shape — continuing tests');
+    }
+    // replace usages below with initTools where needed
+    console.info('Initialize OK: capabilities/tools/serverInstructions present');
+    // call tools/list (JSON-RPC) to verify RPC path works
+    const listPayload = { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} };
+    const listHeaders = { ...commonPostHeaders };
+    if (sessionId)
+        listHeaders['mcp-session-id'] = sessionId;
+    const listRes = await fetchFn(rpcUrl, {
+        method: 'POST',
+        headers: listHeaders,
+        body: JSON.stringify(listPayload),
+    });
+    if (!listRes.ok)
+        throw new Error(`tools/list failed: ${listRes.status}`);
+    const listJsonRaw = await listRes.json();
+    const listJsonObj = listJsonRaw && typeof listJsonRaw === 'object' ? listJsonRaw : undefined;
+    if (!listJsonObj || !('result' in listJsonObj))
+        throw new Error('tools/list returned invalid result');
+    const listResult = listJsonObj['result'];
+    if (!listResult || typeof listResult !== 'object' || !('tools' in listResult) || !Array.isArray(listResult['tools'])) {
+        throw new Error('tools/list returned invalid tools array');
+    }
+    const toolsArray = listResult['tools'];
+    const listed = toolsArray.map((t) => (t && typeof t === 'object' && 'name' in t ? t['name'] : String(t))).join(', ');
+    console.info(`tools/list OK: ${listed}`);
+    // Optionally, attempt to call each tool with empty args (non-destructive expectation)
+    for (const tool of toolsArray) {
+        const toolObj = tool && typeof tool === 'object' ? tool : undefined;
+        const name = toolObj && typeof toolObj['name'] === 'string' ? toolObj['name'] : String(tool);
+        console.info(`Calling tool: ${name}`);
+        const callPayload = {
+            jsonrpc: '2.0',
+            id: Math.floor(Math.random() * 1_000_000),
+            method: 'tools/call',
+            params: { name, arguments: {} },
+        };
+        const callRes = await fetchFn(rpcUrl, {
+            method: 'POST',
+            headers: listHeaders,
+            body: JSON.stringify(callPayload),
+        });
+        if (!callRes.ok) {
+            console.warn(`tools/call ${name} HTTP ${callRes.status}`);
+            continue;
+        }
+        const callJsonRaw = await callRes.json();
+        if (callJsonRaw && typeof callJsonRaw === 'object') {
+            const callJson = callJsonRaw;
+            if ('error' in callJson && callJson.error) {
+                console.warn(`tools/call ${name} returned error: ${JSON.stringify(callJson.error).slice(0, 200)}`);
+            }
+            else {
+                console.info(`tools/call ${name} OK (result truncated): ${JSON.stringify(callJson.result).slice(0, 200)}`);
+            }
+        }
+        else {
+            console.info(`tools/call ${name} OK (result truncated): ${JSON.stringify(callJsonRaw).slice(0, 200)}`);
+        }
+    }
+    console.info('MCP client tests completed successfully');
+    return;
+}

package/dist/src/tests_adapter_runner.js

@@ -0,0 +1,86 @@
+import { strict as assert } from 'assert';
+import { normalizeToTransactionArray, normalizeToId, normalizeImportResult } from './lib/actual-adapter.js';
+async function runAdapterTests() {
+    // normalizeToTransactionArray
+    const single = { id: 't1', amount: 100 };
+    const arrObjs = [{ id: 't1' }, { id: 't2' }];
+    const idList = ['t1', 't2'];
+    const r1 = normalizeToTransactionArray(single);
+    assert.equal(Array.isArray(r1), true);
+    assert.equal(r1.length, 1);
+    assert.equal(r1[0].id, 't1');
+    const txArr = normalizeToTransactionArray(arrObjs);
+    assert.equal(txArr.length, 2);
+    assert.equal(txArr[1].id, 't2');
+    const txFromIds = normalizeToTransactionArray(idList);
+    assert.equal(txFromIds.length, 2);
+    assert.equal(txFromIds[0].id, 't1');
+    const txEmpty = normalizeToTransactionArray(null);
+    assert.equal(Array.isArray(txEmpty), true);
+    assert.equal(txEmpty.length, 0);
+    // normalizeToId
+    assert.equal(normalizeToId('abc'), 'abc');
+    assert.equal(normalizeToId({ id: 'xyz' }), 'xyz');
+    assert.equal(normalizeToId(['first', 'second']), 'first');
+    assert.equal(normalizeToId(null), '');
+    // normalizeImportResult
+    const raw = { added: ['a'], updated: ['b'], errors: ['e'] };
+    const imp = normalizeImportResult(raw);
+    assert.deepEqual(imp.added, ['a']);
+    assert.deepEqual(imp.updated, ['b']);
+    assert.deepEqual(imp.errors, ['e']);
+    const imp2 = normalizeImportResult(null);
+    assert.deepEqual(imp2.added, []);
+    assert.deepEqual(imp2.updated, []);
+    assert.deepEqual(imp2.errors, []);
+    console.log('✅ Adapter normalization tests passed');
+}
+runAdapterTests().catch((e) => {
+    console.error('Adapter tests failed:', e);
+    process.exit(2);
+});
+// Concurrency and retry tests
+import { callWithRetry, getConcurrencyState, setMaxConcurrency } from './lib/actual-adapter.js';
+import retry from './lib/retry.js';
+async function runConcurrencyAndRetryTests() {
+    console.log('Running concurrency and retry tests...');
+    // Concurrency test: set max concurrency to 1 and start 3 tasks that resolve after a delay.
+    setMaxConcurrency(1);
+    const task = (id, delayMs = 50) => async () => {
+        await new Promise(r => setTimeout(r, delayMs));
+        return `done-${id}`;
+    };
+    const p1 = callWithRetry(task(1, 80));
+    const p2 = callWithRetry(task(2, 60));
+    const p3 = callWithRetry(task(3, 40));
+    // allow microtask scheduling
+    await new Promise(r => setTimeout(r, 10));
+    const stateDuring = getConcurrencyState();
+    if (stateDuring.maxConcurrency !== 1)
+        throw new Error('maxConcurrency not set');
+    if (stateDuring.running < 1)
+        throw new Error('expected at least one running task');
+    const results = await Promise.all([p1, p2, p3]);
+    if (!results.includes('done-1') || !results.includes('done-2') || !results.includes('done-3')) {
+        throw new Error('concurrency tasks did not complete as expected');
+    }
+    // Retry test: function fails twice then succeeds
+    let attempts = 0;
+    const flaky = async () => {
+        attempts++;
+        if (attempts < 3)
+            throw new Error('transient');
+        return 'ok';
+    };
+    const res = await callWithRetry(() => retry(flaky, { retries: 3, backoffMs: 5 }));
+    if (res !== 'ok')
+        throw new Error('retry did not return ok');
+    if (attempts !== 3)
+        throw new Error(`retry attempts expected 3 but got ${attempts}`);
+    console.log('✅ Concurrency and retry tests passed');
+}
+// Run the extra tests after the main suite
+runConcurrencyAndRetryTests().catch(e => {
+    console.error('Concurrency/retry tests failed:', e);
+    process.exit(2);
+});

package/dist/src/tools/accounts_close.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    id: z.string().describe('Account ID to close'),
+});
+const tool = {
+    name: 'actual_accounts_close',
+    description: `Mark an account as closed in Actual Budget. Closed accounts are hidden from most views but their transaction history is preserved. Useful for accounts that are no longer active but you want to keep the historical data.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        await adapter.closeAccount(input.id);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/accounts_create.js

@@ -0,0 +1,27 @@
+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_accounts_create',
+    description: 'Create a new account in Actual Budget',
+    schema: z.object({
+        id: z.string().optional(),
+        name: CommonSchemas.name,
+        balance: CommonSchemas.optionalAmountCents
+    }),
+    handler: async (input) => {
+        const accountPayload = { id: input.id, name: input.name, balance: input.balance };
+        return await adapter.createAccount(accountPayload, input.balance);
+    },
+    examples: [
+        {
+            description: 'Create a checking account with $1000 initial balance',
+            input: { name: 'Checking', balance: 100000 },
+        },
+        {
+            description: 'Create a savings account with no initial balance',
+            input: { name: 'Savings' },
+        },
+    ],
+});

package/dist/src/tools/accounts_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('Account ID to delete'),
+});
+const tool = {
+    name: 'actual_accounts_delete',
+    description: 'Delete an account from Actual Budget. Note: The account must not have any transactions. This operation cannot be undone.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        await adapter.deleteAccount(input.id);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/accounts_get_balance.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+import { notFoundMsg } from '../lib/errors.js';
+const InputSchema = z.object({
+    id: z.string().min(1, 'Account ID is required').describe('The UUID of the account'),
+    cutoff: z.string().optional().describe('Optional cutoff date (YYYY-MM-DD format)')
+}).strict();
+const tool = {
+    name: 'actual_accounts_get_balance',
+    description: `Get the current balance of a specific account.
+
+Required:
+- id: Account UUID
+
+Optional:
+- cutoff: Date to calculate balance up to (YYYY-MM-DD format)
+
+Returns the account balance as a number (in cents), or an error if the account does not exist.
+
+Example:
+{
+  "id": "791f738b-847b-48cc-b32b-bbcf2bc8314f"
+}`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Pre-flight: verify account exists (BUG-5)
+        const accounts = await adapter.getAccounts();
+        const account = accounts.find((a) => a.id === input.id);
+        if (!account) {
+            return {
+                error: notFoundMsg('Account', input.id, 'actual_accounts_list'),
+                balance: null,
+            };
+        }
+        const result = await adapter.getAccountBalance(input.id, input.cutoff);
+        return { balance: result, accountName: account.name };
+    },
+};
+export default tool;

package/dist/src/tools/accounts_list.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({});
+const tool = {
+    name: 'actual_accounts_list',
+    description: "List all accounts in Actual Budget including checking, savings, credit cards, and investment accounts. Returns account ID, name, balance (in cents), on-budget/off-budget status, and open/closed state.",
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        // Single API session: getAccounts + all balances in one withActualApi cycle.
+        // Calling getAccountBalance() per-account would open N separate sessions and
+        // overwhelm the Actual server with concurrent init/shutdown cycles.
+        const result = await adapter.getAccountsWithBalances();
+        return { result };
+    },
+};
+export default tool;

package/dist/src/tools/accounts_reopen.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    id: z.string().describe('Account ID to reopen'),
+});
+const tool = {
+    name: 'actual_accounts_reopen',
+    description: `Reopen a previously closed account in Actual Budget. The account will become active again and visible in all views. All historical transactions remain intact.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        await adapter.reopenAccount(input.id);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/accounts_update.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { CommonSchemas } from '../lib/schemas/common.js';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    id: CommonSchemas.accountId,
+    fields: z.object({
+        name: CommonSchemas.name.optional(),
+        offbudget: CommonSchemas.offBudget,
+        closed: CommonSchemas.closed,
+    }).strict().optional().describe('Fields to update - only recognized fields allowed'),
+});
+const tool = {
+    name: 'actual_accounts_update',
+    description: `Update an account's properties in Actual Budget.
+
+Updatable fields:
+- name: Account name (1-255 chars)
+- offbudget: Exclude from budget (true/false)
+- closed: Mark as closed (true/false)
+
+Example: Update account name and offbudget status:
+{
+  "id": "<account-uuid>",
+  "fields": {
+    "name": "Checking Account",
+    "offbudget": false
+  }
+}`,
+    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;
+        }
+    },
+};
+export default tool;

package/dist/src/tools/bank_sync.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    accountId: z.string().nullable().optional().describe('Optional account ID to sync a specific account. If omitted, syncs all linked accounts.'),
+});
+const tool = {
+    name: 'actual_bank_sync',
+    description: 'Trigger 3rd party bank sync (GoCardless, SimpleFIN) for linked bank accounts. Returns immediately with an error if no bank-linked accounts are found. When bank-linked accounts exist, waits up to 30 seconds for the provider to confirm the operation and surfaces errors such as rate limits or auth failures that occur within that window. Successful syncs may take a few additional moments for transactions to appear in Actual Budget.',
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        try {
+            await adapter.runBankSync(input.accountId ?? undefined);
+            return { result: 'Bank sync initiated successfully' };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            throw new Error(msg);
+        }
+    },
+};
+export default tool;

package/dist/src/tools/budget_updates_batch.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+import api from '@actual-app/api';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const { setBudgetAmount: rawSetBudgetAmount, setBudgetCarryover: rawSetBudgetCarryover } = api;
+const BudgetOperationSchema = z.object({
+    month: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/, 'month must be in YYYY-MM format (e.g. 2025-01)').describe('Budget month in YYYY-MM format'),
+    categoryId: z.string().describe('Category ID'),
+    amount: z.number().optional().describe('Budget amount in cents (if setting amount)'),
+    carryover: z.boolean().optional().describe('Carryover flag (if setting carryover)'),
+});
+const InputSchema = z.object({
+    operations: z.array(BudgetOperationSchema).describe('Array of budget operations to perform in batch'),
+});
+const tool = {
+    name: 'actual_budget_updates_batch',
+    description: `Perform multiple budget updates in a single batch operation. More efficient than individual calls for bulk budget changes.
+
+Use cases:
+- Set budget amounts for multiple months/categories at once
+- Copy budgets across time periods
+- Bulk budget initialization
+
+Limits: Recommended max 50 operations per batch to avoid timeouts.
+
+Example: Set health insurance budget for 12 months:
+{
+  "operations": [
+    {"month": "2025-01", "categoryId": "<uuid>", "amount": 50000},
+    {"month": "2025-02", "categoryId": "<uuid>", "amount": 50000}
+  ]
+}`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        // Validate operation count
+        if (input.operations.length > 100) {
+            throw new Error(`Too many operations (${input.operations.length}). Maximum 100 per batch. Split into multiple batches.`);
+        }
+        if (input.operations.length > 50) {
+            console.warn(`Large batch (${input.operations.length} operations). Consider splitting for better reliability.`);
+        }
+        // Track successes and failures
+        const results = { successful: 0, failed: 0, errors: [] };
+        // Use batchBudgetUpdates to wrap all operations in a single transaction
+        await adapter.batchBudgetUpdates(async () => {
+            for (let i = 0; i < input.operations.length; i++) {
+                const op = input.operations[i];
+                try {
+                    // Use raw API calls directly to avoid nested queueing/deadlock
+                    if (op.amount !== undefined) {
+                        await rawSetBudgetAmount(op.month, op.categoryId, op.amount);
+                    }
+                    if (op.carryover !== undefined) {
+                        await rawSetBudgetCarryover(op.month, op.categoryId, op.carryover);
+                    }
+                    results.successful++;
+                }
+                catch (error) {
+                    results.failed++;
+                    const errorMsg = `Operation ${i + 1} failed (month: ${op.month}, category: ${op.categoryId}): ${error.message}`;
+                    results.errors.push(errorMsg);
+                    console.error(errorMsg);
+                    // Continue processing remaining operations
+                }
+            }
+        });
+        return {
+            success: results.failed === 0,
+            totalOperations: input.operations.length,
+            successful: results.successful,
+            failed: results.failed,
+            errors: results.errors.length > 0 ? results.errors.slice(0, 5) : undefined, // Return first 5 errors
+        };
+    },
+};
+export default tool;

package/dist/src/tools/budgets_getMonth.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({ month: z.string().optional() });
+const tool = {
+    name: 'actual_budgets_getMonth',
+    description: "Get budget data for a specific month in YYYY-MM format (e.g., '2025-12'). Returns all categories with their budgeted amounts, actual spending, and available balances for the month.",
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        const result = await adapter.getBudgetMonth(input.month);
+        return { result };
+    },
+};
+export default tool;

package/dist/src/tools/budgets_getMonths.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({});
+const tool = {
+    name: 'actual_budgets_getMonths',
+    description: "Get a list of all available budget months with summary data. Returns an array of months showing total budgeted, spent, and income for each month. Useful for viewing budget history and trends over time.",
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        InputSchema.parse(args || {});
+        const result = await adapter.getBudgetMonths();
+        return { result };
+    },
+};
+export default tool;

package/dist/src/tools/budgets_get_all.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({});
+const tool = {
+    name: 'actual_budgets_get_all',
+    description: 'Get a list of all available budget files. Useful for multi-budget management and discovering available budgets on the server.',
+    inputSchema: InputSchema,
+    call: async (_args, _meta) => {
+        const result = await adapter.getBudgets();
+        return { result };
+    },
+};
+export default tool;

package/dist/src/tools/budgets_holdForNextMonth.js

@@ -0,0 +1,19 @@
+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'),
+    amount: z.number().int().describe('Amount in cents to hold for next month'),
+});
+const tool = {
+    name: 'actual_budgets_holdForNextMonth',
+    description: `Hold an amount from this month's budget to carry into next month. The amount is in cents. This moves money from the current month's available budget into next month.
+
+Note: This operates on the month as a whole, not on a specific category.`,
+    inputSchema: InputSchema,
+    call: async (args, _meta) => {
+        const input = InputSchema.parse(args || {});
+        await adapter.holdBudgetForNextMonth(input.month, input.amount);
+        return { success: true };
+    },
+};
+export default tool;

package/dist/src/tools/budgets_list_available.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({});
+const tool = {
+    name: 'actual_budgets_list_available',
+    description: 'List all pre-configured budgets available for switching. ' +
+        'Each entry shows the budget name, sync ID, server URL, and whether it uses E2E encryption. ' +
+        'Budgets are configured via BUDGET_n_NAME / BUDGET_n_SYNC_ID / BUDGET_n_SERVER_URL env vars. ' +
+        'Pass the budget name to actual_budgets_switch to change the active budget.',
+    inputSchema: InputSchema,
+    call: async (_args) => {
+        const budgets = await Promise.resolve(adapter.getBudgetRegistry());
+        return {
+            budgets,
+            count: budgets.length,
+            hint: 'Pass the name (or partial name) of the desired budget to actual_budgets_switch.',
+        };
+    },
+};
+export default tool;