@oliverames/ynab-mcp-server 1.3.0 → 1.6.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://api.ynab.com/papi/logo_api_meadow.svg" alt="YNAB API" width="200">
+  <img src="assets/icon.png" width="80" height="80" alt="YNAB">
 </p>
 
 <h1 align="center">YNAB MCP Server</h1>
@@ -12,19 +12,21 @@
 <p align="center">
   <code>44 tools</code> &bull;
   <code>100% API coverage</code> &bull;
-  <code>YNAB API v1.82</code>
+  <code>YNAB API v1.83</code>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@oliverames/ynab-mcp-server"><img src="https://img.shields.io/npm/v/%40oliverames%2Fynab-mcp-server?style=flat-square&color=f5a542" alt="npm"></a>
+  <a href="https://github.com/oliverames/ynab-mcp-server/releases/tag/v1.4.0"><img src="https://img.shields.io/github/v/release/oliverames/ynab-mcp-server?style=flat-square&color=f5a542&label=MCPB" alt="MCPB release"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-f5a542?style=flat-square" alt="License"></a>
   <a href="https://www.buymeacoffee.com/oliverames"><img src="https://img.shields.io/badge/Buy_Me_a_Coffee-support-f5a542?style=flat-square&logo=buy-me-a-coffee&logoColor=white" alt="Buy Me a Coffee"></a>
 </p>
 
 <p align="center">
   <a href="#quick-start">Quick Start</a> &bull;
+  <a href="#install-with-mcpb">MCPB Download</a> &bull;
   <a href="#what-you-can-do">What You Can Do</a> &bull;
-  <a href="#tools-reference">All 43 Tools</a> &bull;
+  <a href="#tools-reference">All 44 Tools</a> &bull;
   <a href="#environment-variables">Configuration</a>
 </p>
 
@@ -32,7 +34,7 @@
 
 ## Why This Exists
 
-YNAB's budgeting philosophy works best when you interact with your budget frequently — but the app interface isn't designed for quick queries or bulk operations. "How much did I spend on groceries this month?" shouldn't require navigating three screens. "Categorize all my Amazon orders from this week" shouldn't be a manual, one-by-one process.
+YNAB's budgeting philosophy works best when you interact with your budget frequently - but the app interface isn't designed for quick queries or bulk operations. "How much did I spend on groceries this month?" shouldn't require navigating three screens. "Categorize all my Amazon orders from this week" shouldn't be a manual, one-by-one process.
 
 This server gives your AI assistant full access to YNAB's API, turning natural language into budget operations. All monetary values are automatically converted between dollars and YNAB's internal milliunits format so the AI never has to think about it. Built on the [official YNAB JavaScript SDK](https://github.com/ynab/ynab-sdk-js) with direct API calls for the newest endpoints (category creation, category groups, money movements) that the SDK hasn't caught up with yet.
 
@@ -40,6 +42,14 @@ This server gives your AI assistant full access to YNAB's API, turning natural l
 
 ## Quick Start
 
+### Install with MCPB
+
+For Claude Desktop and other MCPB-compatible clients, download the local bundle from the [v1.4.0 release](https://github.com/oliverames/ynab-mcp-server/releases/tag/v1.4.0):
+
+[Download `ynab-mcp-server-1.4.0.mcpb`](https://github.com/oliverames/ynab-mcp-server/releases/download/v1.4.0/ynab-mcp-server-1.4.0.mcpb)
+
+The bundle includes the YNAB favicon, production runtime dependencies, and setup prompts for your personal access token and optional default budget ID.
+
 ### 1. Get a YNAB Personal Access Token
 
 Go to [YNAB Developer Settings](https://app.ynab.com/settings/developer) and create a new personal access token.
@@ -121,7 +131,7 @@ That's it. Your AI can now talk to YNAB.
 
 ## Features
 
-**Complete YNAB API v1.82 coverage** with 44 tools:
+**Complete YNAB API v1.83 coverage** with 44 tools:
 
 | Resource | Tools | Capabilities |
 |----------|-------|-------------|
@@ -138,15 +148,17 @@ That's it. Your AI can now talk to YNAB.
 
 ### Design Decisions
 
-- **Dollar amounts everywhere** — inputs and outputs are in dollars (`-12.34`), never milliunits (`-12340`). Conversion is automatic and transparent.
-- **Smart budget resolution** — set `YNAB_BUDGET_ID` for a default, or omit it to auto-resolve to your last-used budget. Every tool accepts an optional `budgetId` override.
-- **Split transactions** — first-class support for subtransactions in create, read, and format operations.
-- **Bulk operations** — `create_transactions` and `update_transactions` handle arrays in a single API call.
-- **Fetch-then-merge updates** — scheduled transaction updates (which use PUT semantics) automatically fetch the current state and merge your changes, so you only specify what changed.
-- **Fuzzy search** — `search_categories` and `search_payees` do case-insensitive partial matching across all entries.
-- **Approval workflow** — `review_unapproved` groups transactions into "ready to approve" (categorized, split, or transfer) and "needs attention" (uncategorized), with a built-in warning against approving uncategorized entries.
-- **Nullable updates** — update tools accept `null` for clearable fields (`memo`, `payeeName`, `categoryId`, `flagColor`) to distinguish "don't change" (omit) from "clear this field" (`null`).
-- **Debt account support** — loan and debt accounts include `debt_original_balance`, `debt_interest_rates`, `debt_minimum_payments`, and `debt_escrow_amounts` with correct unit conversion (rates stay as percentages, payments convert from milliunits).
+- **Dollar amounts everywhere** - inputs and outputs are in dollars (`-12.34`), never milliunits (`-12340`). Conversion is automatic and transparent.
+- **Smart budget resolution** - set `YNAB_BUDGET_ID` for a default, or omit it to auto-resolve to your last-used budget. Every tool accepts an optional `budgetId` override.
+- **Split transactions** - first-class support for subtransactions in create, read, and format operations.
+- **Bulk operations** - `create_transactions` and `update_transactions` handle arrays in a single API call.
+- **Fetch-then-merge updates** - scheduled transaction updates (which use PUT semantics) automatically fetch the current state and merge your changes, so you only specify what changed.
+- **Fuzzy search** - `search_categories` and `search_payees` do case-insensitive partial matching across all entries.
+- **Approval workflow with anomaly flags** - `review_unapproved` groups transactions into "ready to approve" (categorized, split, or transfer) and "needs attention" (uncategorized), and attaches a `flags` array to each transaction surfacing anomalies: `manually_entered` (not bank-imported), `match_broken` (stale match reference), `scheduled_transaction_realized`, `new_payee`, `no_prior_amount_match` (novel amount for this payee), and `category_drift:was_X` (payee categorized differently in the prior 60 days). Group-level flags aggregate the union of all transaction flags.
+- **Nullable updates** - update tools accept `null` for clearable fields (`memo`, `payeeName`, `categoryId`, `flagColor`) to distinguish "don't change" (omit) from "clear this field" (`null`).
+- **Target behavior support** - category create/update tools expose `goalNeedsWholeAmount` for YNAB's "Set aside another" vs. "Refill up to" goal behavior.
+- **Delta request support** - high-volume list tools accept `lastKnowledgeOfServer` and return `server_knowledge` when that parameter is provided.
+- **Debt account support** - loan and debt accounts include `debt_original_balance`, `debt_interest_rates`, `debt_minimum_payments`, and `debt_escrow_amounts` with correct unit conversion (rates stay as percentages, payments convert from milliunits).
 
 ---
 
@@ -224,10 +236,10 @@ That's it. Your AI can now talk to YNAB.
 | Tool | Description |
 |------|-------------|
 | `get_transactions` | Get transactions with filters: by account, category, payee, month, or status (`unapproved`/`uncategorized`) |
-| `get_transaction` | Get a single transaction by ID (includes subtransactions) |
+| `get_transaction` | Get a single transaction by ID (includes subtransactions). Auto-handles composite scheduled-transaction IDs like `uuid_YYYY-MM-DD`. |
 | `create_transaction` | Create a transaction with optional split (subtransactions must sum to total) |
 | `create_transactions` | Bulk create multiple transactions in a single API call (supports split transactions) |
-| `update_transaction` | Partial update — only specified fields change |
+| `update_transaction` | Partial update - only specified fields change |
 | `update_transactions` | Batch update multiple transactions at once |
 | `delete_transaction` | Delete a transaction |
 | `import_transactions` | Trigger import from linked bank accounts |
@@ -248,7 +260,7 @@ That's it. Your AI can now talk to YNAB.
 
 | Tool | Description |
 |------|-------------|
-| `review_unapproved` | Get unapproved transactions grouped by readiness: "ready to approve" (categorized, split, or transfer) vs. "needs category first" (uncategorized). Includes a warning against blind approval. |
+| `review_unapproved` | Get unapproved transactions grouped by readiness: "ready to approve" (categorized, split, or transfer) vs. "needs category first" (uncategorized). Each transaction includes a `flags` array highlighting anomalies (manually_entered, match_broken, no_prior_amount_match, category_drift, new_payee, scheduled_transaction_realized) computed against 60 days of payee history. Includes a warning against blind approval. |
 
 ---
 
@@ -299,7 +311,7 @@ All amounts in tool inputs and outputs are in **dollars** (e.g., `-12.34` for a
 
 ## Rate Limiting
 
-The YNAB API allows **200 requests per hour** per access token, enforced on a rolling window. Each tool call typically uses one API request (except `update_scheduled_transaction` which uses two — a GET to fetch current state, then a PUT to merge changes). The server surfaces rate limit errors as standard MCP error responses.
+The YNAB API allows **200 requests per hour** per access token, enforced on a rolling window. Each tool call typically uses one API request (except `update_scheduled_transaction` which uses two - a GET to fetch current state, then a PUT to merge changes). The server surfaces rate limit errors as standard MCP error responses.
 
 ---
 
@@ -323,13 +335,15 @@ The YNAB API allows **200 requests per hour** per access token, enforced on a ro
 
 ## Testing
 
-The test suite (43 tests) runs against a live YNAB budget. It creates test data and cleans up after itself:
+The integration test suite runs against a live YNAB budget. Most write tests create temporary transactions and delete or restore them, but category and category group creation is not reversible through the public API and is skipped unless explicitly enabled.
 
 ```bash
 YNAB_API_TOKEN=your-token YNAB_BUDGET_ID=your-budget-id npm test
 ```
 
-Tests cover all tool categories: reads, writes, bulk operations, search, split transactions, scheduled transaction CRUD with fetch-then-merge verification, category/group creation, money movements, and payee locations.
+Use `YNAB_TEST_BUDGET_ID` to target a dedicated test budget without changing your server default. To include category and category group creation coverage, run with `YNAB_RUN_NONREVERSIBLE_TESTS=1`.
+
+Tests cover all tool categories: reads, reversible writes, bulk operations, search, split transactions, scheduled transaction CRUD with fetch-then-merge verification, money movements, and payee locations.
 
 ---
 
@@ -344,8 +358,8 @@ YNAB_API_TOKEN=your-token npm start
 
 ### Dependencies
 
-- [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) — MCP server framework
-- [`ynab`](https://www.npmjs.com/package/ynab) — Official YNAB JavaScript client
+- [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) - MCP server framework
+- [`ynab`](https://www.npmjs.com/package/ynab) - Official YNAB JavaScript client
 
 Zero additional dependencies. No build step. Pure ESM.
 

package/index.js

@@ -9,18 +9,22 @@ import * as ynab from "ynab";
 // --- Init ---
 
 let API_TOKEN = process.env.YNAB_API_TOKEN;
+let opLookupError;
 if (!API_TOKEN && process.env.YNAB_OP_PATH) {
   try {
     API_TOKEN = execFileSync(
       "op", ["read", process.env.YNAB_OP_PATH],
       { encoding: "utf-8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"] }
     ).trim();
-  } catch {
-    // 1Password CLI unavailable or item not found at YNAB_OP_PATH
+  } catch (e) {
+    opLookupError = e.stderr?.toString().trim() || e.message || "unknown 1Password CLI error";
   }
 }
 if (!API_TOKEN) {
-  console.error("YNAB_API_TOKEN environment variable is required. Set YNAB_OP_PATH to enable 1Password CLI fallback (e.g. op://Vault/Item/credential).");
+  const opMessage = process.env.YNAB_OP_PATH
+    ? ` Could not read YNAB_OP_PATH via 1Password CLI: ${opLookupError}.`
+    : " Set YNAB_OP_PATH to enable 1Password CLI fallback (e.g. op://Vault/Item/credential).";
+  console.error(`YNAB_API_TOKEN environment variable is required.${opMessage}`);
   process.exit(1);
 }
 
@@ -45,6 +49,16 @@ function dollarsMap(obj) {
   return obj ? Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, dollars(v)])) : obj;
 }
 
+function withCurrencyFields(out, source, fields) {
+  for (const field of fields) {
+    const formatted = `${field}_formatted`;
+    const currency = `${field}_currency`;
+    if (formatted in source) out[formatted] = source[formatted];
+    if (currency in source) out[currency] = source[currency];
+  }
+  return out;
+}
+
 function mapTransactionInput(t) {
   const out = {
     account_id: t.accountId,
@@ -71,7 +85,7 @@ function mapTransactionInput(t) {
   return out;
 }
 
-// Sparse patch mapper for update_transaction / update_transactions — only includes fields that were explicitly provided
+// Sparse patch mapper for update_transaction / update_transactions - only includes fields that were explicitly provided
 function mapTransactionUpdate(t) {
   const out = {};
   if (t.accountId  !== undefined) out.account_id  = t.accountId;
@@ -87,10 +101,22 @@ function mapTransactionUpdate(t) {
   return out;
 }
 
+// YNAB scheduled transactions that realize get composite IDs like `uuid_YYYY-MM-DD`.
+// Strip the date suffix so API lookups work correctly.
+function normalizeTransactionId(id) {
+  return id.replace(/_\d{4}-\d{2}-\d{2}$/, "");
+}
+
 function ok(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
 
+function collection(data, key, items, lastKnowledgeOfServer) {
+  return lastKnowledgeOfServer === undefined
+    ? items
+    : { [key]: items, server_knowledge: data.server_knowledge };
+}
+
 async function run(fn) {
   try {
     return await fn();
@@ -106,14 +132,19 @@ async function run(fn) {
 
 // Direct API helper for endpoints not yet in the ynab SDK
 const BASE_URL = "https://api.ynab.com/v1";
-async function ynabFetch(path, { method = "GET", body } = {}) {
+async function ynabFetch(path, { method = "GET", body, query } = {}) {
+  const url = new URL(`${BASE_URL}${path}`);
+  for (const [key, value] of Object.entries(query || {})) {
+    if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+  }
   const opts = {
     method,
     headers: { Authorization: `Bearer ${API_TOKEN}`, "Content-Type": "application/json" },
   };
   if (body) opts.body = JSON.stringify(body);
-  const res = await fetch(`${BASE_URL}${path}`, opts);
-  const json = await res.json();
+  const res = await fetch(url, opts);
+  const text = await res.text();
+  const json = text ? JSON.parse(text) : {};
   if (!res.ok) {
     const err = new Error(json?.error?.detail || `HTTP ${res.status}`);
     err.error = json?.error;
@@ -126,7 +157,7 @@ async function ynabFetch(path, { method = "GET", body } = {}) {
 
 const server = new McpServer({
   name: "ynab-mcp-server",
-  version: "1.3.0",
+  version: "1.6.0",
 });
 
 // ==================== User & Budgets ====================
@@ -212,16 +243,20 @@ function formatAccount(a) {
     deleted: a.deleted,
   };
   if ("note" in a) out.note = a.note;
-  return out;
+  return withCurrencyFields(out, a, ["balance", "cleared_balance", "uncleared_balance"]);
 }
 
 server.registerTool(
   "list_accounts",
-  { description: "List all accounts in a budget", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
-  ({ budgetId }) =>
+  { description: "List all accounts in a budget", inputSchema: {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    lastKnowledgeOfServer: z.number().int().nonnegative().optional().describe("Delta request server knowledge. When provided, returns { accounts, server_knowledge }."),
+  } },
+  ({ budgetId, lastKnowledgeOfServer }) =>
     run(async () => {
-      const { data } = await api.accounts.getAccounts(resolveBudgetId(budgetId));
-      return ok(data.accounts.map(formatAccount));
+      const { data } = await api.accounts.getAccounts(resolveBudgetId(budgetId), lastKnowledgeOfServer);
+      const accounts = data.accounts.map(formatAccount);
+      return ok(collection(data, "accounts", accounts, lastKnowledgeOfServer));
     })
 );
 
@@ -258,7 +293,7 @@ server.registerTool(
 // ==================== Categories ====================
 
 function formatCategory(c) {
-  return {
+  const out = {
     id: c.id,
     category_group_id: c.category_group_id,
     category_group_name: c.category_group_name,
@@ -275,6 +310,7 @@ function formatCategory(c) {
     goal_cadence_frequency: c.goal_cadence_frequency,
     goal_creation_month: c.goal_creation_month,
     goal_target: dollars(c.goal_target),
+    goal_target_month: c.goal_target_month,
     goal_target_date: c.goal_target_date,
     goal_percentage_complete: c.goal_percentage_complete,
     goal_months_to_budget: c.goal_months_to_budget,
@@ -282,34 +318,53 @@ function formatCategory(c) {
     goal_overall_funded: dollars(c.goal_overall_funded),
     goal_overall_left: dollars(c.goal_overall_left),
     goal_needs_whole_amount: c.goal_needs_whole_amount,
+    goal_snoozed_at: c.goal_snoozed_at,
     deleted: c.deleted,
   };
+  return withCurrencyFields(out, c, [
+    "budgeted",
+    "activity",
+    "balance",
+    "goal_target",
+    "goal_under_funded",
+    "goal_overall_funded",
+    "goal_overall_left",
+  ]);
 }
 
 server.registerTool(
   "list_categories",
-  { description: "List all category groups and their categories", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
-  ({ budgetId }) =>
+  { description: "List all category groups and their categories", inputSchema: {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    lastKnowledgeOfServer: z.number().int().nonnegative().optional().describe("Delta request server knowledge. When provided, returns { category_groups, server_knowledge }."),
+  } },
+  ({ budgetId, lastKnowledgeOfServer }) =>
     run(async () => {
-      const { data } = await api.categories.getCategories(resolveBudgetId(budgetId));
-      return ok(
-        data.category_groups.map((g) => ({
+      const { data } = await api.categories.getCategories(resolveBudgetId(budgetId), lastKnowledgeOfServer);
+      const categoryGroups = data.category_groups.map((g) => ({
           id: g.id,
           name: g.name,
           hidden: g.hidden,
           deleted: g.deleted,
-          categories: g.categories.map((c) => ({
-            id: c.id,
-            name: c.name,
-            hidden: c.hidden,
-            budgeted: dollars(c.budgeted),
-            activity: dollars(c.activity),
-            balance: dollars(c.balance),
-            goal_type: c.goal_type,
-            deleted: c.deleted,
-          })),
-        }))
-      );
+          categories: g.categories.map((c) =>
+            withCurrencyFields(
+              {
+                id: c.id,
+                name: c.name,
+                hidden: c.hidden,
+                budgeted: dollars(c.budgeted),
+                activity: dollars(c.activity),
+                balance: dollars(c.balance),
+                goal_type: c.goal_type,
+                goal_needs_whole_amount: c.goal_needs_whole_amount,
+                deleted: c.deleted,
+              },
+              c,
+              ["budgeted", "activity", "balance"]
+            )
+          ),
+        }));
+      return ok(collection(data, "category_groups", categoryGroups, lastKnowledgeOfServer));
     })
 );
 
@@ -367,8 +422,9 @@ server.registerTool(
     categoryGroupId: z.string().optional().describe("Move to a different category group"),
     goalTarget: z.number().nullable().optional().describe("Goal target amount in dollars (only if category already has a goal)"),
     goalTargetDate: z.string().nullable().optional().describe("Goal target date in ISO format (e.g. 2026-12-01, null to clear)"),
+    goalNeedsWholeAmount: z.boolean().nullable().optional().describe("For NEED goals, true uses 'Set aside another' behavior and false uses 'Refill up to' behavior"),
   } },
-  ({ budgetId, categoryId, name, note, categoryGroupId, goalTarget, goalTargetDate }) =>
+  ({ budgetId, categoryId, name, note, categoryGroupId, goalTarget, goalTargetDate, goalNeedsWholeAmount }) =>
     run(async () => {
       const cat = {};
       if (name !== undefined) cat.name = name;
@@ -376,9 +432,11 @@ server.registerTool(
       if (categoryGroupId !== undefined) cat.category_group_id = categoryGroupId;
       if (goalTarget !== undefined) cat.goal_target = goalTarget != null ? milliunits(goalTarget) : null;
       if (goalTargetDate !== undefined) cat.goal_target_date = goalTargetDate;
+      if (goalNeedsWholeAmount !== undefined) cat.goal_needs_whole_amount = goalNeedsWholeAmount;
 
-      const { data } = await api.categories.updateCategory(resolveBudgetId(budgetId), categoryId, {
-        category: cat,
+      const data = await ynabFetch(`/plans/${resolveBudgetId(budgetId)}/categories/${categoryId}`, {
+        method: "PATCH",
+        body: { category: cat },
       });
       return ok(formatCategory(data.category));
     })
@@ -393,15 +451,17 @@ server.registerTool(
     note: z.string().optional().describe("Category note"),
     goalTarget: z.number().optional().describe("Goal target amount in dollars (creates a 'Needed for Spending' goal)"),
     goalTargetDate: z.string().optional().describe("Goal target date in ISO format (e.g. 2026-12-01)"),
+    goalNeedsWholeAmount: z.boolean().optional().describe("For NEED goals, true uses 'Set aside another' behavior and false uses 'Refill up to' behavior"),
   } },
-  ({ budgetId, categoryGroupId, name, note, goalTarget, goalTargetDate }) =>
+  ({ budgetId, categoryGroupId, name, note, goalTarget, goalTargetDate, goalNeedsWholeAmount }) =>
     run(async () => {
       const bid = resolveBudgetId(budgetId);
       const cat = { category_group_id: categoryGroupId, name };
       if (note !== undefined) cat.note = note;
       if (goalTarget !== undefined) cat.goal_target = milliunits(goalTarget);
       if (goalTargetDate !== undefined) cat.goal_target_date = goalTargetDate;
-      const data = await ynabFetch(`/budgets/${bid}/categories`, {
+      if (goalNeedsWholeAmount !== undefined) cat.goal_needs_whole_amount = goalNeedsWholeAmount;
+      const data = await ynabFetch(`/plans/${bid}/categories`, {
         method: "POST",
         body: { category: cat },
       });
@@ -417,7 +477,7 @@ server.registerTool(
   } },
   ({ budgetId, name }) =>
     run(async () => {
-      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/category_groups`, {
+      const data = await ynabFetch(`/plans/${resolveBudgetId(budgetId)}/category_groups`, {
         method: "POST",
         body: { category_group: { name } },
       });
@@ -434,7 +494,7 @@ server.registerTool(
   } },
   ({ budgetId, categoryGroupId, name }) =>
     run(async () => {
-      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/category_groups/${categoryGroupId}`, {
+      const data = await ynabFetch(`/plans/${resolveBudgetId(budgetId)}/category_groups/${categoryGroupId}`, {
         method: "PATCH",
         body: { category_group: { name } },
       });
@@ -446,11 +506,15 @@ server.registerTool(
 
 server.registerTool(
   "list_payees",
-  { description: "List all payees", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
-  ({ budgetId }) =>
+  { description: "List all payees", inputSchema: {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    lastKnowledgeOfServer: z.number().int().nonnegative().optional().describe("Delta request server knowledge. When provided, returns { payees, server_knowledge }."),
+  } },
+  ({ budgetId, lastKnowledgeOfServer }) =>
     run(async () => {
-      const { data } = await api.payees.getPayees(resolveBudgetId(budgetId));
-      return ok(data.payees.map((p) => ({ id: p.id, name: p.name, transfer_account_id: p.transfer_account_id, deleted: p.deleted })));
+      const { data } = await api.payees.getPayees(resolveBudgetId(budgetId), lastKnowledgeOfServer);
+      const payees = data.payees.map((p) => ({ id: p.id, name: p.name, transfer_account_id: p.transfer_account_id, deleted: p.deleted }));
+      return ok(collection(data, "payees", payees, lastKnowledgeOfServer));
     })
 );
 
@@ -491,7 +555,7 @@ server.registerTool(
   } },
   ({ budgetId, name }) =>
     run(async () => {
-      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/payees`, {
+      const data = await ynabFetch(`/plans/${resolveBudgetId(budgetId)}/payees`, {
         method: "POST",
         body: { payee: { name } },
       });
@@ -541,22 +605,30 @@ server.registerTool(
 
 server.registerTool(
   "list_months",
-  { description: "List all budget months", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
-  ({ budgetId }) =>
+  { description: "List all budget months", inputSchema: {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    lastKnowledgeOfServer: z.number().int().nonnegative().optional().describe("Delta request server knowledge. When provided, returns { months, server_knowledge }."),
+  } },
+  ({ budgetId, lastKnowledgeOfServer }) =>
     run(async () => {
-      const { data } = await api.months.getBudgetMonths(resolveBudgetId(budgetId));
-      return ok(
-        data.months.map((m) => ({
-          month: m.month,
-          note: m.note,
-          income: dollars(m.income),
-          budgeted: dollars(m.budgeted),
-          activity: dollars(m.activity),
-          to_be_budgeted: dollars(m.to_be_budgeted),
-          age_of_money: m.age_of_money,
-          deleted: m.deleted,
-        }))
-      );
+      const { data } = await api.months.getBudgetMonths(resolveBudgetId(budgetId), lastKnowledgeOfServer);
+      const months = data.months.map((m) =>
+          withCurrencyFields(
+            {
+              month: m.month,
+              note: m.note,
+              income: dollars(m.income),
+              budgeted: dollars(m.budgeted),
+              activity: dollars(m.activity),
+              to_be_budgeted: dollars(m.to_be_budgeted),
+              age_of_money: m.age_of_money,
+              deleted: m.deleted,
+            },
+            m,
+            ["income", "budgeted", "activity", "to_be_budgeted"]
+          )
+        );
+      return ok(collection(data, "months", months, lastKnowledgeOfServer));
     })
 );
 
@@ -570,7 +642,7 @@ server.registerTool(
     run(async () => {
       const { data } = await api.months.getBudgetMonth(resolveBudgetId(budgetId), month);
       const m = data.month;
-      return ok({
+      const out = {
         month: m.month,
         note: m.note,
         income: dollars(m.income),
@@ -579,27 +651,38 @@ server.registerTool(
         to_be_budgeted: dollars(m.to_be_budgeted),
         age_of_money: m.age_of_money,
         deleted: m.deleted,
-        categories: m.categories?.map((c) => ({
-          id: c.id,
-          name: c.name,
-          hidden: c.hidden,
-          category_group_name: c.category_group_name,
-          budgeted: dollars(c.budgeted),
-          activity: dollars(c.activity),
-          balance: dollars(c.balance),
-          goal_type: c.goal_type,
-          goal_target: dollars(c.goal_target),
-          goal_under_funded: dollars(c.goal_under_funded),
-          deleted: c.deleted,
-        })),
-      });
+        categories: m.categories?.map((c) =>
+          withCurrencyFields(
+            {
+              id: c.id,
+              name: c.name,
+              hidden: c.hidden,
+              category_group_name: c.category_group_name,
+              budgeted: dollars(c.budgeted),
+              activity: dollars(c.activity),
+              balance: dollars(c.balance),
+              goal_type: c.goal_type,
+              goal_needs_whole_amount: c.goal_needs_whole_amount,
+              goal_target: dollars(c.goal_target),
+              goal_target_month: c.goal_target_month,
+              goal_target_date: c.goal_target_date,
+              goal_under_funded: dollars(c.goal_under_funded),
+              goal_snoozed_at: c.goal_snoozed_at,
+              deleted: c.deleted,
+            },
+            c,
+            ["budgeted", "activity", "balance", "goal_target", "goal_under_funded"]
+          )
+        ),
+      };
+      return ok(withCurrencyFields(out, m, ["income", "budgeted", "activity", "to_be_budgeted"]));
     })
 );
 
 // ==================== Money Movements ====================
 
 function formatMoneyMovement(m) {
-  return {
+  return withCurrencyFields({
     id: m.id,
     month: m.month,
     moved_at: m.moved_at,
@@ -610,7 +693,7 @@ function formatMoneyMovement(m) {
     to_category_id: m.to_category_id,
     amount: dollars(m.amount),
     deleted: m.deleted,
-  };
+  }, m, ["amount"]);
 }
 
 server.registerTool(
@@ -618,7 +701,7 @@ server.registerTool(
   { description: "List all money movements (budget re-allocations between categories)", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
   ({ budgetId }) =>
     run(async () => {
-      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/money_movements`);
+      const data = await ynabFetch(`/plans/${resolveBudgetId(budgetId)}/money_movements`);
       return ok(data.money_movements.map(formatMoneyMovement));
     })
 );
@@ -631,7 +714,7 @@ server.registerTool(
   } },
   ({ budgetId, month }) =>
     run(async () => {
-      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/months/${month}/money_movements`);
+      const data = await ynabFetch(`/plans/${resolveBudgetId(budgetId)}/months/${month}/money_movements`);
       return ok(data.money_movements.map(formatMoneyMovement));
     })
 );
@@ -641,7 +724,7 @@ server.registerTool(
   { description: "List all money movement groups (batches of related money movements)", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
   ({ budgetId }) =>
     run(async () => {
-      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/money_movement_groups`);
+      const data = await ynabFetch(`/plans/${resolveBudgetId(budgetId)}/money_movement_groups`);
       return ok(data.money_movement_groups);
     })
 );
@@ -654,7 +737,7 @@ server.registerTool(
   } },
   ({ budgetId, month }) =>
     run(async () => {
-      const data = await ynabFetch(`/budgets/${resolveBudgetId(budgetId)}/months/${month}/money_movement_groups`);
+      const data = await ynabFetch(`/plans/${resolveBudgetId(budgetId)}/months/${month}/money_movement_groups`);
       return ok(data.money_movement_groups);
     })
 );
@@ -662,43 +745,50 @@ server.registerTool(
 // ==================== Transactions ====================
 
 function formatTransaction(t) {
-  return {
+  const out = {
     id: t.id,
     date: t.date,
     amount: dollars(t.amount),
-    memo: t.memo,
+    memo: t.memo ?? null,
     cleared: t.cleared,
     approved: t.approved,
-    flag_color: t.flag_color,
-    flag_name: t.flag_name,
+    flag_color: t.flag_color ?? null,
+    flag_name: t.flag_name ?? null,
     account_id: t.account_id,
     account_name: t.account_name,
-    payee_id: t.payee_id,
-    payee_name: t.payee_name,
-    category_id: t.category_id,
-    category_name: t.category_name,
-    transfer_account_id: t.transfer_account_id,
-    transfer_transaction_id: t.transfer_transaction_id,
-    matched_transaction_id: t.matched_transaction_id,
-    import_id: t.import_id,
-    import_payee_name: t.import_payee_name,
-    import_payee_name_original: t.import_payee_name_original,
-    debt_transaction_type: t.debt_transaction_type,
+    payee_id: t.payee_id ?? null,
+    payee_name: t.payee_name ?? null,
+    category_id: t.category_id ?? null,
+    category_name: t.category_name ?? null,
+    transfer_account_id: t.transfer_account_id ?? null,
+    transfer_transaction_id: t.transfer_transaction_id ?? null,
+    matched_transaction_id: t.matched_transaction_id ?? null,
+    import_id: t.import_id ?? null,
+    import_payee_name: t.import_payee_name ?? null,
+    import_payee_name_original: t.import_payee_name_original ?? null,
+    debt_transaction_type: t.debt_transaction_type ?? null,
     deleted: t.deleted,
-    subtransactions: t.subtransactions?.map((s) => ({
-      id: s.id,
-      transaction_id: s.transaction_id,
-      amount: dollars(s.amount),
-      memo: s.memo,
-      payee_id: s.payee_id,
-      payee_name: s.payee_name,
-      category_id: s.category_id,
-      category_name: s.category_name,
-      transfer_account_id: s.transfer_account_id,
-      transfer_transaction_id: s.transfer_transaction_id,
-      deleted: s.deleted,
-    })),
+    subtransactions: t.subtransactions?.map((s) =>
+      withCurrencyFields(
+        {
+          id: s.id,
+          transaction_id: s.transaction_id,
+          amount: dollars(s.amount),
+          memo: s.memo ?? null,
+          payee_id: s.payee_id ?? null,
+          payee_name: s.payee_name ?? null,
+          category_id: s.category_id ?? null,
+          category_name: s.category_name ?? null,
+          transfer_account_id: s.transfer_account_id ?? null,
+          transfer_transaction_id: s.transfer_transaction_id ?? null,
+          deleted: s.deleted,
+        },
+        s,
+        ["amount"]
+      )
+    ),
   };
+  return withCurrencyFields(out, t, ["amount"]);
 }
 
 server.registerTool(
@@ -711,49 +801,55 @@ server.registerTool(
     categoryId: z.string().optional().describe("Filter by category ID"),
     payeeId: z.string().optional().describe("Filter by payee ID"),
     month: z.string().optional().describe("Filter by month (YYYY-MM-DD, first of month)"),
+    lastKnowledgeOfServer: z.number().int().nonnegative().optional().describe("Delta request server knowledge. When provided, returns { transactions, server_knowledge }."),
   } },
-  ({ budgetId, sinceDate, type, accountId, categoryId, payeeId, month }) =>
+  ({ budgetId, sinceDate, type, accountId, categoryId, payeeId, month, lastKnowledgeOfServer }) =>
     run(async () => {
       const bid = resolveBudgetId(budgetId);
       let transactions;
+      let data;
+      const resourceFilters = [accountId, categoryId, payeeId, month].filter((value) => value !== undefined && value !== null && value !== "");
+      if (resourceFilters.length > 1) {
+        throw new Error("Provide only one of accountId, categoryId, payeeId, or month.");
+      }
 
       if (accountId) {
-        const { data } = await api.transactions.getTransactionsByAccount(bid, accountId, sinceDate, type);
+        ({ data } = await api.transactions.getTransactionsByAccount(bid, accountId, sinceDate, type, lastKnowledgeOfServer));
         transactions = data.transactions;
       } else if (categoryId) {
-        const { data } = await api.transactions.getTransactionsByCategory(bid, categoryId, sinceDate, type);
+        ({ data } = await api.transactions.getTransactionsByCategory(bid, categoryId, sinceDate, type, lastKnowledgeOfServer));
         transactions = data.transactions;
       } else if (payeeId) {
-        const { data } = await api.transactions.getTransactionsByPayee(bid, payeeId, sinceDate, type);
+        ({ data } = await api.transactions.getTransactionsByPayee(bid, payeeId, sinceDate, type, lastKnowledgeOfServer));
         transactions = data.transactions;
       } else if (month) {
-        const { data } = await api.transactions.getTransactionsByMonth(bid, month, sinceDate, type);
+        ({ data } = await api.transactions.getTransactionsByMonth(bid, month, sinceDate, type, lastKnowledgeOfServer));
         transactions = data.transactions;
       } else {
-        const { data } = await api.transactions.getTransactions(bid, sinceDate, type);
+        ({ data } = await api.transactions.getTransactions(bid, sinceDate, type, lastKnowledgeOfServer));
         transactions = data.transactions;
       }
 
-      return ok(transactions.map(formatTransaction));
+      return ok(collection(data, "transactions", transactions.map(formatTransaction), lastKnowledgeOfServer));
     })
 );
 
 server.registerTool(
   "get_transaction",
-  { description: "Get a single transaction by ID", inputSchema: {
+  { description: "Get a single transaction by ID. Automatically handles composite scheduled-transaction IDs (e.g. uuid_YYYY-MM-DD).", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
     transactionId: z.string().describe("Transaction ID"),
   } },
   ({ budgetId, transactionId }) =>
     run(async () => {
-      const { data } = await api.transactions.getTransactionById(resolveBudgetId(budgetId), transactionId);
+      const { data } = await api.transactions.getTransactionById(resolveBudgetId(budgetId), normalizeTransactionId(transactionId));
       return ok(formatTransaction(data.transaction));
     })
 );
 
 server.registerTool(
   "create_transaction",
-  { description: "Create a new transaction. Amounts are in dollars (positive for inflows, negative for outflows). Note: future-dated transactions cannot be created here — use create_scheduled_transaction instead.", inputSchema: {
+  { description: "Create a new transaction. Amounts are in dollars (positive for inflows, negative for outflows). Note: future-dated transactions cannot be created here - use create_scheduled_transaction instead.", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
     accountId: z.string().describe("Account ID"),
     date: z.string().describe("Transaction date (YYYY-MM-DD)"),
@@ -785,7 +881,7 @@ server.registerTool(
 
 server.registerTool(
   "create_transactions",
-  { description: "Create multiple transactions at once. Amounts are in dollars. Returns created transactions and any duplicate import IDs. Future-dated transactions are not supported — use create_scheduled_transaction instead.", inputSchema: {
+  { description: "Create multiple transactions at once. Amounts are in dollars. Returns created transactions and any duplicate import IDs. Future-dated transactions are not supported - use create_scheduled_transaction instead.", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
     transactions: z.array(z.object({
       accountId: z.string().describe("Account ID"),
@@ -906,45 +1002,56 @@ server.registerTool(
 // ==================== Scheduled Transactions ====================
 
 function formatScheduledTransaction(t) {
-  return {
+  const out = {
     id: t.id,
     date_first: t.date_first,
     date_next: t.date_next,
     frequency: t.frequency,
     amount: dollars(t.amount),
-    memo: t.memo,
-    flag_color: t.flag_color,
-    flag_name: t.flag_name,
+    memo: t.memo ?? null,
+    flag_color: t.flag_color ?? null,
+    flag_name: t.flag_name ?? null,
     account_id: t.account_id,
     account_name: t.account_name,
-    payee_id: t.payee_id,
-    payee_name: t.payee_name,
-    category_id: t.category_id,
-    category_name: t.category_name,
-    transfer_account_id: t.transfer_account_id,
+    payee_id: t.payee_id ?? null,
+    payee_name: t.payee_name ?? null,
+    category_id: t.category_id ?? null,
+    category_name: t.category_name ?? null,
+    transfer_account_id: t.transfer_account_id ?? null,
     deleted: t.deleted,
-    subtransactions: t.subtransactions?.map((s) => ({
-      id: s.id,
-      scheduled_transaction_id: s.scheduled_transaction_id,
-      amount: dollars(s.amount),
-      memo: s.memo,
-      payee_id: s.payee_id,
-      payee_name: s.payee_name,
-      category_id: s.category_id,
-      category_name: s.category_name,
-      transfer_account_id: s.transfer_account_id,
-      deleted: s.deleted,
-    })),
+    subtransactions: t.subtransactions?.map((s) =>
+      withCurrencyFields(
+        {
+          id: s.id,
+          scheduled_transaction_id: s.scheduled_transaction_id,
+          amount: dollars(s.amount),
+          memo: s.memo ?? null,
+          payee_id: s.payee_id ?? null,
+          payee_name: s.payee_name ?? null,
+          category_id: s.category_id ?? null,
+          category_name: s.category_name ?? null,
+          transfer_account_id: s.transfer_account_id ?? null,
+          deleted: s.deleted,
+        },
+        s,
+        ["amount"]
+      )
+    ),
   };
+  return withCurrencyFields(out, t, ["amount"]);
 }
 
 server.registerTool(
   "list_scheduled_transactions",
-  { description: "List all scheduled (recurring) transactions", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
-  ({ budgetId }) =>
+  { description: "List all scheduled (recurring) transactions. NOTE: only manually-created recurring entries appear here — auto-imported recurring charges (subscriptions, utilities, insurance) are NOT included. Use prior-month transaction history to identify recurring charge timing instead.", inputSchema: {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    lastKnowledgeOfServer: z.number().int().nonnegative().optional().describe("Delta request server knowledge. When provided, returns { scheduled_transactions, server_knowledge }."),
+  } },
+  ({ budgetId, lastKnowledgeOfServer }) =>
     run(async () => {
-      const { data } = await api.scheduledTransactions.getScheduledTransactions(resolveBudgetId(budgetId));
-      return ok(data.scheduled_transactions.map(formatScheduledTransaction));
+      const { data } = await api.scheduledTransactions.getScheduledTransactions(resolveBudgetId(budgetId), lastKnowledgeOfServer);
+      const scheduledTransactions = data.scheduled_transactions.map(formatScheduledTransaction);
+      return ok(collection(data, "scheduled_transactions", scheduledTransactions, lastKnowledgeOfServer));
     })
 );
 
@@ -1012,7 +1119,7 @@ server.registerTool(
   ({ budgetId, scheduledTransactionId, accountId, date, frequency, amount, payeeId, payeeName, categoryId, memo, flagColor }) =>
     run(async () => {
       const bid = resolveBudgetId(budgetId);
-      // PUT replaces the full resource — fetch current values to merge with updates
+      // PUT replaces the full resource - fetch current values to merge with updates
       const { data: current } = await api.scheduledTransactions.getScheduledTransactionById(bid, scheduledTransactionId);
       const existing = current.scheduled_transaction;
 
@@ -1068,14 +1175,14 @@ server.registerTool(
         for (const c of g.categories) {
           if (c.hidden) continue;
           if (c.name.toLowerCase().includes(q)) {
-            matches.push({
+            matches.push(withCurrencyFields({
               id: c.id,
               name: c.name,
               group: g.name,
               budgeted: dollars(c.budgeted),
               activity: dollars(c.activity),
               balance: dollars(c.balance),
-            });
+            }, c, ["budgeted", "activity", "balance"]));
           }
         }
       }
@@ -1104,21 +1211,91 @@ server.registerTool(
 
 server.registerTool(
   "review_unapproved",
-  { description: "Get all unapproved transactions grouped by status: those already categorized (ready to approve) and those still uncategorized (need category first). Never approve uncategorized transactions without explicit user instruction.", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
+  { description: "Get all unapproved transactions grouped by status: those already categorized (ready to approve) and those still uncategorized (need category first). Each transaction includes a 'flags' array: manually_entered (not bank-imported), match_broken (matched reference may be stale), scheduled_transaction_realized, new_payee (no transaction history for this payee), no_prior_amount_match (novel amount for this payee), category_drift:was_X (payee categorized differently before). Never approve uncategorized transactions without explicit user instruction.", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
   ({ budgetId }) =>
     run(async () => {
-      const { data } = await api.transactions.getTransactions(resolveBudgetId(budgetId), undefined, "unapproved");
-      const txns = data.transactions.map(formatTransaction);
+      const bid = resolveBudgetId(budgetId);
+
+      // Fetch unapproved transactions
+      const { data: unapprovedData } = await api.transactions.getTransactions(bid, undefined, "unapproved");
+      const txns = unapprovedData.transactions.map(formatTransaction);
+      const unapprovedIds = new Set(txns.map((t) => t.id));
+
+      // Fetch 60 days of approved history for context
+      const since60 = new Date(Date.now() - 60 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+      const { data: histData } = await api.transactions.getTransactions(bid, since60);
+      const histTxns = histData.transactions.filter((t) => t.approved && !unapprovedIds.has(t.id));
+
+      // Build payee history lookups (using raw milliunits for history, convert to dollars for the set)
+      const payeeAmounts = {}; // payeeId -> Set of dollar amounts seen
+      const payeeCategories = {}; // payeeId -> Map of categoryId -> categoryName
+      for (const h of histTxns) {
+        if (!h.payee_id) continue;
+        const pid = h.payee_id;
+        const amt = dollars(h.amount);
+        const cid = h.category_id;
+        const cname = h.category_name;
+        if (!payeeAmounts[pid]) payeeAmounts[pid] = new Set();
+        payeeAmounts[pid].add(amt);
+        if (cid) {
+          if (!payeeCategories[pid]) payeeCategories[pid] = new Map();
+          payeeCategories[pid].set(cid, cname);
+        }
+      }
+
+      // Attach flags to each unapproved transaction
+      function flagTransaction(t) {
+        const flags = [];
+        const isTransfer = !!t.transfer_account_id;
+        if (!t.import_id && !isTransfer) flags.push("manually_entered");
+        if (t.matched_transaction_id && !t.import_id) flags.push("match_broken");
+        if (/_\d{4}-\d{2}-\d{2}$/.test(t.id)) flags.push("scheduled_transaction_realized");
+        if (t.payee_id) {
+          const hasHistory = !!payeeAmounts[t.payee_id];
+          if (!hasHistory) {
+            flags.push("new_payee");
+          } else {
+            if (!payeeAmounts[t.payee_id].has(t.amount)) flags.push("no_prior_amount_match");
+            if (t.category_id && payeeCategories[t.payee_id] && !payeeCategories[t.payee_id].has(t.category_id)) {
+              const priorNames = [...payeeCategories[t.payee_id].values()].join(", ");
+              flags.push(`category_drift:was_${priorNames}`);
+            }
+          }
+        }
+        return { ...t, flags };
+      }
+
+      const flaggedTxns = txns.map(flagTransaction);
+
       const isCategorized = (t) => (t.category_id && t.category_name !== "Uncategorized")
-        || (t.subtransactions && t.subtransactions.length > 0) // split transactions are categorized via subtransactions
-        || t.transfer_account_id; // transfers don't need categories
+        || (t.subtransactions && t.subtransactions.length > 0)
+        || t.transfer_account_id;
       const categorized = [], uncategorized = [];
-      for (const t of txns) (isCategorized(t) ? categorized : uncategorized).push(t);
+      for (const t of flaggedTxns) (isCategorized(t) ? categorized : uncategorized).push(t);
+
+      // Group categorized transactions by payee for easier per-group review
+      const byPayee = {};
+      for (const t of categorized) {
+        const key = t.payee_name || "Unknown Payee";
+        if (!byPayee[key]) byPayee[key] = { payee: key, category_name: t.category_name, transactions: [] };
+        byPayee[key].transactions.push(t);
+      }
+      const groups = Object.values(byPayee).map((g) => {
+        // Aggregate flags across all transactions in the group (deduplicated)
+        const allFlags = [...new Set(g.transactions.flatMap((t) => t.flags))];
+        return {
+          ...g,
+          count: g.transactions.length,
+          total: g.transactions.reduce((sum, t) => sum + t.amount, 0),
+          flags: allFlags,
+        };
+      });
+
       return ok({
-        total: txns.length,
+        total: flaggedTxns.length,
         ready_to_approve: {
           count: categorized.length,
-          transactions: categorized,
+          by_payee: groups,
         },
         needs_category_first: {
           count: uncategorized.length,
@@ -1129,6 +1306,35 @@ server.registerTool(
     })
 );
 
+server.registerTool(
+  "get_overspent_categories",
+  { description: "Get all categories with a negative balance for a given month. Use this to find prior-month overspends that are silently reducing the current month's Ready to Assign.", inputSchema: {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    month: z.string().describe("Month in YYYY-MM-DD format (first of month)"),
+  } },
+  ({ budgetId, month }) =>
+    run(async () => {
+      const { data } = await api.months.getBudgetMonth(resolveBudgetId(budgetId), month);
+      const overspent = (data.month.categories || [])
+        .filter((c) => !c.deleted && c.balance < 0 && c.category_group_name !== "Internal Master Category")
+        .map((c) => ({
+          id: c.id,
+          name: c.name,
+          category_group_name: c.category_group_name,
+          budgeted: dollars(c.budgeted),
+          activity: dollars(c.activity),
+          balance: dollars(c.balance),
+        }))
+        .sort((a, b) => a.balance - b.balance);
+      return ok({
+        month,
+        overspent_count: overspent.length,
+        total_overspent: overspent.reduce((sum, c) => sum + c.balance, 0),
+        categories: overspent,
+      });
+    })
+);
+
 // --- Start ---
 
 process.on("uncaughtException", (err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oliverames/ynab-mcp-server",
-  "version": "1.3.0",
+  "version": "1.6.0",
   "description": "YNAB MCP server with full API coverage",
   "type": "module",
   "main": "index.js",
@@ -15,7 +15,11 @@
     "test": "node test.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "ynab": "^2.5.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ynab": "^2.5.0",
+    "zod": "^4.3.6"
+  },
+  "engines": {
+    "node": ">=18"
   }
 }