@oliverames/ynab-mcp-server 1.7.1 → 2.1.1

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}`);
-  process.exit(1);
+  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} Starting in discovery-only mode.`);
 }
 
-const api = new ynab.API(API_TOKEN);
+const ynabRateLimit = createYnabRateLimiter();
+const effectiveApiToken = API_TOKEN || "missing-token-for-tool-discovery";
+const api = new ynab.API(effectiveApiToken, BASE_URL);
+api._configuration.config = { accessToken: effectiveApiToken, 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,28 +234,108 @@ 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));
   }
   const opts = {
     method,
-    headers: { Authorization: `Bearer ${API_TOKEN}`, "Content-Type": "application/json" },
+    headers: { Authorization: `Bearer ${effectiveApiToken}`, "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,12 +345,132 @@ async function ynabFetch(path, { method = "GET", body, query } = {}) {
 
 const server = new McpServer({
   name: "ynab-mcp-server",
-  version: "1.6.0",
+  version: "2.1.1",
 });
 
+const registeredTools = new Map();
+const toolCatalog = new Map();
+
+function registerTool(name, config, handler) {
+  const registration = server.registerTool(name, config, handler);
+  toolCatalog.set(name, { config });
+  if (registration !== undefined) {
+    registeredTools.set(name, { config, handler });
+  }
+  return registration;
+}
+
+function listRegisteredYnabTools() {
+  return [...toolCatalog.entries()]
+    .filter(([name]) => !name.startsWith("ynab_"))
+    .map(([name, { config }]) => {
+      const writeMetadata = WRITE_TOOL_METADATA[name];
+      const isWrite = !!writeMetadata;
+      return {
+        name,
+        title: config?.title ?? name,
+        description: isWrite ? withWriteGateDescription(config?.description ?? "") : config?.description ?? "",
+        has_input_schema: !!config?.inputSchema,
+        is_write: isWrite,
+        registered: registeredTools.has(name),
+        status: isWrite && !writesEnabled() ? "hidden_requires_YNAB_ALLOW_WRITES_1" : "available",
+      };
+    });
+}
+
+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 },
+  ynab_write_tool_execute: { destructiveHint: false, idempotentHint: false },
+  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 ynabAuthStatus() {
+  return {
+    authenticated: !!API_TOKEN,
+    default_budget_id_configured: !!DEFAULT_BUDGET_ID,
+    writes_enabled: writesEnabled(),
+    message: API_TOKEN
+      ? "YNAB MCP server has an API token configured."
+      : "YNAB MCP server is running in discovery-only mode. Set YNAB_API_TOKEN, YNAB_API_TOKEN_FILE, or YNAB_OP_PATH, then restart the MCP server before calling API tools.",
+  };
+}
+
+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(
+registerTool(
   "get_user",
   { description: "Get the authenticated user" },
   () =>
@@ -172,7 +480,7 @@ server.registerTool(
   })
 );
 
-server.registerTool(
+registerTool(
   "list_budgets",
   { description: "List all budgets. Use a budget ID from the results in other tools, or omit budgetId to use the last-used budget." },
   () =>
@@ -188,7 +496,7 @@ server.registerTool(
   })
 );
 
-server.registerTool(
+registerTool(
   "get_budget",
   { description: "Get a budget summary including name, currency format, and account/category/payee counts", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
   ({ budgetId }) =>
@@ -210,7 +518,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "get_budget_settings",
   { description: "Get budget settings (currency format, date format)", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
   ({ budgetId }) =>
@@ -246,7 +554,7 @@ function formatAccount(a) {
   return withCurrencyFields(out, a, ["balance", "cleared_balance", "uncleared_balance"]);
 }
 
-server.registerTool(
+registerTool(
   "list_accounts",
   { description: "List all accounts in a budget", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -260,7 +568,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "get_account",
   { description: "Get details for a specific account", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -273,7 +581,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "create_account",
   { description: "Create a new account", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -332,7 +640,7 @@ function formatCategory(c) {
   ]);
 }
 
-server.registerTool(
+registerTool(
   "list_categories",
   { description: "List all category groups and their categories", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -368,7 +676,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "get_category",
   { description: "Get a specific category", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -381,7 +689,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "get_month_category",
   { description: "Get category budget for a specific month", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -395,7 +703,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "update_month_category",
   { description: "Set the budgeted amount for a category in a specific month", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -412,7 +720,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "update_category",
   { description: "Update a category's name, note, goal target, or move it to a different group", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -442,7 +750,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "create_category",
   { description: "Create a new category in a category group", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -469,7 +777,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "create_category_group",
   { description: "Create a new category group", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -485,7 +793,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "update_category_group",
   { description: "Rename a category group", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -504,7 +812,7 @@ server.registerTool(
 
 // ==================== Payees ====================
 
-server.registerTool(
+registerTool(
   "list_payees",
   { description: "List all payees", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -518,7 +826,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "get_payee",
   { description: "Get a specific payee", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -531,7 +839,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "update_payee",
   { description: "Rename a payee", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -547,7 +855,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "create_payee",
   { description: "Create a new payee", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -565,7 +873,7 @@ server.registerTool(
 
 // ==================== Payee Locations ====================
 
-server.registerTool(
+registerTool(
   "list_payee_locations",
   { description: "List all payee locations (GPS coordinates where transactions occurred)", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
   ({ budgetId }) =>
@@ -575,7 +883,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "get_payee_location",
   { description: "Get a specific payee location", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -588,7 +896,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "get_payee_locations_by_payee",
   { description: "Get all locations for a specific payee", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -603,7 +911,7 @@ server.registerTool(
 
 // ==================== Months ====================
 
-server.registerTool(
+registerTool(
   "list_months",
   { description: "List all budget months", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -632,7 +940,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "get_month",
   { description: "Get budget month detail with per-category breakdown", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -696,7 +1004,7 @@ function formatMoneyMovement(m) {
   }, m, ["amount"]);
 }
 
-server.registerTool(
+registerTool(
   "list_money_movements",
   { description: "List all money movements (budget re-allocations between categories)", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
   ({ budgetId }) =>
@@ -706,7 +1014,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "get_money_movements_by_month",
   { description: "Get money movements for a specific month", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -719,7 +1027,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "list_money_movement_groups",
   { 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 }) =>
@@ -729,7 +1037,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "get_money_movement_groups_by_month",
   { description: "Get money movement groups for a specific month", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -791,7 +1099,7 @@ function formatTransaction(t) {
   return withCurrencyFields(out, t, ["amount"]);
 }
 
-server.registerTool(
+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. 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)"),
@@ -834,20 +1142,47 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+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)`,
+            },
+          };
+        }
+      }
     })
 );
 
-server.registerTool(
+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: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -879,7 +1214,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+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: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -916,7 +1251,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "update_transaction",
   { description: "Update an existing transaction. Only provided fields are changed. Amounts in dollars.", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -941,7 +1276,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "delete_transaction",
   { description: "Delete a transaction", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -954,9 +1289,9 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "update_transactions",
-  { 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 in one round trip, include both 'categoryId' and 'approved: true' in the same entry. The response returns the full updated transaction objects, which can exceed 50KB for batches over ~50 transactions; if the response overflows, the update still succeeded — verify by counting 'approved: true' occurrences in the saved result file.", 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,21 +1310,126 @@ 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,
+      });
+    })
+);
+
+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(
+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 },
+      });
+    })
+);
+
+registerTool(
   "import_transactions",
   { description: "Trigger import of linked account transactions", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
   ({ budgetId }) =>
@@ -1041,7 +1481,7 @@ function formatScheduledTransaction(t) {
   return withCurrencyFields(out, t, ["amount"]);
 }
 
-server.registerTool(
+registerTool(
   "list_scheduled_transactions",
   { 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)"),
@@ -1055,7 +1495,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "get_scheduled_transaction",
   { description: "Get a specific scheduled transaction", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -1068,7 +1508,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "create_scheduled_transaction",
   { description: "Create a new scheduled (recurring) transaction", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -1101,7 +1541,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "update_scheduled_transaction",
   { description: "Update an existing scheduled transaction. Only provided fields are changed. Amounts in dollars.", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -1144,7 +1584,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "delete_scheduled_transaction",
   { description: "Delete a scheduled transaction", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -1159,7 +1599,7 @@ server.registerTool(
 
 // ==================== Convenience Tools ====================
 
-server.registerTool(
+registerTool(
   "search_categories",
   { description: "Search categories by partial name match (case-insensitive). Useful for finding category IDs when you only know part of the name.", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -1191,7 +1631,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "search_payees",
   { description: "Search payees by partial name match (case-insensitive). Useful for finding payee IDs.", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
@@ -1209,13 +1649,14 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+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 is stale — CANNOT be fixed via this API, requires YNAB web/iOS 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 to get counts + by-payee aggregates without per-transaction detail.", inputSchema: {
+  { 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 }) =>
+  ({ budgetId, summary, compact }) =>
     run(async () => {
       const bid = resolveBudgetId(budgetId);
 
@@ -1276,6 +1717,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) {
@@ -1290,15 +1742,15 @@ server.registerTool(
           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: g.transactions };
+        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 uncategorized;
+        if (!summary) return compact ? uncategorized.map(slimTx) : uncategorized;
         const byPayeeUncat = {};
         for (const t of uncategorized) {
           const key = t.payee_name || "Unknown Payee";
@@ -1310,7 +1762,7 @@ server.registerTool(
         return Object.values(byPayeeUncat).map((g) => ({
           payee_name: g.payee_name,
           count: g.count,
-          total: g.total,
+          total: round2(g.total),
           flags: [...g.flags],
         }));
       })();
@@ -1337,7 +1789,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+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)"),
@@ -1360,12 +1812,105 @@ 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,
       });
     })
 );
 
+registerTool(
+  "ynab_auth_status",
+  {
+    title: "YNAB Auth Status",
+    description: "Check whether the YNAB MCP server has credentials configured and whether write tools are enabled.",
+    inputSchema: {},
+  },
+  () => ok(ynabAuthStatus())
+);
+
+registerTool(
+  "ynab_tool_index",
+  {
+    title: "YNAB Tool Index",
+    description: "Discover the YNAB MCP server tools. Use this when you need YNAB budgets, accounts, categories, payees, transactions, scheduled transactions, unapproved transaction review, approval, or budget cleanup tools.",
+    inputSchema: {},
+  },
+  () => ok({
+    server: "ynab-mcp-server",
+    package: "@oliverames/ynab-mcp-server",
+    auth: ynabAuthStatus(),
+    writes_enabled: writesEnabled(),
+    tools: listRegisteredYnabTools(),
+    execute_with: "ynab_tool_execute",
+    write_execute_with: writesEnabled() ? "ynab_write_tool_execute" : null,
+  })
+);
+
+registerTool(
+  "ynab_tool_execute",
+  {
+    title: "Execute YNAB Tool",
+    description: "Execute an existing read-only YNAB MCP tool by name. Use ynab_tool_index first to discover YNAB tool names, then pass the selected tool_name and its JSON input. Write-capable tools must be called directly or through ynab_write_tool_execute when YNAB_ALLOW_WRITES=1.",
+    inputSchema: {
+      tool_name: z.string().describe("Existing read-only YNAB tool name, such as review_unapproved, get_transactions, list_categories, search_categories, or search_payees."),
+      input: z.record(z.string(), z.any()).optional().describe("JSON input for the selected YNAB tool. Omit or pass an empty object for tools that take no input."),
+    },
+  },
+  async ({ tool_name: toolName, input = {} }) => {
+    if (toolName.startsWith("ynab_")) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: "Refusing to execute YNAB discovery helper tools recursively." }],
+      };
+    }
+    if (WRITE_TOOL_METADATA[toolName]) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `${toolName} is a write-capable YNAB tool. Set YNAB_ALLOW_WRITES=1 and call it directly, or use ynab_write_tool_execute.` }],
+      };
+    }
+    const tool = registeredTools.get(toolName);
+    if (!tool) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Unknown YNAB tool: ${toolName}` }],
+      };
+    }
+    return tool.handler(input);
+  }
+);
+
+registerTool(
+  "ynab_write_tool_execute",
+  {
+    title: "Execute YNAB Write Tool",
+    description: "Execute an existing write-capable YNAB MCP tool by name. This tool is registered only when YNAB_ALLOW_WRITES=1 and should be used only after explicit user confirmation.",
+    inputSchema: {
+      tool_name: z.string().describe("Existing write-capable YNAB tool name, such as update_transaction, update_transactions, approve_transactions, create_transaction, or delete_transaction."),
+      input: z.record(z.string(), z.any()).optional().describe("JSON input for the selected YNAB write tool."),
+    },
+  },
+  async ({ tool_name: toolName, input = {} }) => {
+    if (toolName.startsWith("ynab_")) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: "Refusing to execute YNAB discovery helper tools recursively." }],
+      };
+    }
+    if (!WRITE_TOOL_METADATA[toolName]) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: `${toolName} is not a write-capable YNAB tool. Use ynab_tool_execute for read-only tools.` }],
+      };
+    }
+    const tool = registeredTools.get(toolName);
+    if (!tool) {
+      return writeDisabledResult(toolName);
+    }
+    return tool.handler(input);
+  }
+);
+
 // --- Start ---
 
 process.on("uncaughtException", (err) => {