actual-mcp-server 0.22.22 → 0.22.25

package/README.md

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

package/dist/src/index.js

@@ -2,38 +2,25 @@
 // source order, so this arms the Node floor check before zod, before the rejection
 // allowlist, and before the handlers below. `npm start` and the documented
 // `node dist/src/index.js --stdio` reach this file without going through bin/, so the
-// guard cannot live in bin/ alone. Importing the named export does not change that:
-// the module's top-level `enforceNodeVersion()` still fires here, exactly once.
-import { findRootPackageJson } from './lib/node-version-guard.js';
-import path, { dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
+// guard cannot live in bin/ alone. It is a side-effect import: the module's top-level
+// `enforceNodeVersion()` fires here, exactly once.
+import './lib/node-version-guard.js';
+import { getMcpServerVersion } from './lib/mcp-version.js';
+import path from 'node:path';
 import { z } from 'zod';
 import { isKnownBenignRejection } from './lib/rejection-allowlist.js';
 import { format } from 'node:util';
-/**
- * #277: the single version reader for this module.
+/*
+ * #277 / #541: this module's version comes from `getMcpServerVersion()` (src/lib/mcp-version.ts),
+ * which `--version`, `--help`, the startup banner, the MCP initialize `serverInfo.version` and
+ * `actual_server_info` all share. It reads the ROOT package.json through
+ * `findRootPackageJson`, never the stale `dist/package.json` mirror that a dynamic JSON import
+ * once produced (#277), and it honours a build-time `VERSION`.
  *
- * This used to be a dynamic JSON import of `../package.json` carrying an import
- * attribute, which from the compiled `dist/src/index.js` resolved to `dist/package.json`:
- * a mirror that tsc emitted precisely BECAUSE of this import (rootDir is "."), and that
- * went stale between a version bump and the next build. `src/tools/server_info.ts` reads
- * the ROOT manifest, so the two disagreed. Removing the import removes the mirror too.
- *
- * `findRootPackageJson` walks up to the outermost package.json named actual-mcp-server,
- * skipping that mirror. It never throws (it swallows unreadable and malformed files), so
- * the try/catch is belt-and-braces around a future change rather than a live path.
- * Removing the import attributes also removes the last instance of the construct that
- * crashed on Node 18 in #275.
+ * #541 reversed the gate's "leave `--version` unchanged": the old `readRootVersion()` here
+ * ignored `VERSION`, so a Docker image built as `X-dev-abc` printed plain `X` from
+ * `--version` while clients saw `X-dev-abc`. One reader means one string.
  */
-function readRootVersion() {
-    try {
-        const manifest = findRootPackageJson(dirname(fileURLToPath(import.meta.url)));
-        return manifest?.version ?? process.env.VERSION ?? 'unknown';
-    }
-    catch {
-        return process.env.VERSION ?? 'unknown';
-    }
-}
 // Add global error handlers
 process.on('unhandledRejection', (reason, promise) => {
     console.error('=== UNHANDLED REJECTION ===');
@@ -140,7 +127,7 @@ if (!argsEarly.includes('--http') &&
 }
 if (argsEarly.includes('--help') || argsEarly.includes('-h') ||
     argsEarly.includes('--version') || argsEarly.includes('-v')) {
-    const version = readRootVersion();
+    const version = getMcpServerVersion();
     if (argsEarly.includes('--version') || argsEarly.includes('-v')) {
         console.log(version);
     }
@@ -212,26 +199,9 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
     const logger = loggerModule.default;
     const { getLocalIp } = utilsModule;
     const actualToolsManager = actualToolsManagerModule.default;
-    // Load version from environment (Docker build-time) or the ROOT package.json (local dev)
-    let VERSION = process.env.VERSION;
-    if (!VERSION || VERSION === 'unknown') {
-        VERSION = readRootVersion();
-        // Append git commit hash for development builds
-        try {
-            const { execSync } = await import('child_process');
-            const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim();
-            const commitHash = execSync('git rev-parse --short HEAD', { encoding: 'utf8' }).trim();
-            if (branch === 'develop' || branch !== 'main') {
-                VERSION = `${VERSION}-dev-${commitHash}`;
-            }
-        }
-        catch (err) {
-            // Git not available or not in a git repo, use version as-is
-            logger.debug('Could not determine git commit hash:', err);
-        }
-    }
-    // Ensure VERSION is always a string (fallback to 0.1.0 if somehow still undefined)
-    const version = VERSION || '0.1.0';
+    // #541: the build-time VERSION, or the root package version plus a dev suffix on a
+    // checkout. Shared with actual_server_info so both report the identical string.
+    const version = getMcpServerVersion();
     // now continue with the original logic (args, flags, usage, etc.)
     const PORT = process.env.MCP_BRIDGE_PORT ? Number(process.env.MCP_BRIDGE_PORT) : 3600;
     const HTTP_PATH = process.env.MCP_HTTP_PATH || '/http';
@@ -249,7 +219,7 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
             logger.error('❌ --http and --stdio are mutually exclusive. Pick one.');
             process.exit(1);
         }
-        logger.info(`🚀 Starting Actual MCP Server v${VERSION}`);
+        logger.info(`🚀 Starting Actual MCP Server v${version}`);
         // NOTE: Persistent connection disabled - using init/shutdown per operation pattern
         // This ensures tombstone=0 for all created entities (they appear in UI)
         // await connectToActual();

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

@@ -2120,12 +2120,25 @@ export async function updateTransaction(id, fields) {
         }
     });
 }
+/**
+ * Update many transactions in ONE write cycle, with a verdict per item. NOT atomic.
+ *
+ * COOPERATIVE DEADLINE (#538): same 0.75 fraction of ACTUAL_OP_TIMEOUT_MS as `createRulesBatch`
+ * and `setBudgetBatch`, because `withOpTimeout` cannot cancel this callback: without it a slow
+ * batch kept writing after its caller was told the operation timed out. The clock starts before
+ * the existence query, so a slow read counts. Items not reached go to `failed` with
+ * BUDGET_BATCH_DEADLINE_ERROR and were never sent upstream. A missing id keeps its not-found
+ * error even past the deadline: it was never going to be written, and "not attempted" would
+ * tell the client a retry could succeed. A raw update already in flight when the deadline
+ * passes can still overrun; the check runs between items.
+ */
 export async function updateTransactionBatch(updates) {
     observability.incrementToolCall('actual.transactions.updateBatch').catch(() => { });
     // All updates share one queueWriteOperation → one init/sync/shutdown cycle (issue #79).
     // Sequential loop (not Promise.all) is intentional: concurrent rawUpdateTransaction calls
     // within one session can interleave withMutation CRDT messages unpredictably.
     return queueWriteOperation(async () => {
+        const startedAt = Date.now();
         // Nothing to do for an empty batch. The tool enforces min 1, but the adapter is a
         // public export, so guard here and avoid an empty-$oneof existence query.
         if (updates.length === 0)
@@ -2148,11 +2161,16 @@ export async function updateTransactionBatch(updates) {
         }, { retries: 2, backoffMs: 200 }));
         const succeeded = [];
         const failed = [];
+        const deadlineMs = config.ACTUAL_OP_TIMEOUT_MS > 0 ? config.ACTUAL_OP_TIMEOUT_MS * BUDGET_BATCH_DEADLINE_FRACTION : 0;
         for (const [position, { id, fields }] of updates.entries()) {
             if (!existing.has(id)) {
                 failed.push({ id, error: `Transaction "${id}" not found. Use actual_transactions_get to list transactions.` });
                 continue;
             }
+            if (deadlineMs > 0 && Date.now() - startedAt > deadlineMs) {
+                failed.push({ id, error: BUDGET_BATCH_DEADLINE_ERROR });
+                continue;
+            }
             try {
                 await withConcurrency(() => retry(() => rawUpdateTransaction(id, fields), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
                 succeeded.push({ id });

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

@@ -0,0 +1,63 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findRootPackageJson } from './node-version-guard.js';
+/**
+ * #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.
+ *
+ * A build-time `VERSION` (set by the Docker build arg and by CI) wins. Otherwise a
+ * developer checkout gets `<package version>-dev-<short hash>` when it is not on `main`.
+ *
+ * Git runs only when `.git` exists AT the package root, and always with that root as its
+ * cwd. The published npm package has no `.git`, and without that check `git rev-parse`
+ * would walk up from an install under some other repository (a consumer's node_modules)
+ * and report THAT repository's branch and hash. `existsSync` also accepts the `.git` FILE
+ * of a worktree or submodule.
+ */
+export function resolveMcpServerVersion(baseVersion, env, root, runGit) {
+    if (env.VERSION && env.VERSION !== 'unknown')
+        return env.VERSION;
+    // #546: no manifest was found, so there is no version to qualify; 'unknown-dev-<hash>'
+    // would read as a real one.
+    if (baseVersion === 'unknown')
+        return baseVersion;
+    if (!existsSync(join(root, '.git')))
+        return baseVersion;
+    try {
+        const branch = runGit(['rev-parse', '--abbrev-ref', 'HEAD']);
+        const hash = runGit(['rev-parse', '--short', 'HEAD']);
+        if (!hash)
+            return baseVersion;
+        // A detached HEAD reports 'HEAD', which is not main, so it gets the suffix too.
+        return branch !== 'main' ? `${baseVersion}-dev-${hash}` : baseVersion;
+    }
+    catch {
+        // Git missing, not a repository, or the timeout fired: report the plain version.
+        return baseVersion;
+    }
+}
+let cached;
+/**
+ * This package's (the MCP server's) version, computed once per process. Unrelated to the
+ * adapter's `getServerVersion()`, which returns the ACTUAL BUDGET server version.
+ */
+export function getMcpServerVersion() {
+    if (cached !== undefined)
+        return cached;
+    // dist/src/lib/ to the package root. This one root is both the `.git` check directory
+    // and git's cwd; never process.cwd(), which is wherever the server was started from.
+    const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+    const base = findRootPackageJson(root)?.version ?? 'unknown';
+    // stderr is discarded so a "not a git repository" line never reaches the stdio channel
+    // or the log, and the timeout keeps a hung git from blocking startup.
+    const runGit = (args) => execFileSync('git', args, {
+        cwd: root,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 2000,
+    }).trim();
+    cached = resolveMcpServerVersion(base, process.env, root, runGit);
+    return cached;
+}

package/dist/src/lib/transportErrorLogger.js

@@ -14,10 +14,12 @@
 import { createModuleLogger } from './loggerFactory.js';
 const MAX_DETAIL_CODE_POINTS = 200;
 const CUT_CHARS = /[{["'`]/;
-// Control (C0, C1), line/paragraph separators and bidi format characters. Written with
-// escapes, as src/logger.ts does: a raw U+2028 in source would terminate the literal.
+// Control (C0, C1), line/paragraph separators, bidi format characters, and (#535) the
+// invisible marks that can hide or reorder text in a log line: the Arabic letter mark,
+// zero-width space/joiners, LRM/RLM and the BOM. Written with escapes, as src/logger.ts
+// does: a raw U+2028 in source would terminate the literal.
 // eslint-disable-next-line no-control-regex
-const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g;
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/g;
 const OMITTED = '[payload omitted]';
 /** Pure: turn an arbitrary thrown value into a bounded, payload-free, single-line string. */
 export function sanitizeTransportErrorDetail(value) {

package/dist/src/server/httpErrorHandler.js

@@ -28,11 +28,15 @@ 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.
+ *
+ * #545: compared case-insensitively, because this server never enables Express's
+ * `case sensitive routing`, so `/MCP` reaches the MCP route and must get its envelope too.
  */
 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;
+    const pathname = (q === -1 ? originalUrl : originalUrl.slice(0, q)).toLowerCase();
+    const lowered = mcpPath.toLowerCase();
+    const base = lowered.length > 1 && lowered.endsWith('/') ? lowered.slice(0, -1) : lowered;
     // A root MCP path ('/') makes every request an MCP request.
     if (base === '/' || base === '')
         return true;

package/dist/src/tools/rules_create_or_update.js

@@ -15,7 +15,8 @@
  *
  * Adapted for this project's conventions:
  * - No wrapToolCall: uses the direct call() pattern
- * - Reuses the exact same ConditionSchema / ActionSchema / FIELD_OPERATORS as rules_create.ts
+ * - Shares ConditionSchema with rules_create.ts (src/lib/schemas/rules.ts); ActionSchema and the
+ *   FIELD_OPERATORS map are private copies of the same shape (#540 found them identical)
  *
  * #376: the read-match-write cycle lives in `adapter.upsertRule` (identity rules in
  * `src/lib/rule-matching.ts`). This tool owns the schema, the operator/UUID validation and

package/dist/src/tools/server_info.js

@@ -4,40 +4,23 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import actualToolsManager from '../actualToolsManager.js';
 import { INSTALLED_API_VERSION, resolveInstalledVersion } from '../lib/installed-api-version.js';
+import { getMcpServerVersion } from '../lib/mcp-version.js';
 /** Resolved once at module load, not per call: the walk does blocking file reads
  *  and this tool can be called in a loop. The SDK exports no root path, so the
  *  resolvable subpath is passed explicitly (#445). */
 const MCP_SDK_RESOLVED = resolveInstalledVersion('@modelcontextprotocol/sdk', '@modelcontextprotocol/sdk/server/index.js');
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-// Read version from environment variable (set during Docker build) or package.json
+// Name, description and declared dependencies come from package.json. The version does
+// NOT: it comes from getMcpServerVersion() at call time (#541), so it matches the MCP
+// initialize version and importing the tool registry never spawns git.
 let packageInfo;
 try {
     const packagePath = join(__dirname, '../../../package.json');
-    const packageJson = readFileSync(packagePath, 'utf-8');
-    packageInfo = JSON.parse(packageJson);
-    // Use VERSION environment variable if available (set by Docker build or CI/CD)
-    // This includes development metadata like: 0.2.4-dev-abc1234
-    if (process.env.VERSION && process.env.VERSION !== 'unknown') {
-        packageInfo.version = process.env.VERSION;
-    }
-    else {
-        // Fallback: Try to append git commit hash for local development builds
-        try {
-            const { execSync } = require('child_process');
-            const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8', cwd: join(__dirname, '../../..') }).trim();
-            const commitHash = execSync('git rev-parse --short HEAD', { encoding: 'utf8', cwd: join(__dirname, '../../..') }).trim();
-            if (branch === 'develop' || branch === 'development' || branch !== 'main') {
-                packageInfo.version = `${packageInfo.version}-dev-${commitHash}`;
-            }
-        }
-        catch (gitErr) {
-            // Git not available or not in a git repo, use package.json version as-is
-        }
-    }
+    packageInfo = JSON.parse(readFileSync(packagePath, 'utf-8'));
 }
 catch (error) {
-    packageInfo = { version: 'unknown', name: 'actual-mcp-server', description: 'MCP server for Actual Budget' };
+    packageInfo = { name: 'actual-mcp-server', description: 'MCP server for Actual Budget' };
 }
 const InputSchema = z.object({}).strict();
 const tool = {
@@ -61,7 +44,7 @@ Use this to check server status, verify version compatibility, or debug issues.`
         return {
             server: {
                 name: packageInfo.name,
-                version: packageInfo.version,
+                version: getMcpServerVersion(),
                 description: packageInfo.description,
                 transport: process.env.MCP_STDIO_MODE === 'true' ? 'stdio' : 'http',
             },

package/dist/src/tools/transactions_update_batch.js

@@ -37,7 +37,7 @@ const InputSchema = z.object({
 });
 const tool = {
     name: 'actual_transactions_update_batch',
-    description: `Update multiple transactions in a single call. Accepts up to 50 {id, fields} pairs. Each update is applied independently and NOT atomically: items applied before a failure stay applied. A missing id or an update Actual rejects is reported per item in failed, and the rest continue. If the call itself fails (lost connection, out of memory, timeout), the error names the ids already applied; read the transactions back with actual_transactions_get BEFORE retrying. Splits are not supported here: a subtransactions field is ignored in batch. Use actual_transactions_update to edit an existing split's children.
+    description: `Update multiple transactions in a single call. Accepts up to 50 {id, fields} pairs. Each update is applied independently and NOT atomically: items applied before a failure stay applied. A missing id or an update Actual rejects is reported per item in failed, and the rest continue. If the call itself fails (lost connection, out of memory, timeout), the error names the ids already applied; read the transactions back with actual_transactions_get BEFORE retrying. An item whose error says "not attempted" was never sent, because the batch ran out of time; read back before retrying it too, since others may have been applied. Splits are not supported here: a subtransactions field is ignored in batch. Use actual_transactions_update to edit an existing split's children.
 
 Returns: { succeeded: [{id}], failed: [{id, error}], total, successCount, failureCount }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.22.22",
+  "version": "0.22.25",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"