actual-mcp-server 0.22.42 → 0.22.46

package/README.md

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

package/dist/src/index.js

@@ -9,6 +9,7 @@ import { getMcpServerVersion } from './lib/mcp-version.js';
 import path from 'node:path';
 import { z } from 'zod';
 import { isKnownBenignRejection } from './lib/rejection-allowlist.js';
+import { buildServerInstructions } from './lib/serverInstructions.js';
 import { format } from 'node:util';
 /*
  * #277 / #541: this module's version comes from `getMcpServerVersion()` (src/lib/mcp-version.ts),
@@ -104,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);
@@ -211,8 +214,6 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
     const useTestActualConnection = args.includes('--test-actual-connection');
     const useTestMcpClient = args.includes('--test-mcp-client');
     const SERVER_DESCRIPTION = 'Bridge MCP server exposing Actual finance API to LibreChat.';
-    const SERVER_INSTRUCTIONS = 'Welcome to the Actual MCP server. The tools listed here are only the ones currently confirmed and tested, ' +
-        'but the server can proxy any API call supported by Actual. As we expand coverage, more tools will be officially exposed.';
     async function main() {
         // Mutual exclusion — stdio and http are incompatible transports
         if (useHttp && useStdio) {
@@ -234,6 +235,9 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
         // The PUBLISHED tools (#483). This is the one name list every tools/list path receives
         // (HTTP SDK handler, the no-session LobeChat path, the expired-session shim, stdio).
         const implementedTools = actualToolsManager.getPublishedToolNames();
+        // The initialize `instructions` (#560): built once from the published set and the same
+        // resolved policy, before any transport starts, so no transport can send a different text.
+        const serverInstructionsText = buildServerInstructions(implementedTools, actualToolsManager.getToolPolicy().readOnly);
         // Extract schemas map with tool name → JSON schema
         const toolSchemas = {};
         for (const toolName of implementedTools) {
@@ -312,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.
-            await startHttpServer(mcp, PORT, HTTP_PATH, capabilities, implementedTools, SERVER_DESCRIPTION, SERVER_INSTRUCTIONS, toolSchemas, version, bindHost, advertisedUrl);
+            // 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);
             }
@@ -343,13 +357,13 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
             logger.info(`• OAuth Required:       false`);
             logger.info(`• Capabilities:         ${Object.keys(capabilities).join(', ')}`);
             logger.info(`• Tools:                ${implementedTools.join(', ') || 'none'}`);
-            logger.info(`• Server Instructions:  ${SERVER_INSTRUCTIONS}`);
+            logger.info(`• Server Instructions:  ${serverInstructionsText}`);
             logger.info(`• MCP endpoint (advertised): ${advertisedUrl}`);
             logger.info('---------');
         }
         if (useHttp) {
             logger.info('Mode: HTTP');
-            await startHttpServer(mcp, PORT, HTTP_PATH, capabilities, implementedTools, SERVER_DESCRIPTION, SERVER_INSTRUCTIONS, toolSchemas, version, 
+            await startHttpServer(mcp, PORT, HTTP_PATH, capabilities, implementedTools, SERVER_DESCRIPTION, serverInstructionsText, toolSchemas, version, 
             // bind host (ensure server accepts connections on that interface)
             bindHost, 
             // advertised URL shown to clients
@@ -357,7 +371,7 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
         }
         else if (useStdio) {
             logger.debug('Mode: stdio');
-            await startStdioServer(mcp, capabilities, implementedTools, SERVER_DESCRIPTION, SERVER_INSTRUCTIONS, toolSchemas, version);
+            await startStdioServer(mcp, capabilities, implementedTools, SERVER_DESCRIPTION, serverInstructionsText, toolSchemas, version);
         }
         else {
             logger.error('❌ Please specify a transport mode: --http or --stdio');

package/dist/src/lib/ActualMCPConnection.js

@@ -97,7 +97,6 @@ export class ActualMCPConnection extends EventEmitter {
             prompts: false,
             models: false,
             logging: false,
-            serverInstructions: 'This server exposes Actual Finance tools via MCP. You must provide ACTUAL_SERVER_URL, ACTUAL_PASSWORD, and ACTUAL_BUDGET_SYNC_ID as environment variables.'
         };
     }
     /** Executes a tool requested by the client */

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 });
@@ -240,3 +267,64 @@ export function parseWhereClause(query, whereClause, tableName) {
     }
     return query;
 }
+// #561: the joined name columns an empty-result hint can check, and the table that lists each.
+const NAME_CONDITION_TABLES = {
+    'category.name': { table: 'categories', noun: 'category' },
+    'payee.name': { table: 'payees', noun: 'payee' },
+    'account.name': { table: 'accounts', noun: 'account' },
+};
+/**
+ * #561: the `=`, `IN` and `LIKE` conditions on category.name, payee.name or account.name in a
+ * query built by parseWhereClause, read back from its serialized filterExpressions. `!=` and
+ * `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). 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 = [];
+    const isScalar = (v) => typeof v === 'string' || typeof v === 'number';
+    for (const expr of filterExpressions) {
+        if (expr === null || typeof expr !== 'object')
+            continue;
+        for (const [field, cond] of Object.entries(expr)) {
+            const target = NAME_CONDITION_TABLES[field];
+            if (!target)
+                continue;
+            if (isScalar(cond)) {
+                out.push({ ...target, nameFilter: cond, value: String(cond) });
+            }
+            else if (cond !== null && typeof cond === 'object') {
+                const c = cond;
+                if (typeof c.$like === 'string') {
+                    out.push({ ...target, nameFilter: { $like: c.$like }, value: c.$like });
+                }
+                else if (Array.isArray(c.$oneof) && c.$oneof.length > 0 && c.$oneof.every(isScalar)) {
+                    out.push({
+                        ...target,
+                        nameFilter: { $oneof: c.$oneof },
+                        inValues: c.$oneof.map((v) => String(v).replace(/''/g, "'")),
+                    });
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * #561: the hint lines for one condition, given the names its lookup returned. Each value is
+ * echoed at most 100 characters. For an IN list the comparison is exact, because upstream compiles
+ * `$oneof` to a plain SQL IN, which is case-sensitive: 'groceries' does not match 'Groceries' in
+ * the main query, so it must not count as found here either (#561 review round 2).
+ */
+export function nameConditionHintLines(lookup, foundNames) {
+    const line = (v) => `No ${lookup.noun} matches '${v.slice(0, 100)}'. ` +
+        `List the exact names with: SELECT id, name FROM ${lookup.table}`;
+    if (lookup.inValues) {
+        const found = new Set(foundNames);
+        return [...new Set(lookup.inValues)].filter((v) => !found.has(v)).map(line);
+    }
+    return foundNames.length === 0 ? [line(lookup.value ?? '')] : [];
+}

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

@@ -3468,6 +3468,43 @@ export async function resetBudgetHold(month) {
         await withConcurrency(() => retry(() => rawResetBudgetHold(month), { retries: 2, backoffMs: 200 }));
     }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
+/**
+ * #561: an empty result whose category.name, payee.name or account.name condition names no
+ * existing entity gains a sibling `hint` naming the value and the query that lists the exact
+ * names. Runs INSIDE runQuery's withActualApi session: raw reads only, never `adapter.*` (the api
+ * lock is not reentrant). Each lookup is a `q()` filter object carrying the main query's own
+ * operator and value, so the value never reaches a query string. A non-empty result, or one with
+ * no name condition, is returned untouched with no lookup; a failed lookup drops the hint rather
+ * than failing a query that succeeded.
+ */
+async function withEmptyResultHint(result, query, q) {
+    // Upstream answers `{ data }`; a bare array is tolerated the way getFinancialAnalysisSnapshot does.
+    const rows = (r) => Array.isArray(r) ? r : Array.isArray(r?.data) ? r.data : undefined;
+    const data = rows(result);
+    if (!data || data.length > 0)
+        return result;
+    const lookups = nameConditionLookups(query.serialize?.().filterExpressions ?? []);
+    if (lookups.length === 0)
+        return result;
+    try {
+        const lines = [];
+        for (const lookup of lookups) {
+            const found = await withConcurrency(() => rawRunQuery(lookup.inValues
+                ? q(lookup.table).filter({ name: lookup.nameFilter }).select(['name'])
+                : q(lookup.table).filter({ name: lookup.nameFilter }).select(['name']).limit(1)));
+            const names = (rows(found) ?? []).map((row) => String(row?.name ?? ''));
+            lines.push(...nameConditionHintLines(lookup, names));
+        }
+        if (lines.length === 0)
+            return result;
+        const hint = lines.join('\n');
+        return Array.isArray(result) ? { data: result, hint } : { ...result, hint };
+    }
+    catch (err) {
+        logger.warn('[ADAPTER] Empty-result name lookup failed; returning the result without a hint', errorLogFields(err));
+        return result;
+    }
+}
 export async function runQuery(queryString) {
     try {
         return await withActualApi(async () => {
@@ -3510,6 +3547,7 @@ export async function runQuery(queryString) {
                 }
                 const trimmed = queryString.trim();
                 let query;
+                let hasWhereClause = false; // #561: only a parsed SQL WHERE can carry a name condition
                 // Check for GraphQL-like query syntax: query Name { table(...) { fields } }
                 const graphqlMatch = trimmed.match(/^query\s+\w+\s*\{\s*(\w+)\s*\(([^)]*)\)\s*\{([^}]+)\}\s*\}$/is);
                 if (graphqlMatch) {
@@ -3577,6 +3615,7 @@ export async function runQuery(queryString) {
                         // types and coerce boolean literals to real booleans (#420).
                         if (whereClause) {
                             query = parseWhereClause(query, whereClause, tableName);
+                            hasWhereClause = true;
                         }
                         // Apply ORDER BY
                         if (orderField) {
@@ -3593,7 +3632,7 @@ export async function runQuery(queryString) {
                     }
                 }
                 try {
-                    return await withConcurrency(async () => {
+                    const result = await withConcurrency(async () => {
                         try {
                             return await rawRunQuery(query);
                         }
@@ -3607,6 +3646,7 @@ export async function runQuery(queryString) {
                             throw err;
                         }
                     });
+                    return hasWhereClause ? await withEmptyResultHint(result, query, q) : result;
                 }
                 catch (error) {
                     // Enhance error messages with helpful context
@@ -3707,7 +3747,7 @@ export async function getFinancialAnalysisSnapshot(params) {
 }
 // WHERE-clause translation extracted to ./actual-adapter/query.ts (#166).
 // Imported for internal use by runQuery and re-exported (unit-tested directly).
-import { parseWhereClause } from './actual-adapter/query.js';
+import { parseWhereClause, nameConditionLookups, nameConditionHintLines } from './actual-adapter/query.js';
 export { parseWhereClause };
 export async function runBankSync(accountId) {
     try {

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/lib/serverInstructions.js

@@ -0,0 +1,36 @@
+/**
+ * The `instructions` string of the MCP `initialize` result (#560).
+ *
+ * ONE source, built from the tools this process actually publishes (#483), so the text can
+ * never point the model at a tool that MCP_TOOLSETS, MCP_TOOLS or MCP_READ_ONLY hid. Clients
+ * that read the field (LibreChat with `serverInstructions: true`, Claude Desktop, Claude Code,
+ * Gemini's MCP connector) inject it into the system prompt on every turn, so it holds
+ * cross-tool rules only: call order, the data conventions every tool shares, and how to
+ * recover. Facts that belong to one tool (join syntax, LIKE semantics, what an empty query
+ * result means) live in that tool's description and are deliberately not repeated here, where
+ * they would drift. The whole text stays at most 512 characters so it stands on its own in
+ * clients that truncate.
+ *
+ * Ids are promised for accounts and categories only: actual_get_context caps payees at
+ * payeeLimit (default 500) and its own description routes the rest elsewhere.
+ *
+ * Read-only comes from the resolved tool policy, never from tool annotations, which are hints
+ * that nothing in src/ may branch on.
+ */
+export function buildServerInstructions(published, readOnly) {
+    const has = new Set(published);
+    const parts = [
+        'This server exposes an Actual Budget through MCP tools.',
+        'Amounts are integer cents (5000 is 50.00, negative is an outflow) and dates are YYYY-MM-DD strings.',
+    ];
+    if (has.has('actual_get_context')) {
+        parts.push('Call actual_get_context first and use the account and category ids it returns, never guessed names.');
+        if (has.has('actual_query_run')) {
+            parts.push('In actual_query_run, filter on the id columns (account, category, payee) rather than on names; an empty result can mean a name was wrong.');
+        }
+    }
+    if (readOnly) {
+        parts.push('This server is read-only, so do not offer to create, change or delete anything.');
+    }
+    return parts.join(' ');
+}

package/dist/src/server/httpServer.js

@@ -54,7 +54,7 @@ function resolvePrincipal(req) {
 export async function startHttpServer(mcp, port, httpPath, capabilities, // was passed by index.ts
 implementedTools, // was passed by index.ts
 serverDescription, // was passed by index.ts
-serverInstructions, // was passed by index.ts
+instructions, // was passed by index.ts (#560: built once there)
 toolSchemas, // was passed by index.ts
 version, // server version from package.json
 bindHost = 'localhost', // #239: interface to bind; forwarded to listen()
@@ -376,14 +376,11 @@ advertisedUrl) {
         const capabilitiesObj = capabilities && Object.keys(capabilities).length
             ? capabilities
             : { tools: toolsList.reduce((acc, n) => { acc[n] = {}; return acc; }, {}) };
+        // Only the two ServerOptions the MCP spec defines (#560). tools/list is served by the
+        // request handler, not by these options; the SDK ignored the extra keys this once passed.
         const serverOptions = {
-            // Provide instructions and capabilities so the SDK initialize response is correct
-            instructions: serverInstructions || "Welcome to the Actual MCP server.",
-            serverInstructions: { instructions: serverInstructions || "Welcome to the Actual MCP server." },
+            instructions,
             capabilities: capabilitiesObj,
-            implementedTools: toolsList,
-            // Include tools array explicitly so initialize result contains tools: string[]
-            tools: toolsList,
         };
         const server = new Server({
             name: serverDescription || "actual-mcp-server",
@@ -915,8 +912,7 @@ advertisedUrl) {
     const serverIp = process.env.MCP_BRIDGE_PUBLIC_HOST || getLocalIp();
     const mcpInfo = () => ({
         description: serverDescription || "Actual MCP server",
-        instructions: serverInstructions || "Welcome to the Actual MCP server.",
-        serverInstructions: { instructions: serverInstructions || "Welcome to the Actual MCP server." },
+        instructions,
         capabilities: capabilities && Object.keys(capabilities).length ? capabilities : { tools: toolsList.reduce((a, n) => ({ ...a, [n]: {} }), {}) },
         tools: toolsList,
         advertisedUrl: advertisedUrl || `${scheme}://${serverIp}:${port}${httpPath}`,

package/dist/src/server/stdioServer.js

@@ -85,7 +85,7 @@ export function createStdioCallToolHandler(mcp, stdioSessionId) {
         }
     };
 }
-export async function startStdioServer(mcp, capabilities, implementedTools, serverDescription, serverInstructions, toolSchemas, version) {
+export async function startStdioServer(mcp, capabilities, implementedTools, serverDescription, instructions, toolSchemas, version) {
     const toolsList = Array.isArray(implementedTools) ? implementedTools : [];
     // #348: a synthetic session identity for this stdio process.
     //
@@ -108,7 +108,7 @@ export async function startStdioServer(mcp, capabilities, implementedTools, serv
     // restarts and can never collide with an HTTP session id.
     const stdioSessionId = `stdio-${randomUUID()}`;
     logger.debug(`[STDIO] session id ${stdioSessionId}`);
-    const server = new Server({ name: serverDescription || 'actual-mcp-server', version: version || '0.1.0' }, { capabilities, instructions: serverInstructions });
+    const server = new Server({ name: serverDescription || 'actual-mcp-server', version: version || '0.1.0' }, { capabilities, instructions });
     attachTransportErrorLogger(server, 'stdio');
     // List tools handler — mirrors createServerInstance() in httpServer.ts
     server.setRequestHandler(ListToolsRequestSchema, async () => {

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).
@@ -22,11 +22,9 @@ export async function testMcpClient(advertisedUrl, _port, httpPath) {
     const resultObj = resultRaw && typeof resultRaw === 'object' ? resultRaw : undefined;
     if (!resultObj)
         throw new Error('Probe result is not an object');
-    const serverInstructions = resultObj['serverInstructions'];
-    if (serverInstructions && typeof serverInstructions === 'object') {
-        if (typeof serverInstructions['instructions'] !== 'string') {
-            throw new Error('serverInstructions missing or wrong type');
-        }
+    // #560: instructions is the spec's plain string, on /mcp-info as on initialize.
+    if (typeof resultObj['instructions'] !== 'string') {
+        throw new Error('Probe instructions missing or not a string');
     }
     const capabilitiesVal = resultObj['capabilities'];
     if (!capabilitiesVal || typeof capabilitiesVal !== 'object' || !('tools' in capabilitiesVal)) {
@@ -36,7 +34,7 @@ export async function testMcpClient(advertisedUrl, _port, httpPath) {
     if (!Array.isArray(toolsVal)) {
         throw new Error('tools missing or not array');
     }
-    console.info('Probe OK: capabilities/tools/serverInstructions present');
+    console.info('Probe OK: capabilities/tools/instructions present');
     // Now do JSON-RPC initialize + tools/list using the HTTP endpoint
     const rpcUrl = `${base.origin}${httpPath}`;
     const initPayload = {
@@ -77,7 +75,7 @@ export async function testMcpClient(advertisedUrl, _port, httpPath) {
     }
     if (sessionId)
         console.info(`Received session id header: ${sessionId}`);
-    // Validate initialize result fields (capabilities/tools/serverInstructions)
+    // Validate initialize result fields (capabilities/tools/instructions)
     const initResultRaw = initJson['result'];
     const initResult = initResultRaw && typeof initResultRaw === 'object' ? initResultRaw : undefined;
     if (!initResult || typeof initResult['capabilities'] !== 'object') {
@@ -90,21 +88,12 @@ export async function testMcpClient(advertisedUrl, _port, httpPath) {
     if (!hasTools) {
         throw new Error('initialize result.tools missing or not array and capabilities.tools not present');
     }
-    // serverInstructions may be a string, an object { instructions }, or absent.
-    const si = initResult['serverInstructions'];
-    if (!si) {
-        console.warn('Warning: serverInstructions missing from initialize result — continuing tests');
-    }
-    else if (typeof si === 'string') {
-        // ok
-    }
-    else if (typeof si === 'object' && typeof si['instructions'] === 'string') {
-        // ok
+    // #560: the spec's InitializeResult.instructions, a string. The harness never read the spec
+    // field before (it accepted a non-spec key in any shape), so this is now a hard check.
+    if (typeof initResult['instructions'] !== 'string') {
+        throw new Error('initialize result.instructions missing or not a string');
     }
-    else {
-        console.warn('Warning: serverInstructions present but in unexpected shape — continuing tests');
-    }
-    console.info('Initialize OK: capabilities/tools/serverInstructions present');
+    console.info('Initialize OK: capabilities/tools/instructions present');
     // call tools/list (JSON-RPC) to verify RPC path works
     const listPayload = { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} };
     const listHeaders = { ...commonPostHeaders };
@@ -115,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/query_run.js

@@ -15,6 +15,7 @@ Example: "SELECT id, date, amount, payee.name FROM transactions WHERE amount < 0
 WHERE supports: =, !=, >, >=, <, <=; IN (v1, v2); LIKE / NOT LIKE (case and accent-insensitive, % wildcard, e.g. imported_payee LIKE '%amazon%'); IS NULL / IS NOT NULL; boolean columns as true / false (cleared = false, category.hidden = true); conditions joined with AND. OR, REGEXP, NOT IN and parenthesised groups are not supported and return an error (a query is never silently run unfiltered). Transactions come back in split-INLINE mode: "is_parent = true" returns nothing, use "is_parent = false" to exclude split children.
 
 Joins use dot notation: payee.name, category.name, account.name (NOT payee_name). Amounts are in cents: $100.00 = 10000. Dates are quoted YYYY-MM-DD strings: date >= '2025-01-01'.
+An empty result may carry a "hint" naming a category.name, payee.name or account.name value that matches no entity, with the query that lists the exact names.
 
 Tables:
 - transactions: id, date, amount, notes, cleared, account, payee, category

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.22.42",
+  "version": "0.22.46",
   "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",
+    "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: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",