@oliverames/ynab-mcp-server 1.6.0 → 2.1.0

package/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -8,8 +9,24 @@ import * as ynab from "ynab";
 
 // --- Init ---
 
+const BASE_URL = "https://api.ynab.com/v1";
+const YNAB_API_HOST = "api.ynab.com";
+const MAX_TOKEN_FILE_BYTES = 4096;
+const MAX_RESPONSE_BYTES = Number.parseInt(process.env.YNAB_MAX_RESPONSE_BYTES || "8388608", 10);
+
 let API_TOKEN = process.env.YNAB_API_TOKEN;
-let opLookupError;
+let tokenLookupError;
+if (!API_TOKEN && process.env.YNAB_API_TOKEN_FILE) {
+  try {
+    const tokenFileContents = readFileSync(process.env.YNAB_API_TOKEN_FILE, "utf8");
+    if (Buffer.byteLength(tokenFileContents, "utf8") > MAX_TOKEN_FILE_BYTES) {
+      throw new Error(`token file exceeds ${MAX_TOKEN_FILE_BYTES} bytes`);
+    }
+    API_TOKEN = tokenFileContents.trim();
+  } catch (e) {
+    tokenLookupError = `Could not read YNAB_API_TOKEN_FILE: ${e.message || String(e)}`;
+  }
+}
 if (!API_TOKEN && process.env.YNAB_OP_PATH) {
   try {
     API_TOKEN = execFileSync(
@@ -17,18 +34,20 @@ if (!API_TOKEN && process.env.YNAB_OP_PATH) {
       { encoding: "utf-8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"] }
     ).trim();
   } catch (e) {
-    opLookupError = e.stderr?.toString().trim() || e.message || "unknown 1Password CLI error";
+    tokenLookupError = `Could not read YNAB_OP_PATH via 1Password CLI: ${e.stderr?.toString().trim() || e.message || "unknown 1Password CLI error"}`;
   }
 }
 if (!API_TOKEN) {
-  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}`);
+  const fallbackMessage = tokenLookupError
+    ? ` ${tokenLookupError}.`
+    : " Set YNAB_API_TOKEN_FILE or YNAB_OP_PATH to enable token fallback.";
+  console.error(`YNAB_API_TOKEN environment variable is required.${fallbackMessage}`);
   process.exit(1);
 }
 
-const api = new ynab.API(API_TOKEN);
+const ynabRateLimit = createYnabRateLimiter();
+const api = new ynab.API(API_TOKEN, BASE_URL);
+api._configuration.config = { accessToken: API_TOKEN, basePath: BASE_URL, fetchApi: secureFetch };
 const DEFAULT_BUDGET_ID = process.env.YNAB_BUDGET_ID;
 
 // --- Helpers ---
@@ -45,6 +64,12 @@ function milliunits(dollars) {
   return Math.round(dollars * 1000);
 }
 
+// Round a dollar sum to cents, killing IEEE-754 artifacts from summing floats
+// (e.g. a group total like -53.730000000000004 produced by reduce/+= over amounts).
+function round2(n) {
+  return n == null ? n : Math.round(n * 100) / 100;
+}
+
 function dollarsMap(obj) {
   return obj ? Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, dollars(v)])) : obj;
 }
@@ -101,6 +126,89 @@ function mapTransactionUpdate(t) {
   return out;
 }
 
+const TRANSACTION_UPDATE_VERIFICATION_FIELDS = [
+  ["accountId", "account_id"],
+  ["date", "date"],
+  ["amount", "amount"],
+  ["payeeId", "payee_id"],
+  ["payeeName", "payee_name"],
+  ["categoryId", "category_id"],
+  ["memo", "memo"],
+  ["cleared", "cleared"],
+  ["approved", "approved"],
+  ["flagColor", "flag_color"],
+];
+
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+function updateFieldMatches(expected, actual) {
+  if (typeof expected === "number" && typeof actual === "number") {
+    return Math.abs(expected - actual) < 0.0001;
+  }
+  return Object.is(expected, actual);
+}
+
+function transactionUpdateMismatches(requested, actual) {
+  const mismatches = [];
+  for (const [inputField, outputField] of TRANSACTION_UPDATE_VERIFICATION_FIELDS) {
+    if (!hasOwn(requested, inputField)) continue;
+    const expected = requested[inputField] ?? null;
+    const actualValue = actual[outputField] ?? null;
+    if (!updateFieldMatches(expected, actualValue)) {
+      mismatches.push({
+        field: inputField,
+        expected,
+        actual: actualValue,
+      });
+    }
+  }
+  return mismatches;
+}
+
+async function getFormattedTransaction(budgetId, transactionId) {
+  const { data } = await api.transactions.getTransactionById(budgetId, normalizeTransactionId(transactionId));
+  return formatTransaction(data.transaction);
+}
+
+async function verifyBulkTransactionUpdates(budgetId, requestedUpdates) {
+  const verification = {
+    checked: requestedUpdates.length,
+    retried: [],
+    failed: [],
+  };
+  const verified = [];
+
+  for (const requested of requestedUpdates) {
+    let refetched = await getFormattedTransaction(budgetId, requested.id);
+    let mismatches = transactionUpdateMismatches(requested, refetched);
+
+    if (mismatches.length > 0) {
+      verification.retried.push({
+        id: requested.id,
+        mismatches,
+      });
+      const { data } = await api.transactions.updateTransaction(budgetId, requested.id, {
+        transaction: mapTransactionUpdate(requested),
+      });
+      refetched = formatTransaction(data.transaction);
+      mismatches = transactionUpdateMismatches(requested, refetched);
+    }
+
+    if (mismatches.length > 0) {
+      verification.failed.push({
+        id: requested.id,
+        mismatches,
+      });
+    }
+
+    verified.push(refetched);
+  }
+
+  return { verification, verified };
+}
+
 // 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) {
@@ -126,14 +234,87 @@ async function run(fn) {
     const msg = detail
       ? (name ? `${name}: ${detail}` : detail)
       : (e?.message || String(e));
-    return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+    return { content: [{ type: "text", text: `Error: ${sanitizeErrorMessage(msg)}` }], isError: true };
+  }
+}
+
+function sanitizeErrorMessage(value) {
+  let message = String(value ?? "");
+  if (API_TOKEN) {
+    message = message.split(API_TOKEN).join("[REDACTED_TOKEN]");
+  }
+  return message
+    .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED_TOKEN]")
+    .replace(/Authorization:\s*[^\r\n]+/gi, "Authorization: [REDACTED_TOKEN]");
+}
+
+function createYnabRateLimiter() {
+  const requestsPerHour = Number.parseFloat(process.env.YNAB_RATE_LIMIT_PER_HOUR || "190");
+  if (!Number.isFinite(requestsPerHour) || requestsPerHour <= 0) {
+    return async () => {};
+  }
+
+  const burst = Math.max(1, Number.parseInt(process.env.YNAB_RATE_LIMIT_BURST || "10", 10));
+  const refillMs = 3600000 / requestsPerHour;
+  let tokens = burst;
+  let updatedAt = Date.now();
+
+  return async function waitForYnabRateLimit() {
+    while (true) {
+      const now = Date.now();
+      const elapsed = now - updatedAt;
+      tokens = Math.min(burst, tokens + elapsed / refillMs);
+      updatedAt = now;
+
+      if (tokens >= 1) {
+        tokens -= 1;
+        return;
+      }
+
+      const waitMs = Math.ceil((1 - tokens) * refillMs);
+      await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+  };
+}
+
+function assertYnabApiUrl(url) {
+  if (url.protocol !== "https:" || url.hostname.toLowerCase() !== YNAB_API_HOST || (url.port && url.port !== "443")) {
+    throw new Error(`Refusing YNAB API request to non-YNAB host: ${url.origin}`);
+  }
+}
+
+async function secureFetch(input, init = {}) {
+  const url = input instanceof URL ? input : new URL(typeof input === "string" ? input : input.url);
+  assertYnabApiUrl(url);
+  await ynabRateLimit();
+
+  const timeoutMs = Number.parseInt(process.env.YNAB_HTTP_TIMEOUT_MS || "30000", 10);
+  const controller = !init.signal && timeoutMs > 0 ? new AbortController() : null;
+  const timeout = controller
+    ? setTimeout(() => controller.abort(new Error(`YNAB request timed out after ${timeoutMs}ms`)), timeoutMs)
+    : null;
+
+  try {
+    return await fetch(url, {
+      ...init,
+      redirect: "manual",
+      signal: controller?.signal || init.signal,
+    });
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+function buildYnabUrl(path) {
+  if (!path.startsWith("/") || path.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(path) || /[\r\n]/.test(path)) {
+    throw new Error("Refusing unsafe YNAB API path");
   }
+  return new URL(`${BASE_URL}${path}`);
 }
 
 // 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, query } = {}) {
-  const url = new URL(`${BASE_URL}${path}`);
+  const url = buildYnabUrl(path);
   for (const [key, value] of Object.entries(query || {})) {
     if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
   }
@@ -142,12 +323,19 @@ async function ynabFetch(path, { method = "GET", body, query } = {}) {
     headers: { Authorization: `Bearer ${API_TOKEN}`, "Content-Type": "application/json" },
   };
   if (body) opts.body = JSON.stringify(body);
-  const res = await fetch(url, opts);
+  const res = await secureFetch(url, opts);
+  const contentLength = Number.parseInt(res.headers.get("content-length") || "0", 10);
+  if (Number.isFinite(contentLength) && contentLength > MAX_RESPONSE_BYTES) {
+    throw new Error(`YNAB response exceeded ${MAX_RESPONSE_BYTES} bytes`);
+  }
   const text = await res.text();
+  if (Buffer.byteLength(text, "utf8") > MAX_RESPONSE_BYTES) {
+    throw new Error(`YNAB response exceeded ${MAX_RESPONSE_BYTES} bytes`);
+  }
   const json = text ? JSON.parse(text) : {};
   if (!res.ok) {
-    const err = new Error(json?.error?.detail || `HTTP ${res.status}`);
-    err.error = json?.error;
+    const err = new Error(sanitizeErrorMessage(json?.error?.detail || `HTTP ${res.status}`));
+    err.error = json?.error ? { ...json.error, detail: sanitizeErrorMessage(json.error.detail) } : undefined;
     throw err;
   }
   return json.data;
@@ -157,9 +345,87 @@ async function ynabFetch(path, { method = "GET", body, query } = {}) {
 
 const server = new McpServer({
   name: "ynab-mcp-server",
-  version: "1.6.0",
+  version: "2.1.0",
 });
 
+const WRITE_TOOL_METADATA = {
+  create_account: { destructiveHint: false, idempotentHint: false },
+  update_month_category: { destructiveHint: false, idempotentHint: true },
+  update_category: { destructiveHint: false, idempotentHint: true },
+  create_category: { destructiveHint: false, idempotentHint: false },
+  create_category_group: { destructiveHint: false, idempotentHint: false },
+  update_category_group: { destructiveHint: false, idempotentHint: true },
+  update_payee: { destructiveHint: false, idempotentHint: true },
+  create_payee: { destructiveHint: false, idempotentHint: false },
+  create_transaction: { destructiveHint: false, idempotentHint: false },
+  create_transactions: { destructiveHint: false, idempotentHint: false },
+  update_transaction: { destructiveHint: false, idempotentHint: true },
+  delete_transaction: { destructiveHint: true, idempotentHint: true },
+  update_transactions: { destructiveHint: false, idempotentHint: true },
+  approve_transactions: { destructiveHint: false, idempotentHint: true },
+  reassign_payee_transactions: { destructiveHint: false, idempotentHint: true },
+  import_transactions: { destructiveHint: false, idempotentHint: false },
+  create_scheduled_transaction: { destructiveHint: false, idempotentHint: false },
+  update_scheduled_transaction: { destructiveHint: false, idempotentHint: true },
+  delete_scheduled_transaction: { destructiveHint: true, idempotentHint: true },
+};
+
+function writesEnabled() {
+  return process.env.YNAB_ALLOW_WRITES === "1";
+}
+
+function writeDisabledResult(name) {
+  return {
+    content: [{
+      type: "text",
+      text: `Error: ${name} is disabled. Restart the MCP server with YNAB_ALLOW_WRITES=1 to enable write tools.`,
+    }],
+    isError: true,
+  };
+}
+
+function withWriteGateDescription(description = "") {
+  if (description.includes("YNAB_ALLOW_WRITES=1")) return description;
+  return `${description} Requires YNAB_ALLOW_WRITES=1; write tools are not registered by default.`;
+}
+
+const registerRawTool = server.registerTool.bind(server);
+server.registerTool = (name, config, handler) => {
+  const writeMetadata = WRITE_TOOL_METADATA[name];
+  if (!writeMetadata) {
+    return registerRawTool(name, {
+      ...config,
+      annotations: {
+        ...config.annotations,
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: true,
+      },
+    }, handler);
+  }
+
+  if (!writesEnabled()) {
+    return undefined;
+  }
+
+  return registerRawTool(name, {
+    ...config,
+    description: withWriteGateDescription(config.description),
+    annotations: {
+      ...config.annotations,
+      readOnlyHint: false,
+      destructiveHint: writeMetadata.destructiveHint,
+      idempotentHint: writeMetadata.idempotentHint,
+      openWorldHint: true,
+    },
+  }, (args, extra) => {
+    if (!writesEnabled()) {
+      return writeDisabledResult(name);
+    }
+    return handler(args, extra);
+  });
+};
+
 // ==================== User & Budgets ====================
 
 server.registerTool(
@@ -793,7 +1059,7 @@ function formatTransaction(t) {
 
 server.registerTool(
   "get_transactions",
-  { description: "Get transactions with optional filters. Use type='unapproved' or type='uncategorized' to filter. Optionally filter by account, category, payee, or month.", inputSchema: {
+  { description: "Get transactions with optional filters. Use type='unapproved' or type='uncategorized' to filter. Optionally filter by account, category, payee, or month. Each returned transaction includes 'import_payee_name_original' — the raw merchant string from the bank import (e.g. 'AplPay LS ONION RIVEMONTPELIER VT') — which encodes processor flag, merchant name (often longer than the cleaned payee_name), and city+state. This is the primary disambiguation field when payee_name is truncated or ambiguous. Note: large date ranges (6+ months on a busy budget) can return 50KB+ of data; narrow with categoryId/payeeId/month filters when possible.", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
     sinceDate: z.string().optional().describe("Only return transactions on or after this date (YYYY-MM-DD)"),
     type: z.enum(["unapproved", "uncategorized"]).optional().describe("Filter by approval/categorization status"),
@@ -836,14 +1102,41 @@ server.registerTool(
 
 server.registerTool(
   "get_transaction",
-  { description: "Get a single transaction by ID. Automatically handles composite scheduled-transaction IDs (e.g. uuid_YYYY-MM-DD).", inputSchema: {
+  { description: "Get a single transaction by ID. Automatically handles composite scheduled-transaction IDs (e.g. uuid_YYYY-MM-DD): the date suffix is stripped before the lookup. If a composite ID's underlying matched transaction has been deleted, falls back to returning the active scheduled-transaction template wrapped in a marker shape { resource_type: 'scheduled_transaction', reason: 'composite_id_with_no_matched_transaction', scheduled_transaction, requested_id } so callers can distinguish the two return shapes. Non-composite IDs preserve strict behavior: a 404 still surfaces as resource_not_found.", 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), normalizeTransactionId(transactionId));
-      return ok(formatTransaction(data.transaction));
+      const bid = resolveBudgetId(budgetId);
+      const normalizedId = normalizeTransactionId(transactionId);
+      const isComposite = /_\d{4}-\d{2}-\d{2}$/.test(transactionId);
+      try {
+        const { data } = await api.transactions.getTransactionById(bid, normalizedId);
+        return ok(formatTransaction(data.transaction));
+      } catch (e) {
+        // Only fall back for composite IDs on resource_not_found. Other errors
+        // (auth, rate limit, network) and non-composite not-founds bubble up unchanged.
+        if (!isComposite || e?.error?.name !== "resource_not_found") throw e;
+        try {
+          const { data } = await api.scheduledTransactions.getScheduledTransactionById(bid, normalizedId);
+          return ok({
+            resource_type: "scheduled_transaction",
+            reason: "composite_id_with_no_matched_transaction",
+            scheduled_transaction: formatScheduledTransaction(data.scheduled_transaction),
+            requested_id: transactionId,
+          });
+        } catch (e2) {
+          if (e2?.error?.name !== "resource_not_found") throw e2;
+          throw {
+            error: {
+              id: "404",
+              name: "resource_not_found",
+              detail: `Resource not found (tried transaction ${normalizedId} and scheduled transaction ${normalizedId}; both returned not-found)`,
+            },
+          };
+        }
+      }
     })
 );
 
@@ -956,7 +1249,7 @@ server.registerTool(
 
 server.registerTool(
   "update_transactions",
-  { description: "Batch update multiple transactions. Each transaction object must include its id and the fields to update.", inputSchema: {
+  { description: "Batch update multiple transactions. Each transaction object must include its id and the fields to update. IMPORTANT: only use transaction IDs extracted from get_transactions / review_unapproved results — never compose IDs by hand (fabricated IDs return 'transaction does not exist in this budget' errors). For combined category+approval changes, include both 'categoryId' and 'approved: true' in the same entry. This tool refetches each transaction after the bulk update, verifies requested fields actually persisted, and retries mismatches once through single-transaction updates. Never trust review_unapproved counts alone after approving transactions; use this response's verification block or get_transaction to confirm fields.", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
     transactions: z
       .array(
@@ -975,16 +1268,121 @@ server.registerTool(
         })
       )
       .describe("Array of transaction updates"),
+    returnSummary: z.boolean().optional().describe("If true, return compact counts (updated_count, approved_count, and verification counts) instead of the full updated-transaction objects. Use for large batches (~50+) whose full response would exceed the inline tool-result limit; the write is performed identically either way."),
   } },
-  ({ budgetId, transactions: txns }) =>
+  ({ budgetId, transactions: txns, returnSummary }) =>
     run(async () => {
+      const bid = resolveBudgetId(budgetId);
       const mapped = txns.map((t) => ({ id: t.id, ...mapTransactionUpdate(t) }));
-      const { data } = await api.transactions.updateTransactions(resolveBudgetId(budgetId), {
+      const { data } = await api.transactions.updateTransactions(bid, {
         transactions: mapped,
       });
+      const { verification, verified } = await verifyBulkTransactionUpdates(bid, txns);
+      if (verification.failed.length > 0) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error: Bulk transaction update verification failed after retry: ${JSON.stringify(verification.failed, null, 2)}`,
+          }],
+          isError: true,
+        };
+      }
+      if (returnSummary) {
+        return ok({
+          updated_count: verified.length,
+          approved_count: verified.filter((t) => t.approved).length,
+          duplicate_import_ids: data.duplicate_import_ids,
+          verification: {
+            checked: verification.checked,
+            retried: verification.retried.length,
+            failed: verification.failed.length,
+          },
+        });
+      }
       return ok({
-        updated: data.transactions?.map(formatTransaction),
+        updated: verified,
         duplicate_import_ids: data.duplicate_import_ids,
+        verification,
+      });
+    })
+);
+
+server.registerTool(
+  "approve_transactions",
+  { description: "Approve unapproved transactions in bulk by filter, without hand-listing IDs. Fetches the current unapproved queue, optionally narrows by payeeId / categoryId / accountId, and sets approved:true on the matches. By default SKIPS uncategorized transactions (no category and not a transfer) so nothing is approved without a category; set includeUncategorized:true to override. Returns a compact summary (approved_count + verification counts), never full objects, so it is safe on large batches. The CALLER is responsible for getting user confirmation before invoking — this tool does not prompt.", inputSchema: {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    payeeId: z.string().optional().describe("Only approve unapproved transactions for this payee"),
+    categoryId: z.string().optional().describe("Only approve unapproved transactions in this category"),
+    accountId: z.string().optional().describe("Only approve unapproved transactions in this account"),
+    includeUncategorized: z.boolean().optional().describe("If true, also approve transactions with no category (default false — uncategorized are skipped for safety)"),
+  } },
+  ({ budgetId, payeeId, categoryId, accountId, includeUncategorized }) =>
+    run(async () => {
+      const bid = resolveBudgetId(budgetId);
+      const { data } = await api.transactions.getTransactions(bid, undefined, "unapproved");
+      let txns = data.transactions.filter((t) => !t.deleted);
+      if (payeeId) txns = txns.filter((t) => t.payee_id === payeeId);
+      if (categoryId) txns = txns.filter((t) => t.category_id === categoryId);
+      if (accountId) txns = txns.filter((t) => t.account_id === accountId);
+      if (!includeUncategorized) {
+        txns = txns.filter((t) => (t.category_id && t.category_name !== "Uncategorized") || t.transfer_account_id);
+      }
+      if (txns.length === 0) {
+        return ok({ approved_count: 0, matched: 0, message: "No matching unapproved transactions to approve." });
+      }
+      const updates = txns.map((t) => ({ id: t.id, approved: true }));
+      const mapped = updates.map((t) => ({ id: t.id, ...mapTransactionUpdate(t) }));
+      const { data: updData } = await api.transactions.updateTransactions(bid, { transactions: mapped });
+      const { verification, verified } = await verifyBulkTransactionUpdates(bid, updates);
+      if (verification.failed.length > 0) {
+        return {
+          content: [{ type: "text", text: `Error: approval verification failed after retry: ${JSON.stringify(verification.failed, null, 2)}` }],
+          isError: true,
+        };
+      }
+      return ok({
+        matched: txns.length,
+        approved_count: verified.filter((t) => t.approved).length,
+        filters: { payeeId: payeeId || null, categoryId: categoryId || null, accountId: accountId || null, includeUncategorized: !!includeUncategorized },
+        duplicate_import_ids: updData.duplicate_import_ids,
+        verification: { checked: verification.checked, retried: verification.retried.length, failed: verification.failed.length },
+      });
+    })
+);
+
+server.registerTool(
+  "reassign_payee_transactions",
+  { description: "Move all transactions from one payee to another. The YNAB API has no payee-merge or payee-delete endpoint, so this is the merge workaround: refetch every transaction for fromPayeeId and set payee_id = toPayeeId. Use to consolidate a duplicate payee that a slightly different bank-import string created (e.g. fold 'Myles Court Barber' into the existing 'Myles Court Barbershop'). The emptied source payee still exists afterward and must be deleted manually in the YNAB UI (Settings → Manage Payees) if wanted. Returns a compact summary.", inputSchema: {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    fromPayeeId: z.string().describe("Payee whose transactions will be moved"),
+    toPayeeId: z.string().describe("Destination payee that transactions will be reassigned to"),
+    sinceDate: z.string().optional().describe("Only move transactions on or after this date (YYYY-MM-DD); omit to move all history"),
+  } },
+  ({ budgetId, fromPayeeId, toPayeeId, sinceDate }) =>
+    run(async () => {
+      const bid = resolveBudgetId(budgetId);
+      const { data } = await api.transactions.getTransactionsByPayee(bid, fromPayeeId, sinceDate);
+      const txns = data.transactions.filter((t) => !t.deleted);
+      if (txns.length === 0) {
+        return ok({ reassigned_count: 0, message: "No transactions found for fromPayeeId in the given range." });
+      }
+      const updates = txns.map((t) => ({ id: t.id, payeeId: toPayeeId }));
+      const mapped = updates.map((t) => ({ id: t.id, ...mapTransactionUpdate(t) }));
+      const { data: updData } = await api.transactions.updateTransactions(bid, { transactions: mapped });
+      const { verification, verified } = await verifyBulkTransactionUpdates(bid, updates);
+      if (verification.failed.length > 0) {
+        return {
+          content: [{ type: "text", text: `Error: payee reassignment verification failed after retry: ${JSON.stringify(verification.failed, null, 2)}` }],
+          isError: true,
+        };
+      }
+      return ok({
+        reassigned_count: verified.length,
+        from_payee_id: fromPayeeId,
+        to_payee_id: toPayeeId,
+        duplicate_import_ids: updData.duplicate_import_ids,
+        note: "Source payee is now empty but still exists; delete it in the YNAB UI (Settings → Manage Payees) if desired.",
+        verification: { checked: verification.checked, retried: verification.retried.length, failed: verification.failed.length },
       });
     })
 );
@@ -1211,8 +1609,12 @@ 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). 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 }) =>
+  { 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 is stale — the `matched_transaction_id` field is read-only via this API; YNAB web/iOS UI is required to clear that link. The transaction itself remains fully mutable: you CAN approve, recategorize, and edit memo via update_transaction. The broken match persists as a cosmetic flag until the user resolves it in the UI.), 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. For large budgets the full response can exceed 100KB; pass summary:true for counts + by-payee aggregates only, or compact:true to keep per-transaction rows (with IDs) while dropping bulky fields so the response fits inline.", inputSchema: {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    summary: z.boolean().optional().describe("If true, omit per-transaction details from the response and return only counts + by-payee aggregates (for both ready_to_approve and needs_category_first). Use this when the full unapproved queue is large; drill into specifics with get_transactions afterwards."),
+    compact: z.boolean().optional().describe("If true (and summary is not set), keep per-transaction detail but return only the fields needed to act — id, date, payee_name, amount, category_name, account_name, flags — dropping bulky fields (import strings, subtransactions, matched/import ids) that push the full response past the inline size limit. Use when you need transaction IDs to approve or recategorize but the full queue would overflow."),
+  } },
+  ({ budgetId, summary, compact }) =>
     run(async () => {
       const bid = resolveBudgetId(budgetId);
 
@@ -1273,6 +1675,17 @@ server.registerTool(
       const categorized = [], uncategorized = [];
       for (const t of flaggedTxns) (isCategorized(t) ? categorized : uncategorized).push(t);
 
+      // Compact projection: only the fields needed to act on a transaction
+      const slimTx = (t) => ({
+        id: t.id,
+        date: t.date,
+        payee_name: t.payee_name,
+        amount: t.amount,
+        category_name: t.category_name,
+        account_name: t.account_name,
+        flags: t.flags,
+      });
+
       // Group categorized transactions by payee for easier per-group review
       const byPayee = {};
       for (const t of categorized) {
@@ -1283,25 +1696,53 @@ server.registerTool(
       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,
+        const base = {
+          payee: g.payee,
+          category_name: g.category_name,
           count: g.transactions.length,
-          total: g.transactions.reduce((sum, t) => sum + t.amount, 0),
+          total: round2(g.transactions.reduce((sum, t) => sum + t.amount, 0)),
           flags: allFlags,
         };
+        return summary ? base : { ...base, transactions: compact ? g.transactions.map(slimTx) : g.transactions };
       });
 
+      // Build uncategorized payload — full transactions by default, by-payee aggregates when summary:true
+      const uncategorizedPayload = (() => {
+        if (!summary) return compact ? uncategorized.map(slimTx) : uncategorized;
+        const byPayeeUncat = {};
+        for (const t of uncategorized) {
+          const key = t.payee_name || "Unknown Payee";
+          if (!byPayeeUncat[key]) byPayeeUncat[key] = { payee_name: key, count: 0, total: 0, flags: new Set() };
+          byPayeeUncat[key].count += 1;
+          byPayeeUncat[key].total += t.amount;
+          for (const f of t.flags) byPayeeUncat[key].flags.add(f);
+        }
+        return Object.values(byPayeeUncat).map((g) => ({
+          payee_name: g.payee_name,
+          count: g.count,
+          total: round2(g.total),
+          flags: [...g.flags],
+        }));
+      })();
+
+      const needsCategoryFirst = {
+        count: uncategorized.length,
+        warning: "Do NOT approve these without assigning a category first",
+      };
+      if (summary) {
+        needsCategoryFirst.payees = uncategorizedPayload;
+      } else {
+        needsCategoryFirst.transactions = uncategorizedPayload;
+      }
+
       return ok({
         total: flaggedTxns.length,
+        summary: !!summary,
         ready_to_approve: {
           count: categorized.length,
           by_payee: groups,
         },
-        needs_category_first: {
-          count: uncategorized.length,
-          warning: "Do NOT approve these without assigning a category first",
-          transactions: uncategorized,
-        },
+        needs_category_first: needsCategoryFirst,
       });
     })
 );
@@ -1329,7 +1770,7 @@ server.registerTool(
       return ok({
         month,
         overspent_count: overspent.length,
-        total_overspent: overspent.reduce((sum, c) => sum + c.balance, 0),
+        total_overspent: round2(overspent.reduce((sum, c) => sum + c.balance, 0)),
         categories: overspent,
       });
     })