actual-mcp-server 0.8.9 → 0.8.11

package/README.md

@@ -722,4 +722,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.8.9 | **Tool Count:** 71 (verified LibreChat-compatible)
+**Version:** 0.8.11 | **Tool Count:** 71 (verified LibreChat-compatible)

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

@@ -12,6 +12,7 @@ import { retry, isRetryableError } from './retry.js';
 import { withOpTimeout } from './opTimeout.js';
 import { notFoundMsg } from './errors.js';
 import logger from '../logger.js';
+import { checkServerVersionOnce } from './server-version-guard.js';
 import config from '../config.js';
 import { parseBudgetRegistry } from './budget-registry.js';
 import { getPreferredBudgetSyncId, setPreferredBudgetSyncId, pickAllowedPreferredBudget } from './budget-preference-store.js';
@@ -229,11 +230,21 @@ function _enforceBudgetAcl(toolName) {
  * In either mode `withApiLock` serialises against concurrent callers because
  * `@actual-app/api` is a process-wide singleton.
  */
-export async function withActualApi(operation) {
+export async function withActualApi(rawOperation) {
     // ACL enforcement BEFORE pool branching or lock acquisition (#156).
     // Denial here means the lock is never acquired and no upstream resource is
     // touched.
     _enforceBudgetAcl();
+    // #276: on the FIRST successful op, warn (once) if the Actual server version is outside
+    // the range this build supports. It runs inside the op while the connection is live and
+    // reuses it via rawGetServerVersion (NOT the withActualApi-wrapped getServerVersion, which
+    // would re-enter the lock). The once-guard flips its flag synchronously, so this never
+    // repeats per session or op. It is advisory: it never throws and never blocks the op.
+    const operation = async () => {
+        const result = await rawOperation();
+        await checkServerVersionOnce(() => rawGetServerVersion(), logger);
+        return result;
+    };
     const sessionId = _resolveSessionId();
     if (_hasPooledConnection(sessionId)) {
         // Pooled mode: skip init+shutdown.
@@ -1350,14 +1361,46 @@ export async function mergePayees(targetId, mergeIds) {
         await withConcurrency(() => retry(() => rawMergePayees(targetId, mergeIds), { retries: 0, backoffMs: 200 }));
     });
 }
+/**
+ * Does a serialized Actual rule reference this payee? The payee id lives INSIDE a
+ * condition or action whose `field` is 'payee': as `value` (op 'is'/'isNot') or as
+ * a member of `value` (op 'oneOf', an array). A serialized rule has NO top-level
+ * `payee_id` column, so the original BUG-3 post-filter (`r.payee_id === payeeId`)
+ * matched nothing and made actual_payee_rules_get always return empty. This mirrors
+ * `@actual-app/api`'s own getRulesForPayee, which scans payee-typed ids in the rule.
+ */
+export function ruleReferencesPayee(rule, payeeId) {
+    const r = rule;
+    const clauses = [
+        ...(Array.isArray(r?.conditions) ? r.conditions : []),
+        ...(Array.isArray(r?.actions) ? r.actions : []),
+    ];
+    return clauses.some((c) => {
+        if (c?.field !== 'payee')
+            return false;
+        return Array.isArray(c.value) ? c.value.includes(payeeId) : c?.value === payeeId;
+    });
+}
 export async function getPayeeRules(payeeId) {
     return withActualApi(async () => {
         observability.incrementToolCall('actual.payees.getPayeeRules').catch(() => { });
         const allRules = await withConcurrency(() => retry(() => rawGetPayeeRules(payeeId), { retries: 2, backoffMs: 200 }));
         if (!Array.isArray(allRules))
             return [];
-        // API ignores payeeId filter — apply post-filter (BUG-3)
-        return allRules.filter((r) => r?.payee_id === payeeId);
+        // Defensive narrowing to the requested payee. @actual-app/api already scopes
+        // payee-rules-get to the id; the filter must use the real rule shape (payee
+        // referenced in a condition/action), NOT a nonexistent `payee_id` column.
+        const filtered = allRules.filter((r) => ruleReferencesPayee(r, payeeId));
+        // Upstream already scopes to the payee, so this filter should be a no-op. If it
+        // ever drops rows, the serialized rule shape has drifted and the predicate is now
+        // silently under-matching: exactly the failure class that made #284 return empty
+        // for months. Surface it instead of hiding it.
+        if (filtered.length !== allRules.length) {
+            logger.debug('[ADAPTER] getPayeeRules post-filter dropped rows; rule shape may have drifted', {
+                payeeId, upstream: allRules.length, kept: filtered.length,
+            });
+        }
+        return filtered;
     });
 }
 export async function batchBudgetUpdates(fn) {

package/dist/src/lib/constants.js

@@ -81,3 +81,21 @@ export const MONTH_PATTERN = /^\d{4}-\d{2}$/;
  * UUID pattern for ID validation
  */
 export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * #276: the Actual Budget SERVER version range this build's `@actual-app/api` is known
+ * to work with. HAND-MAINTAINED: `@actual-app/api` v26 exposes no supported-server range
+ * (verified: getServerVersion just proxies the server's build.version), so there is no
+ * upstream fact to derive this from and no #275-style drift guard is possible.
+ *
+ * UPDATE THIS when bumping `@actual-app/api`: set `minVersion` to the oldest server the new
+ * client supports, and `testedMaxMajor` to the newest server major it has been tested
+ * against. The check is ADVISORY only (the real compatibility contract is the migration
+ * check `@actual-app/api` runs at downloadBudget), so a wrong value here can at most produce
+ * a spurious or missing warning, never a broken deployment.
+ */
+export const SUPPORTED_ACTUAL_SERVER_RANGE = {
+    /** Oldest server version this client supports. Below this: "too old" warning. */
+    minVersion: '25.0.0',
+    /** Newest server MAJOR tested against `@actual-app/api` v26. Above this: "newer than tested". */
+    testedMaxMajor: 26,
+};

package/dist/src/lib/server-version-guard.js

@@ -0,0 +1,105 @@
+/**
+ * #276: warn (once) when the Actual Budget SERVER version is outside the range this build's
+ * `@actual-app/api` is known to work with.
+ *
+ * Reporting already existed (actual_server_get_version, actual_server_info) but nothing
+ * enforced or even flagged compatibility. This adds an ADVISORY startup-ish warning: the
+ * real compatibility contract is the migration check `@actual-app/api` runs at
+ * downloadBudget, so this warning never fails startup and never blocks an operation.
+ *
+ * Design (mirrors src/lib/node-version-guard.ts):
+ *  - The comparator is PURE (no I/O, no logging), so its truth table is unit-testable.
+ *  - It FAILS OPEN: an unparseable version produces no warning. A spurious warning on a
+ *    healthy deployment would be worse than staying quiet.
+ *  - The firing is a per-PROCESS once-guard: the flag is flipped SYNCHRONOUSLY before any
+ *    await, so the check runs exactly once no matter how many ops or sessions occur, and it
+ *    reuses the connection the triggering op already established (no extra auth burst,
+ *    avoiding the #127/#134 class). There is NO boot-time probe: index.ts deliberately has
+ *    no startup connection, and a naive boot call would double-init then be torn down by
+ *    shutdownActualApi.
+ */
+import { SUPPORTED_ACTUAL_SERVER_RANGE } from './constants.js';
+/** Parse `26.7.0` (or `v26.7.0`) into `[26, 7, 0]`. Returns null when unparseable. */
+export function parseVersion(v) {
+    if (typeof v !== 'string')
+        return null;
+    const m = /^v?(\d+)\.(\d+)(?:\.(\d+))?/.exec(v.trim());
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)];
+}
+/** a < b as semver triples. */
+function lessThan(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i];
+    }
+    return false;
+}
+/**
+ * Pure. Compare a running server version against the supported range.
+ * FAILS OPEN on anything unparseable (returns ok:true, no message), so a version string we
+ * did not anticipate never produces a false warning.
+ */
+export function checkServerVersion(running, range = SUPPORTED_ACTUAL_SERVER_RANGE) {
+    const have = parseVersion(running);
+    const min = parseVersion(range.minVersion);
+    if (!have || !min)
+        return { ok: true };
+    if (lessThan(have, min)) {
+        return {
+            ok: false,
+            message: `Actual Budget server ${running} is older than the minimum this build supports ` +
+                `(>= ${range.minVersion}). Some tools may misbehave. Upgrade the Actual Budget server, ` +
+                'or pin an older actual-mcp-server. This is advisory: the server, not this warning, ' +
+                'enforces compatibility at budget download.',
+        };
+    }
+    if (have[0] > range.testedMaxMajor) {
+        return {
+            ok: false,
+            message: `Actual Budget server ${running} is newer than this build was tested against ` +
+                `(tested up to major ${range.testedMaxMajor}.x). It will very likely work, but if a ` +
+                'tool behaves oddly, update actual-mcp-server. Advisory only.',
+        };
+    }
+    return { ok: true };
+}
+// ---------------------------------------------------------------------------
+// Per-process once-guard.
+// ---------------------------------------------------------------------------
+let checked = false;
+/**
+ * Run the compatibility check at most once per process. Call this from inside a successful
+ * `withActualApi` operation (while the connection is live), passing a function that reads the
+ * server version through the SAME live connection (rawGetServerVersion, not the withActualApi
+ * wrapped getServerVersion, to avoid re-entering the lock).
+ *
+ * NEVER throws. A read failure is a single `debug`; being outside the range is a single
+ * `warn`; being in range is silent. The `log` argument is the module logger so all output
+ * goes through the redaction-protected logger (never console.*), keeping stdio framing intact.
+ */
+export async function checkServerVersionOnce(readVersion, log) {
+    if (checked)
+        return;
+    checked = true; // set synchronously, before any await, so a concurrent op cannot double-fire
+    try {
+        const result = await readVersion();
+        if (!result || 'error' in result || typeof result.version !== 'string') {
+            log.debug('[server-version] could not read the Actual server version; skipping the compatibility check');
+            return;
+        }
+        const verdict = checkServerVersion(result.version);
+        if (!verdict.ok && verdict.message) {
+            log.warn(verdict.message);
+        }
+    }
+    catch {
+        // Advisory only: a failure to check must never surface as an error or affect the op.
+        log.debug('[server-version] compatibility check threw; ignored');
+    }
+}
+/** Test-only: reset the once-guard between cases. */
+export function _resetForTests() {
+    checked = false;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.8.9",
+  "version": "0.8.11",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/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/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.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/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/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/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.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/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js",
     "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",