actual-mcp-server 0.9.5 → 0.10.0

package/README.md

@@ -24,13 +24,13 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 ┌─────────────┐   MCP/HTTP    ┌──────────────────┐   Actual API   ┌──────────────┐
 │  LibreChat  │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  LobeChat   │               │  Server          │               │   Budget     │
-│  (remote)   │               │  (71 tools)      │               │   Server     │
+│  (remote)   │               │  (74 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 
 ┌─────────────┐   MCP/stdio   ┌──────────────────┐   Actual API   ┌──────────────┐
 │  Claude     │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  Desktop    │               │  Server          │               │   Budget     │
-│  (local)    │               │  (71 tools)      │               │   Server     │
+│  (local)    │               │  (74 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 ```
 
@@ -38,14 +38,14 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 
 Most Actual Budget MCP implementations are simple stdio bridges designed for single-user, local use with Claude Desktop. This project goes further:
 
-- **71 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
+- **74 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
 - **HTTP and stdio transport.** Runs as a real remote server for LibreChat/LobeChat (`--http`), or as a direct local process for Claude Desktop (`--stdio`). No Docker or HTTP server is needed for local use.
 - **6 exclusive ActualQL-powered tools.** Search and summarise transactions by month, amount, category, or payee using Actual Budget's native query engine. Aggregated results, no raw data dumped into the AI context window.
 - **Multi-budget switching at runtime.** Configure multiple budget files and let the AI switch between them mid-conversation with `actual_budgets_switch`.
 - **Multi-user ready with OIDC.** Secure every session with JWKS-validated JWTs and per-user budget ACLs. No shared tokens required.
 - **Production-grade reliability.** Connection pooling (up to 15 concurrent sessions), automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
 
-> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 71 tools tested end-to-end. Any MCP-compatible client should work.
+> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 74 tools tested end-to-end. Any MCP-compatible client should work.
 
 ---
 
@@ -178,7 +178,7 @@ Add to `claude_desktop_config.json` (see [docs/guides/MCP_CLIENTS_SETUP.md](docs
 }
 ```
 
-> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 71 tools are available.
+> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 74 tools are available.
 >
 > **`MCP_BRIDGE_DATA_DIR` should be an absolute path.** Without one, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.
 
@@ -304,7 +304,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 ## Available Tools
 
-**71 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
+**74 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
 
 ### Accounts (7)
 
@@ -390,7 +390,13 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_notes_get` | Get the note for any entity (account/category/category-group/payee UUID, or budget-YYYY-MM) |
 | `actual_notes_update` | Set or clear the note for any entity; validates entity exists or matches budget-YYYY-MM pattern |
 
-### Budgets (10)
+### Preferences (1)
+
+| Tool | Description |
+|------|-------------|
+| `actual_preferences_get` | Read the budget's synced display preferences (number format, date format, currency, first day of week). Display only: all amounts stay integer cents |
+
+### Budgets (12)
 
 | Tool | Description |
 |------|-------------|
@@ -404,6 +410,8 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_budgets_setCarryover` | Enable/disable carryover |
 | `actual_budgets_holdForNextMonth` | Hold funds for next month |
 | `actual_budgets_resetHold` | Reset hold status |
+| `actual_budgets_export` | Export the active budget as a `.zip` into `ACTUAL_EXPORT_DIR`; returns path, byte size and sha256, never the file contents |
+| `actual_budgets_import` | Restore a budget from an Actual `.zip` or a YNAB4/YNAB5 export. **Destructive:** the budget id comes from the archive, so re-importing an export *replaces* that budget's data rather than making a copy. Also loads the imported budget, changing the session's active budget |
 
 ### Rules (4)
 
@@ -458,6 +466,7 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `MCP_BRIDGE_PORT` | `3600` | No | Port for MCP server to listen on |
 | `MCP_BRIDGE_BIND_HOST` | `0.0.0.0` | No | Host address to bind server to (`0.0.0.0` = all interfaces) |
 | `MCP_BRIDGE_DATA_DIR` | `./actual-data` | No | Directory to store Actual Budget local data (SQLite). **Required to be a persistent path.** The `@actual-app/api` library downloads a local copy of your budget here to run queries; use a volume mount in Docker to persist it across restarts |
+| `ACTUAL_EXPORT_DIR` | (unset) | No | Directory where `actual_budgets_export` writes budget `.zip` files. Unset means `<MCP_BRIDGE_DATA_DIR>/exports`, which is writable and persisted in the Docker image. Must be writable by the runtime user |
 | `MCP_BRIDGE_PUBLIC_HOST` | auto-detected | No | Public hostname/IP for server (shown in logs) |
 | `MCP_BRIDGE_PUBLIC_SCHEME` | auto-detected | No | Public scheme (`http` or `https`) |
 | `MCP_BRIDGE_USE_TLS` | `false` | No | Set to `true` to advertise `https://` in the server URL (for reverse-proxy setups where TLS is terminated upstream) |
@@ -562,7 +571,7 @@ stdio is the simplest way to connect Claude Desktop directly to Actual Budget. T
 - No auth token. Process ownership is the security boundary.
 - All logs go to stderr so they never corrupt the JSON-RPC framing on stdout
 - The process exits when stdin closes (Claude Desktop shutting down)
-- All 71 tools are available, identical to HTTP mode
+- All 74 tools are available, identical to HTTP mode
 
 **Start manually to verify:**
 
@@ -644,7 +653,7 @@ See [AI Client Setup, OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-m
 | Command | What It Tests | Requires Live Server |
 |---------|---------------|---------------------|
 | `npm run build` | TypeScript compilation | No |
-| `npm run test:unit-js` | 71-tool smoke, schema validation, auth ACL | No |
+| `npm run test:unit-js` | 74-tool smoke, schema validation, auth ACL | No |
 | `npm run test:adapter` | Adapter, retry logic, concurrency | No |
 | `npm run test:e2e` | MCP protocol compliance (Playwright) | No |
 | `npm run test:e2e:docker:full` | Full stack integration | Yes (Docker) |
@@ -729,4 +738,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.9.5 | **Tool Count:** 71 (verified LibreChat-compatible)
+**Version:** 0.10.0 | **Tool Count:** 74 (verified LibreChat-compatible)

package/dist/src/actualToolsManager.js

@@ -75,6 +75,9 @@ const IMPLEMENTED_TOOLS = [
     'actual_tags_delete',
     'actual_notes_get',
     'actual_notes_update',
+    'actual_budgets_export',
+    'actual_budgets_import',
+    'actual_preferences_get',
 ];
 // 🔑 Mapping of Actual API function names → your MCP tool names
 // This allows us to compare what exists in the API vs. what it has been wrapped.
@@ -118,6 +121,9 @@ const API_TOOL_MAP = {
     deleteCategoryGroup: 'actual_category_groups_delete',
     getIDByName: 'actual_get_id_by_name',
     getServerVersion: 'actual_server_get_version',
+    exportBudget: 'actual_budgets_export',
+    importBudget: 'actual_budgets_import',
+    getPreferences: 'actual_preferences_get',
 };
 class ActualToolsManager {
     tools = new Map();

package/dist/src/config.js

@@ -34,6 +34,19 @@ export const configSchema = z.object({
     // Off by default so a plaintext upstream + encryption password is refused.
     ALLOW_INSECURE_UPSTREAM: z.string().optional().transform(val => val === 'true'),
     MCP_BRIDGE_DATA_DIR: z.string().default('./actual-data'),
+    // #332: where actual_budgets_export writes budget zips. A budget export is
+    // megabytes of binary, so the tool returns a PATH plus metadata rather than
+    // base64 in the tool result: inlining it would flood the model's context and
+    // can exceed transport payload limits.
+    //
+    // Empty means "derive as <MCP_BRIDGE_DATA_DIR>/exports", resolved at call time
+    // rather than baked in here. A literal default like './actual-data/exports'
+    // would be resolved against the process CWD, which in the container is /app:
+    // that path is root-owned and the runtime drops to the unprivileged `app` user,
+    // so the very first export would fail with EACCES. The data dir is the one
+    // location guaranteed to be both writable and persisted (Dockerfile chowns it
+    // and it is a named volume), so exports belong under it.
+    ACTUAL_EXPORT_DIR: z.string().default(''),
     MCP_BRIDGE_PORT: z.string().default('3600'),
     MCP_TRANSPORT_MODE: z.enum(['--http']).default('--http'),
     MCP_SSE_AUTHORIZATION: z.string().optional(),

package/dist/src/lib/actual-adapter.js

@@ -4,7 +4,7 @@ import api from '@actual-app/api';
 // cannot expose its named exports via static import syntax. At runtime the default import
 // IS module.exports, so all methods are accessible as properties.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, importTransactions: rawImportTransactions, getTransactions: rawGetTransactions, getCategories: rawGetCategories, createCategory: rawCreateCategory, getPayees: rawGetPayees, getCommonPayees: rawGetCommonPayees, createPayee: rawCreatePayee, getBudgetMonths: rawGetBudgetMonths, getBudgetMonth: rawGetBudgetMonth, setBudgetAmount: rawSetBudgetAmount, createAccount: rawCreateAccount, updateAccount: rawUpdateAccount, getAccountBalance: rawGetAccountBalance, updateTransaction: rawUpdateTransaction, deleteTransaction: rawDeleteTransaction, updateCategory: rawUpdateCategory, deleteCategory: rawDeleteCategory, updatePayee: rawUpdatePayee, deletePayee: rawDeletePayee, deleteAccount: rawDeleteAccount, getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule, deleteRule: rawDeleteRule, setBudgetCarryover: rawSetBudgetCarryover, closeAccount: rawCloseAccount, reopenAccount: rawReopenAccount, getCategoryGroups: rawGetCategoryGroups, createCategoryGroup: rawCreateCategoryGroup, updateCategoryGroup: rawUpdateCategoryGroup, deleteCategoryGroup: rawDeleteCategoryGroup, mergePayees: rawMergePayees, getPayeeRules: rawGetPayeeRules, batchBudgetUpdates: rawBatchBudgetUpdates, holdBudgetForNextMonth: rawHoldBudgetForNextMonth, resetBudgetHold: rawResetBudgetHold, runQuery: rawRunQuery, runBankSync: rawRunBankSync, getBudgets: rawGetBudgets, getIDByName: rawGetIDByName, getServerVersion: rawGetServerVersion, getSchedules: rawGetSchedules, createSchedule: rawCreateSchedule, updateSchedule: rawUpdateSchedule, deleteSchedule: rawDeleteSchedule, getTags: rawGetTags, createTag: rawCreateTag, updateTag: rawUpdateTag, deleteTag: rawDeleteTag, getNote: rawGetNote, updateNote: rawUpdateNote,
+const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, importTransactions: rawImportTransactions, getTransactions: rawGetTransactions, getCategories: rawGetCategories, createCategory: rawCreateCategory, getPayees: rawGetPayees, getCommonPayees: rawGetCommonPayees, createPayee: rawCreatePayee, getBudgetMonths: rawGetBudgetMonths, getBudgetMonth: rawGetBudgetMonth, setBudgetAmount: rawSetBudgetAmount, createAccount: rawCreateAccount, updateAccount: rawUpdateAccount, getAccountBalance: rawGetAccountBalance, updateTransaction: rawUpdateTransaction, deleteTransaction: rawDeleteTransaction, updateCategory: rawUpdateCategory, deleteCategory: rawDeleteCategory, updatePayee: rawUpdatePayee, deletePayee: rawDeletePayee, deleteAccount: rawDeleteAccount, getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule, deleteRule: rawDeleteRule, setBudgetCarryover: rawSetBudgetCarryover, closeAccount: rawCloseAccount, reopenAccount: rawReopenAccount, getCategoryGroups: rawGetCategoryGroups, createCategoryGroup: rawCreateCategoryGroup, updateCategoryGroup: rawUpdateCategoryGroup, deleteCategoryGroup: rawDeleteCategoryGroup, mergePayees: rawMergePayees, getPayeeRules: rawGetPayeeRules, batchBudgetUpdates: rawBatchBudgetUpdates, holdBudgetForNextMonth: rawHoldBudgetForNextMonth, resetBudgetHold: rawResetBudgetHold, runQuery: rawRunQuery, runBankSync: rawRunBankSync, getBudgets: rawGetBudgets, getIDByName: rawGetIDByName, getServerVersion: rawGetServerVersion, getSchedules: rawGetSchedules, createSchedule: rawCreateSchedule, updateSchedule: rawUpdateSchedule, deleteSchedule: rawDeleteSchedule, getTags: rawGetTags, createTag: rawCreateTag, updateTag: rawUpdateTag, deleteTag: rawDeleteTag, getNote: rawGetNote, updateNote: rawUpdateNote, exportBudget: rawExportBudget, importBudget: rawImportBudget, getPreferences: rawGetPreferences,
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
  } = api;
 import { EventEmitter } from 'events';
@@ -1990,6 +1990,66 @@ export async function updateNote(id, note) {
         await withConcurrency(() => retry(() => rawUpdateNote(id, note), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
+/**
+ * Export the currently-loaded budget as a zip (#332).
+ *
+ * READ path (`withActualApi`), not the write queue: the upstream call produces a
+ * snapshot and mutates nothing, so it is safe to retry and must not serialise
+ * behind pending writes.
+ *
+ * Returns the raw bytes. Deliberately NOT base64 here: the encoding decision, the
+ * size cap, and the write-to-disk policy belong to the tool layer, so a future
+ * caller that wants to stream the buffer is not forced through a string.
+ */
+export async function exportBudget() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.budgets.export').catch(() => { });
+        return await withConcurrency(() => retry(() => rawExportBudget(), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
+    });
+}
+/**
+ * Import a budget from an Actual `.zip` export or a YNAB4/YNAB5 export (#334).
+ *
+ * WRITE path, and NON-IDEMPOTENT: it creates a budget file and returns its new id,
+ * so `retries: 0` is mandatory. A retry after a lost response would create a SECOND
+ * budget rather than returning the first one's id. Guarded by
+ * `tests/unit/adapter_nonidempotent_no_retry.test.js`.
+ *
+ * Side effect worth knowing at every call site: upstream `importBudget` LOADS the
+ * imported budget, so the session's active budget changes to the new file. It is
+ * therefore outside the `BUDGET_N_*` registry and outside whatever budget the ACL
+ * resolved for this request. The write queue still enforces the ACL on entry, so a
+ * caller cannot use this to escape a budget they were already denied, but the
+ * resulting budget is un-ACL'd because it did not exist when the ACL was built.
+ */
+export async function importBudget(input, opts = {}) {
+    observability.incrementToolCall('actual.budgets.import').catch(() => { });
+    return queueWriteOperation(async () => {
+        return await withConcurrency(() => retry(() => rawImportBudget(input, opts), {
+            retries: 0,
+            backoffMs: 200,
+            isRetryable: isRetryableError,
+        }));
+    });
+}
+/**
+ * Read the budget's synced preferences: number format, date format, currency,
+ * first day of week, and similar display settings (#333).
+ *
+ * READ path. The shape is upstream's `SyncedPrefs`, which our tsconfig resolves to
+ * the `@actual-app/core` stub (`any`), so there is no compile-time contract here.
+ * The tool layer normalises it rather than trusting the shape.
+ */
+export async function getPreferences() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.preferences.get').catch(() => { });
+        return await withConcurrency(() => retry(() => rawGetPreferences(), {
+            retries: 2,
+            backoffMs: 200,
+            isRetryable: isRetryableError,
+        }));
+    });
+}
 export default {
     getAccounts,
     getAccountsWithBalances,
@@ -2051,5 +2111,8 @@ export default {
     deleteSchedule,
     updateTransactionBatch,
     withWriteSession,
+    exportBudget,
+    importBudget,
+    getPreferences,
     notifications,
 };

package/dist/src/tools/budgets_export.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, isAbsolute, join, resolve } from 'node:path';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+import config from '../config.js';
+/**
+ * #332: expose `@actual-app/api`'s `exportBudget()`.
+ *
+ * WHY THIS WRITES TO DISK INSTEAD OF RETURNING THE ZIP.
+ *
+ * `exportBudget()` returns the whole budget as a zip: megabytes of binary for any
+ * real budget. Returning that inline would mean base64 in the JSON-RPC result,
+ * which (a) floods the model's context window with unreadable payload, and (b) can
+ * exceed transport limits (the HTTP body cap, and a stdio client's line buffer).
+ * So the tool writes the bytes to a configured directory and returns a PATH plus
+ * the metadata a caller actually needs to verify the export: byte size and sha256.
+ *
+ * The sha256 is what makes the export/import round trip assertable: a test can
+ * export, re-import, export again, and compare digests without ever moving the
+ * bytes through the transport.
+ */
+// Deliberately strict: a caller-supplied filename becomes a path on the server's
+// filesystem, so it is restricted to a flat, boring charset. Traversal sequences,
+// separators, and absolute paths are all rejected by this class rather than
+// normalised away, because silently rewriting a caller's filename is worse than
+// telling them it was invalid.
+const SAFE_FILENAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const InputSchema = z
+    .object({
+    filename: z
+        .string()
+        .min(1, 'filename must not be empty')
+        .max(120, 'filename must be at most 120 characters')
+        .refine((value) => SAFE_FILENAME.test(value), 'filename must start with a letter or digit and contain only letters, digits, dots, underscores, and hyphens (no path separators)')
+        .refine((value) => !value.includes('..'), 'filename must not contain ".."')
+        .optional()
+        .describe('Optional file name for the export, without any directory part. Defaults to a timestamped name. ' +
+        'A ".zip" suffix is appended if missing.'),
+})
+    .strict();
+/**
+ * Build the default export name. Uses a UTC timestamp flattened to a
+ * filesystem-safe form, e.g. `budget-export-2026-08-07T10-31-05Z.zip`.
+ *
+ * This is a FILE NAME, not a date field: the project rule that dates are
+ * `YYYY-MM-DD` strings applies to values sent to the Actual API, none of which
+ * this touches.
+ */
+function defaultExportName(now) {
+    const stamp = now.toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/:/g, '-');
+    return `budget-export-${stamp}.zip`;
+}
+export default createTool({
+    name: 'actual_budgets_export',
+    description: 'Export the currently active budget as an Actual Budget ".zip" file, written to the server\'s ' +
+        'configured export directory (ACTUAL_EXPORT_DIR). Returns the file path, byte size, and sha256 ' +
+        'digest, NOT the file contents: a budget export is megabytes of binary and is never inlined into ' +
+        'the response. The resulting file can be restored with actual_budgets_import, or downloaded from ' +
+        'the server by whoever operates it. Use this before any bulk or destructive change as a backup.',
+    schema: InputSchema,
+    handler: async (input) => {
+        const data = await adapter.exportBudget();
+        // Guard the upstream contract rather than assuming it. `exportBudget` is a
+        // young method (added upstream in July 2026) and its own error path already
+        // throws on a missing payload, but a zero-length buffer would slip through and
+        // produce a silently useless "backup", which is the worst possible failure for
+        // a backup tool.
+        if (!data || data.length === 0) {
+            throw new Error('Actual Budget returned an empty export. The budget may not be fully loaded; ' +
+                'retry after confirming the budget is open, and check the server logs.');
+        }
+        const requested = input.filename ? basename(input.filename) : defaultExportName(new Date());
+        const filename = requested.toLowerCase().endsWith('.zip') ? requested : `${requested}.zip`;
+        // An unset ACTUAL_EXPORT_DIR derives from the data dir rather than the CWD.
+        // See the config comment: the CWD in the container is root-owned /app, and
+        // the runtime user is unprivileged, so a CWD-relative default cannot be
+        // created. MCP_BRIDGE_DATA_DIR is writable and persisted by construction.
+        const configured = config.ACTUAL_EXPORT_DIR.trim();
+        const target = configured || join(config.MCP_BRIDGE_DATA_DIR, 'exports');
+        const dir = isAbsolute(target) ? target : resolve(process.cwd(), target);
+        await mkdir(dir, { recursive: true });
+        const path = join(dir, filename);
+        await writeFile(path, data);
+        const sha256 = createHash('sha256').update(data).digest('hex');
+        return {
+            success: true,
+            path,
+            filename,
+            directory: dir,
+            bytes: data.length,
+            sha256,
+            message: `Exported the active budget to ${path} (${data.length} bytes, sha256 ${sha256}). ` +
+                'Restore it with actual_budgets_import using this path.',
+        };
+    },
+    examples: [
+        { description: 'Export the active budget with an auto-generated timestamped name', input: {} },
+        { description: 'Export to a specific file name', input: { filename: 'before-cleanup.zip' } },
+    ],
+});

package/dist/src/tools/budgets_import.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+/**
+ * #334: expose `@actual-app/api`'s `importBudget()`.
+ *
+ * TWO SIDE EFFECTS EVERY CALLER MUST KNOW, both verified against `importActual` in
+ * the installed `@actual-app/api` and against a live server in the Docker E2E run:
+ *
+ * 1. IT CAN OVERWRITE AN EXISTING BUDGET. The budget id is taken from the ARCHIVE,
+ *    not freshly generated. `importActual` closes the current budget, restores the
+ *    archive under the id the archive carries, and loads it. So re-importing an
+ *    export of budget X restores ONTO budget X, replacing that budget's local data.
+ *    This is what makes export/import a genuine backup-and-restore pair, and it is
+ *    also why an import against a budget with real data is destructive. It is only
+ *    "a new budget" when the archive's id is not already present.
+ * 2. IT CHANGES THE ACTIVE BUDGET. The imported budget is loaded, so the session
+ *    switches to it. If the archive's id is not in the `BUDGET_N_*` registry, that
+ *    budget is also outside whatever set the ACL resolved for this request, and
+ *    `actual_budgets_switch` cannot reach it by name.
+ *
+ * The write queue enforces the budget ACL when this is enqueued, so this cannot be
+ * used to reach a budget the caller was already denied. It does mean a budget
+ * created by the import is un-ACL'd, because it did not exist when the ACL was built.
+ *
+ * Accepts either a path on the server's filesystem or the file contents inline as
+ * base64. Exactly one, enforced by the schema.
+ */
+// A generous ceiling that still turns a runaway payload into a clear validation
+// error instead of an out-of-memory kill. ~64 MB of base64 is ~48 MB of zip, far
+// above any realistic Actual export. Consistent with the bounded-input policy the
+// rest of the tool surface adopted in #156.
+const MAX_BASE64_CHARS = 64 * 1024 * 1024;
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+const InputSchema = z
+    .object({
+    path: z
+        .string()
+        .min(1, 'path must not be empty')
+        .max(4096, 'path must be at most 4096 characters')
+        .optional()
+        .describe('Absolute or relative path to the export file ON THE SERVER\'S filesystem. ' +
+        'Use the "path" returned by actual_budgets_export to restore an earlier export.'),
+    base64: z
+        .string()
+        .min(1, 'base64 must not be empty')
+        .max(MAX_BASE64_CHARS, `base64 must be at most ${MAX_BASE64_CHARS} characters`)
+        .refine((value) => BASE64.test(value), 'base64 must be valid base64 (A-Z, a-z, 0-9, +, /, with optional = padding)')
+        .optional()
+        .describe('The export file contents, base64-encoded, for callers that cannot place a file on the server.'),
+    type: z
+        .enum(['actual', 'ynab4', 'ynab5'])
+        .default('actual')
+        .describe('Format of the file being imported. "actual" is an Actual Budget .zip export ' +
+        '(what actual_budgets_export produces). "ynab4" and "ynab5" import from YNAB.'),
+    filename: z
+        .string()
+        .min(1, 'filename must not be empty')
+        .max(120, 'filename must be at most 120 characters')
+        .optional()
+        .describe('Original file name, used only with "base64" so the importer can infer the budget name.'),
+})
+    .strict()
+    .refine((value) => Boolean(value.path) !== Boolean(value.base64), 'Provide exactly one of "path" or "base64", not both and not neither.');
+export default createTool({
+    name: 'actual_budgets_import',
+    description: 'Restore or import a budget from an Actual Budget ".zip" export or a YNAB4/YNAB5 export. ' +
+        'DESTRUCTIVE: the budget id comes from the archive, so re-importing an export REPLACES that ' +
+        'budget\'s data rather than creating a copy. Never call this to "have a look at" a file. Confirm ' +
+        'with the user before importing over a budget that holds real data. ' +
+        'It also LOADS the imported budget, so the active budget for this session changes; if the archive\'s ' +
+        'budget is not in the configured list, call actual_budgets_list_available and actual_budgets_switch ' +
+        'afterwards to go back. Provide exactly one of "path" (a file on the server) or "base64" (inline contents).',
+    schema: InputSchema,
+    handler: async (input) => {
+        const source = input.path
+            ? input.path
+            : new Uint8Array(Buffer.from(input.base64, 'base64'));
+        // Reject an empty decode explicitly. Buffer.from(..., 'base64') is lenient and
+        // returns an empty buffer for input it cannot decode, which would otherwise
+        // reach upstream as a zero-byte zip and fail with a much less useful message.
+        if (typeof source !== 'string' && source.length === 0) {
+            throw new Error('The "base64" payload decoded to zero bytes. Check that it is a complete, valid base64 string.');
+        }
+        const result = await adapter.importBudget(source, {
+            type: input.type,
+            ...(input.filename ? { filename: input.filename } : {}),
+        });
+        return {
+            success: true,
+            budgetId: result.id,
+            type: input.type,
+            source: input.path ? 'path' : 'base64',
+            message: `Imported the budget as id ${result.id}. This budget is now LOADED and active for this session, ` +
+                'and it is not in the server\'s configured budget list. Use actual_budgets_list_available and ' +
+                'actual_budgets_switch to return to a configured budget.',
+        };
+    },
+    examples: [
+        {
+            description: 'Restore an export previously produced by actual_budgets_export',
+            input: { path: './actual-data/exports/before-cleanup.zip', type: 'actual' },
+        },
+        {
+            description: 'Import a YNAB5 export sent inline',
+            input: { base64: 'UEsDBBQAAAAIA...', type: 'ynab5', filename: 'my-ynab-budget.zip' },
+        },
+    ],
+});

package/dist/src/tools/index.js

@@ -18,6 +18,8 @@ export { default as budgets_holdForNextMonth } from './budgets_holdForNextMonth.
 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_export } from './budgets_export.js';
+export { default as budgets_import } from './budgets_import.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';
@@ -70,3 +72,4 @@ export { default as tags_update } from './tags_update.js';
 export { default as tags_delete } from './tags_delete.js';
 export { default as notes_get } from './notes_get.js';
 export { default as notes_update } from './notes_update.js';
+export { default as preferences_get } from './preferences_get.js';

package/dist/src/tools/preferences_get.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+/**
+ * #333: expose `@actual-app/api`'s `getPreferences()`.
+ *
+ * These are the budget's SYNCED preferences (number format, date format,
+ * currency, first day of week), which is exactly the context an assistant needs
+ * to format amounts and dates the way the user's own budget does. Amounts stay
+ * integer cents everywhere in this server; this tool tells a caller how the user
+ * expects those cents to be RENDERED, it does not change any unit.
+ *
+ * Read-only. The upstream return type is `SyncedPrefs`, which our tsconfig maps
+ * to the `@actual-app/core` stub (`any`), so there is no compile-time contract.
+ * We therefore normalise defensively rather than trusting the shape.
+ */
+export default createTool({
+    name: 'actual_preferences_get',
+    description: 'Read the budget\'s synced display preferences: number format, date format, currency, ' +
+        'first day of the week, and similar settings. Use this to format amounts and dates the ' +
+        'way this budget is configured to show them. Note these are DISPLAY preferences only: ' +
+        'all amounts in this API remain integer cents (5000 = $50.00) regardless of what this returns.',
+    schema: z.object({}),
+    handler: async () => {
+        const prefs = await adapter.getPreferences();
+        // Upstream returns a plain synced-prefs object, but it is `any` to us and has
+        // been observed to come back null when a budget has never had a preference
+        // written. Normalise to an object so a caller can always read `.preferences`
+        // without a null check, and report emptiness explicitly instead of silently.
+        const preferences = prefs && typeof prefs === 'object' && !Array.isArray(prefs) ? prefs : {};
+        const keys = Object.keys(preferences);
+        return {
+            preferences,
+            keys,
+            count: keys.length,
+            message: keys.length === 0
+                ? 'This budget has no synced preferences set; Actual Budget is using its defaults.'
+                : `Read ${keys.length} synced preference(s) for the active budget.`,
+        };
+    },
+    examples: [{ description: 'Read the active budget display preferences', input: {} }],
+});

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.9.5",
+  "version": "0.10.0",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
   },
-  "description": "MCP server with 71 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+  "description": "MCP server with 74 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
   "homepage": "https://github.com/agigante80/actual-mcp-server#readme",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/transactions_update_splits.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/transactions_update_splits.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js",
     "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
     "test:e2e": "npx playwright test",
     "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",
@@ -61,7 +61,8 @@
     "tool-count": "node scripts/tool-count.mjs",
     "config-drift": "npm run build && node scripts/config-drift.mjs",
     "node-version-drift": "node scripts/node-version-drift.mjs",
-    "knip": "knip"
+    "knip": "knip",
+    "actionlint": "bash scripts/install-actionlint.sh && ./actionlint -shellcheck= -color"
   },
   "dependencies": {
     "@actual-app/api": "^26.8.0",
@@ -70,7 +71,7 @@
     "dotenv": "^17.4.2",
     "express": "^5.2.1",
     "fuse.js": "^7.4.2",
-    "jose": "^6.2.3",
+    "jose": "^6.2.8",
     "mcp-auth": "^0.2.0",
     "winston": "^3.18.3",
     "winston-daily-rotate-file": "^5.0.0",
@@ -83,7 +84,7 @@
     "@playwright/test": "^1.60.0",
     "@types/express": "^5.0.3",
     "@types/node": "^26.1.0",
-    "knip": "^6.16.1",
+    "knip": "^6.32.0",
     "node-fetch": "^3.3.2",
     "tsconfig-paths": "^4.2.0",
     "typescript": "^7.0.2"