actual-mcp-server 0.22.13 → 0.22.17

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)   │               │  (82 tools)      │               │   Server     │
+│  (remote)   │               │  (83 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 
 ┌─────────────┐   MCP/stdio   ┌──────────────────┐   Actual API   ┌──────────────┐
 │  Claude     │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  Desktop    │               │  Server          │               │   Budget     │
-│  (local)    │               │  (82 tools)      │               │   Server     │
+│  (local)    │               │  (83 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:
 
-- **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.
+- **83 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 82 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 83 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 82 tools are available.
+> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 83 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
 
-**82 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
+**83 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
 
 ### Accounts (12)
 
@@ -425,13 +425,14 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_budgets_export` | Export the active budget as a `.zip` into `ACTUAL_EXPORT_DIR`; returns path, byte size and sha256, never the file contents |
 | `actual_budgets_import` | Restore a budget from an Actual `.zip` or a YNAB4/YNAB5 export. **Destructive:** the budget id comes from the archive, so re-importing an export *replaces* that budget's data rather than making a copy. Also loads the imported budget, changing the session's active budget |
 
-### Rules (5)
+### Rules (6)
 
 `actual_rules_get` · `actual_rules_create` · `actual_rules_update` · `actual_rules_delete`
 
 | Tool | Description |
 |------|-------------|
 | `actual_rules_create_or_update` | Idempotent upsert: create a rule, or update the existing one that matches the same conditions, in a single call. Use this instead of get-then-create when re-running a categorisation setup, so repeated runs do not pile up duplicate rules |
+| `actual_rules_create_batch` | Create 1 to 50 rules in one call, each exactly the input of `actual_rules_create`. Best-effort, not atomic (see Batch Operations): a rule that fails its own checks, names a category, payee or account that does not exist, or is rejected by Actual is reported with its index while the rest continue |
 
 ### Schedules (4)
 
@@ -451,7 +452,12 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 ### Batch Operations (1)
 
-`actual_budget_updates_batch`: batch multiple budget updates in one call
+Four tools take many items in one call, for clients that allow only a few tool calls per turn. They share ONE contract: each item is applied independently and **not atomically**. There is no rollback, so items applied before a failure stay applied; a bad item is reported by its index and the rest continue; an infrastructure failure (lost connection, timeout) fails the whole call, and then you must read the data back before retrying anything. A bulk path never retries a create on its own.
+
+- `actual_transactions_update_batch` (counted under Transactions): update up to 50 transactions, `{id, fields}` each. Result: `{ succeeded: [{id}], failed: [{id, error}], total, successCount, failureCount }`.
+- `actual_transactions_import` (counted under Transactions): bulk create with import semantics (deduplication and reconciliation against existing transactions, rules optionally applied). Use it to add many transactions at once.
+- `actual_budget_updates_batch`: set budget amounts and/or carryover flags for 1 to 100 month/category pairs, and the way to rebalance categories: read the month with `actual_budgets_getMonth`, then send one batch of absolute amounts. Each operation needs at least one of `amount` (integer cents) or `carryover`. Result: `{ succeeded: [{index, month, categoryId}], failed: [{index, month, categoryId, error}], total, successCount, failureCount }`. An unknown category, an out-of-range month or a carryover on an income category fails only that item. After a timeout, read the months back with `actual_budgets_getMonth` before retrying.
+- `actual_rules_create_batch` (counted under Rules): create 1 to 50 rules, each exactly the input of `actual_rules_create`. Result: `{ succeeded: [{index, id}], failed: [{index, error}], total, successCount, failureCount }`. Items marked "not attempted" were never sent. Re-read with `actual_rules_get` before retrying any item.
 
 ### Server Information & Lookup (5)
 
@@ -498,6 +504,10 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `MCP_HTTP_PATH` | `/http` | No | HTTP endpoint routing path |
 | `MCP_BRIDGE_HTTP_PATH` | same as `MCP_HTTP_PATH` | No | Advertised HTTP path shown to clients (set when a reverse proxy rewrites the path) |
 | `MCP_HTTP_BODY_LIMIT` | `512kb` | No | Maximum accepted JSON-RPC request body size (e.g. `512kb`, `1mb`, `1048576`). Validated at startup: an invalid, zero or overflowing size refuses to start naming the variable (#466) |
+| **Tool Surface** ||||
+| `MCP_TOOLSETS` | `all` | No | Comma-separated toolset groups (`context`, `transactions`, `analysis`, `budget`, `rules`, `schedules`, `structure`, `query`, `admin`) and presets (`chat`) to publish; `all` publishes every tool. Unknown names refuse to start. See [Reducing the tool surface](#reducing-the-tool-surface) |
+| `MCP_TOOLS` | _(empty)_ | No | Extra tools to add on top of `MCP_TOOLSETS`, by full registered name (e.g. `actual_accounts_list`). Unknown names refuse to start |
+| `MCP_READ_ONLY` | `false` | No | `true` hides and refuses the 47 write-capable tools. Only `true` or `false` (case-insensitive) are accepted; any other value refuses to start |
 | **Session Management** ||||
 | `USE_CONNECTION_POOL` | `true` | No | Enable session-based connection pooling |
 | `MAX_CONCURRENT_SESSIONS` | `15` | No | Maximum concurrent MCP sessions allowed |
@@ -544,6 +554,42 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `VERSION` | auto-detected | No | Server version (auto-set by build/Docker) |
 | `TZ` | `UTC` | No | Timezone for timestamps (e.g., `America/New_York`) |
 
+### Reducing the tool surface
+
+All 83 tools are published by default. Chat clients with a small tool budget (Gemini, LibreChat) do better with fewer, so the surface can be narrowed at startup. A tool that is not published is also refused if a client calls it by name, and the refusal names the setting responsible.
+
+| Toolset | Tools | Contents |
+|---------|-------|----------|
+| `context` | 14 | Orientation, lookups and server information |
+| `transactions` | 13 | Transaction reads, create, update, delete, import and transfers |
+| `analysis` | 7 | Summaries, aggregates and balances |
+| `budget` | 10 | Budget months, amounts, carryover, holds, transfers, batch updates and notes |
+| `rules` | 7 | Rules and payee rules, including `actual_rules_create_batch` |
+| `schedules` | 4 | Scheduled transactions |
+| `structure` | 21 | Accounts, account groups, categories, category groups, payees and tags |
+| `query` | 1 | `actual_query_run` (SELECT only) |
+| `admin` | 6 | Budget switching, import, export, bank sync and session management |
+
+Each tool is in exactly one group. The `chat` preset cuts across them and publishes 12 tools: `actual_get_context`, `actual_query_run`, `actual_transactions_create`, `actual_transactions_update`, `actual_transactions_delete`, `actual_transactions_update_batch`, `actual_rules_create`, `actual_rules_create_batch`, `actual_budget_updates_batch`, `actual_budgets_transfer`, `actual_budgets_setAmount` and `actual_budgets_getMonth`. Measured on the `tools/list` payload, all 83 tools are 108,164 bytes and the `chat` preset is 25,949 bytes (about 6.5k tokens saved, a 76% cut).
+
+`MCP_READ_ONLY=true` additionally hides and refuses every write-capable tool (47 of the 83, including `actual_bank_sync`, `actual_budgets_export`, `actual_budgets_switch` and `actual_session_close`), leaving 36. `actual_session_list` stays available under read-only. See [Security and Privacy](docs/SECURITY_AND_PRIVACY.md#tool-surface-mcp_toolsets-and-mcp_read_only).
+
+Example: a chat assistant.
+
+```bash
+MCP_TOOLSETS=chat
+MCP_TOOLS=actual_accounts_list,actual_payees_get
+```
+
+Example: a read-only household assistant.
+
+```bash
+MCP_TOOLSETS=context,analysis,query
+MCP_READ_ONLY=true
+```
+
+A configuration that resolves to zero tools refuses to start.
+
 ---
 
 ## Multi-Budget Switching
@@ -602,7 +648,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 82 tools are available, identical to HTTP mode
+- All 83 tools are available, identical to HTTP mode
 
 **Start manually to verify:**
 
@@ -705,7 +751,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` | 82-tool smoke, schema validation, auth ACL | No |
+| `npm run test:unit-js` | 83-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) |
@@ -789,7 +835,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.22.13 | **Tool Count:** 82 (verified LibreChat-compatible)
+**Version:** 0.22.17 | **Tool Count:** 83 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/actualToolsManager.js

@@ -1,6 +1,10 @@
 // src/actualToolsManager.ts
 import logger from './logger.js';
 import { formatZodError } from './lib/zod-error-format.js';
+import config from './config.js';
+import { createModuleLogger } from './lib/loggerFactory.js';
+import { resolvePublishedToolNames, unavailableError } from './lib/toolsets.js';
+const toolsetLog = createModuleLogger('TOOLSETS');
 // ✅ List of tools already implemented in this class.
 // Adding the tool name here is considered fully implemented.
 const IMPLEMENTED_TOOLS = [
@@ -46,6 +50,7 @@ const IMPLEMENTED_TOOLS = [
     'actual_payee_rules_get',
     'actual_query_run',
     'actual_rules_create',
+    'actual_rules_create_batch',
     'actual_rules_create_or_update',
     'actual_rules_delete',
     'actual_rules_get',
@@ -135,8 +140,20 @@ const API_TOOL_MAP = {
 };
 class ActualToolsManager {
     tools = new Map();
+    // Resolved ONCE in initialize() (#483) and never recomputed. Null before that, and every
+    // accessor below throws rather than fall back to "all tools", so a caller that runs
+    // before initialize() fails closed instead of publishing a surface the operator hid.
+    policy = null;
     constructor() { }
-    async initialize() {
+    /**
+     * @param settings Overrides the validated config. Production passes nothing; the unit
+     *   tests pass explicit settings so they never depend on process.env.
+     */
+    async initialize(settings = {
+        toolsets: config.MCP_TOOLSETS,
+        tools: config.MCP_TOOLS,
+        readOnly: config.MCP_READ_ONLY,
+    }) {
         // Dynamically import all tool modules from src/tools/index.ts
         const toolModules = (await import('./tools/index.js'));
         let count = 0;
@@ -148,6 +165,33 @@ class ActualToolsManager {
             }
         }
         logger.info(`🔗 Loaded ${count} tool modules from src/tools`);
+        // Throws on an unknown name or an empty result: startup fails loudly (#483).
+        this.policy = resolvePublishedToolNames(this.getToolNames(), settings);
+        toolsetLog.info(`Publishing ${this.policy.published.length} of ${this.policy.registered} registered tools`, {
+            published: this.policy.published.length,
+            registered: this.policy.registered,
+            toolsets: this.policy.settings.toolsets,
+            extraTools: this.policy.settings.tools,
+            readOnly: this.policy.settings.readOnly,
+        });
+    }
+    requirePolicy() {
+        if (!this.policy) {
+            throw new Error('Tool publication policy is not resolved: actualToolsManager.initialize() has not run');
+        }
+        return this.policy;
+    }
+    /** The tools this process publishes (tools/list) and dispatches, in registry order. */
+    getPublishedToolNames() {
+        return [...this.requirePolicy().published];
+    }
+    isPublished(name) {
+        return !this.requirePolicy().hidden.has(name) && this.tools.has(name);
+    }
+    /** The resolved MCP_TOOLSETS / MCP_TOOLS / MCP_READ_ONLY, for server_info. */
+    getToolPolicy() {
+        const { toolsets, tools, readOnly } = this.requirePolicy().settings;
+        return { toolsets: [...toolsets], tools: [...tools], readOnly };
     }
     getToolNames() {
         return Array.from(this.tools.keys());
@@ -156,9 +200,17 @@ class ActualToolsManager {
         return this.tools.get(name);
     }
     async callTool(name, args) {
+        const policy = this.requirePolicy();
+        // Registration is checked BEFORE publication: an unregistered name stays "not found".
         const tool = this.getTool(name);
         if (!tool)
             throw new Error(`Tool not found: ${name}`);
+        // Hide AND refuse (#483): omitting a tool from tools/list is not access control.
+        const unavailable = unavailableError(policy, name);
+        if (unavailable) {
+            toolsetLog.warn('Refused a call to an unpublished tool', { tool: name, setting: unavailable.setting });
+            throw unavailable;
+        }
         try {
             const result = await tool.call(args);
             // Force-serialize/deserialize to ensure result is JSON-safe (no circular refs,

package/dist/src/config.js

@@ -119,6 +119,35 @@ export const configSchema = z.object({
     MCP_HTTP_BODY_LIMIT: z.string().default('512kb').refine((v) => parseStrictByteSize(v) !== null, 'MCP_HTTP_BODY_LIMIT must be a positive byte size such as 512kb, 1mb or 1048576 (units b, kb, mb, gb, tb, pb; ' +
         'no spaces around it, no separators; at least 1 byte and at most 9007199254740991 bytes) (#466)'),
     MAX_CONCURRENT_SESSIONS: z.string().default('15').transform(val => parseInt(val, 10)),
+    // --- Published tool surface (#483) ---
+    // Which tools this process publishes AND dispatches. Names are validated, and an unknown
+    // one aborts startup, by resolvePublishedToolNames (src/lib/toolsets.ts) in
+    // actualToolsManager.initialize(), because the registry is only known there.
+    //   MCP_TOOLSETS  comma list of toolsets and presets ('all' by default = every tool).
+    //   MCP_TOOLS     extra individual tool names published on top of MCP_TOOLSETS.
+    MCP_TOOLSETS: z.string().default('all'),
+    MCP_TOOLS: z.string().default(''),
+    // MCP_READ_ONLY drops every write-capable tool, and operators read it as a safety
+    // promise, so it is parsed STRICTLY and in this one place: trimmed and case-insensitive
+    // 'true' or 'false'; unset or empty is false; anything else ('1', 'yes', 'on', a typo)
+    // refuses startup naming the value. The usual `=== 'true'` idiom is wrong here: it
+    // fails SAFE for a flag that enables risk, but would fail OPEN for this one, silently
+    // publishing every writer when an operator wrote MCP_READ_ONLY=1.
+    MCP_READ_ONLY: z
+        .string()
+        .optional()
+        .transform((raw, ctx) => {
+        const v = (raw ?? '').trim().toLowerCase();
+        if (v === '' || v === 'false')
+            return false;
+        if (v === 'true')
+            return true;
+        ctx.addIssue({
+            code: 'custom',
+            message: `MCP_READ_ONLY must be "true" or "false" (case-insensitive; unset or empty means false), got ${JSON.stringify(raw)}.`,
+        });
+        return z.NEVER;
+    }),
     // --- OIDC / mcp-auth (CF-5) ---
     // Set AUTH_PROVIDER=oidc to enable JWT validation via mcp-auth.
     // When 'none' (default), the legacy MCP_SSE_AUTHORIZATION static Bearer token is used.

package/dist/src/index.js

@@ -238,8 +238,9 @@ Docs & source: https://github.com/agigante80/actual-mcp-server`);
         }
         // Initialize tools before usage
         await actualToolsManager.initialize();
-        // Now get implemented tools after initialization
-        const implementedTools = actualToolsManager.getToolNames();
+        // The PUBLISHED tools (#483). This is the one name list every tools/list path receives
+        // (HTTP SDK handler, the no-session LobeChat path, the expired-session shim, stdio).
+        const implementedTools = actualToolsManager.getPublishedToolNames();
         // Extract schemas map with tool name → JSON schema
         const toolSchemas = {};
         for (const toolName of implementedTools) {

package/dist/src/lib/ActualMCPConnection.js

@@ -45,7 +45,7 @@ export class ActualMCPConnection extends EventEmitter {
         // If actualToolsManager is not ready, return demo tools
         let tools;
         try {
-            const toolNames = actualToolsManager.getToolNames();
+            const toolNames = actualToolsManager.getPublishedToolNames();
             tools = toolNames.map((name) => {
                 const tool = actualToolsManager.getTool(name);
                 if (!tool) {

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

@@ -2244,9 +2244,176 @@ export async function getRules() {
         return Array.isArray(raw) ? raw : [];
     });
 }
+/** The entity kinds whose ids a rule can reference, with the field name and the listing that proves existence. */
+const RULE_REFERENCE_FIELDS = {
+    category: { entity: 'Category', listTool: 'actual_categories_get' },
+    payee: { entity: 'Payee', listTool: 'actual_payees_get' },
+    account: { entity: 'Account', listTool: 'actual_accounts_get' },
+};
+/** Every (field, id) pair a rule points at. Null, undefined and non-string values are skipped (a null `set category` clears it). */
+function ruleReferences(rule) {
+    const out = [];
+    const r = (rule ?? {});
+    const add = (field, value) => {
+        if (typeof field !== 'string' || !(field in RULE_REFERENCE_FIELDS))
+            return;
+        const values = Array.isArray(value) ? value : [value];
+        for (const v of values)
+            if (typeof v === 'string')
+                out.push({ field: field, id: v });
+    };
+    if (Array.isArray(r.conditions)) {
+        for (const c of r.conditions)
+            add(c?.field, c?.value);
+    }
+    if (Array.isArray(r.actions)) {
+        for (const a of r.actions) {
+            if (a?.op === 'set')
+                add(a?.field, a?.value);
+        }
+    }
+    return out;
+}
+/**
+ * #485: read the listings the given rules need, once per kind, through the drain cache. Call
+ * INSIDE a queued op and BEFORE the first raw create. Only kinds that some rule references
+ * are read. The three listings are what upstream shows a user: categories (hidden included,
+ * group ids are not in it), payees (transfer payees included, tombstoned ones excluded here
+ * even if the listing returns them) and accounts (closed and off-budget accounts included, and
+ * both count as existing: a closed account is not a missing reference).
+ */
+async function loadRuleReferenceListings(rules) {
+    const need = new Set();
+    for (const rule of rules)
+        for (const ref of ruleReferences(rule))
+            need.add(ref.field);
+    const listings = {};
+    if (need.has('category')) {
+        const rows = await withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 }));
+        listings.category = new Set((Array.isArray(rows) ? rows : []).map((c) => String(c?.id)));
+    }
+    if (need.has('payee')) {
+        const rows = await withConcurrency(() => retry(() => readDrainListing('payees', () => rawGetPayees()), { retries: 2, backoffMs: 200 }));
+        listings.payee = new Set((Array.isArray(rows) ? rows : []).filter((p) => !p?.tombstone).map((p) => String(p?.id)));
+    }
+    if (need.has('account')) {
+        const rows = await withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 }));
+        listings.account = new Set((Array.isArray(rows) ? rows : []).map((a) => String(a?.id)));
+    }
+    return listings;
+}
+/**
+ * #485: refuse a rule that points at a category, payee or account that does not exist.
+ * Upstream `createRule` checks field, operator and nullability only, with no existence lookup
+ * of id values, so it stores a rule pointing at nothing. NOT exported: tests drive it through
+ * `createRule` and `createRulesBatch`, and it lives in the adapter so neither call site can
+ * skip it.
+ *
+ * KNOWN GAPS, accepted and tracked in #522: the other rule writes (`upsertRule`, `updateRule`
+ * and `updatePayee`'s default-category rule) are NOT guarded, and `link-schedule` action
+ * values are not checked.
+ */
+function assertRuleReferencesExist(rule, listings) {
+    for (const ref of ruleReferences(rule)) {
+        const known = listings[ref.field];
+        if (known && !known.has(ref.id)) {
+            const meta = RULE_REFERENCE_FIELDS[ref.field];
+            throw new NotFoundRefusal(meta.entity, ref.id, meta.listTool, 'Nothing was created.');
+        }
+    }
+}
+/** Error text for a failed upstream rule create. `APIError` is a PLAIN OBJECT {type, message, meta}; `ruleModel.validate` throws a real Error. */
+function ruleCreateErrorText(error) {
+    const e = error;
+    const base = e && typeof e === 'object' && e.message ? String(e.message) : typeof error === 'string' ? error : 'Failed creating a new rule';
+    const positions = [];
+    const collect = (label, list) => {
+        if (!Array.isArray(list))
+            return;
+        list.forEach((entry, i) => {
+            if (entry !== null && entry !== undefined)
+                positions.push(`${label} ${i}: ${typeof entry === 'string' ? entry : 'invalid'}`);
+        });
+    };
+    if (e && typeof e === 'object' && e.meta) {
+        collect('condition', e.meta.conditionErrors);
+        collect('action', e.meta.actionErrors);
+    }
+    return positions.length > 0 ? `${base} (${positions.join('; ')})` : base;
+}
+/**
+ * #485: create many rules in ONE write cycle with a verdict per item. NOT atomic and no
+ * rollback: rules created before a failure stay created.
+ *
+ * `items` carry the caller's ORIGINAL indices (the tool drops items that fail its own
+ * validation before calling), `total` is the size of the caller's whole array and only feeds
+ * the abort message.
+ *
+ * TWO PHASES inside one `queueWriteOperation`:
+ *  1. Read the reference listings ONCE (before the first raw create), then decide a
+ *     NotFoundRefusal per item.
+ *  2. Raw creates for the items that passed, each with retries 0 (a retried create can store
+ *     the same rule twice if the first attempt landed), each caught per item. Only raw calls
+ *     run here: an `adapter.*` call would nest the api lock and deadlock.
+ *
+ * INFRASTRUCTURE ERRORS STOP THE BATCH. When `_shouldDropPoolOnError` matches, the loop stops
+ * and the error is rethrown with the original text kept (so the classification still matches)
+ * and the indices already created. The rethrow surfaces as a whole-call failure; on the legacy
+ * path of queueWriteOperation it also forces a full shutdown. (In pooled mode the pooled entry
+ * is dropped only if the following sync fails.) Rate limits and upstream rejections are per
+ * item and the loop continues.
+ *
+ * COOPERATIVE DEADLINE: same 0.75 fraction of ACTUAL_OP_TIMEOUT_MS as `setBudgetBatch`,
+ * because `withOpTimeout` cannot cancel this callback. Items not reached go to `failed` with
+ * BUDGET_BATCH_DEADLINE_ERROR and were never sent upstream.
+ */
+export async function createRulesBatch(items, total) {
+    observability.incrementToolCall('actual.rules.createBatch').catch(() => { });
+    return queueWriteOperation(async () => {
+        const startedAt = Date.now();
+        const succeeded = [];
+        const failed = [];
+        const listings = await loadRuleReferenceListings(items.map((i) => i.rule));
+        const toWrite = [];
+        for (const item of items) {
+            try {
+                assertRuleReferencesExist(item.rule, listings);
+                toWrite.push(item);
+            }
+            catch (error) {
+                failed.push({ index: item.index, error: error.message });
+            }
+        }
+        const deadlineMs = config.ACTUAL_OP_TIMEOUT_MS > 0 ? config.ACTUAL_OP_TIMEOUT_MS * BUDGET_BATCH_DEADLINE_FRACTION : 0;
+        for (const { index, rule } of toWrite) {
+            if (deadlineMs > 0 && Date.now() - startedAt > deadlineMs) {
+                failed.push({ index, error: BUDGET_BATCH_DEADLINE_ERROR });
+                continue;
+            }
+            try {
+                const raw = await withConcurrency(() => retry(() => rawCreateRule(rule), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
+                succeeded.push({ index, id: normalizeToId(raw) });
+            }
+            catch (error) {
+                const msg = ruleCreateErrorText(error);
+                if (_shouldDropPoolOnError(error)) {
+                    const applied = succeeded.map((x) => x.index).join(', ') || 'none';
+                    throw new Error(`Rules batch aborted after ${succeeded.length} of ${total} items (applied: ${applied}): ${msg}. ` +
+                        'Read back with actual_rules_get before retrying.', { cause: error });
+                }
+                failed.push({ index, error: msg });
+            }
+        }
+        succeeded.sort((a, b) => a.index - b.index);
+        failed.sort((a, b) => a.index - b.index);
+        return { succeeded, failed };
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
+}
 export async function createRule(rule) {
     observability.incrementToolCall('actual.rules.create').catch(() => { });
     return queueWriteOperation(async () => {
+        // #485: the reference guard shares this drain's cached listings with the write.
+        assertRuleReferencesExist(rule, await loadRuleReferenceListings([rule]));
         const raw = await withConcurrency(() => retry(() => rawCreateRule(rule), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         const id = normalizeToId(raw);
         return id;
@@ -2731,22 +2898,124 @@ export async function getPayeeRules(payeeId) {
         return filtered;
     });
 }
+/** Error recorded for every item the cooperative deadline stopped before it was written. */
+export const BUDGET_BATCH_DEADLINE_ERROR = 'not attempted: batch time budget exhausted';
+/** Fraction of ACTUAL_OP_TIMEOUT_MS the item loop may consume; the rest is left for batch-budget-end and the sync. */
+const BUDGET_BATCH_DEADLINE_FRACTION = 0.75;
 /**
- * #378 CAVEAT ON THIS METHOD'S preservesListings CLAIM. This forwards an arbitrary callback to
- * rawBatchBudgetUpdates, which upstream is only a batch-budget-start / await func() /
- * batch-budget-end transaction bracket: it performs no writes of its own, so the annotation is
- * really a claim about whatever the CALLBACK does. It holds today because
- * src/tools/budget_updates_batch.ts is the only caller passing a real callback and it calls
- * only rawSetBudgetAmount and rawSetBudgetCarryover, both verified listing-safe. Nothing in
- * the signature or upstream constrains that. RE-AUDIT THIS when a second caller appears: a
- * callback reaching rawCreateCategory or rawDeleteAccount would violate the claim with no
- * compiler or runtime signal, and the symptom would be a false not-found elsewhere in the drain.
+ * #516: set budget amounts and/or carryover flags for many (month, category) pairs in ONE
+ * write cycle, with a verdict per item. NOT atomic and no rollback: items applied before a
+ * failure stay applied. The bracket is upstream's `batchMessages` (it batches sync messages),
+ * it is not a database transaction.
+ *
+ * TWO PHASES inside one `queueWriteOperation`:
+ *  1. Before the bracket: read the categories listing and the budget months ONCE each, then
+ *     decide a typed refusal per item. The guards apply to EVERY item, a carryover-only item
+ *     included, because upstream `api/budget-set-amount` validates neither category nor month
+ *     (it INSERTs an orphan `<month>-<category>` row) and the two fields should refuse alike.
+ *  2. ONE `rawBatchBudgetUpdates` whose callback holds only raw writes for the items that
+ *     passed. Every item is caught INSIDE the callback so no item error escapes the bracket
+ *     (upstream closes it in a `finally`, but an escaping error would also lose the verdicts).
+ *     Only `raw*` calls run there: an `adapter.*` call would nest the api lock and deadlock.
+ *
+ * INCOME CATEGORIES (maintainer decision): a carryover item whose category is an income
+ * category is refused in phase 1. Upstream `api/budget-set-carryover` rejects income
+ * categories too, but only AFTER an amount written for the same item has landed, so without
+ * this check an item setting both would half-apply. Upstream's own rejection stays as a
+ * backstop and is reported per item.
+ *
+ * RETRY: none. A refusal must never replay and a replayed partial bracket could double-apply;
+ * the client re-reads (`actual_budgets_getMonth`) and retries instead.
+ *
+ * COOPERATIVE DEADLINE. The whole operation runs under one `withOpTimeout`, a `Promise.race`
+ * that cannot cancel the callback. A callback abandoned mid-bracket keeps writing and leaks
+ * upstream's `IS_BATCHING` / `batchPromise` globals to later operations (a later batch-start
+ * throws "batch already started"). So the loop checks, before each item write, the time since
+ * this operation started against 75% of ACTUAL_OP_TIMEOUT_MS (skipped when it is 0, the
+ * documented "no bound" setting) and stops writing once it is exceeded; the remaining items go
+ * to `failed`. The 25% left over covers batch-budget-end and the sync.
+ * WHY NOT `queueWriteOperation`'s `timeoutMs` option: it would LENGTHEN the hold on the
+ * process-global api lock, and it still would not close the bracket on abandonment.
+ *
+ * `preservesListings` claim is safe: only raw budget amount and carryover writes run here.
  */
-export async function batchBudgetUpdates(fn) {
-    observability.incrementToolCall('actual.budgets.batchUpdates').catch(() => { });
+export async function setBudgetBatch(items) {
+    observability.incrementToolCall('actual.budgets.setBatch').catch(() => { });
     return queueWriteOperation(async () => {
-        await withConcurrency(() => retry(() => rawBatchBudgetUpdates(fn), { retries: 2, backoffMs: 200 }));
-    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
+        const startedAt = Date.now();
+        const succeeded = [];
+        const failed = [];
+        // Phase 1: reads, then refusal decisions. Both reads happen BEFORE the bracket opens.
+        const categories = await withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 }));
+        const categoryById = new Map();
+        for (const c of categories)
+            categoryById.set(c.id, c);
+        const months = await withConcurrency(() => retry(() => rawGetBudgetMonths(), { retries: 2, backoffMs: 200 }));
+        const monthKnown = Array.isArray(months) && months.length > 0;
+        const toWrite = [];
+        items.forEach((item, index) => {
+            let refusal = null;
+            const category = categoryById.get(item.categoryId);
+            if (!category) {
+                refusal = new NotFoundRefusal('Category', String(item.categoryId), 'actual_categories_get');
+            }
+            else if (monthKnown && !months.includes(String(item.month))) {
+                refusal = new OutOfRangeRefusal(`Month "${item.month}" is outside this budget's range, which runs from ${months[0]} to ` +
+                    `${months[months.length - 1]}. Use actual_budgets_getMonths to see the months you can budget to.`, String(item.month));
+            }
+            else if (item.carryover !== undefined && category.is_income) {
+                refusal = new OutOfRangeRefusal(`Category "${item.categoryId}" is an income category, which cannot carry over. ` +
+                    'Nothing was written for this item.', String(item.categoryId));
+            }
+            if (refusal)
+                failed.push({ index, month: item.month, categoryId: item.categoryId, error: refusal.message });
+            else
+                toWrite.push({ index, item });
+        });
+        // Phase 2: one bracket, raw writes only.
+        if (toWrite.length > 0) {
+            const deadlineMs = config.ACTUAL_OP_TIMEOUT_MS > 0 ? config.ACTUAL_OP_TIMEOUT_MS * BUDGET_BATCH_DEADLINE_FRACTION : 0;
+            await withConcurrency(() => rawBatchBudgetUpdates(async () => {
+                for (const { index, item } of toWrite) {
+                    const ref = { index, month: item.month, categoryId: item.categoryId };
+                    if (deadlineMs > 0 && Date.now() - startedAt > deadlineMs) {
+                        failed.push({ ...ref, error: BUDGET_BATCH_DEADLINE_ERROR });
+                        continue;
+                    }
+                    let amountWritten = false;
+                    try {
+                        if (item.amount !== undefined) {
+                            await rawSetBudgetAmount(item.month, item.categoryId, item.amount);
+                            amountWritten = true;
+                        }
+                        if (item.carryover !== undefined) {
+                            await rawSetBudgetCarryover(item.month, item.categoryId, item.carryover);
+                        }
+                        succeeded.push(ref);
+                    }
+                    catch (error) {
+                        const msg = error instanceof Error ? error.message : String(error);
+                        // INFRASTRUCTURE ERRORS ARE NOT PER-ITEM FAILURES. queueWriteOperation sets
+                        // drainForceFullShutdown only when _shouldDropPoolOnError sees the error reach
+                        // it. Swallowing a dropped connection into `failed` would leave the dead pooled
+                        // connection in place for the next caller, so stop the loop and rethrow out of
+                        // the bracket (upstream closes it in a `finally`). The original message text is
+                        // kept so the pattern classification still matches. Rate-limit errors are not
+                        // pool-drop errors (see _shouldDropPoolOnError), so they stay per-item failures.
+                        if (_shouldDropPoolOnError(error)) {
+                            const applied = succeeded.map((x) => x.index).join(', ') || 'none';
+                            throw new Error(`Budget batch aborted after ${succeeded.length} of ${items.length} items (applied: ${applied}): ${msg}. ` +
+                                'Read back with actual_budgets_getMonth before retrying.');
+                        }
+                        failed.push({ ...ref, error: amountWritten ? `amount was applied, then the carryover failed: ${msg}` : msg });
+                    }
+                }
+            }));
+        }
+        succeeded.sort((a, b) => a.index - b.index);
+        failed.sort((a, b) => a.index - b.index);
+        return { succeeded, failed };
+    }, { preservesListings: ['accounts', 'categories', 'categoryGroups', 'payees'] });
 }
 /**
  * #355: RETURNS the upstream verdict instead of discarding it.
@@ -3660,6 +3929,7 @@ export default {
     deletePayee,
     getRules,
     createRule,
+    createRulesBatch,
     updateRule,
     deleteRule,
     upsertRule,
@@ -3672,7 +3942,7 @@ export default {
     deleteCategoryGroup,
     mergePayees,
     getPayeeRules,
-    batchBudgetUpdates,
+    setBudgetBatch,
     transferBudgetAmount,
     holdBudgetForNextMonth,
     resetBudgetHold,