actual-mcp-server 0.22.6 → 0.22.8

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 |
 
@@ -508,11 +509,12 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `OIDC_ISSUER` | _(none)_ | If OIDC | OIDC issuer URL (e.g., `https://sso.example.com`) |
 | `OIDC_ALLOW_INSECURE_ISSUER` | `false` | No | Allow a plaintext (http) OIDC issuer on a trusted network (#244). Off by default (http issuer refused at startup); set `true` only for local/LAN testing |
 | `OIDC_RESOURCE` | _(none)_ | If OIDC | This server's canonical URL, the RFC 9728 resource identifier and the expected `aud` (#461). Use the full public MCP endpoint URL, e.g. `https://actual-mcp.example.com/http`, no trailing slash. Must be an absolute http(s) URL (a bare client id refuses to start); put a client-id `aud` in `OIDC_ACCEPTED_AUDIENCES` instead |
-| `OIDC_ACCEPTED_AUDIENCES` | _(none)_ | No | Extra accepted `aud` values beyond `OIDC_RESOURCE`, comma-separated (#245). For IdPs that put the client-id in `aud` (e.g. Authentik). Strict allowlist, never a wildcard |
+| `OIDC_ACCEPTED_AUDIENCES` | _(none)_ | No | Extra accepted `aud` values beyond `OIDC_RESOURCE`, comma-separated (#245). For IdPs that put the client-id in `aud` (e.g. Authentik) or the OAuth client's redirect URI (Cloudflare Access for SaaS). Strict allowlist, never a wildcard |
 | `OIDC_JWKS_TRUSTED_HOSTS` | _(none)_ | No | Opt-in cross-origin JWKS hosts, comma-separated `host` or `host:port` (#254). For IdPs whose `jwks_uri` lives on another host, e.g. Google needs `www.googleapis.com`. Exact match, no wildcards; empty default keeps same-origin-only |
 | `OIDC_JWKS_URI` | _(none)_ | No | Direct JWKS URL that bypasses OpenID discovery (#462), for issuers with no discovery document (Cloudflare Access: `https://<team>.cloudflareaccess.com/cdn-cgi/access/certs`). Same https, credentials and origin-or-trusted-host rules as a discovered `jwks_uri`, plus no query or fragment. When set, `/.well-known/oauth-authorization-server` is not served and `AUTH_BUDGET_ACL_IDENTITY_SOURCE=userinfo` is refused |
-| `OIDC_TOKEN_SOURCE` | `authorization` | No | Where the bearer JWT is read from (#462): `authorization` (default) or `cf-access-jwt-assertion` for an MCP server behind Cloudflare Access with Managed OAuth (the edge forwards the signed Access JWT in that header; `Authorization` is then never consulted, `OIDC_SCOPES` must be empty, and the origin must be reachable only via Cloudflare). See the Cloudflare recipe in `docs/guides/AI_CLIENT_SETUP.md` |
-| `OIDC_SCOPES` | _(none)_ | No | Comma-separated required scopes; leave empty for Casdoor |
+| `OIDC_TOKEN_SOURCE` | `authorization` | No | Where the bearer JWT is read from (#462): `authorization` (default) or `cf-access-jwt-assertion` for an MCP server behind Cloudflare Access with Managed OAuth (the edge forwards the signed Access JWT in that header; `Authorization` is then never consulted, `OIDC_SCOPES` must be empty, `OIDC_SCOPES_SUPPORTED` is allowed, and the origin must be reachable only via Cloudflare). See the Cloudflare recipe in `docs/guides/AI_CLIENT_SETUP.md` |
+| `OIDC_SCOPES` | _(none)_ | No | Comma-separated required (enforced) scopes, also advertised. Leave empty when the IdP's JWTs carry no `scope` claim (Casdoor, Cloudflare Access for SaaS) |
+| `OIDC_SCOPES_SUPPORTED` | _(none)_ | No | Comma-separated scopes advertised in `scopes_supported` but not enforced. Use when the IdP's JWTs carry no `scope` claim but the client needs a scope such as `offline_access` advertised (e.g. Gemini with Cloudflare Access for SaaS). Required scopes from `OIDC_SCOPES` are always advertised too |
 | `AUTH_BUDGET_ACL` | _(none)_ | No | Per-user budget ACL; see [AI Client Setup](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) |
 | `AUTH_BUDGET_ACL_SOURCE` | `static` | No | `static` uses the `AUTH_BUDGET_ACL` map above. `actual` derives the ACL from the Actual server's own per-file access list, so revoking someone in Actual takes effect here without a config edit. Requires a multi-user (OpenID) Actual server that was password-bootstrapped first |
 | `AUTH_BUDGET_ACL_CLAIM` | `auto` | No | Which token claim identifies the principal when the source is `actual`. `auto` mirrors Actual's own precedence (`preferred_username`, `login`, `email`, `id`, `sub`) and matches the result against Actual's `userName`. Set a single claim name to pin one instead |
@@ -600,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:**
 
@@ -666,14 +668,15 @@ AUTH_PROVIDER=oidc
 OIDC_ISSUER=https://sso.yourdomain.com
 OIDC_RESOURCE=https://actual-mcp.yourdomain.com/http   # this server's public MCP URL (the expected 'aud')
 OIDC_ACCEPTED_AUDIENCES=your-client-id                  # only if your IdP puts the client id in 'aud' (#245)
-OIDC_SCOPES=                                            # leave empty for Casdoor
+OIDC_SCOPES=                                            # leave empty for Casdoor / Cloudflare Access for SaaS
+# OIDC_SCOPES_SUPPORTED=openid,offline_access           # extra scopes advertised in discovery without enforcement (#472)
 ```
 
-`OIDC_RESOURCE` is the canonical URL of this MCP server (the MCP authorization spec's "canonical server URI" and the RFC 9728 resource identifier), not an IdP client id: the protected-resource metadata route and the expected token audience are both derived from it, and a value that is not an absolute http(s) URL refuses to start with a message naming the variable (#461). Use the full public endpoint URL (`https://host/http`, or whatever `MCP_BRIDGE_HTTP_PATH` / `MCP_HTTP_PATH` advertises) rather than the bare origin: with the endpoint form the server publishes the path-specific document a strict client looks for, and it warns at startup when the two disagree.
+`OIDC_RESOURCE` is the canonical URL of this MCP server (the MCP authorization spec's "canonical server URI" and the RFC 9728 resource identifier), not an IdP client id: the protected-resource metadata route and the expected token audience are both derived from it, and a value that is not an absolute http(s) URL refuses to start with a message naming the variable (#461). Use the full public endpoint URL (`https://host/http`, or whatever `MCP_BRIDGE_HTTP_PATH` / `MCP_HTTP_PATH` advertises) rather than the bare origin: with the endpoint form the server publishes both the path-specific document (canonical) and a root copy for clients that look only at the root (#473), and it warns at startup when the resource path and advertised path disagree.
 
 **OAuth discovery endpoints (automatic in OIDC mode).** When `AUTH_PROVIDER=oidc`, the server publishes the two metadata documents an OAuth client needs to bootstrap a login, so `mcp-remote` and Claude.ai's native connector can discover the flow without manual endpoint configuration:
 
-- `GET /.well-known/oauth-protected-resource[<path>]` (RFC 9728): identifies this server as a protected resource and points at your `OIDC_ISSUER` as the authorization server. The route follows `OIDC_RESOURCE`: `https://host/http` is served at `/.well-known/oauth-protected-resource/http` (RFC 9728 section 3.1), the bare origin at the root path. The official MCP SDK tries the path-specific URL first and falls back to the root; clients without that fallback need the endpoint form (#461).
+- `GET /.well-known/oauth-protected-resource[<path>]` (RFC 9728): identifies this server as a protected resource and points at your `OIDC_ISSUER` as the authorization server. The route follows `OIDC_RESOURCE`: with `https://host/http`, the canonical document is served at `/.well-known/oauth-protected-resource/http` (RFC 9728 section 3.1) and a root copy is also served at `/.well-known/oauth-protected-resource` for clients that skip the path-specific URL (e.g. Google Gemini, #473); the bare origin serves only the root path. The official MCP SDK tries the path-specific URL first and falls back to the root.
 - `GET /.well-known/oauth-authorization-server` (RFC 8414, #285): the authorization server metadata (its `authorization_endpoint` / `token_endpoint` / `registration_endpoint`), re-served from your IdP's own OpenID discovery document. This is here because several clients look for it on the resource-server origin, and some IdPs (e.g. Authentik) do not expose it where those clients look. It is fetched once at startup and served verbatim, exposes only endpoints your IdP already publishes publicly, and requires no authentication (a client reads it before it has a token). No extra configuration is needed; it is absent when `AUTH_PROVIDER` is not `oidc`.
 
 **Where the per-user budget ACL comes from.** By default the ACL is the `AUTH_BUDGET_ACL` map you maintain by hand. Since v0.10.x it can instead be derived from the Actual server's own per-file access list, so granting or revoking someone in Actual takes effect here without a config edit and a restart:
@@ -693,7 +696,7 @@ Three things to know before enabling it:
 
 It is opt-in and fails closed: if the budget list cannot be read, or the principal matches no file, access is denied rather than granted.
 
-See [AI Client Setup, OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) for `AUTH_BUDGET_ACL` format and Casdoor notes.
+See [AI Client Setup, OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-multi-user) for `AUTH_BUDGET_ACL` format, Casdoor notes, and the Cloudflare Access for SaaS + Gemini recipe.
 
 ---
 
@@ -702,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) |
@@ -786,7 +789,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.22.6 | **Tool Count:** 81 (verified LibreChat-compatible)
+**Version:** 0.22.8 | **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/auth/setup.js

@@ -10,6 +10,7 @@ import { MCPAuth } from 'mcp-auth';
 import config from '../config.js';
 import logger from '../logger.js';
 import { validateOidcResource } from '../lib/oidc-resource.js';
+import { parseScopeList, buildScopesSupported } from '../lib/oidc-scopes.js';
 let _instance = null;
 /**
  * Returns an MCPAuth instance configured for this server's OIDC settings,
@@ -41,12 +42,12 @@ export function createMcpAuth() {
     const resourceUrl = validateOidcResource(config.OIDC_RESOURCE);
     if (_instance)
         return _instance;
-    const scopesSupported = config.OIDC_SCOPES
-        ? config.OIDC_SCOPES.split(',').map((s) => s.trim()).filter(Boolean)
-        : [];
+    const requiredScopes = parseScopeList(config.OIDC_SCOPES);
+    const scopesSupported = buildScopesSupported(config.OIDC_SCOPES_SUPPORTED, config.OIDC_SCOPES);
     logger.info(`[OIDC] Configuring mcp-auth, issuer: ${config.OIDC_ISSUER}`);
     logger.info(`[OIDC] Resource identifier: ${resourceUrl.origin}${resourceUrl.pathname}`);
-    logger.info(`[OIDC] Scopes required: ${scopesSupported.length ? scopesSupported.join(', ') : '(none)'}`);
+    logger.info(`[OIDC] Scopes required: ${requiredScopes.length ? requiredScopes.join(', ') : '(none)'}`);
+    logger.info(`[OIDC] Scopes advertised: ${scopesSupported.length ? scopesSupported.join(', ') : '(none)'}`);
     _instance = new MCPAuth({
         protectedResources: [
             {

package/dist/src/config.js

@@ -155,8 +155,10 @@ export const configSchema = z.object({
     // validate it. In that mode Authorization is NEVER consulted (one source, one
     // verification, no fallback). Closed enum, default is today's behaviour.
     OIDC_TOKEN_SOURCE: z.enum(['authorization', 'cf-access-jwt-assertion']).default('authorization'),
-    // Comma-separated required scopes (e.g. "read,write"). Optional.
+    // Comma-separated required (enforced) scopes; also advertised (e.g. "read,write"). Optional.
     OIDC_SCOPES: z.string().optional(),
+    // Comma-separated scopes advertised in discovery (scopes_supported) but not enforced. Optional.
+    OIDC_SCOPES_SUPPORTED: z.string().optional(),
     // JSON map of principal → budget sync-ID list for per-user budget ACL.
     // Keys: email, sub, or "group:<name>". Values: array of sync IDs or ["*"] for all.
     // Example: {"alice@example.com":["budget-1"],"group:admin":["*"]}

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/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/oidc-resource.js

@@ -107,6 +107,39 @@ export function advertisedPathFrom(advertisedUrl, httpPath) {
         };
     }
 }
+const METADATA_ROOT = '/.well-known/oauth-protected-resource';
+/**
+ * The route mcp-auth 0.2.0 serves the RFC 9728 document under for `resource` (#473), or
+ * null for the origin form, where it serves the root itself. This copies the rule in
+ * mcp-auth's `create-resource-metadata-endpoint.js` exactly, raw pathname included: it
+ * must NOT use `stripped()` below, because mcp-auth registers the route under the
+ * pathname as given, trailing slash and all, and a rewrite aimed anywhere else 404s.
+ */
+export function resourceMetadataPath(resource) {
+    const { pathname } = new URL(resource);
+    return pathname === '/' ? null : `${METADATA_ROOT}${pathname}`;
+}
+/**
+ * The request URL a root metadata request is rewritten to (#473): the fixed target plus
+ * the original query string, verbatim from the first `?`. Pure so the query handling is
+ * testable: mcp-auth's route ignores the query, so a served 200 cannot tell a kept query
+ * from a dropped one.
+ */
+export function rootMetadataRewriteUrl(url, target) {
+    const q = url.indexOf('?');
+    return q >= 0 ? `${target}${url.slice(q)}` : target;
+}
+/**
+ * True for a request the root rewrite applies to (#473). Exact lowercase path, with or
+ * without one trailing slash: Express 5's default non-strict routing already serves
+ * mcp-auth's own path-specific route both ways, so the root behaves the same, but it is
+ * two exact comparisons rather than a prefix, so no deeper path is ever rewritten. Only
+ * GET, HEAD (Express answers it through GET routes) and the OPTIONS CORS preflight.
+ */
+export function isRootMetadataRequest(method, path) {
+    return ((method === 'GET' || method === 'HEAD' || method === 'OPTIONS') &&
+        (path === METADATA_ROOT || path === `${METADATA_ROOT}/`));
+}
 /**
  * Null when the identifier's path equals the advertised MCP path (the form under which
  * mcp-auth serves the path-specific RFC 9728 document a strict client looks for);
@@ -122,13 +155,15 @@ export function resourceMetadataWarning(opts) {
         return null;
     const recommended = `${url.origin}${canonicalPath}`;
     const onlyTrailingSlash = stripped(url.pathname) === canonicalPath;
+    const metadataPath = resourceMetadataPath(opts.resource);
     // Express serves the metadata route with and without the slash, so the slash form is
     // not a discovery 404; the hazard is the audience: a client that canonicalises the
     // resource mints aud=${recommended}, which the closed allowlist then rejects.
     const detail = onlyTrailingSlash
         ? `The only difference is the trailing slash. A client that canonicalises the resource will request a token for ${recommended}, which is not in the accepted audience set, so use the form without the slash.`
-        : `Protected-resource metadata is served at /.well-known/oauth-protected-resource${url.pathname === '/' ? '' : url.pathname} only; ` +
-            `a client that looks for the path-specific document under ${canonicalPath} and does not fall back to the root will fail discovery. ` +
+        : (metadataPath === null
+            ? `Protected-resource metadata is served at the root ${METADATA_ROOT} only; a client that looks for the path-specific document under ${canonicalPath} and does not fall back to the root will fail discovery. `
+            : `Protected-resource metadata is served at ${metadataPath} and, for clients that look only there, the root ${METADATA_ROOT} (#473); a client that looks for the path-specific document under ${canonicalPath} will fail discovery. `) +
             `Switching changes the expected aud and stops serving the current document, so during the switch add OIDC_ACCEPTED_AUDIENCES=${url.origin}${url.pathname === '/' ? '' : url.pathname} to keep tokens minted for the old value valid.`;
     return (`[OIDC] ${VAR} is ${displayForm(url)} but the MCP endpoint is advertised at ${opts.advertisedPath}. ${detail} ` +
         `Recommended: ${VAR}=${recommended}`);

package/dist/src/lib/oidc-scopes.js

@@ -0,0 +1,53 @@
+/**
+ * OIDC scope parsing and discovery helpers (#472).
+ *
+ * Separates scopes advertised in discovery (RFC 9728 `scopes_supported`) from
+ * scopes required (enforced) on incoming access tokens (`requiredScopes`).
+ *
+ * Some IdPs (such as Cloudflare Access for SaaS or Casdoor) issue JWTs without
+ * a `scope` claim, while clients (such as Google Gemini) require `offline_access`
+ * to be advertised in discovery in order to request and receive a refresh token.
+ *
+ * Pure and side-effect-free for hermetic unit testing.
+ */
+/**
+ * Split a comma-separated scope string into trimmed, non-empty, de-duplicated tokens,
+ * preserving first-seen order.
+ *
+ * Returns an empty array if `csv` is undefined, empty, or whitespace-only.
+ */
+export function parseScopeList(csv) {
+    if (!csv)
+        return [];
+    const seen = new Set();
+    const result = [];
+    for (const part of csv.split(',')) {
+        const trimmed = part.trim();
+        if (trimmed && !seen.has(trimmed)) {
+            seen.add(trimmed);
+            result.push(trimmed);
+        }
+    }
+    return result;
+}
+/**
+ * Build the full list of scopes advertised in RFC 9728 `scopes_supported`.
+ *
+ * Advertised scopes (`OIDC_SCOPES_SUPPORTED`) come first, followed by any
+ * required scopes (`OIDC_SCOPES`) not already present. A required scope is
+ * always advertised so clients cannot fail to request a scope the server demands.
+ * With `OIDC_SCOPES_SUPPORTED` unset, this matches `parseScopeList(requiredCsv)`.
+ */
+export function buildScopesSupported(advertisedCsv, requiredCsv) {
+    const advertised = parseScopeList(advertisedCsv);
+    const required = parseScopeList(requiredCsv);
+    const seen = new Set(advertised);
+    const result = [...advertised];
+    for (const s of required) {
+        if (!seen.has(s)) {
+            seen.add(s);
+            result.push(s);
+        }
+    }
+    return result;
+}

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/server/httpServer.js

@@ -15,9 +15,10 @@ import { MCPAuthTokenVerificationError } from 'mcp-auth';
 import { createMcpAuth } from '../auth/setup.js';
 import { resolveJwksSource, buildTrustedJwksHosts, setResolvedOidcMetadata } from '../lib/oidc-discovery.js';
 import { createAssertionPromotionMiddleware } from '../lib/oidc-token-source.js';
-import { oidcResourceStartupWarnings } from '../lib/oidc-resource.js';
+import { isRootMetadataRequest, oidcResourceStartupWarnings, resourceMetadataPath, rootMetadataRewriteUrl } from '../lib/oidc-resource.js';
 import { stripJoseCause } from '../lib/oidc-error-cause.js';
 import { buildAcceptedAudiences } from '../lib/oidc-audiences.js';
+import { parseScopeList } from '../lib/oidc-scopes.js';
 import { budgetAclMiddleware } from '../auth/budget-acl.js';
 import { runAclPreflight } from '../auth/budget-acl-dynamic.js';
 import * as https from 'node:https';
@@ -69,12 +70,25 @@ advertisedUrl) {
         for (const w of oidcResourceStartupWarnings({ resource: config.OIDC_RESOURCE, advertisedUrl, httpPath }))
             logger.warn(w);
         if (mcpAuth) {
+            // #473: clients that skip the path-specific RFC 9728 discovery URL (e.g. Google Gemini)
+            // fetch /.well-known/oauth-protected-resource at the root. When OIDC_RESOURCE has a path,
+            // rewrite those requests onto the path-specific route so mcp-auth serves the identical
+            // document and CORS headers in-process. The target is fixed at startup from
+            // OIDC_RESOURCE, never taken from the request; the match rule is isRootMetadataRequest.
+            // Mounted inside `if (mcpAuth)` and before the router, so `none` mode never gets it and
+            // clients reach it without a token.
+            const metadataTarget = config.OIDC_RESOURCE ? resourceMetadataPath(config.OIDC_RESOURCE) : null;
+            if (metadataTarget) {
+                app.use((req, _res, next) => {
+                    if (isRootMetadataRequest(req.method, req.path))
+                        req.url = rootMetadataRewriteUrl(req.url, metadataTarget);
+                    next();
+                });
+            }
             // Serve RFC 8707 Protected Resource Metadata (/.well-known/oauth-protected-resource/...)
             app.use(mcpAuth.protectedResourceMetadataRouter());
             // Protect ALL httpPath routes with JWT validation + budget ACL
-            const requiredScopes = config.OIDC_SCOPES
-                ? config.OIDC_SCOPES.split(',').map((s) => s.trim()).filter(Boolean)
-                : [];
+            const requiredScopes = parseScopeList(config.OIDC_SCOPES);
             // #245: the strict, closed audience allowlist (OIDC_RESOURCE plus any
             // explicitly configured OIDC_ACCEPTED_AUDIENCES). jose treats the array as
             // match-any membership, so an IdP that puts the client-id in `aud` works

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.6",
+  "version": "0.22.8",
   "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",
+    "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/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",
     "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",