actual-mcp-server 0.22.44 → 0.22.47

package/README.md

@@ -836,7 +836,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.22.44 | **Tool Count:** 84 (verified LibreChat-compatible)
+**Version:** 0.22.47 | **Tool Count:** 84 (verified LibreChat-compatible)
 
 ## Sponsor
 

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

@@ -40,7 +40,10 @@
 // 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: ['*'] }, ...)`.
+// inside `requestContext.run({ allowedBudgets: ['*'] }, ...)`. Since #570 the
+// wildcard matters twice: `getBudgets()` also FILTERS its result to the context's
+// allowedBudgets, so without it the resolver would see only the files the
+// caller's (not yet computed) list already permits.
 //
 // 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

package/dist/src/index.js

@@ -105,7 +105,9 @@ const KNOWN_FLAGS = new Set([
     '--http', '--stdio', '--test-actual-connection', '--test-mcp-client',
     '--debug', '--help', '-h', '--version', '-v',
 ]);
-const unknownFlags = argsEarly.filter(a => a.startsWith('-') && !KNOWN_FLAGS.has(a));
+// A bare `--` is the conventional end-of-options marker that `node script.js -- --flag` passes
+// through (the npm `dev` and `test:mcp-client` launchers did, #565); it is not an option.
+const unknownFlags = argsEarly.filter(a => a.startsWith('-') && a !== '--' && !KNOWN_FLAGS.has(a));
 if (unknownFlags.length > 0) {
     console.error(`Unknown option: ${unknownFlags.join(', ')}\nRun \`actual-mcp-server --help\` for usage.`);
     process.exit(1);
@@ -314,13 +316,23 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
         // If requested, run the MCP client-side tests now that all variables are ready
         if (useTestMcpClient) {
             logger.info('⚙️  --test-mcp-client specified, starting HTTP server and running client-side MCP tests...');
-            // start server in http mode. Bind all interfaces by default (#239): advertisedUrl
-            // uses the LAN IP (getLocalIp), so the self-test client must be able to reach it.
+            // start server in http mode. Bind all interfaces by default (#239).
             await startHttpServer(mcp, PORT, HTTP_PATH, capabilities, implementedTools, SERVER_DESCRIPTION, serverInstructionsText, toolSchemas, version, bindHost, advertisedUrl);
             // dynamic import to avoid circular at top
             const { testMcpClient } = await import('./tests/testMcpClient.js');
             try {
-                await testMcpClient(advertisedUrl, PORT, HTTP_PATH);
+                // #565: the self-test talks to the address this process bound, not advertisedUrl. The
+                // advertised LAN IP can be answered by another listener on the same port (a Docker
+                // container publishing it is NATed ahead of local sockets), which turned the run into a
+                // 401 from a different server. A wildcard bind is reached on loopback, '::' on '::1' (an
+                // IPv6-only socket refuses IPv4). The scheme is the listener's, not the advertised one
+                // (MCP_BRIDGE_PUBLIC_SCHEME and MCP_BRIDGE_USE_TLS only change what is advertised).
+                // Under native TLS the advertised host is kept: the certificate names it, not 127.0.0.1.
+                const nativeTls = process.env.MCP_ENABLE_HTTPS === 'true';
+                const loopback = bindHost === '0.0.0.0' ? '127.0.0.1' : bindHost === '::' ? '::1' : bindHost;
+                const selfHost = nativeTls ? advertisedHost : loopback;
+                const selfUrl = `${nativeTls ? 'https' : 'http'}://${selfHost.includes(':') ? `[${selfHost}]` : selfHost}:${PORT}${HTTP_PATH}`;
+                await testMcpClient(selfUrl, HTTP_PATH);
                 logger.info('✅ MCP client-side tests passed');
                 process.exit(0);
             }

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

@@ -48,6 +48,15 @@ function _splitInList(valuesStr) {
 /** A single-quoted literal whose internal quotes are SQL-ESCAPED by doubling.
  *  `'McDonald''s'` matches; `'McDonald's'` (a lone quote) does not. */
 const SQL_ESCAPED_SINGLE_QUOTED = /^'(?:[^']|'')*'$/;
+// ActualQL's value compiler escapes comparison and LIKE strings for SQLite, so SQL's doubled
+// apostrophe must be decoded first. IN uses a separate path that deliberately preserves it.
+function _stripWhereSqlLiteral(s) {
+    const t = s.trim();
+    if (SQL_ESCAPED_SINGLE_QUOTED.test(t)) {
+        return t.slice(1, -1).replace(/''/g, "'");
+    }
+    return _stripWhereQuotes(s);
+}
 function _isSafeInListElement(raw) {
     const t = raw.trim();
     // #433: a single-quoted element may now carry DOUBLED internal quotes. That is
@@ -83,11 +92,11 @@ function _coerceInListValue(s) {
     }
     return _coerceWhereValue(s);
 }
-// Coerce a SQL value literal to a number when it looks numeric, else keep the
-// (unquoted) string. Used for IN lists and comparison operands. Empty stays a
-// string so an empty literal is not silently turned into 0.
+// Coerce a comparison operand (and an IN element with no doubled quote) to a number when it
+// looks numeric, else keep the unquoted string. Empty stays a string so an empty literal is not
+// turned into 0.
 function _coerceWhereValue(s) {
-    const v = _stripWhereQuotes(s);
+    const v = _stripWhereSqlLiteral(s);
     if (v === '')
         return v;
     const n = Number(v);
@@ -158,7 +167,7 @@ export function parseWhereClause(query, whereClause, tableName) {
         const notLikeMatch = trimmedCondition.match(/^([\w.]+)\s+NOT\s+LIKE\s+(.+)$/i);
         if (notLikeMatch) {
             const [, field, valueStr] = notLikeMatch;
-            query = query.filter({ [field]: { $notlike: _stripWhereQuotes(valueStr) } });
+            query = query.filter({ [field]: { $notlike: _stripWhereSqlLiteral(valueStr) } });
             continue;
         }
         // LIKE: pattern match. ActualQL's $like runs through NORMALISE + UNICODE_LIKE,
@@ -167,7 +176,7 @@ export function parseWhereClause(query, whereClause, tableName) {
         const likeMatch = trimmedCondition.match(/^([\w.]+)\s+LIKE\s+(.+)$/i);
         if (likeMatch) {
             const [, field, valueStr] = likeMatch;
-            query = query.filter({ [field]: { $like: _stripWhereQuotes(valueStr) } });
+            query = query.filter({ [field]: { $like: _stripWhereSqlLiteral(valueStr) } });
             continue;
         }
         // IN clause: field IN (value1, value2, ...)
@@ -221,7 +230,25 @@ export function parseWhereClause(query, whereClause, tableName) {
             // operators are left to their normal path, where ActualQL will reject them for a boolean as
             // it does today, rather than us inventing an ordering the column does not have.
             const isBool = _isBooleanField(tableName, field) && (actualOp === '$eq' || actualOp === '$ne');
-            const finalValue = isBool ? _coerceBoolean(field, valueStr) : _coerceWhereValue(valueStr);
+            const isText = tableName !== undefined && getFieldType(tableName, field) === 'string';
+            // #567 review: a quoted number stays a string on a text column. Coercing `notes = '123'` to
+            // the number 123 made upstream throw "Can't convert integer to string".
+            const finalValue = isBool
+                ? _coerceBoolean(field, valueStr)
+                : isText ? _stripWhereSqlLiteral(valueStr) : _coerceWhereValue(valueStr);
+            // #567 review: upstream's val() (aql/compiler.ts) re-escapes a value only when it casts to
+            // type `string`. A value compared against an `id` column is inlined as `'${value}'` with NO
+            // escaping, so a quote in it closes the literal: `account = 'x'||(SELECT ...)||'x'` ran the
+            // subquery, past both validators, and decoding `''` made the doubled form do the same. A
+            // quote is therefore allowed only on a column our schema types as `string` (checked against
+            // upstream's schema: every one of them is `string` there, or does not exist and fails to
+            // compile). Any other or unknown type refuses it, which is fail closed: no id, date, number
+            // or boolean legitimately contains a single quote. LIKE and NOT LIKE always cast to string,
+            // so they need no such check.
+            if (!isText && typeof finalValue === 'string' && finalValue.includes("'")) {
+                throw new Error(`Invalid value for column "${field}": a single quote is only allowed in a value ` +
+                    `compared against a text column (for example payee.name = 'O''Brien').`);
+            }
             if (actualOp === '$eq') {
                 // Simple equality can use the direct field: value shorthand.
                 query = query.filter({ [field]: finalValue });
@@ -252,8 +279,9 @@ const NAME_CONDITION_TABLES = {
  * `NOT LIKE` are skipped: an unknown name there cannot make the result empty. Each condition is
  * ONE lookup, an IN list included (the ticket allows one extra read per name condition), and the
  * lookup reuses the main query's operator and value, so a `$oneof` element compiles exactly as in
- * the main query (where upstream inlines the doubled-quote form #433 keeps). A numeric-looking
- * literal arrives coerced to a number and is kept as is.
+ * the main query (where upstream inlines the doubled-quote form #433 keeps). The three name
+ * columns are text, so since #567 a numeric-looking `=` value arrives as a string; a number is
+ * still accepted (an IN element can be one) and kept as is.
  */
 export function nameConditionLookups(filterExpressions) {
     const out = [];

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

@@ -379,9 +379,7 @@ function abortBatchOnInfrastructureError(error, ctx) {
  * Claude Desktop / Claude Code compatibility.
  */
 function _enforceBudgetAcl(toolName) {
-    const store = requestContext.getStore();
-    const sessionId = store?.sessionId;
-    const allowedBudgets = store?.allowedBudgets;
+    const sessionId = requestContext.getStore()?.sessionId;
     // Trusted-local short-circuit. stdio and startup health checks run with no
     // sessionId; in non-OIDC modes those are by-construction trusted (single
     // user, local process). The ACL only applies when an authenticated multi-
@@ -389,20 +387,8 @@ function _enforceBudgetAcl(toolName) {
     if (!sessionId && config.AUTH_PROVIDER !== 'oidc') {
         return;
     }
-    // OIDC + no allowedBudgets in context: the request slipped past the
-    // middleware. Defence-in-depth: refuse rather than fail open.
-    if (config.AUTH_PROVIDER === 'oidc' && !allowedBudgets) {
-        logger.warn(JSON.stringify({
-            event: 'acl_denied',
-            reason: 'no_allowed_budgets_in_context',
-            sessionId: sessionId ?? null,
-            tool: toolName ?? null,
-        }));
-        throw new Error('Budget ACL: no allowedBudgets in request context. ' +
-            'This request bypassed the budget-acl middleware. Refusing for safety. See #156.');
-    }
-    // No restriction.
-    if (!allowedBudgets || allowedBudgets.includes('*'))
+    const allowedBudgets = restrictedAllowedBudgets(toolName);
+    if (!allowedBudgets)
         return;
     const target = getActiveBudgetConfig();
     if (!allowedBudgets.includes(target.syncId)) {
@@ -414,9 +400,46 @@ function _enforceBudgetAcl(toolName) {
             sessionId: sessionId ?? null,
             tool: toolName ?? null,
         }));
-        throw new Error(`Budget ACL: budget "${target.name}" (${target.syncId}) is not in this session's allowedBudgets.`);
+        // #570: the name and syncId stay in the log above, never in the caller-facing
+        // text. With no selection the active budget is the registry's first entry, so
+        // naming it told a principal allowed only another budget what the default was.
+        throw new Error("Budget ACL: the active budget is not in this session's allowedBudgets. " +
+            'Call actual_budgets_list_available and switch to a permitted budget.');
     }
 }
+/**
+ * The request's budget allow-list when the caller is RESTRICTED, else `undefined` (#570).
+ *
+ * Shared by `_enforceBudgetAcl` (the active budget) and the paths that check nothing
+ * about the active budget: the two listings, the import and the switch's not-found
+ * list. One decision, so the two kinds of check cannot drift apart.
+ *
+ *   - `AUTH_PROVIDER=oidc` with no `allowedBudgets` in context: the request slipped
+ *     past the middleware, so throw (fail closed), with an `acl_denied` warn.
+ *   - a list containing `"*"`, or no list outside OIDC (bearer, no-auth, stdio, CLI,
+ *     startup): unrestricted.
+ *   - otherwise: the list.
+ *
+ * Keyed on the request's allow-list, not on AUTH_PROVIDER, so any auth mode that
+ * attaches a list is restricted by it.
+ */
+function restrictedAllowedBudgets(toolName) {
+    const store = requestContext.getStore();
+    const allowedBudgets = store?.allowedBudgets;
+    if (config.AUTH_PROVIDER === 'oidc' && !allowedBudgets) {
+        logger.warn(JSON.stringify({
+            event: 'acl_denied',
+            reason: 'no_allowed_budgets_in_context',
+            sessionId: store?.sessionId ?? null,
+            tool: toolName ?? null,
+        }));
+        throw new Error('Budget ACL: no allowedBudgets in request context. ' +
+            'This request bypassed the budget-acl middleware. Refusing for safety. See #156.');
+    }
+    if (!allowedBudgets || allowedBudgets.includes('*'))
+        return undefined;
+    return allowedBudgets;
+}
 /**
  * Helper to run an operation with the Actual API ready, deciding the lifecycle
  * mode automatically:
@@ -3862,7 +3885,18 @@ export async function getBudgets() {
     return withActualApi(async () => {
         observability.incrementToolCall('actual.budgets.getAll').catch(() => { });
         const raw = await withConcurrency(() => retry(() => rawGetBudgets(), { retries: 2, backoffMs: 200 }));
-        return Array.isArray(raw) ? raw : [];
+        const files = Array.isArray(raw) ? raw : [];
+        // #570: a restricted caller sees only files whose groupId (the sync id) it may
+        // use. A file with no groupId was never uploaded and belongs to no list. The
+        // dynamic ACL resolver calls this under its own `allowedBudgets: ['*']`, so it
+        // still sees every file.
+        const allowed = restrictedAllowedBudgets('actual_budgets_get_all');
+        if (!allowed)
+            return files;
+        return files.filter(f => {
+            const groupId = f?.groupId;
+            return typeof groupId === 'string' && allowed.includes(groupId);
+        });
     });
 }
 /**
@@ -3899,12 +3933,18 @@ export async function switchBudget(name) {
     }
     const key = name.toLowerCase();
     const found = budgetRegistry.get(key);
-    if (!found) {
-        const available = [...budgetRegistry.values()].map(b => `"${b.name}"`).join(', ');
-        throw new Error(`Budget "${name}" not found in configuration. ` +
+    // #570: a restricted caller is told only about budgets it may use.
+    const notFound = () => {
+        const permitted = restrictedAllowedBudgets('actual_budgets_switch');
+        const available = [...budgetRegistry.values()]
+            .filter(b => !permitted || permitted.includes(b.syncId))
+            .map(b => `"${b.name}"`).join(', ') || 'none permitted for this session';
+        return new Error(`Budget "${name}" not found in configuration. ` +
             `Available budgets: ${available}. ` +
             `Add BUDGET_n_NAME/SYNC_ID/SERVER_URL vars to configure additional budgets.`);
-    }
+    };
+    if (!found)
+        throw notFound();
     // ACL enforcement: the target budget must be in this session's allowedBudgets.
     // OIDC mode: explicit ACL required. Non-OIDC: short-circuit allow (single-user).
     if (config.AUTH_PROVIDER === 'oidc') {
@@ -3926,7 +3966,12 @@ export async function switchBudget(name) {
                 sessionId,
                 tool: 'actual_budgets_switch',
             }));
-            throw new Error(`Budget ACL: budget "${found.name}" (${found.syncId}) is not in this session's allowedBudgets.`);
+            // #570: a denied budget gets the SAME error as an unknown name, so guessing
+            // names cannot confirm that a budget outside the list exists. The round 1
+            // review accepted a distinct "Budget ACL:" refusal here; that was reversed
+            // because hiding other budgets is the point of this ticket. The log above
+            // keeps the syncId for the operator.
+            throw notFound();
         }
     }
     // #189 Phase 1: the principal's chosen budget is persisted at each commit
@@ -4033,10 +4078,13 @@ export function clearSessionBudgetState(sessionId) {
     sessionBudgetState.delete(sessionId);
 }
 /**
- * Return all configured budgets from the registry (for listing in actual_budgets_list_available).
+ * Return the configured budgets this caller may use (for actual_budgets_list_available).
+ * A restricted caller sees only its permitted entries (#570); the startup registry log
+ * reads the Map directly and is not filtered.
  */
 export function getBudgetRegistry() {
-    return [...budgetRegistry.values()].map(b => ({
+    const allowed = restrictedAllowedBudgets('actual_budgets_list_available');
+    return [...budgetRegistry.values()].filter(b => !allowed || allowed.includes(b.syncId)).map(b => ({
         name: b.name,
         syncId: b.syncId,
         serverUrl: b.serverUrl,
@@ -4237,11 +4285,28 @@ export async function exportBudget() {
  * 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.
+ * resolved for this request. The resulting budget is un-ACL'd because it did not
+ * exist when the ACL was built, so a RESTRICTED caller is refused outright (#570),
+ * before any lock or upstream call. Wildcard and unrestricted callers can still
+ * import; the write queue also enforces the ACL on their active budget.
+ *
+ * Upstream creates a NEW cloud file for the import (fresh id, best-effort upload),
+ * so it never overwrites another budget on the server. The local copy is keyed by
+ * the archive's own id, so an archive of budget X replaces X's LOCAL copy.
  */
 export async function importBudget(input, opts = {}) {
+    const restricted = restrictedAllowedBudgets('actual_budgets_import');
+    if (restricted) {
+        logger.warn(JSON.stringify({
+            event: 'acl_denied',
+            reason: 'import_by_restricted_principal',
+            allowedBudgets: restricted,
+            sessionId: requestContext.getStore()?.sessionId ?? null,
+            tool: 'actual_budgets_import',
+        }));
+        throw new Error('Budget ACL: actual_budgets_import is not available to a session with a restricted ' +
+            'allowedBudgets list: the imported budget would belong to no permitted list.');
+    }
     observability.incrementToolCall('actual.budgets.import').catch(() => { });
     const result = await queueWriteOperation(async () => {
         // #394: an import re-points the process-global singleton exactly as a download does, so it

package/dist/src/lib/query-validator.js

@@ -175,7 +175,12 @@ function extractWhereFields(sql) {
     // comparison operator, but also before IN / LIKE / IS / BETWEEN (with their NOT forms). Before
     // this, `bogus_col IN ('a')`, `bogus_col LIKE '%a%'` and `bogus_col IS NULL` extracted no field
     // and so skipped the allowlist check entirely, while `bogus_col = 'a'` was correctly rejected.
-    const fieldMatches = whereClause.matchAll(/(\w+)\.(\w+)|(?:^|\s)(\w+)\s*[=<>!]|(?:^|\s)(\w+)\s+(?:NOT\s+)?(?:IN|LIKE|BETWEEN)\b|(?:^|\s)(\w+)\s+IS\b/gi);
+    // #566: the IN / LIKE / BETWEEN alternative must not capture the keyword NOT as a field. After
+    // `(\w+)\.(\w+)` consumes a joined name such as `payee.name`, the scan resumes at ` NOT LIKE`,
+    // and without the `(?!NOT\s)` lookahead that alternative read `NOT` as a column and rejected a
+    // valid query with `Field "NOT" does not exist`. The lookahead is exact on purpose: it skips only
+    // the word NOT followed by whitespace, so every real column name is still extracted and checked.
+    const fieldMatches = whereClause.matchAll(/(\w+)\.(\w+)|(?:^|\s)(\w+)\s*[=<>!]|(?:^|\s)(?!NOT\s)(\w+)\s+(?:NOT\s+)?(?:IN|LIKE|BETWEEN)\b|(?:^|\s)(\w+)\s+IS\b/gi);
     for (const match of fieldMatches) {
         if (match[1] && match[2]) {
             // table.field

package/dist/src/tests/testMcpClient.js

@@ -1,9 +1,9 @@
-export async function testMcpClient(advertisedUrl, _port, httpPath) {
+export async function testMcpClient(serverUrl, httpPath) {
     // Try builtin fetch or fallback to node-fetch if necessary
     const globalFetch = globalThis.fetch;
     const fetchAny = globalFetch ?? (await import('node-fetch')).default;
     const fetchFn = fetchAny;
-    const base = new URL(advertisedUrl);
+    const base = new URL(serverUrl);
     // quick probe endpoint (#286: the server-info probe moved off the reserved
     // /.well-known/oauth-protected-resource OAuth path to the non-reserved /mcp-info,
     // now a bare object; the `result ?? raw` unwrap below tolerates both shapes).
@@ -104,8 +104,12 @@ export async function testMcpClient(advertisedUrl, _port, httpPath) {
         headers: listHeaders,
         body: JSON.stringify(listPayload),
     });
-    if (!listRes.ok)
-        throw new Error(`tools/list failed: ${listRes.status}`);
+    if (!listRes.ok) {
+        // #565: a 404 here is usually the session's Actual connection failing (bad credentials or no
+        // reachable server); the body names the cause (#438), so carry it rather than a bare status.
+        const body = await listRes.json().catch(() => undefined);
+        throw new Error(`tools/list failed: ${listRes.status}${body === undefined ? '' : ` ${JSON.stringify(body).slice(0, 300)}`}`);
+    }
     const listJsonRaw = await listRes.json();
     const listJsonObj = listJsonRaw && typeof listJsonRaw === 'object' ? listJsonRaw : undefined;
     if (!listJsonObj || !('result' in listJsonObj))

package/dist/src/tools/budgets_get_all.js

@@ -3,7 +3,7 @@ import adapter from '../lib/actual-adapter.js';
 const InputSchema = z.object({});
 const tool = {
     name: 'actual_budgets_get_all',
-    description: 'Get a list of all available budget files. Useful for multi-budget management and discovering available budgets on the server.',
+    description: 'Get the budget files on the server that this session may use. Useful for multi-budget management and discovering available budgets.',
     inputSchema: InputSchema,
     call: async (_args, _meta) => {
         const result = await adapter.getBudgets();

package/dist/src/tools/budgets_import.js

@@ -7,13 +7,12 @@ import adapter from '../lib/actual-adapter.js';
  * 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.
+ * 1. IT CAN OVERWRITE AN EXISTING BUDGET'S LOCAL COPY. The local budget directory is
+ *    keyed by the id the ARCHIVE carries, so re-importing an export of budget X
+ *    replaces X's local data. On the SERVER it never overwrites anything (#570):
+ *    `importActual` clears the cloud file and group ids and uploads the result as a
+ *    NEW budget file (best effort; a failed upload leaves it local only).
+ *    A session with a restricted budget ACL is refused this tool outright (#570).
  * 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
@@ -66,7 +65,7 @@ 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 ' +
+        'budget\'s local copy, and the result is uploaded to the server as a new budget file. 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 ' +

package/dist/src/tools/budgets_list_available.js

@@ -3,7 +3,7 @@ import adapter from '../lib/actual-adapter.js';
 const InputSchema = z.object({});
 const tool = {
     name: 'actual_budgets_list_available',
-    description: 'List all pre-configured budgets available for switching. ' +
+    description: 'List the pre-configured budgets this session may switch to (a session limited to some budgets sees only those). ' +
         'Each entry shows the budget name, sync ID, server URL, and whether it uses E2E encryption. ' +
         'Budgets are configured via BUDGET_n_NAME / BUDGET_n_SYNC_ID / BUDGET_n_SERVER_URL env vars. ' +
         'Pass the budget name to actual_budgets_switch to change the active budget.',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.22.44",
+  "version": "0.22.47",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
@@ -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/transactions_aggregate.test.js && node tests/unit/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.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/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/new_tool_completeness.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/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.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/adapter_set_budget_batch.test.js && node tests/unit/budget_updates_batch.test.js && node tests/unit/rules_create.test.js && node tests/unit/adapter_rule_reference_guard.test.js && node tests/unit/rules_create_batch.test.js && node tests/unit/budgets_hold_for_next_month.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/httpServer_init_failure_report.test.js && node tests/unit/stdio_init_failure_report.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/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.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/session_ownership.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/oidc_resource_identifier.test.js && node tests/unit/httpServer_oidc_resource_metadata.test.js && node tests/unit/oidc_error_cause.test.js && node tests/unit/httpServer_oidc_error_body.test.js && node tests/unit/oidc_token_source.test.js && node tests/unit/config_oidc_assertion_refines.test.js && node tests/unit/httpServer_oidc_assertion_mode.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpErrorHandler.test.js && node tests/unit/httpServer_error_handler_wiring.test.js && node tests/unit/httpServer_trust_proxy.test.js && node tests/unit/httpServer_batch_cap.test.js && node tests/unit/dotenv_stdout_quiet.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.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/transactions_update_split_convert.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/transactions_update_batch.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/stdio_budget_switch.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/tool_content_logging.test.js && node tests/unit/adapter_error_logging.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/playwright_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/batch_uncategorized_cleanup.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/server_version_probe_outside_op_timeout.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/budgets_import_syncid.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js && node tests/unit/oidc_scope_list.test.js && node tests/unit/get_context.test.js && node tests/unit/contributor_docs.test.js && node tests/unit/toolsets.test.js && node tests/unit/toolsets_entrypoint.test.js && node tests/unit/tools_list_size_budget.test.js && node tests/unit/rules_update_schedules_schema.test.js && node tests/unit/schedules_update_amount_guard.test.js && node tests/unit/source_text_helper.test.js && node tests/unit/transport_onerror.test.js && node tests/unit/adapter_transaction_batch_abort.test.js && node tests/unit/transactions_merge_adapter.test.js && node tests/unit/schedules_dead_conditions.test.js && node tests/unit/session_ownership_express.test.js && node tests/unit/pool_orphan_sweep.test.js && node tests/unit/session_budget_state_cleanup.test.js && node tests/unit/http_session_delete.test.js && node tests/unit/budget_acl_parse.test.js && node tests/unit/server_instructions.test.js && node tests/unit/query_run_empty_hint.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/transactions_aggregate.test.js && node tests/unit/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.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/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/new_tool_completeness.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/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.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/adapter_set_budget_batch.test.js && node tests/unit/budget_updates_batch.test.js && node tests/unit/rules_create.test.js && node tests/unit/adapter_rule_reference_guard.test.js && node tests/unit/rules_create_batch.test.js && node tests/unit/budgets_hold_for_next_month.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/httpServer_init_failure_report.test.js && node tests/unit/stdio_init_failure_report.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/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.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/session_ownership.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/oidc_resource_identifier.test.js && node tests/unit/httpServer_oidc_resource_metadata.test.js && node tests/unit/oidc_error_cause.test.js && node tests/unit/httpServer_oidc_error_body.test.js && node tests/unit/oidc_token_source.test.js && node tests/unit/config_oidc_assertion_refines.test.js && node tests/unit/httpServer_oidc_assertion_mode.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpErrorHandler.test.js && node tests/unit/httpServer_error_handler_wiring.test.js && node tests/unit/httpServer_trust_proxy.test.js && node tests/unit/httpServer_batch_cap.test.js && node tests/unit/dotenv_stdout_quiet.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_acl_listing.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.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/transactions_update_split_convert.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/transactions_update_batch.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/stdio_budget_switch.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/tool_content_logging.test.js && node tests/unit/adapter_error_logging.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/playwright_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/batch_uncategorized_cleanup.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/server_version_probe_outside_op_timeout.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/budgets_import_syncid.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js && node tests/unit/oidc_scope_list.test.js && node tests/unit/get_context.test.js && node tests/unit/contributor_docs.test.js && node tests/unit/toolsets.test.js && node tests/unit/toolsets_entrypoint.test.js && node tests/unit/tools_list_size_budget.test.js && node tests/unit/rules_update_schedules_schema.test.js && node tests/unit/schedules_update_amount_guard.test.js && node tests/unit/source_text_helper.test.js && node tests/unit/transport_onerror.test.js && node tests/unit/adapter_transaction_batch_abort.test.js && node tests/unit/transactions_merge_adapter.test.js && node tests/unit/schedules_dead_conditions.test.js && node tests/unit/session_ownership_express.test.js && node tests/unit/pool_orphan_sweep.test.js && node tests/unit/session_budget_state_cleanup.test.js && node tests/unit/http_session_delete.test.js && node tests/unit/budget_acl_parse.test.js && node tests/unit/server_instructions.test.js && node tests/unit/query_run_empty_hint.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",