actual-mcp-server 0.22.7 → 0.22.11

package/README.md

@@ -24,13 +24,13 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 ┌─────────────┐   MCP/HTTP    ┌──────────────────┐   Actual API   ┌──────────────┐
 │  LibreChat  │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  LobeChat   │               │  Server          │               │   Budget     │
-│  (remote)   │               │  (81 tools)      │               │   Server     │
+│  (remote)   │               │  (82 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 
 ┌─────────────┐   MCP/stdio   ┌──────────────────┐   Actual API   ┌──────────────┐
 │  Claude     │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  Desktop    │               │  Server          │               │   Budget     │
-│  (local)    │               │  (81 tools)      │               │   Server     │
+│  (local)    │               │  (82 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 ```
 
@@ -38,14 +38,14 @@ 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:
 
-- **81 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
+- **82 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
 - **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`. Works on both transports: HTTP keys the active budget to the MCP session, and stdio (Claude Desktop, Claude Code, Cursor) gets a synthetic per-process session so a switch is scoped to that process rather than shared globally (#348).
 - **Multi-user ready with OIDC.** Secure every session with JWKS-validated JWTs and per-user budget ACLs. No shared tokens required.
 - **Production-grade reliability on both transports.** HTTP connection pooling (up to 15 concurrent sessions), and a long-lived stdio process that logs in ONCE and reuses that connection for every tool call instead of re-authenticating per call, so Claude Desktop and Claude Code stay fast and a burst of calls no longer risks a per-call login storm against the upstream limiter. Automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
 
-> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 81 tools tested end-to-end. Any MCP-compatible client should work.
+> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 82 tools tested end-to-end. Any MCP-compatible client should work.
 
 ---
 
@@ -182,7 +182,7 @@ Add to `claude_desktop_config.json` (see [docs/guides/MCP_CLIENTS_SETUP.md](docs
 }
 ```
 
-> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 81 tools are available.
+> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 82 tools are available.
 >
 > **`MCP_BRIDGE_DATA_DIR` should be an absolute path.** Without one, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.
 
@@ -308,7 +308,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 ## Available Tools
 
-**81 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
+**82 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
 
 ### Accounts (12)
 
@@ -337,10 +337,10 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_transactions_filter` | Filter with advanced criteria |
 | `actual_transactions_create` | Create new transaction(s), including splits (pass a `subtransactions` array) |
 | `actual_transactions_import` | Import and reconcile transactions |
-| `actual_transactions_update` | Update a transaction, or edit the children of an existing split via `subtransactions` |
+| `actual_transactions_update` | Update a transaction, split a plain one in place, or edit the children of an existing split via `subtransactions` |
 | `actual_transactions_delete` | Delete a transaction |
 
-> **Split transactions:** pass a `subtransactions` array (each child needs an `amount` in integer cents; `category` and `notes` are optional). The child amounts must sum to the parent `amount` (the server does not enforce this, so the tool does). A split parent carries no category of its own: put categories on the children. `actual_transactions_update` can edit the children of a transaction that is ALREADY a split; converting a plain transaction into a split via update is not supported (create it as a split instead). Note: `actual_transactions_import` forwards a `subtransactions` array to the API but does NOT apply the sum check, so use `actual_transactions_create` for guaranteed-balanced splits.
+> **Split transactions:** pass a `subtransactions` array (each child needs an `amount` in integer cents; `category` and `notes` are optional). The child amounts must sum to the parent `amount` (the server does not enforce this, so the tool does). A split parent carries no category of its own: put categories on the children. `actual_transactions_update` with `subtransactions` edits the children of a transaction that is already a split, or splits a plain transaction IN PLACE: it keeps its id, `imported_id` and cleared state, so a bank-synced transaction can be split without breaking import matching. Its own category is cleared, and a child that names no category inherits it. A split child cannot itself be split. Note: `actual_transactions_import` forwards a `subtransactions` array to the API but does NOT apply the sum check, so use `actual_transactions_create` for guaranteed-balanced splits.
 
 **Utility (2)**
 
@@ -453,12 +453,13 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 `actual_budget_updates_batch`: batch multiple budget updates in one call
 
-### Server Information & Lookup (4)
+### Server Information & Lookup (5)
 
 | Tool | Description |
 |------|-------------|
 | `actual_server_info` | Server status, version, build info |
 | `actual_server_get_version` | Actual Budget server version |
+| `actual_get_context` | Retrieve open accounts, category groups with nested categories, and payees (name-sorted, capped by `payeeLimit`) in a single call |
 | `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 |
 
@@ -601,7 +602,7 @@ stdio is the simplest way to connect Claude Desktop directly to Actual Budget. T
 - No auth token. Process ownership is the security boundary.
 - All logs go to stderr so they never corrupt the JSON-RPC framing on stdout
 - The process exits when stdin closes (Claude Desktop shutting down)
-- All 81 tools are available, identical to HTTP mode
+- All 82 tools are available, identical to HTTP mode
 
 **Start manually to verify:**
 
@@ -704,7 +705,7 @@ See [AI Client Setup, OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-m
 | Command | What It Tests | Requires Live Server |
 |---------|---------------|---------------------|
 | `npm run build` | TypeScript compilation | No |
-| `npm run test:unit-js` | 81-tool smoke, schema validation, auth ACL | No |
+| `npm run test:unit-js` | 82-tool smoke, schema validation, auth ACL | No |
 | `npm run test:adapter` | Adapter, retry logic, concurrency | No |
 | `npm run test:e2e` | MCP protocol compliance (Playwright) | No |
 | `npm run test:e2e:docker:full` | Full stack integration | Yes (Docker) |
@@ -788,7 +789,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.22.7 | **Tool Count:** 81 (verified LibreChat-compatible)
+**Version:** 0.22.11 | **Tool Count:** 82 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/actualToolsManager.js

@@ -85,6 +85,7 @@ const IMPLEMENTED_TOOLS = [
     'actual_budgets_export',
     'actual_budgets_import',
     'actual_preferences_get',
+    'actual_get_context',
 ];
 // 🔑 Mapping of Actual API function names → your MCP tool names
 // This allows us to compare what exists in the API vs. what it has been wrapped.

package/dist/src/index.js

@@ -5,7 +5,7 @@
 // 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 { dirname } from 'node:path';
+import path, { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import { isKnownBenignRejection } from './lib/rejection-allowlist.js';
@@ -83,10 +83,6 @@ process.on('uncaughtException', (error) => {
 });
 // Minimal early help handling before any side-effectful modules (prevents dotenv from running on --help)
 const argsEarly = process.argv.slice(2);
-// dotenv v17 outputs diagnostic text to stdout by default (console.log).
-// Suppress it unconditionally — in stdio mode stdout is the JSON-RPC channel
-// (non-JSON corrupts the framing), and in other modes the diagnostic is noise.
-process.env.DOTENV_CONFIG_QUIET = 'true';
 // Set MCP_STDIO_MODE before the async IIFE so it is in place when src/logger.ts is first
 // imported. The Winston Console transport reads this env var at construction time to decide
 // whether to route all output to stderr (required in stdio mode — stdout writes corrupt JSON-RPC).
@@ -148,7 +144,24 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
     // Load dotenv here (dynamic import) only when not running with --help
     if (!argsEarly.includes('--help')) {
         const dotenv = await import('dotenv');
-        dotenv.config();
+        // #501: this runs BEFORE ./logger.js hijacks console.*, so anything dotenv prints
+        // lands on the real stdout (the JSON-RPC channel under --stdio) and skips the #220
+        // redaction. Explicit options beat every DOTENV_* environment knob, so each is pinned:
+        // quiet and debug keep both streams empty, override keeps a secret already in the
+        // environment authoritative over the file, encoding stops DOTENV_ENCODING from silently
+        // skipping the file (a bogus value loads nothing and reports it only in the discarded
+        // result), fast keeps DOTENV_FAST from swapping in the alternate parser (no input was
+        // found that the two parse differently, so this pin is defensive rather than tested
+        // by behaviour), and path keeps the cwd-relative .env
+        // that npx, `node dist/src/index.js` and Docker (WORKDIR /app) all rely on.
+        dotenv.config({
+            quiet: true,
+            debug: false,
+            override: false,
+            encoding: 'utf8',
+            fast: false,
+            path: path.resolve(process.cwd(), '.env'),
+        });
     }
     // Enable verbose debug output when --debug is passed
     if (argsEarly.includes('--debug')) {

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

@@ -760,7 +760,7 @@ async function shutdownActualApi(opts) {
         setApiInitialized(false);
     }
 }
-import { BANK_SYNC_SETTLE_MS, WRITE_SESSION_DELAY_MS } from './constants.js';
+import { BANK_SYNC_SETTLE_MS, SPLIT_VERIFY_INTERVAL_MS, SPLIT_VERIFY_TIMEOUT_MS, WRITE_SESSION_DELAY_MS } from './constants.js';
 // Concurrency limiter extracted to ./actual-adapter/concurrency.ts (#166).
 // Imported for internal use (every method wraps its raw call in withConcurrency)
 // and setMaxConcurrency is re-exported.
@@ -1646,6 +1646,81 @@ export async function getPayees() {
         return await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
     });
 }
+/**
+ * #484: accounts, category groups and payees in ONE withActualApi session, so one api lock cycle
+ * and one consistent snapshot. The reads are raw and sequential: an `adapter.get*` call here would
+ * nest a session inside this one and deadlock until ACTUAL_OP_TIMEOUT_MS, and Promise.all would buy
+ * nothing because every call serialises on the one api singleton anyway.
+ */
+export async function getContext(options) {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.context.get').catch(() => { });
+        const includeAccounts = options?.includeAccounts ?? true;
+        const includeCategories = options?.includeCategories ?? true;
+        const includePayees = options?.includePayees ?? true;
+        const includeClosed = options?.includeClosed ?? false;
+        const payeeLimit = options?.payeeLimit ?? 500;
+        const result = {};
+        // Payees need the account listing even when accounts were not requested: upstream getPayees()
+        // drops the transfer payees of DELETED accounts but not of CLOSED ones, so hiding closed
+        // accounts means hiding their transfer payees here too.
+        const closedIds = new Set();
+        if (includeAccounts || (includePayees && !includeClosed)) {
+            const rawAccounts = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+            const all = Array.isArray(rawAccounts) ? rawAccounts : [];
+            for (const a of all)
+                if (a.closed)
+                    closedIds.add(String(a.id));
+            if (includeAccounts) {
+                result.accounts = all
+                    .filter((a) => includeClosed || !a.closed)
+                    .map((a) => ({
+                    id: String(a.id),
+                    name: String(a.name ?? ''),
+                    offbudget: Boolean(a.offbudget),
+                    closed: Boolean(a.closed),
+                }));
+            }
+        }
+        if (includeCategories) {
+            // No options: upstream then returns hidden groups and categories too, flagged by `hidden`.
+            const rawGroups = await withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 }));
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            result.categoryGroups = (Array.isArray(rawGroups) ? rawGroups : []).map((g) => ({
+                id: String(g.id),
+                name: String(g.name ?? ''),
+                is_income: Boolean(g.is_income),
+                hidden: Boolean(g.hidden),
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                categories: (Array.isArray(g.categories) ? g.categories : []).map((c) => ({
+                    id: String(c.id),
+                    name: String(c.name ?? ''),
+                    hidden: Boolean(c.hidden),
+                })),
+            }));
+        }
+        if (includePayees) {
+            const rawPayees = await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
+            // Name order, case-insensitive, id as the tie-break, so the cut is deterministic. Transfer
+            // payees count toward the cap. Recency is not an option: payees carry no last-used field.
+            const list = (Array.isArray(rawPayees) ? rawPayees : [])
+                .map((p) => ({
+                id: String(p.id),
+                name: String(p.name ?? ''),
+                transfer_acct: p.transfer_acct != null ? String(p.transfer_acct) : null,
+            }))
+                .filter((p) => includeClosed || p.transfer_acct === null || !closedIds.has(p.transfer_acct))
+                .sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+            result.payees = list.slice(0, payeeLimit);
+            result.payeesTruncated = list.length > payeeLimit;
+            result.payeeTotal = list.length;
+            if (result.payeesTruncated) {
+                result.hint = `Showing ${result.payees.length} of ${list.length} payees. Use actual_entities_search or actual_get_id_by_name to find the rest.`;
+            }
+        }
+        return result;
+    });
+}
 /**
  * #388: turn an optional FILTER id that is actually a NAME into a refusal that names the id.
  *
@@ -1875,7 +1950,7 @@ export async function updateTransaction(id, fields) {
         // so an update that changed nothing would otherwise be reported as success. A
         // targeted ActualQL query by id keeps this cheap (indexed lookup). #305 extends
         // the select to is_parent + amount so the split guards below can run off the
-        // same read (single source; no second out-of-queue read).
+        // same read (single source; no second out-of-queue read); #489 adds is_child.
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const { q } = (await import('@actual-app/api'));
         const rows = await withConcurrency(() => retry(async () => {
@@ -1885,34 +1960,80 @@ export async function updateTransaction(id, fields) {
             // (which is exactly what broke editing a split). `splits: 'all'` returns
             // regular transactions, split parents, and split children as flat rows, so
             // the existence + is_parent + amount read is correct for every kind.
-            const res = (await rawRunQuery(q('transactions').options({ splits: 'all' }).filter({ id }).select(['id', 'is_parent', 'amount'])));
+            const res = (await rawRunQuery(q('transactions').options({ splits: 'all' }).filter({ id }).select(['id', 'is_parent', 'is_child', 'amount', 'category'])));
             return Array.isArray(res?.data) ? res.data : [];
         }, { retries: 2, backoffMs: 200 }));
         if (rows.length === 0) {
-            throw new Error(`Transaction "${id}" not found. Use actual_transactions_get to list transactions.`);
-        }
-        // #305: split-edit guards, BEFORE the raw write. Two rules:
-        //   (a) subtransactions may only edit a transaction that is ALREADY a split;
-        //       converting a plain transaction into a split via updateTransaction is
-        //       broken in @actual-app/api 26.7.0 (it strands orphan children), so it
-        //       is rejected here rather than silently corrupting data.
-        //   (b) child amounts must sum to the effective parent amount. The API does
-        //       not enforce this; the ground truth is the caller's new `amount` if
-        //       supplied, else the stored amount read above.
+            // #489: a typed refusal (nothing was written), wording kept byte-identical to what callers saw.
+            throw new NotFoundRefusal('Transaction', id, 'actual_transactions_get', undefined, `Transaction "${id}" not found. Use actual_transactions_get to list transactions.`);
+        }
+        // Split guards, BEFORE the raw write:
+        //   (a) a CHILD cannot itself be split: upstream nests one level only.
+        //   (b) child amounts must sum to the effective parent amount. The API does not
+        //       enforce this; the ground truth is the caller's new `amount` if supplied,
+        //       else the stored amount read above.
+        // #489 lifted #305's third rule, which refused a PLAIN target: "converting a plain
+        // transaction into a split via updateTransaction is broken in 26.7.0 (it strands orphan
+        // children)". That is no longer true. Upstream #8207 (`shared/transactions.ts`) converts in
+        // place through makeChild, and a live probe at 26.9.0 confirmed it persists across a fresh
+        // download with the SAME id and `imported_id`, and keeps a transfer balanced by replacing the
+        // single counterpart with one per child. Reusing that path is why #489 is not a create plus
+        // delete: raw `addTransactions` does not run transfers while `deleteTransaction` does, so the
+        // orchestration deleted a transfer's counterpart, and it re-ran rules on the new parent.
         const subs = fields?.subtransactions;
+        const row = rows[0];
+        const converting = Boolean(subs) && row.is_parent !== true;
         if (subs) {
-            const row = rows[0];
-            if (row.is_parent !== true) {
-                throw new Error(`Transaction "${id}" is not a split. Converting a plain transaction into a split is not supported here; create the split with actual_transactions_create instead.`);
+            if (row.is_child === true) {
+                throw new OutOfRangeRefusal(`Transaction "${id}" is a split child and cannot itself be split. Edit its parent's subtransactions with actual_transactions_update instead.`, id);
             }
             const providedAmount = fields.amount;
             const parentAmount = providedAmount != null ? providedAmount : row.amount;
             const sum = subtransactionsSum(subs);
             if (sum !== parentAmount) {
-                throw new Error(`Subtransactions must sum to the parent amount. Expected ${parentAmount}, got ${sum}.`);
+                throw new OutOfRangeRefusal(`Subtransactions must sum to the parent amount. Expected ${parentAmount}, got ${sum}.`, String(sum));
+            }
+        }
+        // #489: a converted parent keeps its old category upstream (the update path nulls a parent's
+        // category only when `account` is in the diff), while the Actual UI shows a split parent with
+        // none. Clear it in the SAME write, and hand its category to every child that names none, so
+        // the children still inherit it exactly as upstream's makeChild would have done.
+        let payload = fields;
+        if (converting) {
+            const f = fields;
+            const inherited = 'category' in f ? f.category : (row.category ?? null);
+            payload = {
+                ...f,
+                category: null,
+                subtransactions: f.subtransactions.map((c) => ('category' in c ? c : { ...c, category: inherited })),
+            };
+        }
+        await withConcurrency(() => retry(() => rawUpdateTransaction(id, payload), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
+        if (!converting)
+            return {};
+        // #489: verify AFTER the write. Upstream resolves before the conversion lands (see
+        // SPLIT_VERIFY_TIMEOUT_MS), so success is only claimed once the parent reads as a split
+        // with every requested child. Polling here, inside the drain, also guarantees the change is
+        // local before the drain's api.sync(). A retry after a timeout is safe: the row is then a
+        // split, so a second call EDITS its children rather than creating anything new.
+        const expected = subs.length;
+        const deadline = Date.now() + SPLIT_VERIFY_TIMEOUT_MS;
+        for (;;) {
+            const res = (await rawRunQuery(q('transactions').options({ splits: 'all' })
+                .filter({ $or: [{ id }, { parent_id: id }] })
+                .select(['id', 'is_parent', 'parent_id'])));
+            const data = Array.isArray(res?.data) ? res.data : [];
+            const parent = data.find((r) => r.id === id);
+            const children = data.filter((r) => r.parent_id === id).map((r) => r.id);
+            if (parent?.is_parent === true && children.length === expected) {
+                return { split: { parent: id, children } };
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Transaction "${id}" was sent to be split into ${expected} parts, but the split was not visible after ${SPLIT_VERIFY_TIMEOUT_MS}ms (found ${children.length} children), so the outcome is unknown. ` +
+                    'Read it back with actual_transactions_get before retrying: if it is already a split, a retry edits its children rather than duplicating them.');
             }
+            await new Promise((resolve) => setTimeout(resolve, SPLIT_VERIFY_INTERVAL_MS));
         }
-        await withConcurrency(() => retry(() => rawUpdateTransaction(id, fields), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
 export async function updateTransactionBatch(updates) {
@@ -3571,5 +3692,6 @@ export default {
     exportBudget,
     importBudget,
     getPreferences,
+    getContext,
     notifications,
 };

package/dist/src/lib/config-registry.js

@@ -42,7 +42,6 @@ export const RAW_ENV_ALLOWLIST = [
     { name: 'NODE_ENV', reason: 'framework var; selects prod log format and prod behaviours', readSite: 'httpServer.ts, logger.ts (resolveLogConfig)' },
     { name: 'DEBUG', reason: 'framework debug toggle', readSite: 'utils.ts, index.ts' },
     { name: 'LOG_LEVEL', reason: 'debug-detection toggle (distinct from MCP_BRIDGE_LOG_LEVEL, the winston level)', readSite: 'utils.ts' },
-    { name: 'DOTENV_CONFIG_QUIET', reason: 'dotenv internal flag, not an operator knob', readSite: 'index.ts', documented: false },
     { name: 'VERSION', reason: 'build-time version arg, injected by the Docker build, not an operator knob', readSite: 'index.ts, server_info.ts', documented: false },
     // Domain-time: read after config loads; future candidates for schema promotion.
     { name: 'ACTUAL_API_CONCURRENCY', reason: 'adapter concurrency tuning; future schema-promotion candidate', readSite: 'lib/actual-adapter/concurrency.ts' },

package/dist/src/lib/constants.js

@@ -46,6 +46,18 @@ export const BANK_SYNC_SETTLE_MS = 30_000;
  * session at the cost of slightly higher latency.
  */
 export const WRITE_SESSION_DELAY_MS = 100;
+/**
+ * #489: how long (ms) to wait for a plain-to-split conversion to become visible.
+ *
+ * Upstream `api/transaction-update` returns `handlers['transactions-batch-update'](diff)['updated']`
+ * without awaiting it (verified at @actual-app/api 26.9.0), so the write lands AFTER the call
+ * resolves. Measured live, a read issued immediately after still sees the plain row. The adapter
+ * therefore reads the split back, polling every SPLIT_VERIFY_INTERVAL_MS, and refuses to report
+ * success if it has not appeared within this bound. A local SQLite write, so milliseconds in
+ * practice; the bound only decides how long a genuinely lost write takes to be reported.
+ */
+export const SPLIT_VERIFY_TIMEOUT_MS = 2000;
+export const SPLIT_VERIFY_INTERVAL_MS = 25;
 // ============================================================================
 // MCP SERVER
 // ============================================================================

package/dist/src/lib/schemas/common.js

@@ -3,7 +3,7 @@
  *
  * Common validation schemas used across MCP tools for Actual Budget.
  * These schemas provide consistent validation, better error messages,
- * and reduce duplication across the 81 tool definitions.
+ * and reduce duplication across the 82 tool definitions.
  */
 import { z } from 'zod';
 import { MAX_NAME_LENGTH, MAX_NOTES_LENGTH, DATE_PATTERN, MONTH_PATTERN, UUID_PATTERN } from '../constants.js';

package/dist/src/lib/tool-annotations.js

@@ -67,6 +67,7 @@ const READ_ONLY = new Set([
     'actual_categories_get',
     'actual_category_groups_get',
     'actual_entities_search',
+    'actual_get_context',
     'actual_get_id_by_name',
     'actual_notes_get',
     'actual_payee_rules_get',

package/dist/src/tools/get_context.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import adapter from '../lib/actual-adapter.js';
+/**
+ * actual_get_context (#484)
+ *
+ * One call that returns the ids an assistant needs before it can do anything else: accounts,
+ * category groups with their categories, and payees, read in a single api session.
+ *
+ * The name follows the actual_get_id_by_name precedent: a cross-entity snapshot has no single
+ * domain noun for actual_{domain}_{action}. Read-only.
+ */
+const schema = z
+    .object({
+    includeAccounts: z.boolean().optional().default(true)
+        .describe('Include accounts (default: true).'),
+    includeCategories: z.boolean().optional().default(true)
+        .describe('Include category groups with their categories, hidden ones flagged (default: true).'),
+    includePayees: z.boolean().optional().default(true)
+        .describe('Include payees (default: true).'),
+    includeClosed: z.boolean().optional().default(false)
+        .describe('Include closed accounts and their transfer payees (default: false).'),
+    payeeLimit: z.number().int().min(1).max(2000).optional().default(500)
+        .describe('Maximum payees to return, 1 to 2000 (default: 500). Payees are sorted by name; when more exist, payeesTruncated is true and payeeTotal gives the full count. Use actual_entities_search or actual_get_id_by_name for the rest.'),
+})
+    .refine((v) => v.includeAccounts || v.includeCategories || v.includePayees, {
+    message: 'At least one of includeAccounts, includeCategories or includePayees must be true.',
+    path: ['includeAccounts'],
+});
+export default createTool({
+    name: 'actual_get_context',
+    description: 'Read the budget structure and entity UUIDs (accounts, category groups with nested categories, and payees) in a single call. ' +
+        'Call this first to bootstrap context so you have the ids needed for transactions, rules, or budget operations without several list calls. ' +
+        'A section you exclude is omitted from the response rather than returned empty. Read-only.',
+    schema,
+    handler: async (input) => {
+        return await adapter.getContext(input);
+    },
+    examples: [
+        {
+            description: 'Bootstrap budget context with open accounts, categories, and up to 500 payees',
+            input: {},
+        },
+        {
+            description: 'Fetch accounts and categories without reading payees',
+            input: { includePayees: false },
+        },
+    ],
+});

package/dist/src/tools/index.js

@@ -80,3 +80,4 @@ export { default as tags_delete } from './tags_delete.js';
 export { default as notes_get } from './notes_get.js';
 export { default as notes_update } from './notes_update.js';
 export { default as preferences_get } from './preferences_get.js';
+export { default as get_context } from './get_context.js';

package/dist/src/tools/transactions_update.js

@@ -24,24 +24,28 @@ const InputSchema = z.object({
         transfer_id: z.string().nullable().optional().describe('Transfer transaction ID if this is a transfer'),
         cleared: z.boolean().nullable().optional().describe('Whether transaction is cleared'),
         reconciled: z.boolean().nullable().optional().describe('Whether transaction is reconciled'),
-        // #305: edit the children of an EXISTING split. The child amounts must sum
-        // to the parent amount; the target must already be a split. Both are
-        // enforced in the adapter pre-flight (it reads is_parent + amount), because
-        // the parent amount is not part of this input. Converting a plain
-        // transaction into a split here is rejected (unsupported by the API).
+        // #305: edit the children of an existing split. #489: or split a PLAIN transaction in
+        // place (same id, so imported_id and bank-sync matching are kept). The child amounts must
+        // sum to the parent amount, and a split child cannot itself be split; both are enforced in
+        // the adapter pre-flight (it reads is_parent, is_child and amount), because the stored
+        // amount is not part of this input.
         subtransactions: CommonSchemas.subtransactions
             .optional()
-            .describe('Replace the children of an existing split; amounts must sum to the parent amount. To create a split, use actual_transactions_create.'),
+            .describe('Split children. On a plain transaction this splits it in place (same id, import fields kept); on a split it replaces the children. Amounts must sum to the parent amount.'),
     }).describe('Fields to update'),
 });
 const tool = {
     name: 'actual_transactions_update',
-    description: 'Update an existing transaction in Actual Budget. Provide the transaction ID and the fields you want to update.',
+    description: 'Update an existing transaction in Actual Budget. Provide the transaction ID and the fields you want to update. ' +
+        'To split an existing transaction across categories in one call, pass fields.subtransactions (amounts summing to the transaction amount): ' +
+        'it is split in place, keeping its id and import fields, and the result lists the new child ids. ' +
+        'The parent\'s own category is cleared; a child that names no category inherits it.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        await adapter.updateTransaction(input.id, input.fields);
-        return { success: true };
+        const split = (await adapter.updateTransaction(input.id, input.fields))?.split;
+        // #489: name the children only when a split was CREATED, so the common edit keeps its shape.
+        return split ? { success: true, split } : { success: true };
     },
 };
 export default tool;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.22.7",
+  "version": "0.22.11",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
   },
-  "description": "MCP server with 81 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 82 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/transactions_aggregate.test.js && node tests/unit/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.test.js && node tests/unit/generated_tools.smoke.test.js &&node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.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/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/new_tool_completeness.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/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.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_hold_for_next_month.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/httpServer_init_failure_report.test.js && node tests/unit/stdio_init_failure_report.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/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.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/oidc_resource_identifier.test.js && node tests/unit/httpServer_oidc_resource_metadata.test.js && node tests/unit/oidc_error_cause.test.js && node tests/unit/httpServer_oidc_error_body.test.js && node tests/unit/oidc_token_source.test.js && node tests/unit/config_oidc_assertion_refines.test.js && node tests/unit/httpServer_oidc_assertion_mode.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/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.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/transactions_update_splits.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/stdio_budget_switch.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/playwright_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/server_version_probe_outside_op_timeout.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budgets_import_syncid.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js && node tests/unit/oidc_scope_list.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/transactions_aggregate.test.js && node tests/unit/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.test.js && node tests/unit/generated_tools.smoke.test.js &&node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.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/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/new_tool_completeness.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/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.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_hold_for_next_month.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/httpServer_init_failure_report.test.js && node tests/unit/stdio_init_failure_report.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/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.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/oidc_resource_identifier.test.js && node tests/unit/httpServer_oidc_resource_metadata.test.js && node tests/unit/oidc_error_cause.test.js && node tests/unit/httpServer_oidc_error_body.test.js && node tests/unit/oidc_token_source.test.js && node tests/unit/config_oidc_assertion_refines.test.js && node tests/unit/httpServer_oidc_assertion_mode.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_batch_cap.test.js && node tests/unit/dotenv_stdout_quiet.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.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/transactions_update_splits.test.js && node tests/unit/transactions_update_split_convert.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/stdio_budget_switch.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/playwright_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/server_version_probe_outside_op_timeout.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budgets_import_syncid.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js && node tests/unit/oidc_scope_list.test.js && node tests/unit/get_context.test.js && node tests/unit/contributor_docs.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",
@@ -69,9 +69,9 @@
   },
   "dependencies": {
     "@actual-app/api": "^26.9.0",
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.30.1",
     "debug": "^4.4.3",
-    "dotenv": "^17.4.2",
+    "dotenv": "^18.0.3",
     "express": "^5.2.1",
     "fuse.js": "^7.4.2",
     "jose": "^6.2.12",
@@ -86,8 +86,8 @@
   "devDependencies": {
     "@playwright/test": "^1.63.0",
     "@types/express": "^5.0.3",
-    "@types/node": "^26.6.2",
-    "knip": "^6.37.0",
+    "@types/node": "^26.6.3",
+    "knip": "^6.38.0",
     "node-fetch": "^3.3.2",
     "tsconfig-paths": "^4.2.0",
     "typescript": "^7.0.2"