actual-mcp-server 0.16.9 → 0.16.10

package/README.md

@@ -775,7 +775,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.16.9 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.16.10 | **Tool Count:** 74 (verified LibreChat-compatible)
 
 ## Sponsor
 

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

@@ -0,0 +1,85 @@
+/**
+ * #388: what an OPTIONAL FILTER id means when the caller passes a NAME.
+ *
+ * The surface used to answer that question three different ways, and the inconsistency was the
+ * real defect rather than the schema question that surfaced it:
+ *
+ *   1. `transactions_search_by_amount` DETECTED the name, looked it up, and answered with the
+ *      correct UUID. Strictly the most useful thing any of them did.
+ *   2. `transactions_get` pre-flighted and returned `notFoundMsg`, naming the entity and the
+ *      listing tool but not resolving the name.
+ *   3. Everything else silently returned an EMPTY result set, which is the worst of the three:
+ *      a plausible-looking wrong answer that reads as "no transactions match".
+ *
+ * #380 swept the REQUIRED lookup ids onto `CommonSchemas` and deliberately left these behind,
+ * because tightening them is a contract decision rather than a sweep. Tightening alone (making
+ * the schema reject a non-UUID) would have deleted accommodation 1, trading the best message on
+ * the surface for a ZodError. So the schema stays a bare string and the answer moves here.
+ *
+ * THE FAST PATH READS NOTHING. A value that is already a UUID is returned untouched, without a
+ * listing call, so a correct call costs exactly what it costs today. The listing read happens
+ * only on the unhappy path, where the caller has already made a mistake and the alternative is
+ * a wrong answer.
+ *
+ * This module is deliberately PURE so it can be unit-tested without an api session; the adapter
+ * owns the impure half (fetching the listing) because that is where a listing read gets `retry`
+ * and the observability call site, and because #371 and #376 concluded that a check the tools
+ * share belongs in the adapter rather than copied into ten tool files.
+ */
+import { UUID_PATTERN } from '../constants.js';
+/** Human-readable entity name and the tool that lists it, for the refusal message. */
+export const FILTER_ID_ENTITIES = {
+    account: { entity: 'Account', listTool: 'actual_accounts_list' },
+    category: { entity: 'Category', listTool: 'actual_categories_get' },
+    payee: { entity: 'Payee', listTool: 'actual_payees_get' },
+};
+/**
+ * Is this value already a well-formed entity id?
+ *
+ * When it is, NOTHING else in this module runs: the value is handed straight back and no
+ * listing is read. That is what keeps the change free for every correct call, and it is also
+ * why a non-existent but well-formed UUID still behaves exactly as it does today (an empty
+ * result). Checking existence would mean a listing read on EVERY call, which is a cost this
+ * ticket explicitly declined to impose to fix a mistake nobody makes: the failure being fixed
+ * is a name passed where an id belongs, not a mistyped UUID.
+ */
+export function isEntityId(value) {
+    return UUID_PATTERN.test(value);
+}
+/**
+ * Find the row whose NAME is what the caller passed.
+ *
+ * Case-insensitive and trimmed, matching the accommodation this generalises. Returns undefined
+ * rather than throwing so the caller decides between "resolved" and "no such name", which are
+ * two different messages.
+ *
+ * Ambiguity is resolved by taking the FIRST match, deliberately. Actual permits two categories
+ * with the same name in different groups, so a name is not a key. Reporting the first is still
+ * strictly better than the empty result set this replaces, and the message names the id it
+ * chose, so a caller who meant the other one can see that it is not theirs.
+ */
+export function matchByName(rows, value) {
+    const wanted = value.trim().toLowerCase();
+    if (wanted === '')
+        return undefined;
+    return rows.find((r) => typeof r.name === 'string' && r.name.trim().toLowerCase() === wanted);
+}
+/**
+ * The refusal text for a name that DID resolve.
+ *
+ * It names the id rather than silently substituting it. Substituting would be friendlier for
+ * one call and wrong as a contract: the caller's next call would still pass the name, and a
+ * server that quietly accepts names has no way to report the ambiguity above.
+ */
+export function resolvedNameDetail(kind, name, id) {
+    const { entity, listTool } = FILTER_ID_ENTITIES[kind];
+    const noun = entity.toLowerCase();
+    // The article matters here only because getting it wrong ("a account") reads as a bug in the
+    // server to the person who hits this, and this string is the one they see.
+    const article = /^[aeiou]/.test(noun) ? 'an' : 'a';
+    // The ANSWER comes first, deliberately. The generic not-found prefix would otherwise put "use
+    // the listing tool" ahead of the id we already resolved, and that is the instruction a model
+    // follows.
+    return (`"${name}" is ${article} ${noun} NAME, not an id. Use "${id}" instead ` +
+        `(${listTool} lists them if that is not the ${noun} you meant).`);
+}

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

@@ -1345,6 +1345,7 @@ export const notifications = new EventEmitter();
 // Extracted to ./actual-adapter/normalize.ts (#166). Imported for internal use
 // and re-exported so the public surface and external importers are unchanged.
 import { normalizeToTransactionArray, normalizeToId, normalizeImportResult } from './actual-adapter/normalize.js';
+import { isEntityId, matchByName, resolvedNameDetail, FILTER_ID_ENTITIES } from './actual-adapter/filter-ids.js';
 export { normalizeToTransactionArray, normalizeToId, normalizeImportResult };
 // ---------------------------------------------------------------------------
 export async function getAccounts() {
@@ -1524,6 +1525,64 @@ export async function getPayees() {
         return await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
     });
 }
+/**
+ * #388: turn an optional FILTER id that is actually a NAME into a refusal that names the id.
+ *
+ * Every Category B field routes through here, so the surface has ONE answer to the single most
+ * likely caller mistake instead of the three it had (a helpful resolution in one tool, a bare
+ * not-found in another, and a silent empty result set in the other nine).
+ *
+ * COSTS NOTHING ON THE HAPPY PATH. A well-formed id returns immediately, with no listing read,
+ * so a correct call is byte-identical to before. Only a non-id value pays a listing, and only
+ * because the alternative is answering it with an empty result the caller will read as "no
+ * matches".
+ *
+ * It lives in the adapter rather than in the ten tool files for the reason #371 and #376 both
+ * landed on: a check the tools share belongs where the reads keep `retry` and the observability
+ * call site, and where the next caller of the same listing cannot skip it by accident.
+ *
+ * It THROWS rather than returning a result envelope, per #377's taxonomy: does-not-exist throws,
+ * and `{ success: false }` is only for a genuine multi-outcome contract. A filter id that names
+ * nothing is not a multi-outcome contract. That is also why the four tools that already had an
+ * accommodation stop returning `{ transactions: [], count: 0, error }`: an empty result set with
+ * an error tucked inside it is the shape this ticket exists to remove, not a milder version of it.
+ *
+ * `verifyExists` EXISTS SO THIS CHANGE REMOVES NOTHING, and the asymmetry is deliberate rather
+ * than an oversight, so do not "tidy" it into one behaviour without deciding the same question
+ * again. Five tools already read the listing unconditionally and already refuse a well-formed id
+ * that names nothing; they pass `verifyExists: true` and keep exactly that, with a better message.
+ * The rest never paid a listing read, and making them pay one on EVERY call to catch a mistyped
+ * UUID would impose a cost on every correct call to fix a mistake nobody makes. The mistake that
+ * actually happens, and that this ticket is about, is a NAME passed where an id belongs, which is
+ * caught on both paths because a name is never a UUID.
+ */
+export async function resolveFilterId(kind, value, opts) {
+    // The free path, and the one every correct call takes.
+    if (!opts?.verifyExists && isEntityId(value))
+        return value;
+    const { entity, listTool } = FILTER_ID_ENTITIES[kind];
+    // `rows` lets a caller that ALREADY holds the listing avoid a second read of it. Without it,
+    // `transactions_search_by_category` (which fetches accounts anyway, for off-budget filtering
+    // and enrichment) would pay two listing calls on every filtered call, which is a cost this
+    // change is supposed to avoid rather than introduce.
+    const rows = opts?.rows
+        ?? (kind === 'account' ? await getAccounts()
+            : kind === 'category' ? await getCategories()
+                : await getPayees());
+    if (isEntityId(value)) {
+        // Only reachable under verifyExists. A well-formed id that names nothing is a not-found,
+        // not a name to resolve.
+        if (rows.some((r) => r.id === value))
+            return value;
+        throw new NotFoundRefusal(entity, value, listTool);
+    }
+    const hit = matchByName(rows, value);
+    if (hit && typeof hit.id === 'string') {
+        const resolved = resolvedNameDetail(kind, String(hit.name), hit.id);
+        throw new NotFoundRefusal(entity, value, listTool, undefined, resolved);
+    }
+    throw new NotFoundRefusal(entity, value, listTool);
+}
 export async function getCommonPayees() {
     return withActualApi(async () => {
         observability.incrementToolCall('actual.payees.commonList').catch(() => { });
@@ -3196,6 +3255,7 @@ export async function getPreferences() {
 }
 export default {
     getAccounts,
+    resolveFilterId,
     getAccountsWithBalances,
     addTransactions,
     importTransactions,

package/dist/src/lib/errors.js

@@ -60,8 +60,17 @@ export class NotFoundRefusal extends PreflightRefusal {
      * @param listTool  MCP tool name the caller should use to get valid ids
      * @param detail    Optional extra sentence, e.g. what was NOT written as a result
      */
-    constructor(entity, id, listTool, detail) {
-        super(notFoundMsg(entity, id, listTool) + (detail ? ` ${detail}` : ''), 'not-found');
+    /**
+     * `overrideMessage` is for the one case where we can say something strictly MORE useful than
+     * "not found, go and list them": we already know the answer. #388 resolves a NAME passed where
+     * an id belongs, so telling the caller to list the accounts buries the id we just found behind
+     * an instruction they no longer need, and a model reading top to bottom will follow the
+     * instruction rather than the answer. The TYPE is unchanged, because the request still names
+     * something that does not exist under that identifier, and #377 is explicit that callers branch
+     * on the type rather than on message prose.
+     */
+    constructor(entity, id, listTool, detail, overrideMessage) {
+        super(overrideMessage ?? (notFoundMsg(entity, id, listTool) + (detail ? ` ${detail}` : '')), 'not-found');
         this.entity = entity;
         this.id = id;
         this.listTool = listTool;

package/dist/src/tools/bank_sync.js

@@ -9,6 +9,14 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
+        // #388: the one Category B field where `verifyExists: true` is worth a listing read on the
+        // HAPPY path too. Every other filter id costs at most a wrong-looking local result; this one
+        // reaches a THIRD PARTY, so an id that names nothing spends a provider call (and, with
+        // GoCardless, part of a rate-limited quota) to accomplish nothing. Omitting accountId still
+        // means "sync everything" and is not validated, because there is nothing to validate.
+        if (input.accountId) {
+            await adapter.resolveFilterId('account', input.accountId, { verifyExists: true });
+        }
         try {
             await adapter.runBankSync(input.accountId ?? undefined);
             return { result: 'Bank sync initiated successfully' };

package/dist/src/tools/transactions_filter.js

@@ -19,6 +19,15 @@ const tool = {
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
         // Convert null to undefined for adapter (LibreChat sends null, adapter expects undefined)
+        // #388: these three filters silently returned an EMPTY result set when given a NAME, which
+        // is the worst of the three answers the surface used to give: a plausible-looking wrong
+        // answer. No listing is read for a well-formed id, so a correct call costs what it did.
+        if (input.accountId)
+            await adapter.resolveFilterId('account', input.accountId);
+        if (input.categoryId)
+            await adapter.resolveFilterId('category', input.categoryId);
+        if (input.payeeId)
+            await adapter.resolveFilterId('payee', input.payeeId);
         const accountId = input.accountId ?? undefined;
         const startDate = input.startDate ?? undefined;
         const endDate = input.endDate ?? undefined;

package/dist/src/tools/transactions_get.js

@@ -1,6 +1,5 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
-import { notFoundMsg } from '../lib/errors.js';
 const InputSchema = z.object({ accountId: z.string().optional(), startDate: z.string().optional(), endDate: z.string().optional() });
 const tool = {
     name: 'actual_transactions_get',
@@ -8,13 +7,13 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Pre-flight: verify account exists when accountId is provided (BUG-7)
+        // Pre-flight: verify the account exists when accountId is provided (BUG-7, then #388).
+        // This tool already refused a well-formed id that names nothing, and `verifyExists: true`
+        // keeps exactly that. What it gains is the third case: a NAME passed where an id belongs
+        // now comes back with the id it resolves to, instead of a refusal that only says not found.
+        // It also stops returning `{ error }` and THROWS, per #377: does-not-exist throws.
         if (input.accountId) {
-            const accounts = await adapter.getAccounts();
-            const accountExists = accounts.some((a) => a.id === input.accountId);
-            if (!accountExists) {
-                return { error: notFoundMsg('Account', input.accountId, 'actual_accounts_list') };
-            }
+            await adapter.resolveFilterId('account', input.accountId, { verifyExists: true });
         }
         const result = await adapter.getTransactions(input.accountId, input.startDate, input.endDate);
         return { result };

package/dist/src/tools/transactions_search_by_amount.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+import { isPreflightRefusal } from '../lib/errors.js';
 const InputSchema = z.object({
     minAmount: z.number().optional().describe('Minimum amount in cents (use negative for expenses, e.g., -10000 for $-100.00). For expenses, use negative values (e.g., -5000 for -$50.00)'),
     maxAmount: z.number().optional().describe('Maximum amount in cents (e.g., 10000 for $100.00). For expenses, use negative values (e.g., -5000 for -$50.00)'),
@@ -23,36 +24,17 @@ const tool = {
                 throw new Error('Unbounded query: provide at least one of accountId, startDate, or endDate ' +
                     'to limit the scan scope. Full-database scans without filters can exhaust memory.');
             }
-            // Validate accountId exists if provided
+            // #388: ONE answer to a name passed where an id belongs, shared by every Category B field.
+            // This block used to return an empty result set with the error tucked inside it, which reads
+            // to a model as "no transactions match". `verifyExists: true` keeps the existence check this
+            // tool already paid for.
+            // Fetched HERE rather than at the enrichment step below so the guard can reuse it.
+            // Both need the same listing, and reading it twice on every filtered call is a cost this
+            // change is meant to avoid rather than introduce.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const accounts = await adapter.getAccounts();
             if (input.accountId) {
-                const accounts = await adapter.getAccounts();
-                const accountExists = accounts.some((acc) => acc.id === input.accountId);
-                if (!accountExists) {
-                    // Check if user provided account name instead of UUID
-                    const accountByName = accounts.find((acc) => acc.name && acc.name.toLowerCase() === input.accountId.toLowerCase());
-                    if (accountByName) {
-                        return {
-                            transactions: [],
-                            count: 0,
-                            totalAmount: 0,
-                            amountRange: {
-                                min: input.minAmount,
-                                max: input.maxAmount,
-                            },
-                            error: `Account '${input.accountId}' appears to be a name, not an ID. Use account UUID '${accountByName.id}' instead.`,
-                        };
-                    }
-                    return {
-                        transactions: [],
-                        count: 0,
-                        totalAmount: 0,
-                        amountRange: {
-                            min: input.minAmount,
-                            max: input.maxAmount,
-                        },
-                        error: `Account '${input.accountId}' not found. Did you mean to use account UUID instead of name? Use actual_accounts_list to get valid account UUIDs.`,
-                    };
-                }
+                await adapter.resolveFilterId('account', input.accountId, { verifyExists: true, rows: accounts });
             }
             // Get base transactions (filtered by account and date range if provided)
             const allTransactions = await adapter.getTransactions(input.accountId, input.startDate, input.endDate);
@@ -111,8 +93,7 @@ const tool = {
                 return amountB - amountA;
             });
             const limited = filtered.slice(0, input.limit || 100);
-            // Enrich transactions with account names
-            const accounts = await adapter.getAccounts();
+            // Enrich transactions with account names (listing already in hand, see above)
             const accountMap = new Map(accounts.map((acc) => [acc.id, acc.name]));
             const enrichedTransactions = limited.map((t) => ({
                 ...t,
@@ -131,6 +112,12 @@ const tool = {
         }
         catch (error) {
             const message = error?.message || String(error);
+            // #377/#388: a PREFLIGHT REFUSAL is not a crash and must not be flattened into one.
+            // This guard exists so an unexpected failure does not take the server down. A refusal is
+            // the opposite: a deliberate answer that the request cannot be served, and burying it here
+            // would restore exactly the empty-result-with-an-error shape #388 removed.
+            if (isPreflightRefusal(error))
+                throw error;
             // Don't crash the server — return structured error
             return {
                 transactions: [],

package/dist/src/tools/transactions_search_by_category.js

@@ -18,29 +18,12 @@ const tool = {
         // Fetch accounts once — used for validation, off-budget filtering (issue #81), and enrichment
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const allAccounts = await adapter.getAccounts();
-        // Step 0: Validate accountId exists if provided
+        // #388: ONE answer to a name passed where an id belongs, shared by every Category B field.
+        // This block used to return an empty result set with the error tucked inside it, which reads
+        // to a model as "no transactions match". `verifyExists: true` keeps the existence check this
+        // tool already paid for.
         if (input.accountId) {
-            const accountExists = allAccounts.some((acc) => acc.id === input.accountId);
-            if (!accountExists) {
-                // Check if user provided account name instead of UUID
-                const accountByName = allAccounts.find((acc) => acc.name && acc.name.toLowerCase() === input.accountId.toLowerCase());
-                if (accountByName) {
-                    return {
-                        transactions: [],
-                        count: 0,
-                        totalAmount: 0,
-                        categoryName: input.categoryName,
-                        error: `Account '${input.accountId}' appears to be a name, not an ID. Use account UUID '${accountByName.id}' instead.`,
-                    };
-                }
-                return {
-                    transactions: [],
-                    count: 0,
-                    totalAmount: 0,
-                    categoryName: input.categoryName,
-                    error: `Account '${input.accountId}' not found. Did you mean to use account UUID instead of name? Use actual_accounts_list to get valid account UUIDs.`,
-                };
-            }
+            await adapter.resolveFilterId('account', input.accountId, { verifyExists: true, rows: allAccounts });
         }
         // Step 1: Find category ID by name
         let categoryId;

package/dist/src/tools/transactions_search_by_month.js

@@ -15,31 +15,17 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Step 0: Validate accountId exists if provided
+        // Fetched HERE rather than further down so the #388 guard below can reuse it. The guard
+        // needs the listing and so does the off-budget filtering, and without sharing them this
+        // handler read the same listing twice on every filtered call.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await adapter.getAccounts();
+        // #388: ONE answer to a name passed where an id belongs, shared by every Category B field.
+        // This block used to return { transactions: [], count: 0, ..., error }, an empty result set
+        // with the error tucked inside it, which reads to a model as "no transactions match".
+        // `verifyExists: true` keeps the existence check this tool already paid for.
         if (input.accountId) {
-            const accounts = await adapter.getAccounts();
-            const accountExists = accounts.some((acc) => acc.id === input.accountId);
-            if (!accountExists) {
-                // Check if user provided account name instead of UUID
-                const accountByName = accounts.find((acc) => acc.name && acc.name.toLowerCase() === input.accountId.toLowerCase());
-                const month = input.month || `${new Date().getFullYear()}-${String(new Date().getMonth() + 1).padStart(2, '0')}`;
-                if (accountByName) {
-                    return {
-                        transactions: [],
-                        count: 0,
-                        totalAmount: 0,
-                        month,
-                        error: `Account '${input.accountId}' appears to be a name, not an ID. Use account UUID '${accountByName.id}' instead.`,
-                    };
-                }
-                return {
-                    transactions: [],
-                    count: 0,
-                    totalAmount: 0,
-                    month,
-                    error: `Account '${input.accountId}' not found. Did you mean to use account UUID instead of name? Use actual_accounts_list to get valid account UUIDs.`,
-                };
-            }
+            await adapter.resolveFilterId('account', input.accountId, { verifyExists: true, rows: accounts });
         }
         // Default to current month if not provided
         const today = new Date();
@@ -60,9 +46,6 @@ const tool = {
                 month,
             };
         }
-        // Fetch accounts once — used for off-budget filtering (issue #81) and enrichment
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const accounts = await adapter.getAccounts();
         // Exclude off-budget accounts (issue #81) — their transactions cannot have
         // categories set; any update is silently discarded by Actual Budget.
         const offBudgetIds = new Set(

package/dist/src/tools/transactions_search_by_payee.js

@@ -16,30 +16,12 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Step 0: Validate accountId exists if provided
+        // #388: ONE answer to a name passed where an id belongs, shared by every Category B field.
+        // This block used to return an empty result set with the error tucked inside it, which reads
+        // to a model as "no transactions match". `verifyExists: true` keeps the existence check this
+        // tool already paid for.
         if (input.accountId) {
-            const accounts = await adapter.getAccounts();
-            const accountExists = accounts.some((acc) => acc.id === input.accountId);
-            if (!accountExists) {
-                // Check if user provided account name instead of UUID
-                const accountByName = accounts.find((acc) => acc.name && acc.name.toLowerCase() === input.accountId.toLowerCase());
-                if (accountByName) {
-                    return {
-                        transactions: [],
-                        count: 0,
-                        totalAmount: 0,
-                        payeeName: input.payeeName,
-                        error: `Account '${input.accountId}' appears to be a name, not an ID. Use account UUID '${accountByName.id}' instead.`,
-                    };
-                }
-                return {
-                    transactions: [],
-                    count: 0,
-                    totalAmount: 0,
-                    payeeName: input.payeeName,
-                    error: `Account '${input.accountId}' not found. Did you mean to use account UUID instead of name? Use actual_accounts_list to get valid account UUIDs.`,
-                };
-            }
+            await adapter.resolveFilterId('account', input.accountId, { verifyExists: true });
         }
         // Step 1: Find payee ID by name
         let payeeId;

package/dist/src/tools/transactions_summary_by_category.js

@@ -12,6 +12,11 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
+        // #388: this filter silently returned an EMPTY result set when given an account NAME, a
+        // plausible-looking wrong answer. A well-formed id reads no listing, so a correct call is
+        // unchanged.
+        if (input.accountId)
+            await adapter.resolveFilterId('account', input.accountId);
         // Default to current month if dates not provided
         const today = new Date();
         const firstDayOfMonth = new Date(today.getFullYear(), today.getMonth(), 1);

package/dist/src/tools/transactions_summary_by_payee.js

@@ -12,6 +12,11 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
+        // #388: this filter silently returned an EMPTY result set when given an account NAME, a
+        // plausible-looking wrong answer. A well-formed id reads no listing, so a correct call is
+        // unchanged.
+        if (input.accountId)
+            await adapter.resolveFilterId('account', input.accountId);
         // Build ActualQL query with groupBy and aggregation
         const api = await import('@actual-app/api');
         const q = api.q;

package/dist/src/tools/transactions_uncategorized.js

@@ -15,7 +15,12 @@ import { CommonSchemas } from '../lib/schemas/common.js';
 const InputSchema = z.object({
     startDate: CommonSchemas.date.optional().describe('Start date in YYYY-MM-DD format (default: all-time)'),
     endDate: CommonSchemas.date.optional().describe('End date in YYYY-MM-DD format (default: today)'),
-    accountId: CommonSchemas.accountId.optional().describe('Filter to a specific account ID (optional)'),
+    // #388: an OPTIONAL FILTER, so it belongs with the other twelve rather than with the required
+    // lookup ids #380 tightened. Under `CommonSchemas.accountId` a caller passing an account NAME
+    // got "Invalid uuid" and no way to learn the id, which is the answer this ticket argues is worse
+    // than resolving the name. The schema is bare so the handler runs and can resolve it; the
+    // exception entry in tool_id_schema_drift records that this is deliberate.
+    accountId: z.string().optional().describe('Filter to a specific account ID (optional)'),
     includeTransactions: z.boolean().optional().default(false).describe('When true, include paginated transaction rows in the response (default: false)'),
     limit: z.number().int().min(1).max(1000).optional().default(50).describe('Max transactions per page when includeTransactions is true (default: 50, max: 1000)'),
     offset: z.number().int().min(0).optional().default(0).describe('Pagination start index when includeTransactions is true (default: 0)'),
@@ -46,6 +51,8 @@ const tool = {
         const today = new Date();
         const startDate = input.startDate || '2000-01-01';
         const endDate = input.endDate || today.toISOString().split('T')[0];
+        if (input.accountId)
+            await adapter.resolveFilterId('account', input.accountId);
         const accountId = input.accountId ?? undefined;
         // Full table scan when no accountId — reliably returns newly written transactions
         // across separate WAL sessions in CI Docker. Filtering by accountId uses an index

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.16.9",
+  "version": "0.16.10",
   "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/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/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/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_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/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/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/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/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/stdio_budget_switch.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/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",
+    "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/e2e_spec_collection.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/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/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/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/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/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/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/stdio_budget_switch.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/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",
     "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",