actual-mcp-server 0.25.2 → 0.26.1

package/dist/src/lib/budget-registry.js

@@ -25,6 +25,44 @@
  * The AI uses `actual_budgets_list_available` to see all configured budgets,
  * then `actual_budgets_switch` with the budget name to switch between them.
  */
+/**
+ * #621: a server URL as it may appear in a log line: scheme, host and port only. URL userinfo
+ * (a reverse-proxy credential), path and query are dropped. Never throws; an unparseable URL
+ * or one with a `null` origin (a non-special scheme such as a schemeless `user:pass@host`
+ * typo) becomes `<invalid url>`. Display text only, for log lines and tool results (#628):
+ * its output is never used to connect, and the login itself must keep the full URL.
+ */
+export function logSafeOrigin(url) {
+    try {
+        const origin = new URL(url).origin;
+        return origin === 'null' ? '<invalid url>' : origin;
+    }
+    catch {
+        return '<invalid url>';
+    }
+}
+/**
+ * #621: the startup registry line, counts and schemes only, so no budget name, host or
+ * credential reaches the log. Servers are counted by the same [serverUrl, password] key
+ * setLoginsSpanServers uses, so the two can never disagree. Never throws.
+ */
+export function formatBudgetRegistrySummary(registry) {
+    const budgets = [...registry.values()];
+    const servers = new Set(budgets.map((b) => JSON.stringify([b.serverUrl, b.password || '']))).size;
+    const schemes = new Set();
+    for (const b of budgets) {
+        let scheme;
+        try {
+            const protocol = new URL(b.serverUrl).protocol;
+            scheme = protocol === 'http:' ? 'http' : protocol === 'https:' ? 'https' : 'other';
+        }
+        catch {
+            scheme = 'invalid';
+        }
+        schemes.add(scheme);
+    }
+    return `Budget registry: ${budgets.length} budget(s) across ${servers} server(s) (${[...schemes].sort().join(', ')})`;
+}
 /**
  * Parse the budget registry from environment variables.
  * Always includes the default budget from the provided defaults (ACTUAL_* vars).
@@ -62,7 +100,7 @@ export function parseBudgetRegistry(env, defaults) {
         // Mirror the default-budget check (#161): never send an E2E encryption
         // password over an http:// upstream unless ALLOW_INSECURE_UPSTREAM is set.
         if (encryptionPassword && env.ALLOW_INSECURE_UPSTREAM !== 'true' && /^http:\/\//i.test(serverUrl)) {
-            console.error(`[CONFIG] BUDGET_${i}_ENCRYPTION_PASSWORD is set but the upstream URL is http:// (${serverUrl}). ` +
+            console.error(`[CONFIG] BUDGET_${i}_ENCRYPTION_PASSWORD is set but the upstream URL is http:// (${logSafeOrigin(serverUrl)}). ` +
                 `Refusing to send the encryption password over plaintext (#161). ` +
                 `Use https:// or set ALLOW_INSECURE_UPSTREAM=true to override.`);
             process.exit(1);

package/dist/src/lib/constants.js

@@ -31,15 +31,11 @@ export const DEFAULT_CONCURRENCY_LIMIT = 5;
 // TIMEOUTS
 // ============================================================================
 /**
- * How long (ms) to wait after calling rawRunBankSync for the SDK's background
- * promise to surface a BankSyncError as an unhandledRejection.
- *
- * Bank provider errors (GoCardless RATE_LIMIT_EXCEEDED, auth failures, etc.)
- * arrive as HTTP responses. Fast banks respond within 1-3 seconds; slower
- * institutions can take considerably longer. 30 seconds gives a comfortable
- * margin while keeping the tool's wall-clock time acceptable for MCP clients.
+ * How many ids each list of an `actual_bank_sync` report carries (#548). The counts are
+ * always the full lengths; only the id lists are cut, so a first sync of a large account
+ * cannot flood the client's context. The tool sets `truncated` when any list was cut.
  */
-export const BANK_SYNC_SETTLE_MS = 30_000;
+export const BANK_SYNC_IDS_CAP = 100;
 /**
  * How long (ms) to wait for additional queued writes before closing the
  * shared budget session. Increasing this value batches more writes per
@@ -80,6 +76,10 @@ export const DEFAULT_HTTP_PORT = 3600;
 // ============================================================================
 // VALIDATION & LIMITS
 // ============================================================================
+/**
+ * #479: the most dates actual_schedules_dates returns, so a daily schedule cannot flood the context.
+ */
+export const SCHEDULE_DATES_CAP = 366;
 /**
  * Maximum length for name fields (accounts, categories, payees)
  */

package/dist/src/lib/mcp-version.js

@@ -3,6 +3,12 @@ import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { findRootPackageJson } from './node-version-guard.js';
+/**
+ * #624: the MCP initialize `serverInfo.name` on both transports. It equals the package.json
+ * name (tests/unit/server_identity.test.js pins that), so a client shows the server under the
+ * name it was installed as, never a description sentence.
+ */
+export const SERVER_NAME = 'actual-mcp-server';
 /**
  * #541: the single source of this server's own version, shared by the MCP initialize
  * `serverInfo.version` (src/index.ts) and the `actual_server_info` tool.

package/dist/src/lib/processHandlers.js

@@ -0,0 +1,183 @@
+/**
+ * #622: the process-level unhandledRejection and uncaughtException handlers, as a pure
+ * factory so unit tests can drive them without exiting. src/lib/processHandlersInstall.ts
+ * registers them on `process`.
+ *
+ * Records are built from gated fields only (logging convention v1, agreed with
+ * actual-sync): `{ type, code?, httpStatus?, category, safeMessage }`. The reason itself,
+ * its message, its stack and any upstream `.type` never reach a record or winston, because
+ * a rejection reason can carry a request object with an Authorization header, and upstream
+ * text can quote account or payee names (#559).
+ *
+ * INVARIANT: imports only node: builtins, ./errors.js and ./rejection-allowlist.js, never
+ * logger.ts or loggerFactory.ts. This module loads before MCP_STDIO_MODE is set, and the
+ * logger reads that variable when winston is built.
+ */
+import { errorLogFields } from './errors.js';
+import { isKnownBenignRejection } from './rejection-allowlist.js';
+/** Fixed sentence per category, used when the throw site set no log-safe text. */
+const SAFE_MESSAGES = {
+    not_found: 'A requested item was not found.',
+    validation: 'A request was rejected as invalid.',
+    auth: 'An upstream request was not authorized.',
+    timeout: 'An operation timed out.',
+    conflict: 'An operation conflicted with existing state.',
+    rate_limited: 'An upstream service rate limited the request.',
+    upstream_unavailable: 'An upstream service was unavailable.',
+    cancelled: 'An operation was cancelled.',
+    internal: 'An internal error occurred.',
+};
+const UNAVAILABLE_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'EAI_AGAIN', 'EPIPE']);
+/** Closed mapping, first match wins. Never reads message text. */
+export function categorizeError({ errorClass, refusalKind, code, httpStatus: s }) {
+    if (refusalKind === 'not-found')
+        return 'not_found';
+    if (refusalKind === 'out-of-range')
+        return 'validation';
+    if (s === 401 || s === 403)
+        return 'auth';
+    if (s === 404)
+        return 'not_found';
+    if (s === 408 || s === 504 || code === 'ETIMEDOUT')
+        return 'timeout';
+    if (s === 409)
+        return 'conflict';
+    if (s === 429)
+        return 'rate_limited';
+    if (s === 400 || s === 422)
+        return 'validation';
+    if ((s !== undefined && s >= 500 && s <= 599) || (code !== undefined && UNAVAILABLE_CODES.has(code))) {
+        return 'upstream_unavailable';
+    }
+    // The Node AbortError class (its ABORT_ERR code fails the E-shape gate). A fetch abort is a
+    // DOMException and falls to internal by design: this keys on the class, never on `name`.
+    if (errorClass === 'AbortError')
+        return 'cancelled';
+    return 'internal';
+}
+function isHttpStatus(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v >= 100 && v <= 599;
+}
+function readHttpStatus(reason) {
+    if (typeof reason !== 'object' || reason === null)
+        return undefined;
+    const r = reason;
+    if (isHttpStatus(r.status))
+        return r.status;
+    if (isHttpStatus(r.statusCode))
+        return r.statusCode;
+    const response = r.response;
+    if (typeof response === 'object' && response !== null && isHttpStatus(response.status))
+        return response.status;
+    return undefined;
+}
+/**
+ * The gated error object of a record. `type` is the prototype class name, never the
+ * reason's own `.type` property (that can carry CR/LF from upstream). Can throw when the
+ * reason has a hostile getter; the handlers catch that and write the fixed fallback.
+ */
+export function errorRecordFields(reason) {
+    const { errorClass, refusalKind, code, logMessage } = errorLogFields(reason);
+    const httpStatus = readHttpStatus(reason);
+    const category = categorizeError({ errorClass, refusalKind, code, httpStatus });
+    const record = { type: errorClass, category, safeMessage: logMessage ?? SAFE_MESSAGES[category] };
+    if (code !== undefined)
+        record.code = code;
+    if (httpStatus !== undefined)
+        record.httpStatus = httpStatus;
+    return record;
+}
+const NODE_FLOOR_HINT = [
+    `This almost certainly means Node ${process.version} is too old.`,
+    'actual-mcp-server requires the Node version in package.json "engines".',
+    'Import attributes (`with { type: "json" }`) need Node 22 or newer.',
+];
+/**
+ * Upstream raises bank sync failures as plain Errors with no code, so message text is the
+ * only signal. This is a documented exception to the no-text-matching rule: the text only
+ * decides survive versus exit, and is never logged.
+ */
+function isBankSyncError(error) {
+    const errMsg = String(error?.message || error);
+    const errType = error?.type;
+    return (errType === 'BankSyncError' ||
+        errMsg.includes('BankSyncError') ||
+        errMsg.includes('NORDIGEN_ERROR') ||
+        errMsg.includes('RATE_LIMIT_EXCEEDED') ||
+        errMsg.includes('Rate limit exceeded') ||
+        errMsg.includes('Failed syncing account') ||
+        errMsg.includes('GoCardless') ||
+        errMsg.includes('SimpleFIN'));
+}
+export function createProcessHandlers(deps) {
+    const { exit, writeSync, getLogger } = deps;
+    // Fatal: the one synchronous record, then exit 1 even when the write fails. Never also
+    // through winston, which under stdio already writes to stderr (one record per event).
+    function crash(source, error) {
+        try {
+            writeSync(2, JSON.stringify({ level: 'error', event: 'sys_crash', source, error }) + '\n');
+        }
+        catch {
+            // stderr is a full or closed pipe: nothing more can be written.
+        }
+        finally {
+            exit(1);
+        }
+    }
+    function fallback(source) {
+        crash(source, { type: 'unknown', category: 'internal', safeMessage: SAFE_MESSAGES.internal });
+    }
+    function survive(source, event, message, error) {
+        const logger = getLogger();
+        if (logger) {
+            logger.warn(message, { event, source, error });
+        }
+        else {
+            writeSync(2, JSON.stringify({ level: 'warn', event, source, error }) + '\n');
+        }
+    }
+    function writeNodeFloorHint(error) {
+        if (error.code !== 'ERR_IMPORT_ASSERTION_TYPE_MISSING')
+            return;
+        for (const line of NODE_FLOOR_HINT)
+            writeSync(2, line + '\n');
+    }
+    function onUnhandledRejection(reason) {
+        try {
+            const error = errorRecordFields(reason);
+            // #275 backstop: a library consumer reaches neither entry point's guard, and import
+            // attributes fail asynchronously on an under-floor Node, so name the real cause.
+            writeNodeFloorHint(error);
+            if (isKnownBenignRejection(reason)) {
+                survive('unhandledRejection', 'process.rejection_benign', 'Process-level rejection survived', error);
+                return;
+            }
+            crash('unhandledRejection', error);
+        }
+        catch {
+            fallback('unhandledRejection');
+        }
+    }
+    function onUncaughtException(reason) {
+        try {
+            const error = errorRecordFields(reason);
+            writeNodeFloorHint(error);
+            // GoCardless and SimpleFIN failures can surface here from inside @actual-app/api when
+            // the provider answers asynchronously (RATE_LIMIT_EXCEEDED, for example). Non-fatal.
+            if (isBankSyncError(reason)) {
+                if (error.category === 'internal') {
+                    error.category = 'upstream_unavailable';
+                    if (error.safeMessage === SAFE_MESSAGES.internal)
+                        error.safeMessage = SAFE_MESSAGES.upstream_unavailable;
+                }
+                survive('uncaughtException', 'bank_sync.exception_benign', 'Bank sync error survived', error);
+                return;
+            }
+            crash('uncaughtException', error);
+        }
+        catch {
+            fallback('uncaughtException');
+        }
+    }
+    return { onUnhandledRejection, onUncaughtException };
+}

package/dist/src/lib/processHandlersInstall.js

@@ -0,0 +1,25 @@
+/**
+ * #622: side-effect module that registers the process-level handlers. src/index.ts imports
+ * it SECOND, right after ./node-version-guard.js (#275), so the handlers are armed before
+ * any other module evaluates. The logger arrives later through attachProcessLogger, once
+ * src/index.ts has set MCP_STDIO_MODE and loaded src/logger.ts; until then the handlers
+ * write one fixed JSON line to stderr.
+ *
+ * INVARIANT: no import of logger.ts or loggerFactory.ts (see processHandlers.ts).
+ */
+import { writeSync } from 'node:fs';
+import { createProcessHandlers } from './processHandlers.js';
+let attached;
+/** Route the survivable records through the logger from now on. */
+export function attachProcessLogger(logger) {
+    attached = logger;
+}
+const handlers = createProcessHandlers({
+    exit: (code) => process.exit(code),
+    writeSync: (fd, text) => {
+        writeSync(fd, text);
+    },
+    getLogger: () => attached,
+});
+process.on('unhandledRejection', handlers.onUnhandledRejection);
+process.on('uncaughtException', handlers.onUncaughtException);

package/dist/src/lib/rejection-allowlist.js

@@ -7,9 +7,10 @@
  *
  * INVARIANT: this module MUST remain side-effect-free.
  *
- * src/index.ts registers the process.on('unhandledRejection', ...) handler
- * AFTER importing this module (ESM static imports are evaluated before the
- * top-level body runs). Any side effect introduced here, e.g. importing a
+ * src/lib/processHandlersInstall.ts (the second import of src/index.ts, #622)
+ * registers the process.on('unhandledRejection', ...) handler AFTER importing
+ * this module through processHandlers.ts (ESM static imports are evaluated
+ * before the top-level body runs). Any side effect introduced here, e.g. importing a
  * logger that performs winston/file-handle init, importing dotenv, or any
  * code that runs at module load, opens a window during ESM evaluation in
  * which an unhandled rejection bypasses this allow-list and crashes the

package/dist/src/lib/schemas/common.js

@@ -3,7 +3,7 @@
  *
  * Common validation schemas used across MCP tools for Actual Budget.
  * These schemas provide consistent validation, better error messages,
- * and reduce duplication across the 84 tool definitions.
+ * and reduce duplication across the 85 tool definitions.
  */
 import { z } from 'zod';
 import { MAX_NAME_LENGTH, MAX_NOTES_LENGTH, DATE_PATTERN, MONTH_PATTERN, UUID_PATTERN } from '../constants.js';

package/dist/src/lib/tool-annotations.js

@@ -44,13 +44,13 @@ const OPEN_WORLD = new Set(['actual_bank_sync']);
  * `tests/unit/tool_annotations.test.js`, which resolves each tool's `adapter.*` calls and
  * fails if one of these reaches `queueWriteOperation`.
  *
- * Claimed only where it is certain. Three read-path tools are deliberately absent because
+ * Claimed only where it is certain. Three tools are deliberately absent because
  * "does not modify its environment" is false for them, and a wrong `true` here is worse
  * than no annotation at all:
  *
- *   actual_bank_sync       runs through `withActualApi` (the read path) but IMPORTS
- *                          transactions, so the call graph says read and reality says
- *                          write. Reality wins.
+ *   actual_bank_sync       IMPORTS transactions through `withActualApiWrite` (one
+ *                          upstream call, not the write queue, #548), so a queue-based
+ *                          reading of the call graph misses it.
  *   actual_budgets_export  writes a zip into the server's data directory.
  *   actual_budgets_switch  changes the session's active budget and persists a preference.
  *   actual_session_close   closes a pooled connection: server state, not budget data.
@@ -77,6 +77,7 @@ const READ_ONLY = new Set([
     'actual_preferences_get',
     'actual_query_run',
     'actual_rules_get',
+    'actual_schedules_dates',
     'actual_schedules_get',
     'actual_server_get_version',
     'actual_server_info',

package/dist/src/lib/toolsets.js

@@ -94,6 +94,7 @@ export const TOOLSETS = {
     ],
     schedules: [
         'actual_schedules_get',
+        'actual_schedules_dates',
         'actual_schedules_create',
         'actual_schedules_update',
         'actual_schedules_delete',
@@ -170,7 +171,7 @@ export const PRESET_NAMES = Object.keys(PRESETS);
  *
  * Derived by hand from the adapter call graph: the 43 tools whose adapter path reaches
  * queueWriteOperation, plus the four that mutate WITHOUT the write queue (bank_sync imports
- * transactions through the read path, budgets_export writes a zip to ACTUAL_EXPORT_DIR,
+ * transactions through withActualApiWrite, budgets_export writes a zip to ACTUAL_EXPORT_DIR,
  * budgets_switch changes the active budget, session_close closes a pooled connection).
  * Never derive this from tool annotations.
  *

package/dist/src/server/httpServer.js

@@ -5,6 +5,8 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import logger, { resolveRequestId } from '../logger.js';
 import { attachTransportErrorLogger } from '../lib/transportErrorLogger.js';
+import { SERVER_NAME } from '../lib/mcp-version.js';
+import { createModuleLogger } from '../lib/loggerFactory.js';
 import { getLocalIp } from '../utils.js';
 import actualToolsManager from '../actualToolsManager.js';
 import { getConnectionState, connectToActualForSession, shutdownActualForSession, shutdownActual, admitSession, releaseAdmission, isConnectionPoolEnabled } from '../actualConnection.js';
@@ -43,6 +45,7 @@ import { buildToolListEntries } from '../lib/tool-list-entry.js';
 import { classifyInitFailure } from '../lib/init-failure.js';
 import { createHttpErrorHandler } from './httpErrorHandler.js';
 export { classifyInitFailure };
+const httpLog = createModuleLogger('HTTP');
 export { requestContext };
 // Resolve the authenticated principal for the per-principal budget preference
 // (#189). OIDC: the verified JWT subject. A MCP_STATIC_TOKENS token (#572): its
@@ -486,7 +489,7 @@ advertisedUrl) {
             capabilities: capabilitiesObj,
         };
         const server = new Server({
-            name: serverDescription || "actual-mcp-server",
+            name: SERVER_NAME,
             version: version || "0.1.0",
         }, serverOptions);
         attachTransportErrorLogger(server, 'http');
@@ -1124,9 +1127,9 @@ advertisedUrl) {
         // #239: when bound to a specific (non all-interfaces) host the server is NOT on
         // loopback, so point the health hint at the actual bind host instead of localhost.
         const healthHost = (!bindHost || bindHost === '0.0.0.0' || bindHost === '::') ? 'localhost' : bindHost;
-        console.info(`MCP Streamable HTTP Server listening on ${port}`);
-        console.info(`📨 MCP endpoint: ${advertised}`);
-        console.info(`❤️ Health check: ${scheme}://${healthHost}:${port}/health`);
+        const health = `${scheme}://${healthHost}:${port}/health`;
+        // #625: one structured record through the module logger instead of three console.info lines.
+        httpLog.info(`MCP Streamable HTTP Server listening on ${port}; MCP endpoint: ${advertised} (health: ${health})`, { port, endpoint: advertised, health });
         if (config.AUTH_PROVIDER === 'oidc') {
             logger.info(`🔒 OIDC authentication enabled (JWT Bearer token required; issuer: ${config.OIDC_ISSUER})`);
             // #345: name the userNames the ACL can match, once, at boot. Deliberately

package/dist/src/server/stdioServer.js

@@ -5,6 +5,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprot
 import { randomUUID } from 'node:crypto';
 import logger from '../logger.js';
 import { attachTransportErrorLogger } from '../lib/transportErrorLogger.js';
+import { SERVER_NAME } from '../lib/mcp-version.js';
 import actualToolsManager from '../actualToolsManager.js';
 import { requestContext } from '../lib/requestContext.js';
 import { buildToolListEntries } from '../lib/tool-list-entry.js';
@@ -85,7 +86,9 @@ export function createStdioCallToolHandler(mcp, stdioSessionId) {
         }
     };
 }
-export async function startStdioServer(mcp, capabilities, implementedTools, serverDescription, instructions, toolSchemas, version) {
+export async function startStdioServer(mcp, capabilities, implementedTools, 
+// #624: no longer the serverInfo name; kept so the positional signature matches HTTP.
+_serverDescription, instructions, toolSchemas, version) {
     const toolsList = Array.isArray(implementedTools) ? implementedTools : [];
     // #348: a synthetic session identity for this stdio process.
     //
@@ -108,7 +111,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 });
+    const server = new Server({ name: SERVER_NAME, 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/tools/bank_sync.js

@@ -1,11 +1,17 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+import { BANK_SYNC_IDS_CAP } from '../lib/constants.js';
 const InputSchema = z.object({
     accountId: z.string().nullable().optional().describe('Optional account ID to sync a specific account. If omitted, syncs all linked accounts.'),
 });
 const tool = {
     name: 'actual_bank_sync',
-    description: 'Trigger 3rd party bank sync (GoCardless, SimpleFIN) for linked bank accounts. Returns immediately with an error if no bank-linked accounts are found. When bank-linked accounts exist, waits up to 30 seconds for the provider to confirm the operation and surfaces errors such as rate limits or auth failures that occur within that window. Successful syncs may take a few additional moments for transactions to appear in Actual Budget.',
+    description: 'Run 3rd party bank sync (GoCardless, SimpleFIN) for one linked account, or for every linked open account when accountId is omitted. ' +
+        'Refuses at once for a local, closed, half-linked or unknown account, or when no open account is linked. ' +
+        'Reports what Actual reconciled: newTransactions (imported), matchedTransactions (existing ones updated) and updatedAccounts (accounts that received new transactions), ' +
+        `each as { count, ids } with up to ${BANK_SYNC_IDS_CAP} ids (count is always the full total; truncated is true when any list was cut). ` +
+        'Never retried. A sync that runs past the server operation timeout reports "timed out" and may still have imported, so re-list transactions before retrying. ' +
+        'An all-accounts sync that fails on one account may still have imported the others; those imports reach the Actual server with the next write in this session or when it closes, so other clients may not see them yet.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
@@ -17,14 +23,21 @@ const tool = {
         if (input.accountId) {
             await adapter.resolveFilterId('account', input.accountId, { verifyExists: true });
         }
-        try {
-            await adapter.runBankSync(input.accountId ?? undefined);
-            return { result: 'Bank sync initiated successfully' };
-        }
-        catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            throw new Error(msg);
-        }
+        // #548: rethrow the adapter's error as is, so a typed refusal keeps its brand.
+        const report = await adapter.runBankSync(input.accountId ?? undefined);
+        let truncated = false;
+        const capped = (ids) => {
+            if (ids.length > BANK_SYNC_IDS_CAP)
+                truncated = true;
+            return { count: ids.length, ids: ids.slice(0, BANK_SYNC_IDS_CAP) };
+        };
+        return {
+            result: 'Bank sync completed',
+            newTransactions: capped(report.newTransactions),
+            matchedTransactions: capped(report.matchedTransactions),
+            updatedAccounts: capped(report.updatedAccounts),
+            truncated,
+        };
     },
 };
 export default tool;

package/dist/src/tools/budgets_list_available.js

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

package/dist/src/tools/index.js

@@ -52,6 +52,7 @@ export { default as rules_delete } from './rules_delete.js';
 export { default as rules_get } from './rules_get.js';
 export { default as rules_update } from './rules_update.js';
 export { default as schedules_create } from './schedules_create.js';
+export { default as schedules_dates } from './schedules_dates.js';
 export { default as schedules_delete } from './schedules_delete.js';
 export { default as schedules_get } from './schedules_get.js';
 export { default as schedules_update } from './schedules_update.js';

package/dist/src/tools/schedules_dates.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import { CommonSchemas } from '../lib/schemas/common.js';
+import adapter from '../lib/actual-adapter.js';
+import { SCHEDULE_DATES_CAP } from '../lib/constants.js';
+export default createTool({
+    name: 'actual_schedules_dates',
+    description: 'List the dates one schedule falls on, computed by Actual itself, so month ends, patterns ' +
+        '("last Friday"), intervals and the weekend move match the Actual UI. Use this instead of ' +
+        'expanding a schedule\'s recurrence yourself. Get schedule ids from actual_schedules_get. ' +
+        '`start` defaults to today; pass it whenever you pass `end`. With `end` and `count` both set, the list stops at whichever ' +
+        `comes first. At most ${SCHEDULE_DATES_CAP} dates are returned. \`truncated\` is true when more dates exist ` +
+        'after the last one returned (within `end`, if given): ask again with a later `start` to continue. ' +
+        'Returns { schedule_id, name, dates (ascending YYYY-MM-DD), count, truncated }.',
+    schema: z.object({
+        schedule_id: CommonSchemas.scheduleId,
+        start: CommonSchemas.date.optional().describe('First date to consider (YYYY-MM-DD); defaults to today'),
+        end: CommonSchemas.date.optional().describe('Last date to consider (YYYY-MM-DD), inclusive'),
+        count: z.number().int().min(1).max(SCHEDULE_DATES_CAP).optional()
+            .describe(`How many dates to return, 1 to ${SCHEDULE_DATES_CAP}`),
+    }),
+    handler: async ({ schedule_id, start, end, count }) => {
+        return await adapter.getScheduleDates(schedule_id, { start, end, count });
+    },
+    examples: [
+        {
+            description: 'Next three dates of a schedule',
+            input: { schedule_id: '00000000-0000-0000-0000-000000000001', count: 3 },
+        },
+        {
+            description: 'Every date of a schedule in Q4 2026',
+            input: { schedule_id: '00000000-0000-0000-0000-000000000001', start: '2026-10-01', end: '2026-12-31' },
+        },
+    ],
+});

package/dist/src/tools/schedules_update.js

@@ -3,7 +3,7 @@ import adapter from '../lib/actual-adapter.js';
 import { CommonSchemas } from '../lib/schemas/common.js';
 import { RecurConfigSchema } from '../lib/schemas/recur.js';
 import { ScheduleAmountSchema, amountOpMismatch } from '../lib/schemas/schedule-amount.js';
-const InputSchema = z.object({
+const InputSchema = z.strictObject({
     id: CommonSchemas.scheduleId.describe('Schedule UUID'),
     name: z.string().optional()
         .describe('New display name'),
@@ -24,10 +24,12 @@ const InputSchema = z.object({
         .describe('New YYYY-MM-DD date or RecurConfig object'),
     posts_transaction: z.boolean().optional()
         .describe('Auto-post a transaction on each occurrence'),
-    completed: z.boolean().optional()
-        .describe('true marks it completed, false reactivates it'),
     resetNextDate: z.boolean().optional().default(false)
         .describe('Recalculate next_date'),
+    // #627: strict, because upstream updateSchedule refuses `completed` and `next_date` as
+    // system-managed. A stripped key would return success while changing nothing; an advertised
+    // one failed upstream after the write queue. Either is refused here, before any write, as
+    // "unexpected field(s): completed" (formatZodError sanitises the key); the description says why.
 }).superRefine((input, ctx) => {
     // #527: with both fields supplied the input alone decides. With only one, the answer
     // depends on the stored schedule, so adapter.updateSchedule checks it inside the write queue.
@@ -39,7 +41,7 @@ const InputSchema = z.object({
 });
 const tool = {
     name: 'actual_schedules_update',
-    description: `Update a schedule; supply only the fields to change. A new date replaces the stored recurrence, patterns included. Set resetNextDate: true when changing the date or recurrence.`,
+    description: `Update a schedule; supply only the fields to change. A new date replaces the stored recurrence, patterns included. Set resetNextDate: true when changing the date or recurrence. Completion and next_date are managed by Actual and cannot be set.`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});