actual-mcp-server 0.6.9 → 0.6.11

package/README.md

@@ -33,7 +33,7 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 
 Most Actual Budget MCP implementations are simple stdio bridges designed for single-user, local use with Claude Desktop. This project goes further:
 
-- **62 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, rules, budgets, batch operations, bank sync, and more. Covers 84% of the Actual Budget API.
+- **63 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, rules, budgets, batch operations, bank sync, and more. Covers 84% of the Actual Budget API.
 - **HTTP and stdio transport.** Runs as a real remote server for LibreChat/LobeChat (`--http`), or as a direct local process for Claude Desktop (`--stdio`). No Docker or HTTP server is needed for local use.
 - **6 exclusive ActualQL-powered tools.** Search and summarise transactions by month, amount, category, or payee using Actual Budget's native query engine. Aggregated results, no raw data dumped into the AI context window.
 - **Multi-budget switching at runtime.** Configure multiple budget files and let the AI switch between them mid-conversation with `actual_budgets_switch`.
@@ -730,4 +730,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.9 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.11 | **Tool Count:** 63 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.9",
+    "version": "0.6.11",
     "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/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/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/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",
+        "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/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/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/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",
         "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/index.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { isKnownBenignRejection } from './lib/rejection-allowlist.js';
 // Add global error handlers
 let isHandlingQueryError = false;
 process.on('unhandledRejection', (reason, promise) => {
@@ -9,45 +10,12 @@ process.on('unhandledRejection', (reason, promise) => {
         console.error('Stack:', reason.stack);
     }
     console.error('===========================');
-    // Check if this is a known domain-level error from @actual-app/api
-    // These indicate invalid user input, not server bugs — the error is properly
-    // returned to the caller; if it somehow escapes as an unhandled rejection
-    // we should log but NOT crash the server.
-    const reasonStr = String(reason);
-    const reasonObj = reason;
-    if (reasonStr.includes('does not exist in table') ||
-        (reasonStr.includes('Field') && reasonStr.includes('does not exist')) ||
-        reasonStr.includes('Expression stack') ||
-        reasonStr.includes('Date is required') ||
-        reasonStr.includes('date condition is required') ||
-        reasonStr.includes('Cannot create schedules with the same name') ||
-        reasonStr.includes('Schedule') && reasonStr.includes('not found') ||
-        reasonStr.includes('is system-managed and not user-editable') ||
-        reasonStr.includes('is not an expense category') ||
-        // Bank sync errors from GoCardless/SimpleFIN/Nordigen surface as unhandled
-        // rejections from within the @actual-app/api SDK worker. These are non-fatal:
-        // the caller already received a proper error response (or the retry will).
-        reasonObj?.type === 'BankSyncError' ||
-        reasonStr.includes('BankSyncError') ||
-        reasonStr.includes('NORDIGEN_ERROR') ||
-        reasonStr.includes('RATE_LIMIT_EXCEEDED') ||
-        reasonStr.includes('Rate limit exceeded') ||
-        reasonStr.includes('Failed syncing account') ||
-        reasonStr.includes('GoCardless') ||
-        reasonStr.includes('SimpleFIN') ||
-        // Actual API auth failures (network-failure, too-many-requests, invalid-password,
-        // etc.) can escape as unhandled rejections from session-init code paths that
-        // create a deferred Promise but only conditionally await it (see #132). The
-        // primary fix lives in httpServer.ts (.catch on initPromise); this allow-list
-        // entry is defence-in-depth so any future deferred-promise leak in the same
-        // family also fails non-fatally.
-        reasonStr.includes('Authentication failed:')) {
+    if (isKnownBenignRejection(reason)) {
         console.error('⚠️  Known Actual API domain error escaped to unhandledRejection:');
-        console.error('⚠️  ' + reasonStr);
+        console.error('⚠️  ' + String(reason));
         console.error('⚠️  Server will continue running. The caller received an error response.');
         return;
     }
-    // For all other unhandled rejections, exit
     process.exit(1);
 });
 process.on('uncaughtException', (error) => {

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

@@ -0,0 +1,55 @@
+/**
+ * Predicate for the unhandledRejection allow-list in src/index.ts.
+ *
+ * Returns true when a rejection should be logged but the server should keep
+ * running. Centralised here so it can be unit-tested without importing the
+ * full server entrypoint.
+ */
+export function isKnownBenignRejection(reason) {
+    const reasonStr = String(reason);
+    const reasonObj = reason;
+    return (reasonStr.includes('does not exist in table') ||
+        (reasonStr.includes('Field') && reasonStr.includes('does not exist')) ||
+        reasonStr.includes('Expression stack') ||
+        reasonStr.includes('Date is required') ||
+        reasonStr.includes('date condition is required') ||
+        reasonStr.includes('Cannot create schedules with the same name') ||
+        (reasonStr.includes('Schedule') && reasonStr.includes('not found')) ||
+        reasonStr.includes('is system-managed and not user-editable') ||
+        reasonStr.includes('is not an expense category') ||
+        reasonObj?.type === 'BankSyncError' ||
+        reasonStr.includes('BankSyncError') ||
+        reasonStr.includes('NORDIGEN_ERROR') ||
+        reasonStr.includes('RATE_LIMIT_EXCEEDED') ||
+        reasonStr.includes('Rate limit exceeded') ||
+        reasonStr.includes('Failed syncing account') ||
+        reasonStr.includes('GoCardless') ||
+        reasonStr.includes('SimpleFIN') ||
+        reasonStr.includes('Authentication failed:') ||
+        isActualApiWorkerRejection(reason));
+}
+/**
+ * Rejection that escapes from the @actual-app/api worker's internal cleanup
+ * path. The known trigger is a non-writable MCP_BRIDGE_DATA_DIR causing an
+ * EACCES during budget download, but the same code path emits a secondary
+ * rejection for other internal failures too.
+ *
+ * The secondary rejection is an Error whose only set property is `stack`
+ * (no code/errno/syscall, even non-enumerable, on the rejection itself; those
+ * are on the PRIMARY error which ActualConnectionPool already catches).
+ * Anchoring on the stack alone is therefore the correct signal.
+ *
+ * Two-anchor disjunction:
+ *   - 'download-budget': the precise frame for today's known trigger.
+ *   - '@actual-app/api/dist': the durable path anchor; survives upstream
+ *     handler renames as long as the package is still loaded from a
+ *     conventional npm install path.
+ */
+export function isActualApiWorkerRejection(reason) {
+    if (!reason || typeof reason !== 'object')
+        return false;
+    const stack = reason.stack;
+    if (typeof stack !== 'string')
+        return false;
+    return stack.includes('download-budget') || stack.includes('@actual-app/api/dist');
+}

package/package.json

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