actual-mcp-server 0.10.0 → 0.11.1

package/README.md

@@ -318,7 +318,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_accounts_reopen` | Reopen closed account |
 | `actual_accounts_get_balance` | Get account balance at a date |
 
-### Transactions (13)
+### Transactions (14)
 
 **Standard (6)**
 
@@ -333,11 +333,12 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 > **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.
 
-**Utility (1)**
+**Utility (2)**
 
 | Tool | Description |
 |------|-------------|
 | `actual_transactions_uncategorized` | Summary of uncategorized transactions (totalCount, totalAmount, per-account breakdown); pass `includeTransactions:true` for paginated rows |
+| `actual_transactions_update_batch` | Apply many transaction updates in ONE call (`updates: [{ id, fields }]`); returns per-item success and failure counts |
 
 **Exclusive ActualQL-powered (6)**, unique to this MCP server
 
@@ -413,10 +414,23 @@ 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 (4)
+### Rules (5)
 
 `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 |
+
+### Schedules (4)
+
+| Tool | Description |
+|------|-------------|
+| `actual_schedules_get` | List scheduled transactions, with their next occurrence date |
+| `actual_schedules_create` | Create a schedule (one-off or recurring); recurrence is a typed config, see `src/lib/schemas/recur.ts` |
+| `actual_schedules_update` | Update an existing schedule's amount, payee, account, or recurrence |
+| `actual_schedules_delete` | Delete a schedule |
+
 ### Advanced Query & Sync (2)
 
 | Tool | Description |
@@ -490,6 +504,8 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `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_SCOPES` | _(none)_ | No | Comma-separated required scopes; leave empty for Casdoor |
 | `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` | `sub` | No | Which OIDC claim is matched against Actual's user identity when the source is `actual`. `sub` matches Actual's `userId` and is strongly preferred; matching a name claim is riskier |
 | `MCP_ENABLE_HTTPS` | `false` | No | Enable native TLS. Requires `MCP_HTTPS_CERT` and `MCP_HTTPS_KEY` |
 | `MCP_HTTPS_CERT` | _(none)_ | No | Path to PEM certificate file (required when `MCP_ENABLE_HTTPS=true`) |
 | `MCP_HTTPS_KEY` | _(none)_ | No | Path to PEM private key file (required when `MCP_ENABLE_HTTPS=true`) |
@@ -644,6 +660,21 @@ OIDC_SCOPES=                    # leave empty for Casdoor
 - `GET /.well-known/oauth-protected-resource` (RFC 9728): identifies this server as a protected resource and points at your `OIDC_ISSUER` as the authorization server.
 - `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:
+
+```bash
+AUTH_BUDGET_ACL_SOURCE=actual   # default: static (the AUTH_BUDGET_ACL map)
+AUTH_BUDGET_ACL_CLAIM=sub       # default: sub, matched against Actual's userId
+```
+
+Three things to know before enabling it:
+
+- **It requires a multi-user Actual server**, meaning one configured with `ACTUAL_OPENID_*`. On a password-only server no named users exist and every principal resolves to nothing.
+- **Your Actual server must have been bootstrapped with a PASSWORD before OpenID was added.** This is a hard prerequisite of this MCP server generally, not just of this feature: `@actual-app/api` authenticates with a password, and an Actual server set up with OpenID from scratch refuses password login, so this server cannot connect to it at all. A password cannot be added afterwards.
+- **Keep `AUTH_BUDGET_ACL_CLAIM=sub` unless you have a specific reason not to.** `sub` is matched against Actual's stable `userId`. Matching a name-like claim instead is riskier: this server's own service account appears in every file's access list as the owner with a blank `userName`, so a principal whose name claim resolves to empty would match 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.
 
 ---
@@ -738,4 +769,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.10.0 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.11.1 | **Tool Count:** 74 (verified LibreChat-compatible)

package/dist/src/auth/budget-acl-dynamic.js

@@ -0,0 +1,155 @@
+// src/auth/budget-acl-dynamic.ts
+//
+// #338: derive the budget ACL from the Actual server's own per-file access list
+// instead of hand-maintained JSON, so revoking someone in Actual takes effect
+// here without a config edit and a restart.
+//
+// WHY userId AND NOT userName, verified against a live multi-user server.
+//
+// `getBudgets()` returns, per remote file:
+//
+//   "owner": "a6067f04-...",
+//   "usersWithAccess": [
+//     { "userId": "5311397e-...", "displayName": "Alice", "userName": "alice", "owner": false },
+//     { "userId": "a6067f04-...", "displayName": "",      "userName": "",      "owner": true  }
+//   ]
+//
+// That second row is THIS SERVER'S OWN service account. `@actual-app/api`
+// authenticates with a password, that password identity owns every file the API
+// creates, and it has no userName because it is not an OpenID user. So a blank
+// `userName` is present in every file's access list on every deployment.
+//
+// A name-based match therefore has a live escalation path: a principal whose
+// configured claim is missing or empty would match the blank row, which carries
+// `owner: true`, and be granted access to every file on the server. Matching
+// UUIDs makes that unrepresentable, because no IdP subject equals the service
+// account's UUID. AUTH_BUDGET_ACL_CLAIM still allows name matching for
+// deployments that need it, and the empty-principal guard below is what keeps
+// that option from reintroducing the hole.
+//
+// WHY THE RESOLUTION RUNS UNDER AN EXPLICIT WILDCARD CONTEXT.
+//
+// Resolving the ACL requires `adapter.getBudgets()`, and every adapter entry
+// point runs `_enforceBudgetAcl`, which refuses when the request context has no
+// allowedBudgets. Resolving the ACL would therefore be blocked by the ACL it is
+// trying to compute. We break that circularity by running ONLY this one call
+// inside `requestContext.run({ allowedBudgets: ['*'] }, ...)`.
+//
+// That is sound rather than a loophole: `getBudgets()` lists budget FILES
+// (name, id, who may access them). It reads no budget CONTENTS: no accounts, no
+// transactions, no balances. The wildcard is scoped to this single listing call
+// and never leaks into the caller's context, because AsyncLocalStorage restores
+// the previous store when the callback returns.
+import config from '../config.js';
+import adapter from '../lib/actual-adapter.js';
+import { requestContext } from '../lib/requestContext.js';
+import { createModuleLogger } from '../lib/loggerFactory.js';
+const log = createModuleLogger('ACL');
+/**
+ * Cache of principal to allowed sync IDs.
+ *
+ * Bounded by TTL rather than size: the key space is the set of authenticated
+ * principals, which is small and operator-controlled. A short TTL is what makes
+ * a revocation in Actual take effect here promptly; without it this feature
+ * would reintroduce exactly the staleness it exists to remove.
+ */
+const CACHE_TTL_MS = 60_000;
+const _cache = new Map();
+/** Clear the resolver cache (test helper, and used when config is re-read). */
+export function _resetDynamicAclCache() {
+    _cache.clear();
+}
+/**
+ * Extract the identity value to match on, from the claim named by
+ * AUTH_BUDGET_ACL_CLAIM. Returns null when the claim is absent or blank.
+ *
+ * Blank is deliberately null and not '': an empty string would compare equal to
+ * the service account's empty userName. See the header note.
+ */
+export function extractPrincipalValue(claims, subject, claimName) {
+    const raw = claimName === 'sub' ? (subject ?? claims['sub']) : claims[claimName];
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Map a getBudgets() payload to the sync IDs the given principal may access.
+ *
+ * Pure, so the matching rules are unit-testable against the captured live
+ * fixture without a server. Exported for that reason.
+ */
+export function matchAllowedFiles(files, principalValue, claimName) {
+    if (!Array.isArray(files))
+        return [];
+    // An empty principal can never match. Belt and braces: extractPrincipalValue
+    // already returns null for blank, but this function is exported and must not
+    // depend on its callers for that guarantee.
+    if (!principalValue)
+        return [];
+    const matchesName = claimName !== 'sub';
+    const allowed = new Set();
+    for (const entry of files) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        // groupId, NOT cloudFileId. See the BudgetFileEntry note: groupId is the
+        // "Sync ID" that _enforceBudgetAcl compares against.
+        const syncId = entry.groupId;
+        const access = entry.usersWithAccess;
+        if (!syncId || !Array.isArray(access))
+            continue;
+        for (const u of access) {
+            if (!u || typeof u !== 'object')
+                continue;
+            // Read the whole list, not only `owner: true`. A file shared with a
+            // household member appears with owner: false, and that is exactly the
+            // case this feature exists to honour.
+            const candidate = matchesName ? u.userName : u.userId;
+            if (typeof candidate !== 'string')
+                continue;
+            const trimmed = candidate.trim();
+            if (trimmed.length === 0)
+                continue; // never match the blank service-account row
+            if (trimmed === principalValue) {
+                allowed.add(syncId);
+                break;
+            }
+        }
+    }
+    return [...allowed];
+}
+/**
+ * Resolve the allowed sync IDs for a principal from the Actual server.
+ *
+ * FAILS CLOSED. Every error path returns [] (no access) rather than ['*'].
+ * An authorization source that opens up when the thing it queries is unreachable
+ * is worse than no authorization source at all.
+ */
+export async function resolveAllowedBudgetsFromActual(principalValue) {
+    if (!principalValue) {
+        log.warn('dynamic ACL: no usable principal value; denying', { claim: config.AUTH_BUDGET_ACL_CLAIM });
+        return [];
+    }
+    const cached = _cache.get(principalValue);
+    if (cached && Date.now() - cached.at < CACHE_TTL_MS)
+        return cached.allowed;
+    let files;
+    try {
+        // The scoped wildcard described in the header. Nothing outside this call
+        // observes it.
+        files = await requestContext.run({ allowedBudgets: ['*'] }, () => adapter.getBudgets());
+    }
+    catch (err) {
+        log.error('dynamic ACL: could not read the budget list; denying access', err);
+        return [];
+    }
+    const allowed = matchAllowedFiles(files, principalValue, config.AUTH_BUDGET_ACL_CLAIM);
+    if (allowed.length === 0) {
+        log.warn('dynamic ACL: principal matched no budget file', {
+            claim: config.AUTH_BUDGET_ACL_CLAIM,
+            fileCount: Array.isArray(files) ? files.length : 0,
+        });
+    }
+    _cache.set(principalValue, { at: Date.now(), allowed });
+    return allowed;
+}

package/dist/src/auth/budget-acl.js

@@ -24,6 +24,7 @@
 // to filter results by permitted sync IDs (forward-looking multi-budget support).
 import config from '../config.js';
 import logger from '../logger.js';
+import { extractPrincipalValue, resolveAllowedBudgetsFromActual } from './budget-acl-dynamic.js';
 // ---------------------------------------------------------------------------
 // ACL map (parsed once from env, cached)
 // ---------------------------------------------------------------------------
@@ -121,6 +122,12 @@ export function budgetAclMiddleware(req, res, next) {
         next();
         return;
     }
+    // #338: dynamic source. Deliberately a separate branch so the static path
+    // below is unreachable-by-default and byte-for-byte what it was before.
+    if (config.AUTH_BUDGET_ACL_SOURCE === 'actual') {
+        void resolveDynamicAcl(req, res, next);
+        return;
+    }
     const allowed = getAllowedBudgets(req);
     if (allowed.includes('*') || allowed.length > 0) {
         // Expose allowed budgets for use in tools
@@ -133,6 +140,39 @@ export function budgetAclMiddleware(req, res, next) {
     logger.warn(`[ACL] Access denied for '${identity}': no permitted budgets in ACL`);
     res.status(403).json({ error: 'Forbidden: no budget access configured for this user' });
 }
+/**
+ * #338: the async half of the middleware, for AUTH_BUDGET_ACL_SOURCE=actual.
+ *
+ * Split out rather than making budgetAclMiddleware itself async, because an
+ * async Express handler that rejects before Express 5's error plumbing sees it
+ * would hang the request. Here every path either calls next() or sends a
+ * response, and the catch is exhaustive, so a rejection cannot escape.
+ *
+ * The upstream read is cached per principal inside the resolver, so this is not
+ * an Actual API call per request.
+ */
+async function resolveDynamicAcl(req, res, next) {
+    const auth = req.auth;
+    const claims = (auth?.claims ?? {});
+    const subject = auth?.subject;
+    try {
+        const principalValue = extractPrincipalValue(claims, subject, config.AUTH_BUDGET_ACL_CLAIM);
+        const allowed = await resolveAllowedBudgetsFromActual(principalValue);
+        if (allowed.length > 0) {
+            req.allowedBudgets = allowed;
+            next();
+            return;
+        }
+        logger.warn(`[ACL] Access denied for '${subject ?? 'unknown'}': no budget files grant this principal access`);
+        res.status(403).json({ error: 'Forbidden: no budget access configured for this user' });
+    }
+    catch (err) {
+        // Fail closed. A resolver fault must never fall through to the static path
+        // or to an unrestricted context.
+        logger.error('[ACL] Dynamic ACL resolution failed; denying access', err);
+        res.status(403).json({ error: 'Forbidden: budget access could not be determined' });
+    }
+}
 /** Reset cached state (test helper). */
 export function _resetAclForTests() {
     _aclMap = null;

package/dist/src/config.js

@@ -95,6 +95,27 @@ export const configSchema = z.object({
     // Example: {"alice@example.com":["budget-1"],"group:admin":["*"]}
     // Leave unset to allow all authenticated users to access all budgets.
     AUTH_BUDGET_ACL: z.string().optional(),
+    // #338: where the budget ACL comes from.
+    //   'static' (default) = AUTH_BUDGET_ACL above, exactly as before.
+    //   'actual'           = derived from the Actual server's own per-file access
+    //                        list (`usersWithAccess` on getBudgets()).
+    // Opt-in on purpose. Two reasons: it moves the authorization source from local
+    // reviewable config to data the UPSTREAM server returns at runtime, and it only
+    // functions when that server runs in multi-user (OpenID) mode. Defaulting to
+    // 'static' means no existing deployment changes posture on upgrade.
+    AUTH_BUDGET_ACL_SOURCE: z.enum(['static', 'actual']).default('static'),
+    // #338: which OIDC claim is matched against Actual's user identity when
+    // AUTH_BUDGET_ACL_SOURCE=actual. Default 'sub', matched against `userId`.
+    //
+    // Do NOT casually change this to a name-like claim. Verified against a live
+    // multi-user server: the MCP server's own service account appears in EVERY
+    // file's usersWithAccess with `owner: true` and a BLANK `userName`. A
+    // name-based match whose claim resolves to empty would match that row and gain
+    // owner access to every file. Matching UUIDs makes that unrepresentable.
+    AUTH_BUDGET_ACL_CLAIM: z
+        .string()
+        .default('sub')
+        .refine((v) => /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(v), 'AUTH_BUDGET_ACL_CLAIM must be a simple claim name'),
 })
     // When native TLS is enabled, both the cert and key paths must be provided.
     // MCP_ENABLE_HTTPS is transformed to a boolean above, so this object-level

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

@@ -1302,7 +1302,20 @@ export async function updateRule(id, fields) {
         const fieldsObj = fields;
         const rule = {
             id,
-            stage: fieldsObj.stage ?? existingRule.stage,
+            // #342: `??` is WRONG for stage, and only for stage. null is a MEANINGFUL
+            // value here (Actual's normal stage), not an absent one, so
+            // `fieldsObj.stage ?? existingRule.stage` silently discards an explicit
+            // `stage: null` and leaves the rule where it was. That made it impossible
+            // to move a rule OUT of 'pre' or 'post' back to the normal stage, and it
+            // failed silently: the call still returned success.
+            //
+            // Decide on PRESENCE of the key instead. The tool clones its input with
+            // JSON.parse(JSON.stringify(...)), which preserves an explicit null key, so
+            // `in` distinguishes "not supplied" from "supplied as null" correctly.
+            //
+            // The other three fields keep `??` deliberately: none of them treats null
+            // as a distinct legal value, so nullish-coalescing is the right merge there.
+            stage: 'stage' in fieldsObj ? fieldsObj.stage : existingRule.stage,
             conditionsOp: fieldsObj.conditionsOp ?? existingRule.conditionsOp,
             conditions: fieldsObj.conditions ?? existingRule.conditions ?? [],
             actions: fieldsObj.actions ?? existingRule.actions ?? [],

package/dist/src/tools/rules_create.js

@@ -33,7 +33,29 @@ const FIELD_OPERATORS = {
     'date': { type: 'date', operators: ['is', 'gte', 'lte', 'gt', 'lt'] },
 };
 const InputSchema = z.object({
-    stage: z.enum(['pre', 'post']).optional().default('pre').describe('When to apply the rule - "pre" (before transactions sync) or "post" (after transactions sync)'),
+    // #342: three stages, and the default one is `null`, not a string.
+    //
+    // Verified against Actual's validator (transaction-rules.ts) and a live server:
+    // it accepts exactly 'pre', 'post' and null, and REJECTS the literal "default"
+    // with `Invalid rule stage: default`. The published API reference says
+    // pre/default/post, which is wrong in both directions (reported upstream as
+    // actualbudget/actual#8682).
+    //
+    // The default here MUST be null and must be SENT. Two traps:
+    //   - Defaulting to 'pre' (what this did until #342) silently puts every
+    //     MCP-created rule ahead of every rule the user made in the UI, because
+    //     Actual runs stages in the order pre, default, post. No error, no warning.
+    //   - Simply making it .optional() and omitting the key does NOT work: on a
+    //     create the validator always runs and rejects `undefined` with
+    //     `Invalid rule stage: undefined`.
+    stage: z
+        .enum(['pre', 'post'])
+        .nullable()
+        .optional()
+        .default(null)
+        .describe('When to apply the rule. null (the default) is Actual\'s normal stage, the one a rule gets in the UI ' +
+        'when no stage is chosen. "pre" runs before the default stage, "post" after. Leave unset unless you ' +
+        'specifically need the rule to out-rank or defer to the user\'s existing rules.'),
     conditionsOp: z.enum(['and', 'or']).optional().default('and').describe('How to combine multiple conditions'),
     conditions: z.array(ConditionSchema).describe('Array of conditions that must be met for the rule to apply'),
     actions: z.array(ActionSchema).describe('Array of actions to perform when conditions are met'),
@@ -49,10 +71,11 @@ IMPORTANT Field Types:
 - "notes", "description" (string) - for text matching. Supports: contains, matches, doesNotContain, is, isNot
 - "amount", "date" (number/date) - supports: is, gte, lte, gt, lt
 
-Stage options: 'pre' or 'post'.
+Stage: omit it (the normal stage, recommended), or 'pre' to run before the user's own rules, or 'post' to run after.
+Do NOT pass "default" as a string; Actual rejects it. The normal stage is null, which is what omitting gives you.
 Action operators: 'set', 'set-split-amount', 'link-schedule', 'append-notes'.
 
-Example: {stage: "post", conditionsOp: "and", conditions: [{field: "imported_payee", op: "contains", value: "Amazon"}], actions: [{op: "set", field: "category", value: "category-uuid"}]}`,
+Example (no stage, so the rule lands in the normal stage alongside the user's own rules): {conditionsOp: "and", conditions: [{field: "imported_payee", op: "contains", value: "Amazon"}], actions: [{op: "set", field: "category", value: "category-uuid"}]}`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         // Zod validation errors are formatted centrally by actualToolsManager (#206).

package/dist/src/tools/rules_create_or_update.js

@@ -55,7 +55,17 @@ const FIELD_OPERATORS = {
     'date': { type: 'date', operators: ['is', 'gte', 'lte', 'gt', 'lt'] },
 };
 const InputSchema = z.object({
-    stage: z.enum(['pre', 'post']).optional().default('pre').describe('When to apply the rule — "pre" or "post"'),
+    // #342: see the long note in rules_create.ts. null is Actual's DEFAULT stage;
+    // the literal "default" is rejected by the validator. No .default() here on
+    // purpose: this tool upserts, so "not supplied" must mean "leave the matched
+    // rule's stage alone", which is decided at the merge below. The create path
+    // supplies null explicitly.
+    stage: z
+        .enum(['pre', 'post'])
+        .nullable()
+        .optional()
+        .describe('When to apply the rule. null is Actual\'s normal stage (what the UI gives a rule with no stage chosen); ' +
+        '"pre" runs before it, "post" after. On an update, omitting this leaves the existing stage unchanged.'),
     conditionsOp: z.enum(['and', 'or']).optional().default('and').describe('How to combine multiple conditions'),
     conditions: z.array(ConditionSchema).describe('Array of conditions that must be met'),
     actions: z.array(ActionSchema).describe('Array of actions to perform when conditions match'),
@@ -102,7 +112,9 @@ const tool = {
 
 Matching logic: a rule is considered a "match" when it has the same set of conditions (field + op + value triples) and the same conditionsOp ("and"/"or"). Condition order is irrelevant.
 
-When a match is found: the rule's actions (and stage) are REPLACED with the new values.
+When a match is found: the rule's actions are REPLACED with the new values. The stage is replaced ONLY if you
+supply one; omit stage to leave the matched rule in whatever stage it is already in. On a newly created rule,
+an omitted stage means the normal stage (null), the same one the UI assigns.
 When no match exists: a new rule is created.
 
 IMPORTANT Field Types:
@@ -176,7 +188,13 @@ Returns: { id, created: boolean } — created=true if new rule was created, fals
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 const merged = {
                     id: matchedRule.id,
-                    stage: ruleData.stage ?? matchedRule.stage,
+                    // #342: `??` is WRONG for stage. null is a MEANINGFUL value here (Actual's
+                    // default stage), not an absent one, so `ruleData.stage ?? existing` would
+                    // silently discard an explicit `stage: null` and keep the old stage,
+                    // making it impossible to move a rule back to the default stage. Decide on
+                    // PRESENCE of the key instead. Every other field below is fine with `??`
+                    // because none of them treats null as a distinct legal value.
+                    stage: 'stage' in ruleData ? ruleData.stage : matchedRule.stage,
                     conditionsOp: ruleData.conditionsOp ?? matchedRule.conditionsOp,
                     conditions: ruleData.conditions ?? matchedRule.conditions ?? [],
                     actions: ruleData.actions ?? matchedRule.actions ?? [],
@@ -185,7 +203,13 @@ Returns: { id, created: boolean } — created=true if new rule was created, fals
                 return { id: matchedRule.id, created: false };
             }
             else {
-                // CREATE new rule
+                // CREATE new rule.
+                // #342: stage has no Zod default on this tool (see the schema note), so an
+                // omitted stage arrives as undefined. Actual's validator ALWAYS runs on a
+                // create and rejects undefined with `Invalid rule stage: undefined`, so the
+                // key must be present. null is the correct value: Actual's default stage.
+                if (ruleData.stage === undefined)
+                    ruleData.stage = null;
                 const rawId = await rawCreateRule(ruleData);
                 return { id: normalizeToId(rawId), created: true };
             }

package/dist/src/tools/rules_update.js

@@ -28,7 +28,17 @@ const FIELD_OPERATORS = {
 const InputSchema = z.object({
     id: z.string().describe('Rule ID to update'),
     fields: z.object({
-        stage: z.enum(['pre', 'post']).optional().describe('When to apply the rule - "pre" (before transactions sync) or "post" (after transactions sync)'),
+        // #342: null is Actual's DEFAULT stage; the literal "default" is rejected by
+        // its validator. Deliberately NO .default() here: this is a partial update, so
+        // omitting stage must leave the existing one alone. Actual only validates
+        // stage on an update when the key is present, so omitting it is safe (unlike
+        // on a create, where undefined is rejected).
+        stage: z
+            .enum(['pre', 'post'])
+            .nullable()
+            .optional()
+            .describe('When to apply the rule. null is Actual\'s normal stage (what the UI gives a rule with no stage chosen); ' +
+            '"pre" runs before it, "post" after. Omit to leave the rule\'s current stage unchanged.'),
         conditionsOp: z.enum(['and', 'or']).optional().describe('How to combine multiple conditions'),
         conditions: z.array(ConditionSchema).optional().describe('New array of conditions'),
         actions: z.array(ActionSchema).optional().describe('New array of actions'),
@@ -45,7 +55,9 @@ IMPORTANT Field Types:
 - "notes", "description" (string) - for text matching. Supports: contains, matches, doesNotContain, is, isNot
 - "amount", "date" (number/date) - supports: is, gte, lte, gt, lt
 
-Stage options: 'pre' or 'post'.
+Stage: omit it to leave the rule where it is. Pass null to move it to the normal stage (where UI-created
+rules live), 'pre' to run before that stage, or 'post' to run after. Do NOT pass "default" as a string;
+Actual rejects it.
 Action operators: 'set', 'set-split-amount', 'link-schedule', 'append-notes'.
 
 Do not include the rule ID in the fields object - it is provided separately.`,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/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/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.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/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_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.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/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/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/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/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/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",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/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/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.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/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_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.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/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/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/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/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/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/budget_acl_dynamic.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.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",