actual-mcp-server 0.22.19 → 0.22.22

package/README.md

@@ -835,7 +835,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.22.19 | **Tool Count:** 83 (verified LibreChat-compatible)
+**Version:** 0.22.22 | **Tool Count:** 83 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/actualToolsManager.js

@@ -119,6 +119,7 @@ const API_TOOL_MAP = {
     deletePayee: 'actual_payees_delete',
     mergePayees: 'actual_payees_merge',
     getPayeeRules: 'actual_payee_rules_get',
+    // #539: the tool covers this capability through per-item writes; it never calls batchBudgetUpdates.
     batchBudgetUpdates: 'actual_budget_updates_batch',
     holdBudgetForNextMonth: 'actual_budgets_holdForNextMonth',
     resetBudgetHold: 'actual_budgets_resetHold',

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

@@ -5,7 +5,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, exportBudget: rawExportBudget, importBudget: rawImportBudget, getPreferences: rawGetPreferences, getAccountGroups: rawGetAccountGroups, createAccountGroup: rawCreateAccountGroup, updateAccountGroup: rawUpdateAccountGroup, deleteAccountGroup: rawDeleteAccountGroup,
+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, 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, getAccountGroups: rawGetAccountGroups, createAccountGroup: rawCreateAccountGroup, updateAccountGroup: rawUpdateAccountGroup, deleteAccountGroup: rawDeleteAccountGroup,
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
  } = api;
 import { EventEmitter } from 'events';
@@ -1868,12 +1868,49 @@ export async function setBudgetAmount(month, categoryId, amount) {
         return result;
     }, { preservesListings: ['accounts', 'categories', 'categoryGroups', 'payees'] });
 }
+/**
+ * Budget transfer between two categories within a single month.
+ *
+ * Reads the current budget amounts, validates source-side sufficient funds,
+ * and writes both adjustments inside ONE `queueWriteOperation` cycle. This
+ * is the structural fix for issue #141: the previous tool body did three
+ * separate lock cycles (read + write + write) which could hang for the
+ * full Playwright timeout when the upstream server's mutator queue stalled
+ * between cycles. The month read and the funds check run before either write.
+ *
+ * NOT atomic and no rollback (#518). The two writes are separate raw calls,
+ * each awaited on its own: outside a batch bracket upstream applies each
+ * write (`_sendMessages` then `applyMessages`) before the call returns and
+ * rethrows an apply failure to us (read from the shipped upstream source, not
+ * verified here by a read-back), so an apply failure is returned rather than
+ * detached. If the second write fails or is not attempted, the first stays
+ * applied and the thrown error says so (see below).
+ *
+ * COOPERATIVE DEADLINE between the two writes, for the same reason as
+ * `setBudgetBatch`: `withOpTimeout` cannot cancel this callback, so without the
+ * check an abandoned callback would still make the second write after the
+ * caller was told the operation timed out.
+ *
+ * WHY NO `batchBudgetUpdates` BRACKET (#539). Upstream `api/batch-budget-start`
+ * runs `batchMessages` un-awaited and `api/batch-budget-end` returns before the
+ * queued messages are applied, so an apply failure under the bracket is a
+ * rejection on a promise nobody holds: it reaches the `unhandledRejection`
+ * handler and exits the server, after the tool already reported success. The
+ * bracket did apply both writes in one sqlite transaction, so dropping it trades
+ * that all-or-nothing apply for a partial transfer that is REPORTED; upstream
+ * has no awaited bracket that keeps both. Do not reintroduce it (a unit test
+ * guards this). The upstream trace is the `actual_budgets_transfer` and
+ * `actual_budget_updates_batch` rows of `docs/audit/write-effect-audit.md`.
+ */
 export async function transferBudgetAmount(month, fromCategoryId, toCategoryId, amount) {
     observability.incrementToolCall('actual.budgets.transfer').catch(() => { });
     return queueWriteOperation(async () => {
         // Inside processWriteQueue we already hold the api mutex in apiLock.ts and the api is
         // initialised. Call raw functions only: adapter wrappers would re-enter
         // queueWriteOperation / withActualApi and defeat the single-cycle goal.
+        // The deadline clock starts here, before the read, because withOpTimeout times the whole
+        // callback: starting it at the first write would let a slow read hide (#539 review round 2).
+        const startedAt = Date.now();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const budgetMonth = await rawGetBudgetMonth(month);
         if (!budgetMonth?.categoryGroups) {
@@ -1894,10 +1931,31 @@ export async function transferBudgetAmount(month, fromCategoryId, toCategoryId,
         if (prevFrom < amount) {
             throw new Error(`Insufficient budget in source category. Available: ${prevFrom}, Requested: ${amount}`);
         }
-        await rawBatchBudgetUpdates(async () => {
-            await rawSetBudgetAmount(month, fromCategoryId, prevFrom - amount);
-            await rawSetBudgetAmount(month, toCategoryId, prevTo + amount);
-        });
+        // No retry on either write: a replayed amount write after a partial apply is not safe to
+        // reason about, and the client re-reads instead.
+        await withConcurrency(() => rawSetBudgetAmount(month, fromCategoryId, prevFrom - amount));
+        const sourceDone = `Partial transfer: the source category ${fromCategoryId} was set from ${prevFrom} to ${prevFrom - amount}`;
+        const readBack = 'Read back with actual_budgets_getMonth before retrying.';
+        const deadlineMs = config.ACTUAL_OP_TIMEOUT_MS > 0 ? config.ACTUAL_OP_TIMEOUT_MS * BUDGET_BATCH_DEADLINE_FRACTION : 0;
+        if (deadlineMs > 0 && Date.now() - startedAt > deadlineMs) {
+            throw new Error(`${sourceDone}, but the target category ${toCategoryId} was not attempted (${BUDGET_BATCH_DEADLINE_ERROR}), ` +
+                `so it is unchanged at ${prevTo}. ${readBack}`);
+        }
+        try {
+            await withConcurrency(() => rawSetBudgetAmount(month, toCategoryId, prevTo + amount));
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            // An infrastructure error says nothing about whether the write landed, so only a
+            // deterministic (domain) rejection may claim the target is unchanged.
+            const target = _shouldDropPoolOnError(error)
+                ? `its outcome is unknown (it was ${prevTo})`
+                : `it is unchanged at ${prevTo}`;
+            // The original text stays INSIDE the message: isRetryableError classifies by message only
+            // and never reads `cause`, and the write queue's self-heal (_shouldDropPoolOnError) depends
+            // on that classification. Same reason as abortBatchOnInfrastructureError.
+            throw new Error(`${sourceDone}, but setting the target category ${toCategoryId} failed, so ${target}: ${msg}. ${readBack}`, { cause: error });
+        }
         return {
             transferred: amount,
             fromCategory: { id: fromCategoryId, previousAmount: prevFrom, newAmount: prevFrom - amount },
@@ -2991,23 +3049,32 @@ export async function getPayeeRules(payeeId) {
 }
 /** Error recorded for every item the cooperative deadline stopped before it was written. */
 export const BUDGET_BATCH_DEADLINE_ERROR = 'not attempted: batch time budget exhausted';
-/** Fraction of ACTUAL_OP_TIMEOUT_MS the item loop may consume; the rest is left for batch-budget-end and the sync. */
+/** Fraction of ACTUAL_OP_TIMEOUT_MS the item loop may consume; the rest is left for the trailing sync. */
 const BUDGET_BATCH_DEADLINE_FRACTION = 0.75;
 /**
  * #516: set budget amounts and/or carryover flags for many (month, category) pairs in ONE
  * write cycle, with a verdict per item. NOT atomic and no rollback: items applied before a
- * failure stay applied. The bracket is upstream's `batchMessages` (it batches sync messages),
- * it is not a database transaction.
+ * failure stay applied.
+ *
+ * NO `batchBudgetUpdates` BRACKET (#539). Each raw write is awaited on its own. Outside a
+ * bracket upstream applies the write (`_sendMessages` then `applyMessages`) before the call
+ * returns and rethrows an apply failure (read from the shipped upstream source, not verified by
+ * a read-back), so `succeeded` means the write call returned without error and a failed
+ * apply lands on that item's verdict. Under the bracket (#516 to #539) upstream applied the
+ * queued writes AFTER `batch-budget-end` returned, on a promise it never awaits, so an apply
+ * failure was an unhandled rejection that exited the server after we had reported success. The
+ * cost is one apply per write instead of one per batch; the server sync is a debounced timer
+ * (`scheduleFullSync`), so it still runs once, except under NODE_ENV=test where upstream syncs on
+ * every write. Do not reintroduce the bracket (a unit test guards this).
  *
  * TWO PHASES inside one `queueWriteOperation`:
- *  1. Before the bracket: read the categories listing and the budget months ONCE each, then
+ *  1. Before any write: read the categories listing and the budget months ONCE each, then
  *     decide a typed refusal per item. The guards apply to EVERY item, a carryover-only item
  *     included, because upstream `api/budget-set-amount` validates neither category nor month
  *     (it INSERTs an orphan `<month>-<category>` row) and the two fields should refuse alike.
- *  2. ONE `rawBatchBudgetUpdates` whose callback holds only raw writes for the items that
- *     passed. Every item is caught INSIDE the callback so no item error escapes the bracket
- *     (upstream closes it in a `finally`, but an escaping error would also lose the verdicts).
- *     Only `raw*` calls run there: an `adapter.*` call would nest the api lock and deadlock.
+ *  2. Raw writes for the items that passed, each caught per item so one failure does not lose
+ *     the other verdicts. Only `raw*` calls run here: an `adapter.*` call would nest the api
+ *     lock and deadlock.
  *
  * INCOME CATEGORIES (maintainer decision): a carryover item whose category is an income
  * category is refused in phase 1. Upstream `api/budget-set-carryover` rejects income
@@ -3015,18 +3082,18 @@ const BUDGET_BATCH_DEADLINE_FRACTION = 0.75;
  * this check an item setting both would half-apply. Upstream's own rejection stays as a
  * backstop and is reported per item.
  *
- * RETRY: none. A refusal must never replay and a replayed partial bracket could double-apply;
- * the client re-reads (`actual_budgets_getMonth`) and retries instead.
+ * RETRY: none. A refusal must never replay, an apply failure is deterministic, a retry would
+ * spend the deadline, and infrastructure errors abort the batch instead; the client re-reads
+ * (`actual_budgets_getMonth`) and retries.
  *
  * COOPERATIVE DEADLINE. The whole operation runs under one `withOpTimeout`, a `Promise.race`
- * that cannot cancel the callback. A callback abandoned mid-bracket keeps writing and leaks
- * upstream's `IS_BATCHING` / `batchPromise` globals to later operations (a later batch-start
- * throws "batch already started"). So the loop checks, before each item write, the time since
- * this operation started against 75% of ACTUAL_OP_TIMEOUT_MS (skipped when it is 0, the
- * documented "no bound" setting) and stops writing once it is exceeded; the remaining items go
- * to `failed`. The 25% left over covers batch-budget-end and the sync.
+ * that cannot cancel the callback, so an abandoned loop would keep writing after the caller was
+ * told it timed out (as in `createRulesBatch`). So the loop checks, before each item write, the
+ * time since this operation started against 75% of ACTUAL_OP_TIMEOUT_MS (skipped when it is 0,
+ * the documented "no bound" setting) and stops writing once it is exceeded; the remaining items
+ * go to `failed`. The 25% left over covers the drain's trailing sync.
  * WHY NOT `queueWriteOperation`'s `timeoutMs` option: it would LENGTHEN the hold on the
- * process-global api lock, and it still would not close the bracket on abandonment.
+ * process-global api lock, and it still would not stop an abandoned loop from writing.
  *
  * `preservesListings` claim is safe: only raw budget amount and carryover writes run here.
  */
@@ -3036,7 +3103,7 @@ export async function setBudgetBatch(items) {
         const startedAt = Date.now();
         const succeeded = [];
         const failed = [];
-        // Phase 1: reads, then refusal decisions. Both reads happen BEFORE the bracket opens.
+        // Phase 1: reads, then refusal decisions. Both reads happen BEFORE the first write.
         const categories = await withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 }));
         const categoryById = new Map();
         for (const c of categories)
@@ -3063,43 +3130,38 @@ export async function setBudgetBatch(items) {
             else
                 toWrite.push({ index, item });
         });
-        // Phase 2: one bracket, raw writes only.
-        if (toWrite.length > 0) {
-            const deadlineMs = config.ACTUAL_OP_TIMEOUT_MS > 0 ? config.ACTUAL_OP_TIMEOUT_MS * BUDGET_BATCH_DEADLINE_FRACTION : 0;
-            await withConcurrency(() => rawBatchBudgetUpdates(async () => {
-                for (const { index, item } of toWrite) {
-                    const ref = { index, month: item.month, categoryId: item.categoryId };
-                    if (deadlineMs > 0 && Date.now() - startedAt > deadlineMs) {
-                        failed.push({ ...ref, error: BUDGET_BATCH_DEADLINE_ERROR });
-                        continue;
-                    }
-                    let amountWritten = false;
-                    try {
-                        if (item.amount !== undefined) {
-                            await rawSetBudgetAmount(item.month, item.categoryId, item.amount);
-                            amountWritten = true;
-                        }
-                        if (item.carryover !== undefined) {
-                            await rawSetBudgetCarryover(item.month, item.categoryId, item.carryover);
-                        }
-                        succeeded.push(ref);
-                    }
-                    catch (error) {
-                        const msg = error instanceof Error ? error.message : String(error);
-                        // Infrastructure errors stop the batch (see abortBatchOnInfrastructureError);
-                        // the throw leaves the bracket and upstream closes it in a `finally`.
-                        abortBatchOnInfrastructureError(error, {
-                            label: 'Budget',
-                            appliedCount: succeeded.length,
-                            total: items.length,
-                            applied: succeeded.map((x) => x.index).join(', '),
-                            message: msg,
-                            readBackTool: 'actual_budgets_getMonth',
-                        });
-                        failed.push({ ...ref, error: amountWritten ? `amount was applied, then the carryover failed: ${msg}` : msg });
-                    }
+        // Phase 2: raw writes only, each awaited on its own (no bracket, see #539 above).
+        const deadlineMs = config.ACTUAL_OP_TIMEOUT_MS > 0 ? config.ACTUAL_OP_TIMEOUT_MS * BUDGET_BATCH_DEADLINE_FRACTION : 0;
+        for (const { index, item } of toWrite) {
+            const ref = { index, month: item.month, categoryId: item.categoryId };
+            if (deadlineMs > 0 && Date.now() - startedAt > deadlineMs) {
+                failed.push({ ...ref, error: BUDGET_BATCH_DEADLINE_ERROR });
+                continue;
+            }
+            let amountWritten = false;
+            try {
+                if (item.amount !== undefined) {
+                    await withConcurrency(() => rawSetBudgetAmount(item.month, item.categoryId, item.amount));
+                    amountWritten = true;
                 }
-            }));
+                if (item.carryover !== undefined) {
+                    await withConcurrency(() => rawSetBudgetCarryover(item.month, item.categoryId, item.carryover));
+                }
+                succeeded.push(ref);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                // Infrastructure errors stop the batch (see abortBatchOnInfrastructureError).
+                abortBatchOnInfrastructureError(error, {
+                    label: 'Budget',
+                    appliedCount: succeeded.length,
+                    total: items.length,
+                    applied: succeeded.map((x) => x.index).join(', '),
+                    message: msg,
+                    readBackTool: 'actual_budgets_getMonth',
+                });
+                failed.push({ ...ref, error: amountWritten ? `amount was applied, then the carryover failed: ${msg}` : msg });
+            }
         }
         succeeded.sort((a, b) => a.index - b.index);
         failed.sort((a, b) => a.index - b.index);

package/dist/src/server/httpErrorHandler.js

@@ -0,0 +1,105 @@
+// src/server/httpErrorHandler.ts
+//
+// #543: the final Express error layer for the HTTP transport. Without it, an error falls
+// through to Express's default handler, and from express 5.3.0 that handler logs the WHOLE
+// error object with console.error (5.2.1 logged err.stack). body-parser 2.3.0 attaches the
+// raw request text to a JSON parse error as `err.body`, and express.json runs before any
+// auth, so an unauthenticated malformed POST would put its raw body in the logs. The default
+// handler also renders the stack into the response under NODE_ENV=development.
+//
+// Contract:
+//   - The response NEVER carries err.message, err.body or err.stack, whatever NODE_ENV is.
+//   - The log NEVER carries request body content: not err.body, and not err.message either,
+//     because the V8 JSON SyntaxError message quotes the input text. Only an allowlist of
+//     fields is logged.
+//   - next(err) is NEVER called: app.handle wires finalhandler with onerror: logerror, which
+//     is the console.error(err) path this module exists to close.
+//
+// The handler also absorbs any non-MCPAuth error that mcp-auth's bearerAuth rethrows, with
+// the same fixed 500 and the same allowlisted log.
+import { STATUS_CODES } from 'node:http';
+import { createModuleLogger } from '../lib/loggerFactory.js';
+import { resolveRequestId } from '../logger.js';
+const log = createModuleLogger('HTTP');
+const JSONRPC_PARSE_ERROR = -32700;
+const JSONRPC_INVALID_REQUEST = -32600;
+const JSONRPC_INTERNAL_ERROR = -32603;
+/**
+ * True when the request targets the MCP endpoint: the pathname of `originalUrl` (the query
+ * string removed) equals `mcpPath` or starts with `mcpPath + '/'`. Never a bare prefix match:
+ * with an MCP path of `/mcp`, `/mcp-info` is NOT the MCP endpoint and gets the plain shape.
+ */
+function isMcpRequestPath(originalUrl, mcpPath) {
+    const q = originalUrl.indexOf('?');
+    const pathname = q === -1 ? originalUrl : originalUrl.slice(0, q);
+    const base = mcpPath.length > 1 && mcpPath.endsWith('/') ? mcpPath.slice(0, -1) : mcpPath;
+    // A root MCP path ('/') makes every request an MCP request.
+    if (base === '/' || base === '')
+        return true;
+    return pathname === base || pathname.startsWith(`${base}/`);
+}
+export function createHttpErrorHandler({ mcpPath }) {
+    // Four parameters: Express identifies an error handler by its arity.
+    return function httpErrorHandler(err, req, res, _next) {
+        const e = err !== null && typeof err === 'object' ? err : {};
+        const type = typeof e.type === 'string' ? e.type : undefined;
+        // The ticket's first cut mapped everything except parse and size errors to 500. That was
+        // reversed in review: body-parser raises other CLIENT errors before auth (unsupported
+        // charset or encoding: 415; a corrupt gzip body or an aborted request: 400), each marked
+        // expose with its own 4xx status. Reporting those as 500 and logging them at error level
+        // let any caller fire 5xx alerts at will. So an exposed 4xx keeps its status; only the
+        // status is taken from the error, never its message.
+        let status = 500;
+        if (type === 'entity.parse.failed')
+            status = 400;
+        else if (type === 'entity.too.large')
+            status = 413;
+        else {
+            const s = typeof e.status === 'number' ? e.status : e.statusCode;
+            if (e.expose === true && Number.isInteger(s) && s >= 400 && s <= 499)
+                status = s;
+        }
+        const mcp = isMcpRequestPath(req.originalUrl || req.url || '', mcpPath);
+        const meta = {
+            type,
+            status,
+            method: req.method,
+            // The pathname only: a query string can carry anything.
+            path: (req.originalUrl || '').split('?')[0],
+            requestId: resolveRequestId(req.get('x-correlation-id')),
+        };
+        if (status === 500) {
+            if (typeof e.name === 'string')
+                meta.errorName = e.name;
+            if (typeof e.code === 'string' || typeof e.code === 'number')
+                meta.errorCode = e.code;
+        }
+        if (res.headersSent) {
+            log.warn('Request error after the response started; closing the connection', meta);
+            req.socket?.destroy();
+            return;
+        }
+        if (status === 500)
+            log.error('Unhandled request error', undefined, meta);
+        else
+            log.warn('Rejected request body', meta);
+        let message = 'Internal error';
+        if (type === 'entity.parse.failed')
+            message = mcp ? 'Parse error' : 'Invalid JSON body';
+        else if (status === 413)
+            message = 'Request body too large';
+        else if (status !== 500)
+            message = STATUS_CODES[status] ?? 'Bad Request';
+        if (mcp) {
+            let code = JSONRPC_INVALID_REQUEST;
+            if (type === 'entity.parse.failed')
+                code = JSONRPC_PARSE_ERROR;
+            else if (status === 500)
+                code = JSONRPC_INTERNAL_ERROR;
+            res.status(status).json({ jsonrpc: '2.0', error: { code, message }, id: null });
+        }
+        else {
+            res.status(status).json({ error: message });
+        }
+    };
+}

package/dist/src/server/httpServer.js

@@ -35,6 +35,7 @@ import { buildToolListEntries } from '../lib/tool-list-entry.js';
 // transports can reach it (stdio could not, which was the whole of #452). Re-exported here
 // unchanged so existing importers and tests are unaffected.
 import { classifyInitFailure } from '../lib/init-failure.js';
+import { createHttpErrorHandler } from './httpErrorHandler.js';
 export { classifyInitFailure };
 export { requestContext };
 // Resolve the authenticated principal for the per-principal budget preference
@@ -821,9 +822,17 @@ advertisedUrl) {
             res.status(204).end();
             return;
         }
-        res.setHeader('Content-Type', 'text/plain; version=0.0.4');
+        // #543: the charset is spelled out because res.send appends it, and express 5.3.0
+        // appends it AFTER version=0.0.4 where 5.2.1 put it before. Stated in full, the header
+        // is passed through unchanged on both, so scrapers see the same value.
+        res.setHeader('Content-Type', 'text/plain; charset=utf-8; version=0.0.4');
         res.send(txt);
     });
+    // #543: the FINAL layer, mounted globally (express.json above is global). Without it an
+    // error reaches Express's default handler, which from express 5.3.0 logs the whole error
+    // object, raw request body included, and under NODE_ENV=development renders the stack.
+    // Keep this the last app.use: anything registered after it is never reached on error.
+    app.use(createHttpErrorHandler({ mcpPath: httpPath }));
     // config validation (#169) guarantees both paths are set when HTTPS is on, so
     // the non-null assertions are safe. Wrap the reads so a missing/unreadable
     // file fails with an actionable message naming the env vars and paths instead

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.22.19",
+  "version": "0.22.22",
   "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/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/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/source_text_helper.test.js && node tests/unit/transport_onerror.test.js && node tests/unit/adapter_transaction_batch_abort.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_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/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/source_text_helper.test.js && node tests/unit/transport_onerror.test.js && node tests/unit/adapter_transaction_batch_abort.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",
@@ -72,7 +72,7 @@
     "@modelcontextprotocol/sdk": "^1.32.1",
     "debug": "^4.4.3",
     "dotenv": "^18.0.6",
-    "express": "^5.2.1",
+    "express": "^5.3.0",
     "fuse.js": "^7.4.2",
     "jose": "^6.2.12",
     "mcp-auth": "^0.2.0",
@@ -87,7 +87,7 @@
     "@playwright/test": "^1.63.0",
     "@types/express": "^5.0.3",
     "@types/node": "^26.6.4",
-    "knip": "^6.40.0",
+    "knip": "^6.41.0",
     "node-fetch": "^3.3.2",
     "tsconfig-paths": "^4.2.0",
     "typescript": "^7.0.2"