actual-mcp-server 0.6.40 → 0.6.42

package/README.md

@@ -750,4 +750,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.40 | **Tool Count:** 70 (verified LibreChat-compatible)
+**Version:** 0.6.42 | **Tool Count:** 70 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.40",
+    "version": "0.6.42",
     "engines": {
         "node": ">=20.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_insecure_upstream.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_body_limit.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/check_coverage.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_insecure_upstream.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_body_limit.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/check_coverage.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",

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

@@ -1010,6 +1010,18 @@ export async function updateTransaction(id, fields) {
     observability.incrementToolCall('actual.transactions.update').catch(() => { });
     // Use write queue to batch concurrent updates in a single budget session
     return queueWriteOperation(async () => {
+        // Pre-flight existence check (#212): the raw API silently no-ops on a missing id,
+        // so an update that changed nothing would otherwise be reported as success. A
+        // targeted ActualQL query by id keeps this cheap (indexed lookup).
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { q } = (await import('@actual-app/api'));
+        const found = await withConcurrency(() => retry(async () => {
+            const res = (await rawRunQuery(q('transactions').filter({ id }).select(['id'])));
+            return Array.isArray(res?.data) && res.data.length > 0;
+        }, { retries: 2, backoffMs: 200 }));
+        if (!found) {
+            throw new Error(`Transaction "${id}" not found. Use actual_transactions_get to list transactions.`);
+        }
         await withConcurrency(() => retry(() => rawUpdateTransaction(id, fields), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
@@ -1019,9 +1031,27 @@ export async function updateTransactionBatch(updates) {
     // Sequential loop (not Promise.all) is intentional: concurrent rawUpdateTransaction calls
     // within one session can interleave withMutation CRDT messages unpredictably.
     return queueWriteOperation(async () => {
+        // 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)
+            return { succeeded: [], failed: [] };
+        // Pre-flight existence check (#212): ONE query for all ids (not one per item),
+        // since the raw API silently no-ops on a missing id and would otherwise report
+        // a no-op as success. Missing ids are routed to failed[] without an update call.
+        const ids = updates.map((u) => u.id);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { q } = (await import('@actual-app/api'));
+        const existing = await withConcurrency(() => retry(async () => {
+            const res = (await rawRunQuery(q('transactions').filter({ id: { $oneof: ids } }).select(['id'])));
+            return new Set(Array.isArray(res?.data) ? res.data.map((r) => r.id) : []);
+        }, { retries: 2, backoffMs: 200 }));
         const succeeded = [];
         const failed = [];
         for (const { id, fields } of updates) {
+            if (!existing.has(id)) {
+                failed.push({ id, error: `Transaction "${id}" not found. Use actual_transactions_get to list transactions.` });
+                continue;
+            }
             try {
                 await withConcurrency(() => retry(() => rawUpdateTransaction(id, fields), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
                 succeeded.push({ id });
@@ -1037,6 +1067,18 @@ export async function updateTransactionBatch(updates) {
 export async function deleteTransaction(id) {
     observability.incrementToolCall('actual.transactions.delete').catch(() => { });
     return queueWriteOperation(async () => {
+        // Pre-flight existence check: the raw API silently no-ops on a missing id and would
+        // otherwise report success for a delete that removed nothing. A targeted ActualQL
+        // query by id keeps this cheap (indexed lookup, not a full-table scan).
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { q } = (await import('@actual-app/api'));
+        const found = await withConcurrency(() => retry(async () => {
+            const res = (await rawRunQuery(q('transactions').filter({ id }).select(['id'])));
+            return Array.isArray(res?.data) && res.data.length > 0;
+        }, { retries: 2, backoffMs: 200 }));
+        if (!found) {
+            throw new Error(`Transaction "${id}" not found. Use actual_transactions_get to list transactions.`);
+        }
         // Non-idempotent: do not retry (#165). A retry after a lost-response would
         // re-issue the delete against an already-removed record and surface a
         // confusing "not found" even though the first attempt succeeded.

package/dist/src/tools/category_groups_delete.js

@@ -20,10 +20,9 @@ const tool = {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const groupExists = groups.some((g) => g.id === input.id);
             if (!groupExists) {
-                return {
-                    error: notFoundMsg('Category group', input.id, 'actual_category_groups_get'),
-                    success: false,
-                };
+                // Throw (not return {success:false}) so a non-existent id surfaces as an MCP
+                // error, consistent with every other delete tool's not-found behavior.
+                throw new Error(notFoundMsg('Category group', input.id, 'actual_category_groups_get'));
             }
             await rawDeleteCategoryGroup(input.id);
             return { success: true };

package/dist/src/tools/payees_delete.js

@@ -1,8 +1,5 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
-import api from '@actual-app/api';
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const { deletePayee: rawDeletePayee } = api;
 const InputSchema = z.object({
     id: z.string().describe('Payee ID to delete'),
 });
@@ -12,12 +9,13 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Single-write tool, but uses withWriteSession for consistency with the other
-        // delete tools and to share the same lock-cycle invariant (#142).
-        return await adapter.withWriteSession(async () => {
-            await rawDeletePayee(input.id);
-            return { success: true };
-        });
+        // Route through the guarded adapter method (pre-flight existence check), not the
+        // raw api.deletePayee. The raw call throws a cryptic "Cannot destructure property
+        // 'transfer_acct' of null" on a non-existent id; adapter.deletePayee returns an
+        // actionable "Payee not found" instead. adapter.deletePayee already runs inside a
+        // single write-queue cycle, preserving the #142 lock invariant.
+        await adapter.deletePayee(input.id);
+        return { success: true };
     },
 };
 export default tool;

package/dist/src/tools/rules_delete.js

@@ -20,10 +20,9 @@ const tool = {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const ruleExists = allRules.some((r) => r.id === input.id);
             if (!ruleExists) {
-                return {
-                    error: notFoundMsg('Rule', input.id, 'actual_rules_get'),
-                    success: false,
-                };
+                // Throw (not return {success:false}) so a non-existent id surfaces as an MCP
+                // error, consistent with every other delete tool's not-found behavior.
+                throw new Error(notFoundMsg('Rule', input.id, 'actual_rules_get'));
             }
             await rawDeleteRule(input.id);
             return { success: true };

package/dist/src/tools/schedules_delete.js

@@ -23,10 +23,9 @@ const tool = {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const scheduleExists = schedules.some((s) => s.id === input.id);
             if (!scheduleExists) {
-                return {
-                    error: notFoundMsg('Schedule', input.id, 'actual_schedules_get'),
-                    success: false,
-                };
+                // Throw (not return {success:false}) so a non-existent id surfaces as an MCP
+                // error, consistent with every other delete tool's not-found behavior.
+                throw new Error(notFoundMsg('Schedule', input.id, 'actual_schedules_get'));
             }
             try {
                 await rawDeleteSchedule(input.id);
@@ -35,10 +34,9 @@ const tool = {
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
                 if (msg.includes('NOT NULL constraint') || msg.includes('messages_crdt')) {
-                    return {
-                        error: constraintErrorMsg('Schedule', input.id, 'actual_schedules_get'),
-                        success: false,
-                    };
+                    // Translate the raw SQLite constraint error into an actionable message, thrown
+                    // for the same consistency reason as the not-found case above.
+                    throw new Error(constraintErrorMsg('Schedule', input.id, 'actual_schedules_get'));
                 }
                 throw err;
             }

package/dist/src/tools/transactions_delete.js

@@ -6,9 +6,8 @@ const InputSchema = z.object({
 const tool = {
     name: 'actual_transactions_delete',
     description: 'Delete a transaction from Actual Budget by its ID. ' +
-        'Note: if the transaction does not exist, the call will still return { success: true } ' +
-        'because the Actual Budget API does not distinguish between a successful delete and a no-op. ' +
-        'Use actual_transactions_filter to verify the transaction exists before deleting. ' +
+        'If the transaction does not exist, the call returns an actionable "not found" error ' +
+        '(the adapter verifies existence first, since the raw Actual Budget API silently no-ops on a missing id). ' +
         'This permanently removes the transaction and updates account balances accordingly. This operation cannot be undone.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {

package/dist/src/tools/transactions_update_batch.js

@@ -8,7 +8,7 @@
  * Credit: ZanzyTHEbar (https://github.com/ZanzyTHEbar)
  *
  * Adapted for this project's conventions:
- * - No wrapToolCall — uses direct call() pattern
+ * - No wrapToolCall: uses direct call() pattern
  * - Returns a plain BatchResult object (no { result } wrapper)
  */
 import { z } from 'zod';
@@ -36,7 +36,7 @@ const InputSchema = z.object({
 });
 const tool = {
     name: 'actual_transactions_update_batch',
-    description: `Update multiple transactions in a single call. Accepts up to 100 {id, fields} pairs. Each update is applied independently — partial failures are reported per-item so you know exactly which succeeded and which failed.
+    description: `Update multiple transactions in a single call. Accepts up to 50 {id, fields} pairs. Each update is applied independently: partial failures are reported per-item so you know exactly which succeeded and which failed.
 
 Returns: { succeeded: [{id}], failed: [{id, error}], total, successCount, failureCount }
 
@@ -45,7 +45,7 @@ Example: { updates: [{ id: "txn-uuid-1", fields: { category: "cat-uuid" } }, { i
     call: async (args, _meta) => {
         try {
             const input = InputSchema.parse(args || {});
-            // Single adapter call — all updates share one init/sync/shutdown cycle (fixes issue #79).
+            // Single adapter call: all updates share one init/sync/shutdown cycle (fixes issue #79).
             // Calling adapter.updateTransaction() in a loop would trigger N separate budget sessions.
             const { succeeded, failed } = await adapter.updateTransactionBatch(input.updates);
             const result = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.40",
+  "version": "0.6.42",
   "engines": {
     "node": ">=20.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_insecure_upstream.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_body_limit.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/check_coverage.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_insecure_upstream.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_body_limit.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/check_coverage.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",