actual-mcp-server 0.6.41 → 0.6.43

package/README.md

@@ -396,13 +396,14 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 `actual_budget_updates_batch`: batch multiple budget updates in one call
 
-### Server Information & Lookup (3)
+### Server Information & Lookup (4)
 
 | Tool | Description |
 |------|-------------|
 | `actual_server_info` | Server status, version, build info |
 | `actual_server_get_version` | Actual Budget server version |
-| `actual_get_id_by_name` | Resolve name → UUID for accounts, categories, payees |
+| `actual_get_id_by_name` | Resolve an exact name → UUID for accounts, categories, payees |
+| `actual_entities_search` | Find accounts/categories/payees by a name pattern (contains/startsWith/endsWith/exact/fuzzy). Fixes "payee not found" from a partial or mistyped name |
 
 ### Session Management (2)
 
@@ -750,4 +751,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.41 | **Tool Count:** 70 (verified LibreChat-compatible)
+**Version:** 0.6.43 | **Tool Count:** 71 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,12 +1,12 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.41",
+    "version": "0.6.43",
     "engines": {
         "node": ">=20.0.0",
         "npm": ">=10.0.0"
     },
-    "description": "MCP server with 70 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+    "description": "MCP server with 71 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
     "homepage": "https://github.com/agigante80/actual-mcp-server#readme",
     "repository": {
         "type": "git",
@@ -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/entities_search.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",
@@ -62,6 +62,7 @@
         "debug": "^4.4.3",
         "dotenv": "^17.4.2",
         "express": "^5.2.1",
+        "fuse.js": "^7.4.2",
         "jose": "^6.2.3",
         "mcp-auth": "^0.2.0",
         "winston": "^3.18.3",

package/dist/src/actualToolsManager.js

@@ -66,6 +66,7 @@ const IMPLEMENTED_TOOLS = [
     'actual_session_close',
     'actual_session_list',
     'actual_get_id_by_name',
+    'actual_entities_search',
     'actual_server_get_version',
     'actual_tags_list',
     'actual_tags_create',

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 });

package/dist/src/tools/entities_search.js

@@ -0,0 +1,100 @@
+import Fuse from 'fuse.js';
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+/**
+ * actual_entities_search (#204)
+ *
+ * Find payees, categories, or accounts by a NAME pattern, so an AI can resolve a
+ * partial or mistyped name (the common "payee not found" failure) without knowing
+ * the exact string. Read-only.
+ *
+ * matchType: contains (default) | startsWith | endsWith | exact are case-insensitive
+ * native string ops; fuzzy is typo-tolerant via Fuse.js (a maintained, zero-dependency
+ * library, chosen over a hand-rolled Levenshtein). Regex is intentionally out of scope
+ * (separate Phase 2 ticket: ReDoS attack surface).
+ *
+ * On no match the tool returns `{ matches: [], count: 0 }` (never an error): an empty
+ * result is a valid "found nothing" signal that lets the AI retry with a broader
+ * matchType (e.g. switch `contains` to `fuzzy`).
+ */
+const ENTITY_TYPES = ['accounts', 'categories', 'payees'];
+const FETCH = {
+    accounts: () => adapter.getAccounts(),
+    categories: () => adapter.getCategories(),
+    payees: () => adapter.getPayees(),
+};
+const schema = z.object({
+    type: z.enum(ENTITY_TYPES).describe('Entity type to search: accounts, categories, or payees.'),
+    query: z
+        .union([z.string().trim().min(1), z.array(z.string().trim().min(1)).min(1)])
+        .describe('Name pattern to match. A single string, or an array of strings (matches if ANY pattern matches).'),
+    matchType: z
+        .enum(['contains', 'startsWith', 'endsWith', 'exact', 'fuzzy'])
+        .default('contains')
+        .describe('contains (default), startsWith, endsWith, exact (all case-insensitive), or fuzzy (typo-tolerant). Regex is not supported.'),
+    limit: z.number().int().min(1).max(100).default(10).describe('Maximum number of matches to return (1 to 100, default 10).'),
+});
+export default createTool({
+    name: 'actual_entities_search',
+    description: 'Find accounts, categories, or payees by a name pattern. Use this to resolve a partial or mistyped name to its entity (the fix for "payee not found"). ' +
+        'matchType: contains (default), startsWith, endsWith, exact (all case-insensitive), or fuzzy (typo-tolerant, e.g. "amzon" matches "Amazon.com"). ' +
+        'query may be a single string or an array (matches if ANY matches). Read-only. ' +
+        'On no match it returns { matches: [], count: 0 } (not an error): retry with a broader matchType such as fuzzy.',
+    schema,
+    examples: [
+        { description: 'Find the payee for a partial name', input: { type: 'payees', query: 'amazon', matchType: 'contains', limit: 10 } },
+        { description: 'Typo-tolerant payee lookup', input: { type: 'payees', query: 'amzon', matchType: 'fuzzy', limit: 10 } },
+        { description: 'Categories starting with "Gro"', input: { type: 'categories', query: 'gro', matchType: 'startsWith', limit: 10 } },
+    ],
+    handler: async (input) => {
+        const { type, matchType, limit } = input;
+        const patterns = (Array.isArray(input.query) ? input.query : [input.query]).map((p) => p.trim());
+        const raw = (await FETCH[type]());
+        // Only entities with a usable string name can be matched (some payees have null names).
+        const entities = raw.filter((e) => typeof e?.name === 'string' && e.name.length > 0);
+        let matches;
+        if (matchType === 'fuzzy') {
+            const fuse = new Fuse(entities, {
+                keys: ['name'],
+                includeScore: true,
+                threshold: 0.4,
+                ignoreLocation: true,
+                minMatchCharLength: 1,
+            });
+            // Multi-pattern OR: search each pattern, keep the best (lowest) score per entity.
+            const bestById = new Map();
+            for (const pattern of patterns) {
+                for (const r of fuse.search(pattern)) {
+                    const score = typeof r.score === 'number' ? r.score : 1;
+                    const prev = bestById.get(r.item.id);
+                    if (!prev || score < (prev.score ?? 1)) {
+                        bestById.set(r.item.id, { id: r.item.id, name: r.item.name, score: Math.round(score * 1000) / 1000 });
+                    }
+                }
+            }
+            matches = [...bestById.values()].sort((a, b) => (a.score ?? 1) - (b.score ?? 1));
+        }
+        else {
+            const needles = patterns.map((p) => p.toLowerCase());
+            const test = (name) => {
+                const n = name.toLowerCase();
+                return needles.some((q) => {
+                    switch (matchType) {
+                        case 'startsWith': return n.startsWith(q);
+                        case 'endsWith': return n.endsWith(q);
+                        case 'exact': return n === q;
+                        case 'contains':
+                        default: return n.includes(q);
+                    }
+                });
+            };
+            matches = entities
+                .filter((e) => test(e.name))
+                .map((e) => ({ id: e.id, name: e.name }))
+                .sort((a, b) => a.name.localeCompare(b.name));
+        }
+        const limited = matches.slice(0, limit);
+        return { matches: limited, count: limited.length, type, matchType };
+    },
+});

package/dist/src/tools/index.js

@@ -1,4 +1,5 @@
 // Auto-generated index for all tool modules
+export { default as entities_search } from './entities_search.js';
 export { default as accounts_close } from './accounts_close.js';
 export { default as accounts_create } from './accounts_create.js';
 export { default as accounts_delete } from './accounts_delete.js';

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,12 +1,12 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.41",
+  "version": "0.6.43",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"
   },
-  "description": "MCP server with 70 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
+  "description": "MCP server with 71 tools for AI-driven financial management with Actual Budget. HTTP and stdio transports for LibreChat, Claude Desktop, Cursor, VS Code, Gemini CLI",
   "homepage": "https://github.com/agigante80/actual-mcp-server#readme",
   "repository": {
     "type": "git",
@@ -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/entities_search.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",
@@ -62,6 +62,7 @@
     "debug": "^4.4.3",
     "dotenv": "^17.4.2",
     "express": "^5.2.1",
+    "fuse.js": "^7.4.2",
     "jose": "^6.2.3",
     "mcp-auth": "^0.2.0",
     "winston": "^3.18.3",