actual-mcp-server 0.9.6 → 0.11.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)
 
@@ -318,7 +318,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_accounts_reopen` | Reopen closed account |
 | `actual_accounts_get_balance` | Get account balance at a date |
 
-### Transactions (13)
+### Transactions (14)
 
 **Standard (6)**
 
@@ -333,11 +333,12 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 > **Split transactions:** pass a `subtransactions` array (each child needs an `amount` in integer cents; `category` and `notes` are optional). The child amounts must sum to the parent `amount` (the server does not enforce this, so the tool does). A split parent carries no category of its own: put categories on the children. `actual_transactions_update` can edit the children of a transaction that is ALREADY a split; converting a plain transaction into a split via update is not supported (create it as a split instead). Note: `actual_transactions_import` forwards a `subtransactions` array to the API but does NOT apply the sum check, so use `actual_transactions_create` for guaranteed-balanced splits.
 
-**Utility (1)**
+**Utility (2)**
 
 | Tool | Description |
 |------|-------------|
 | `actual_transactions_uncategorized` | Summary of uncategorized transactions (totalCount, totalAmount, per-account breakdown); pass `includeTransactions:true` for paginated rows |
+| `actual_transactions_update_batch` | Apply many transaction updates in ONE call (`updates: [{ id, fields }]`); returns per-item success and failure counts |
 
 **Exclusive ActualQL-powered (6)**, unique to this MCP server
 
@@ -390,7 +391,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,11 +411,26 @@ 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)
+### Rules (5)
 
 `actual_rules_get` · `actual_rules_create` · `actual_rules_update` · `actual_rules_delete`
 
+| Tool | Description |
+|------|-------------|
+| `actual_rules_create_or_update` | Idempotent upsert: create a rule, or update the existing one that matches the same conditions, in a single call. Use this instead of get-then-create when re-running a categorisation setup, so repeated runs do not pile up duplicate rules |
+
+### Schedules (4)
+
+| Tool | Description |
+|------|-------------|
+| `actual_schedules_get` | List scheduled transactions, with their next occurrence date |
+| `actual_schedules_create` | Create a schedule (one-off or recurring); recurrence is a typed config, see `src/lib/schemas/recur.ts` |
+| `actual_schedules_update` | Update an existing schedule's amount, payee, account, or recurrence |
+| `actual_schedules_delete` | Delete a schedule |
+
 ### Advanced Query & Sync (2)
 
 | Tool | Description |
@@ -458,6 +480,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) |
@@ -481,6 +504,8 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `OIDC_JWKS_TRUSTED_HOSTS` | _(none)_ | No | Opt-in cross-origin JWKS hosts, comma-separated `host` or `host:port` (#254). For IdPs whose `jwks_uri` lives on another host, e.g. Google needs `www.googleapis.com`. Exact match, no wildcards; empty default keeps same-origin-only |
 | `OIDC_SCOPES` | _(none)_ | No | Comma-separated required scopes; leave empty for Casdoor |
 | `AUTH_BUDGET_ACL` | _(none)_ | No | Per-user budget ACL; see [AI Client Setup](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) |
+| `AUTH_BUDGET_ACL_SOURCE` | `static` | No | `static` uses the `AUTH_BUDGET_ACL` map above. `actual` derives the ACL from the Actual server's own per-file access list, so revoking someone in Actual takes effect here without a config edit. Requires a multi-user (OpenID) Actual server that was password-bootstrapped first |
+| `AUTH_BUDGET_ACL_CLAIM` | `sub` | No | Which OIDC claim is matched against Actual's user identity when the source is `actual`. `sub` matches Actual's `userId` and is strongly preferred; matching a name claim is riskier |
 | `MCP_ENABLE_HTTPS` | `false` | No | Enable native TLS. Requires `MCP_HTTPS_CERT` and `MCP_HTTPS_KEY` |
 | `MCP_HTTPS_CERT` | _(none)_ | No | Path to PEM certificate file (required when `MCP_ENABLE_HTTPS=true`) |
 | `MCP_HTTPS_KEY` | _(none)_ | No | Path to PEM private key file (required when `MCP_ENABLE_HTTPS=true`) |
@@ -562,7 +587,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:**
 
@@ -635,6 +660,21 @@ OIDC_SCOPES=                    # leave empty for Casdoor
 - `GET /.well-known/oauth-protected-resource` (RFC 9728): identifies this server as a protected resource and points at your `OIDC_ISSUER` as the authorization server.
 - `GET /.well-known/oauth-authorization-server` (RFC 8414, #285): the authorization server metadata (its `authorization_endpoint` / `token_endpoint` / `registration_endpoint`), re-served from your IdP's own OpenID discovery document. This is here because several clients look for it on the resource-server origin, and some IdPs (e.g. Authentik) do not expose it where those clients look. It is fetched once at startup and served verbatim, exposes only endpoints your IdP already publishes publicly, and requires no authentication (a client reads it before it has a token). No extra configuration is needed; it is absent when `AUTH_PROVIDER` is not `oidc`.
 
+**Where the per-user budget ACL comes from.** By default the ACL is the `AUTH_BUDGET_ACL` map you maintain by hand. Since v0.10.x it can instead be derived from the Actual server's own per-file access list, so granting or revoking someone in Actual takes effect here without a config edit and a restart:
+
+```bash
+AUTH_BUDGET_ACL_SOURCE=actual   # default: static (the AUTH_BUDGET_ACL map)
+AUTH_BUDGET_ACL_CLAIM=sub       # default: sub, matched against Actual's userId
+```
+
+Three things to know before enabling it:
+
+- **It requires a multi-user Actual server**, meaning one configured with `ACTUAL_OPENID_*`. On a password-only server no named users exist and every principal resolves to nothing.
+- **Your Actual server must have been bootstrapped with a PASSWORD before OpenID was added.** This is a hard prerequisite of this MCP server generally, not just of this feature: `@actual-app/api` authenticates with a password, and an Actual server set up with OpenID from scratch refuses password login, so this server cannot connect to it at all. A password cannot be added afterwards.
+- **Keep `AUTH_BUDGET_ACL_CLAIM=sub` unless you have a specific reason not to.** `sub` is matched against Actual's stable `userId`. Matching a name-like claim instead is riskier: this server's own service account appears in every file's access list as the owner with a blank `userName`, so a principal whose name claim resolves to empty would match it.
+
+It is opt-in and fails closed: if the budget list cannot be read, or the principal matches no file, access is denied rather than granted.
+
 See [AI Client Setup, OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) for `AUTH_BUDGET_ACL` format and Casdoor notes.
 
 ---
@@ -644,7 +684,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 +769,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.9.6 | **Tool Count:** 71 (verified LibreChat-compatible)
+**Version:** 0.11.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/auth/budget-acl-dynamic.js

@@ -0,0 +1,155 @@
+// src/auth/budget-acl-dynamic.ts
+//
+// #338: derive the budget ACL from the Actual server's own per-file access list
+// instead of hand-maintained JSON, so revoking someone in Actual takes effect
+// here without a config edit and a restart.
+//
+// WHY userId AND NOT userName, verified against a live multi-user server.
+//
+// `getBudgets()` returns, per remote file:
+//
+//   "owner": "a6067f04-...",
+//   "usersWithAccess": [
+//     { "userId": "5311397e-...", "displayName": "Alice", "userName": "alice", "owner": false },
+//     { "userId": "a6067f04-...", "displayName": "",      "userName": "",      "owner": true  }
+//   ]
+//
+// That second row is THIS SERVER'S OWN service account. `@actual-app/api`
+// authenticates with a password, that password identity owns every file the API
+// creates, and it has no userName because it is not an OpenID user. So a blank
+// `userName` is present in every file's access list on every deployment.
+//
+// A name-based match therefore has a live escalation path: a principal whose
+// configured claim is missing or empty would match the blank row, which carries
+// `owner: true`, and be granted access to every file on the server. Matching
+// UUIDs makes that unrepresentable, because no IdP subject equals the service
+// account's UUID. AUTH_BUDGET_ACL_CLAIM still allows name matching for
+// deployments that need it, and the empty-principal guard below is what keeps
+// that option from reintroducing the hole.
+//
+// WHY THE RESOLUTION RUNS UNDER AN EXPLICIT WILDCARD CONTEXT.
+//
+// Resolving the ACL requires `adapter.getBudgets()`, and every adapter entry
+// point runs `_enforceBudgetAcl`, which refuses when the request context has no
+// allowedBudgets. Resolving the ACL would therefore be blocked by the ACL it is
+// trying to compute. We break that circularity by running ONLY this one call
+// inside `requestContext.run({ allowedBudgets: ['*'] }, ...)`.
+//
+// That is sound rather than a loophole: `getBudgets()` lists budget FILES
+// (name, id, who may access them). It reads no budget CONTENTS: no accounts, no
+// transactions, no balances. The wildcard is scoped to this single listing call
+// and never leaks into the caller's context, because AsyncLocalStorage restores
+// the previous store when the callback returns.
+import config from '../config.js';
+import adapter from '../lib/actual-adapter.js';
+import { requestContext } from '../lib/requestContext.js';
+import { createModuleLogger } from '../lib/loggerFactory.js';
+const log = createModuleLogger('ACL');
+/**
+ * Cache of principal to allowed sync IDs.
+ *
+ * Bounded by TTL rather than size: the key space is the set of authenticated
+ * principals, which is small and operator-controlled. A short TTL is what makes
+ * a revocation in Actual take effect here promptly; without it this feature
+ * would reintroduce exactly the staleness it exists to remove.
+ */
+const CACHE_TTL_MS = 60_000;
+const _cache = new Map();
+/** Clear the resolver cache (test helper, and used when config is re-read). */
+export function _resetDynamicAclCache() {
+    _cache.clear();
+}
+/**
+ * Extract the identity value to match on, from the claim named by
+ * AUTH_BUDGET_ACL_CLAIM. Returns null when the claim is absent or blank.
+ *
+ * Blank is deliberately null and not '': an empty string would compare equal to
+ * the service account's empty userName. See the header note.
+ */
+export function extractPrincipalValue(claims, subject, claimName) {
+    const raw = claimName === 'sub' ? (subject ?? claims['sub']) : claims[claimName];
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Map a getBudgets() payload to the sync IDs the given principal may access.
+ *
+ * Pure, so the matching rules are unit-testable against the captured live
+ * fixture without a server. Exported for that reason.
+ */
+export function matchAllowedFiles(files, principalValue, claimName) {
+    if (!Array.isArray(files))
+        return [];
+    // An empty principal can never match. Belt and braces: extractPrincipalValue
+    // already returns null for blank, but this function is exported and must not
+    // depend on its callers for that guarantee.
+    if (!principalValue)
+        return [];
+    const matchesName = claimName !== 'sub';
+    const allowed = new Set();
+    for (const entry of files) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        // groupId, NOT cloudFileId. See the BudgetFileEntry note: groupId is the
+        // "Sync ID" that _enforceBudgetAcl compares against.
+        const syncId = entry.groupId;
+        const access = entry.usersWithAccess;
+        if (!syncId || !Array.isArray(access))
+            continue;
+        for (const u of access) {
+            if (!u || typeof u !== 'object')
+                continue;
+            // Read the whole list, not only `owner: true`. A file shared with a
+            // household member appears with owner: false, and that is exactly the
+            // case this feature exists to honour.
+            const candidate = matchesName ? u.userName : u.userId;
+            if (typeof candidate !== 'string')
+                continue;
+            const trimmed = candidate.trim();
+            if (trimmed.length === 0)
+                continue; // never match the blank service-account row
+            if (trimmed === principalValue) {
+                allowed.add(syncId);
+                break;
+            }
+        }
+    }
+    return [...allowed];
+}
+/**
+ * Resolve the allowed sync IDs for a principal from the Actual server.
+ *
+ * FAILS CLOSED. Every error path returns [] (no access) rather than ['*'].
+ * An authorization source that opens up when the thing it queries is unreachable
+ * is worse than no authorization source at all.
+ */
+export async function resolveAllowedBudgetsFromActual(principalValue) {
+    if (!principalValue) {
+        log.warn('dynamic ACL: no usable principal value; denying', { claim: config.AUTH_BUDGET_ACL_CLAIM });
+        return [];
+    }
+    const cached = _cache.get(principalValue);
+    if (cached && Date.now() - cached.at < CACHE_TTL_MS)
+        return cached.allowed;
+    let files;
+    try {
+        // The scoped wildcard described in the header. Nothing outside this call
+        // observes it.
+        files = await requestContext.run({ allowedBudgets: ['*'] }, () => adapter.getBudgets());
+    }
+    catch (err) {
+        log.error('dynamic ACL: could not read the budget list; denying access', err);
+        return [];
+    }
+    const allowed = matchAllowedFiles(files, principalValue, config.AUTH_BUDGET_ACL_CLAIM);
+    if (allowed.length === 0) {
+        log.warn('dynamic ACL: principal matched no budget file', {
+            claim: config.AUTH_BUDGET_ACL_CLAIM,
+            fileCount: Array.isArray(files) ? files.length : 0,
+        });
+    }
+    _cache.set(principalValue, { at: Date.now(), allowed });
+    return allowed;
+}

package/dist/src/auth/budget-acl.js

@@ -24,6 +24,7 @@
 // to filter results by permitted sync IDs (forward-looking multi-budget support).
 import config from '../config.js';
 import logger from '../logger.js';
+import { extractPrincipalValue, resolveAllowedBudgetsFromActual } from './budget-acl-dynamic.js';
 // ---------------------------------------------------------------------------
 // ACL map (parsed once from env, cached)
 // ---------------------------------------------------------------------------
@@ -121,6 +122,12 @@ export function budgetAclMiddleware(req, res, next) {
         next();
         return;
     }
+    // #338: dynamic source. Deliberately a separate branch so the static path
+    // below is unreachable-by-default and byte-for-byte what it was before.
+    if (config.AUTH_BUDGET_ACL_SOURCE === 'actual') {
+        void resolveDynamicAcl(req, res, next);
+        return;
+    }
     const allowed = getAllowedBudgets(req);
     if (allowed.includes('*') || allowed.length > 0) {
         // Expose allowed budgets for use in tools
@@ -133,6 +140,39 @@ export function budgetAclMiddleware(req, res, next) {
     logger.warn(`[ACL] Access denied for '${identity}': no permitted budgets in ACL`);
     res.status(403).json({ error: 'Forbidden: no budget access configured for this user' });
 }
+/**
+ * #338: the async half of the middleware, for AUTH_BUDGET_ACL_SOURCE=actual.
+ *
+ * Split out rather than making budgetAclMiddleware itself async, because an
+ * async Express handler that rejects before Express 5's error plumbing sees it
+ * would hang the request. Here every path either calls next() or sends a
+ * response, and the catch is exhaustive, so a rejection cannot escape.
+ *
+ * The upstream read is cached per principal inside the resolver, so this is not
+ * an Actual API call per request.
+ */
+async function resolveDynamicAcl(req, res, next) {
+    const auth = req.auth;
+    const claims = (auth?.claims ?? {});
+    const subject = auth?.subject;
+    try {
+        const principalValue = extractPrincipalValue(claims, subject, config.AUTH_BUDGET_ACL_CLAIM);
+        const allowed = await resolveAllowedBudgetsFromActual(principalValue);
+        if (allowed.length > 0) {
+            req.allowedBudgets = allowed;
+            next();
+            return;
+        }
+        logger.warn(`[ACL] Access denied for '${subject ?? 'unknown'}': no budget files grant this principal access`);
+        res.status(403).json({ error: 'Forbidden: no budget access configured for this user' });
+    }
+    catch (err) {
+        // Fail closed. A resolver fault must never fall through to the static path
+        // or to an unrestricted context.
+        logger.error('[ACL] Dynamic ACL resolution failed; denying access', err);
+        res.status(403).json({ error: 'Forbidden: budget access could not be determined' });
+    }
+}
 /** Reset cached state (test helper). */
 export function _resetAclForTests() {
     _aclMap = null;

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(),
@@ -82,6 +95,27 @@ export const configSchema = z.object({
     // Example: {"alice@example.com":["budget-1"],"group:admin":["*"]}
     // Leave unset to allow all authenticated users to access all budgets.
     AUTH_BUDGET_ACL: z.string().optional(),
+    // #338: where the budget ACL comes from.
+    //   'static' (default) = AUTH_BUDGET_ACL above, exactly as before.
+    //   'actual'           = derived from the Actual server's own per-file access
+    //                        list (`usersWithAccess` on getBudgets()).
+    // Opt-in on purpose. Two reasons: it moves the authorization source from local
+    // reviewable config to data the UPSTREAM server returns at runtime, and it only
+    // functions when that server runs in multi-user (OpenID) mode. Defaulting to
+    // 'static' means no existing deployment changes posture on upgrade.
+    AUTH_BUDGET_ACL_SOURCE: z.enum(['static', 'actual']).default('static'),
+    // #338: which OIDC claim is matched against Actual's user identity when
+    // AUTH_BUDGET_ACL_SOURCE=actual. Default 'sub', matched against `userId`.
+    //
+    // Do NOT casually change this to a name-like claim. Verified against a live
+    // multi-user server: the MCP server's own service account appears in EVERY
+    // file's usersWithAccess with `owner: true` and a BLANK `userName`. A
+    // name-based match whose claim resolves to empty would match that row and gain
+    // owner access to every file. Matching UUIDs makes that unrepresentable.
+    AUTH_BUDGET_ACL_CLAIM: z
+        .string()
+        .default('sub')
+        .refine((v) => /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(v), 'AUTH_BUDGET_ACL_CLAIM must be a simple claim name'),
 })
     // When native TLS is enabled, both the cert and key paths must be provided.
     // MCP_ENABLE_HTTPS is transformed to a boolean above, so this object-level

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.6",
+  "version": "0.11.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/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",
+    "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 && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_middleware.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",
@@ -71,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",
@@ -84,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"