@oliverames/ynab-mcp-server 2.1.0 → 3.0.0

package/index.js

@@ -2,6 +2,8 @@
 
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -13,44 +15,360 @@ 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);
+const YNAB_RUNTIME_KEYS = [
+  "YNAB_API_TOKEN",
+  "YNAB_API_TOKEN_FILE",
+  "YNAB_OP_PATH",
+  "YNAB_BUDGET_ID",
+  "YNAB_ALLOW_WRITES",
+];
 
-let API_TOKEN = process.env.YNAB_API_TOKEN;
-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`);
+const runtimeConfig = resolveYnabRuntimeConfig();
+const API_TOKEN = runtimeConfig.apiToken;
+const tokenLookupError = runtimeConfig.tokenLookupError;
+const DEFAULT_BUDGET_ID = runtimeConfig.values.YNAB_BUDGET_ID?.value;
+if (!API_TOKEN) {
+  const fallbackMessage = tokenLookupError
+    ? ` ${tokenLookupError}.`
+    : " Add YNAB_API_TOKEN to the agent config file, set YNAB_API_TOKEN_FILE, or set YNAB_OP_PATH.";
+  console.error(`YNAB_API_TOKEN is required.${fallbackMessage} Starting MCP Server for YNAB in discovery-only mode.`);
+}
+
+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 };
+
+// --- Helpers ---
+
+function resolveYnabRuntimeConfig() {
+  const sources = loadYnabSettingSources();
+  const values = {};
+
+  for (const key of YNAB_RUNTIME_KEYS) {
+    const source = sources.find((candidate) => hasNonEmptyString(candidate.values[key]));
+    if (source) {
+      values[key] = {
+        value: source.values[key].trim(),
+        source: source.id,
+        source_label: source.label,
+        path: source.path,
+        section: source.section,
+      };
+    }
+  }
+
+  const lookupErrors = sources
+    .flatMap((source) => source.errors || [])
+    .filter(Boolean);
+
+  let apiToken = values.YNAB_API_TOKEN?.value;
+  let tokenSource = values.YNAB_API_TOKEN || null;
+
+  if (!apiToken && values.YNAB_API_TOKEN_FILE?.value) {
+    try {
+      const tokenFileContents = readFileSync(values.YNAB_API_TOKEN_FILE.value, "utf8");
+      if (Buffer.byteLength(tokenFileContents, "utf8") > MAX_TOKEN_FILE_BYTES) {
+        throw new Error(`token file exceeds ${MAX_TOKEN_FILE_BYTES} bytes`);
+      }
+      apiToken = tokenFileContents.trim();
+      tokenSource = {
+        source: "token_file",
+        source_label: "YNAB_API_TOKEN_FILE",
+        path: values.YNAB_API_TOKEN_FILE.value,
+      };
+    } catch (e) {
+      lookupErrors.push(`Could not read YNAB_API_TOKEN_FILE: ${e.message || String(e)}`);
     }
-    API_TOKEN = tokenFileContents.trim();
+  }
+
+  if (!apiToken && values.YNAB_OP_PATH?.value) {
+    try {
+      apiToken = execFileSync(
+        "op", ["read", values.YNAB_OP_PATH.value],
+        { encoding: "utf-8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"] }
+      ).trim();
+      tokenSource = {
+        source: "onepassword_cli",
+        source_label: "YNAB_OP_PATH via 1Password CLI",
+      };
+    } catch (e) {
+      lookupErrors.push(`Could not read YNAB_OP_PATH via 1Password CLI: ${e.stderr?.toString().trim() || e.message || "unknown 1Password CLI error"}`);
+    }
+  }
+
+  return {
+    apiToken,
+    tokenSource,
+    values,
+    sources_checked: sources.map((source) => ({
+      id: source.id,
+      label: source.label,
+      path: source.path,
+      section: source.section,
+      available: source.available,
+      keys_found: source.keysFound,
+    })),
+    config_fallback_disabled: process.env.YNAB_DISABLE_AGENT_CONFIG_FALLBACK === "1",
+    detected_agent: detectAgentRuntime(),
+    tokenLookupError: lookupErrors[lookupErrors.length - 1],
+    lookup_errors: lookupErrors,
+  };
+}
+
+function loadYnabSettingSources() {
+  const finalize = (sources) => sources.map((source) => ({
+    ...source,
+    keysFound: YNAB_RUNTIME_KEYS.filter((key) => hasNonEmptyString(source.values[key])),
+  }));
+
+  const sources = [{
+    id: "process_env",
+    label: "process environment",
+    path: null,
+    section: null,
+    available: true,
+    values: pickYnabValues(process.env),
+    errors: [],
+  }];
+
+  if (process.env.YNAB_DISABLE_AGENT_CONFIG_FALLBACK === "1") {
+    return finalize(sources);
+  }
+
+  const codexSources = loadCodexConfigSources();
+  const claudeSource = loadClaudeSettingsSource();
+  if (detectAgentRuntime() === "claude") {
+    sources.push(claudeSource, ...codexSources);
+  } else {
+    sources.push(...codexSources, claudeSource);
+  }
+  return finalize(sources);
+}
+
+function loadCodexConfigSources() {
+  const configPath = path.join(userHomeDir(), ".codex", "config.toml");
+  const emptySources = [
+    configSource("codex_shell_environment", "Codex shell_environment_policy.set", configPath, "shell_environment_policy.set"),
+    configSource("codex_mcp_env", "Codex mcp_servers.ynab.env", configPath, "mcp_servers.ynab.env"),
+  ];
+
+  let text;
+  try {
+    text = readFileSync(configPath, "utf8");
   } catch (e) {
-    tokenLookupError = `Could not read YNAB_API_TOKEN_FILE: ${e.message || String(e)}`;
+    return emptySources.map((source) => ({
+      ...source,
+      available: false,
+      errors: isMissingFileError(e) ? [] : [`Could not read ${configPath}: ${e.message || String(e)}`],
+    }));
   }
+
+  const sections = parseSimpleTomlSections(text);
+  return emptySources.map((source) => ({
+    ...source,
+    available: true,
+    values: pickYnabValues(sections[source.section] || {}),
+    errors: [],
+  }));
 }
-if (!API_TOKEN && process.env.YNAB_OP_PATH) {
+
+function loadClaudeSettingsSource() {
+  const settingsPath = path.join(userHomeDir(), ".claude", "settings.json");
+  const source = configSource("claude_settings_env", "Claude settings.json env", settingsPath, "env");
+
+  let settings;
   try {
-    API_TOKEN = execFileSync(
-      "op", ["read", process.env.YNAB_OP_PATH],
-      { encoding: "utf-8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"] }
-    ).trim();
+    settings = JSON.parse(readFileSync(settingsPath, "utf8"));
   } catch (e) {
-    tokenLookupError = `Could not read YNAB_OP_PATH via 1Password CLI: ${e.stderr?.toString().trim() || e.message || "unknown 1Password CLI error"}`;
+    return {
+      ...source,
+      available: false,
+      errors: isMissingFileError(e) ? [] : [`Could not read ${settingsPath}: ${e.message || String(e)}`],
+    };
   }
+
+  return {
+    ...source,
+    available: true,
+    values: pickYnabValues(settings?.env || {}),
+    errors: [],
+  };
 }
-if (!API_TOKEN) {
-  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);
+
+function configSource(id, label, filePath, section) {
+  return {
+    id,
+    label,
+    path: filePath,
+    section,
+    available: false,
+    values: {},
+    errors: [],
+  };
 }
 
-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;
+function pickYnabValues(source) {
+  return Object.fromEntries(
+    YNAB_RUNTIME_KEYS
+      .filter((key) => hasNonEmptyString(source?.[key]))
+      .map((key) => [key, String(source[key])])
+  );
+}
 
-// --- Helpers ---
+function parseSimpleTomlSections(text) {
+  const sections = {};
+  let currentSection = "";
+
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const sectionMatch = line.match(/^\[([^\]]+)\]$/);
+    if (sectionMatch) {
+      currentSection = sectionMatch[1].trim();
+      sections[currentSection] ||= {};
+      continue;
+    }
+
+    const assignmentMatch = line.match(/^([A-Za-z0-9_]+)\s*=\s*(.+)$/);
+    if (!assignmentMatch || !currentSection) continue;
+
+    const [, key, rawValue] = assignmentMatch;
+    const value = parseSimpleTomlString(rawValue);
+    if (value !== undefined) {
+      sections[currentSection] ||= {};
+      sections[currentSection][key] = value;
+    }
+  }
+
+  return sections;
+}
+
+function parseSimpleTomlString(rawValue) {
+  const value = stripTomlComment(rawValue).trim();
+  if (!value) return undefined;
+  if (value.startsWith("\"") && value.endsWith("\"")) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value.slice(1, -1);
+    }
+  }
+  if (value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function stripTomlComment(value) {
+  let quote = null;
+  let escaped = false;
+  for (let i = 0; i < value.length; i += 1) {
+    const char = value[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === "\"" || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === "#") {
+      return value.slice(0, i);
+    }
+  }
+  return value;
+}
+
+function userHomeDir() {
+  return process.env.HOME || homedir();
+}
+
+function hasNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function isMissingFileError(error) {
+  return error?.code === "ENOENT" || error?.code === "ENOTDIR";
+}
+
+function detectAgentRuntime() {
+  if (Object.keys(process.env).some((key) => key.startsWith("CODEX_"))) return "codex";
+  if (Object.keys(process.env).some((key) => key.startsWith("CLAUDE_"))) return "claude";
+  return "unknown";
+}
+
+function publicYnabRuntimeSettings() {
+  return Object.fromEntries(
+    Object.entries(runtimeConfig.values)
+      .filter(([key]) => key !== "YNAB_API_TOKEN")
+      .map(([key, entry]) => [key, {
+        configured: true,
+        source: entry.source,
+        source_label: entry.source_label,
+      }])
+  );
+}
+
+function ynabAuthSetupGuide() {
+  const agent = runtimeConfig.detected_agent;
+  const codexPath = path.join(userHomeDir(), ".codex", "config.toml");
+  const claudePath = path.join(userHomeDir(), ".claude", "settings.json");
+  const shouldShowCodex = agent === "codex" || agent === "unknown";
+  const shouldShowClaude = agent === "claude" || agent === "unknown";
+  const manualTargets = [];
+  const passwordManagerTargets = [];
+
+  if (shouldShowCodex) {
+    manualTargets.push({
+      agent: "codex",
+      path: codexPath,
+      section: "shell_environment_policy.set",
+      snippet: "[shell_environment_policy.set]\nYNAB_API_TOKEN = \"your-token-here\"",
+    });
+    passwordManagerTargets.push({
+      agent: "codex",
+      path: codexPath,
+      section: "shell_environment_policy.set",
+      snippet: "[shell_environment_policy.set]\nYNAB_OP_PATH = \"op://Personal/YNAB API Token/credential\"",
+      note: "Ask the user for permission before editing this config, and confirm the 1Password item path they want to use.",
+    });
+  }
+
+  if (shouldShowClaude) {
+    manualTargets.push({
+      agent: "claude",
+      path: claudePath,
+      section: "env",
+      snippet: "{\n  \"env\": {\n    \"YNAB_API_TOKEN\": \"your-token-here\"\n  }\n}",
+    });
+    passwordManagerTargets.push({
+      agent: "claude",
+      path: claudePath,
+      section: "env",
+      snippet: "{\n  \"env\": {\n    \"YNAB_OP_PATH\": \"op://Personal/YNAB API Token/credential\"\n  }\n}",
+      note: "Ask the user for permission before editing this config, and confirm the 1Password item path they want to use.",
+    });
+  }
+
+  return {
+    prompt_for_agent: "Ask the user whether they already have a YNAB API key in a password manager such as 1Password. If yes, ask permission to configure YNAB_OP_PATH for this agent. If no, ask them to add YNAB_API_TOKEN to the correct agent config file, then restart the MCP server.",
+    detected_agent: agent,
+    manual_api_key_targets: manualTargets,
+    password_manager_targets: passwordManagerTargets,
+    token_file_option: "Alternatively, set YNAB_API_TOKEN_FILE to a small local file containing only the token.",
+    restart_required: true,
+  };
+}
 
 function resolveBudgetId(input) {
   return input || DEFAULT_BUDGET_ID || "last-used";
@@ -225,7 +543,49 @@ function collection(data, key, items, lastKnowledgeOfServer) {
     : { [key]: items, server_knowledge: data.server_knowledge };
 }
 
+function pathSegment(value) {
+  return encodeURIComponent(String(value));
+}
+
+function allHistorySinceDate() {
+  return "1970-01-01";
+}
+
+function buildTransactionListPath({ budgetId, accountId, categoryId, payeeId, month }) {
+  const bid = pathSegment(resolveBudgetId(budgetId));
+  if (accountId) return `/plans/${bid}/accounts/${pathSegment(accountId)}/transactions`;
+  if (categoryId) return `/plans/${bid}/categories/${pathSegment(categoryId)}/transactions`;
+  if (payeeId) return `/plans/${bid}/payees/${pathSegment(payeeId)}/transactions`;
+  if (month) return `/plans/${bid}/months/${pathSegment(month)}/transactions`;
+  return `/plans/${bid}/transactions`;
+}
+
+async function fetchTransactions({
+  budgetId,
+  sinceDate,
+  untilDate,
+  type,
+  accountId,
+  categoryId,
+  payeeId,
+  month,
+  lastKnowledgeOfServer,
+}) {
+  return ynabFetch(buildTransactionListPath({ budgetId, accountId, categoryId, payeeId, month }), {
+    query: {
+      since_date: sinceDate,
+      until_date: untilDate,
+      type,
+      last_knowledge_of_server: lastKnowledgeOfServer,
+    },
+  });
+}
+
 async function run(fn) {
+  if (!API_TOKEN) {
+    return missingCredentialsResult();
+  }
+
   try {
     return await fn();
   } catch (e) {
@@ -238,6 +598,17 @@ async function run(fn) {
   }
 }
 
+function missingCredentialsResult() {
+  return {
+    content: [{ type: "text", text: JSON.stringify({
+      error: "missing_credentials",
+      message: "YNAB API credentials are not configured for this MCP server process.",
+      auth: ynabAuthStatus(),
+    }, null, 2) }],
+    isError: true,
+  };
+}
+
 function sanitizeErrorMessage(value) {
   let message = String(value ?? "");
   if (API_TOKEN) {
@@ -320,7 +691,7 @@ async function ynabFetch(path, { method = "GET", body, query } = {}) {
   }
   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 secureFetch(url, opts);
@@ -344,10 +715,46 @@ async function ynabFetch(path, { method = "GET", body, query } = {}) {
 // --- Server ---
 
 const server = new McpServer({
-  name: "ynab-mcp-server",
-  version: "2.1.0",
+  name: "mcp-server-for-ynab",
+  version: "3.0.0",
 });
 
+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;
+      let status = "available";
+      if (isWrite && !writesEnabled()) {
+        status = "hidden_requires_YNAB_ALLOW_WRITES_1";
+      } else if (!API_TOKEN) {
+        status = "discoverable_requires_credentials";
+      }
+      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,
+      };
+    });
+}
+
 const WRITE_TOOL_METADATA = {
   create_account: { destructiveHint: false, idempotentHint: false },
   update_month_category: { destructiveHint: false, idempotentHint: true },
@@ -364,6 +771,7 @@ const WRITE_TOOL_METADATA = {
   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 },
@@ -371,7 +779,29 @@ const WRITE_TOOL_METADATA = {
 };
 
 function writesEnabled() {
-  return process.env.YNAB_ALLOW_WRITES === "1";
+  return runtimeConfig.values.YNAB_ALLOW_WRITES?.value === "1";
+}
+
+function ynabAuthStatus() {
+  const authenticated = !!API_TOKEN;
+  const writeToolsAvailable = authenticated && writesEnabled();
+  return {
+    authenticated,
+    default_budget_id_configured: !!DEFAULT_BUDGET_ID,
+    writes_enabled: writesEnabled(),
+    write_tools_available: writeToolsAvailable,
+    credential_source: runtimeConfig.tokenSource?.source ?? null,
+    credential_source_label: runtimeConfig.tokenSource?.source_label ?? null,
+    detected_agent: runtimeConfig.detected_agent,
+    config_fallback_disabled: runtimeConfig.config_fallback_disabled,
+    configured_settings: publicYnabRuntimeSettings(),
+    credential_sources_checked: runtimeConfig.sources_checked,
+    lookup_error: authenticated ? null : tokenLookupError ?? null,
+    setup: authenticated ? null : ynabAuthSetupGuide(),
+    message: authenticated
+      ? "MCP Server for YNAB has an API token configured."
+      : "MCP Server for YNAB is running in discovery-only mode. Check setup.prompt_for_agent for the safe credential setup flow, then restart the MCP server before calling API tools.",
+  };
 }
 
 function writeDisabledResult(name) {
@@ -428,7 +858,7 @@ server.registerTool = (name, config, handler) => {
 
 // ==================== User & Budgets ====================
 
-server.registerTool(
+registerTool(
   "get_user",
   { description: "Get the authenticated user" },
   () =>
@@ -438,29 +868,31 @@ 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." },
   () =>
   run(async () => {
-    const { data } = await api.budgets.getBudgets();
+    const { data } = await api.plans.getPlans();
+    const plans = data.plans || data.budgets || [];
+    const defaultPlan = data.default_plan || data.default_budget;
     const result = {
-      budgets: data.budgets.map((b) => ({ id: b.id, name: b.name, last_modified_on: b.last_modified_on, first_month: b.first_month, last_month: b.last_month, date_format: b.date_format, currency_format: b.currency_format })),
+      budgets: plans.map((b) => ({ id: b.id, name: b.name, last_modified_on: b.last_modified_on, first_month: b.first_month, last_month: b.last_month, date_format: b.date_format, currency_format: b.currency_format })),
     };
-    if (data.default_budget) {
-      result.default_budget = { id: data.default_budget.id, name: data.default_budget.name };
+    if (defaultPlan) {
+      result.default_budget = { id: defaultPlan.id, name: defaultPlan.name };
     }
     return ok(result);
   })
 );
 
-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 }) =>
     run(async () => {
-      const { data } = await api.budgets.getBudgetById(resolveBudgetId(budgetId));
-      const b = data.budget;
+      const { data } = await api.plans.getPlanById(resolveBudgetId(budgetId));
+      const b = data.plan || data.budget;
       return ok({
         id: b.id,
         name: b.name,
@@ -476,12 +908,12 @@ 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 }) =>
     run(async () => {
-      const { data } = await api.budgets.getBudgetSettingsById(resolveBudgetId(budgetId));
+      const { data } = await api.plans.getPlanSettingsById(resolveBudgetId(budgetId));
       return ok(data.settings);
     })
 );
@@ -512,7 +944,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)"),
@@ -526,7 +958,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)"),
@@ -539,7 +971,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)"),
@@ -598,7 +1030,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)"),
@@ -634,7 +1066,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)"),
@@ -647,7 +1079,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)"),
@@ -661,7 +1093,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)"),
@@ -678,7 +1110,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)"),
@@ -708,7 +1140,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)"),
@@ -735,7 +1167,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)"),
@@ -751,7 +1183,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)"),
@@ -770,7 +1202,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)"),
@@ -784,7 +1216,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)"),
@@ -797,7 +1229,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)"),
@@ -813,7 +1245,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)"),
@@ -831,7 +1263,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 }) =>
@@ -841,7 +1273,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)"),
@@ -854,7 +1286,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)"),
@@ -869,7 +1301,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)"),
@@ -877,7 +1309,7 @@ server.registerTool(
   } },
   ({ budgetId, lastKnowledgeOfServer }) =>
     run(async () => {
-      const { data } = await api.months.getBudgetMonths(resolveBudgetId(budgetId), lastKnowledgeOfServer);
+      const { data } = await api.months.getPlanMonths(resolveBudgetId(budgetId), lastKnowledgeOfServer);
       const months = data.months.map((m) =>
           withCurrencyFields(
             {
@@ -898,7 +1330,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)"),
@@ -906,7 +1338,7 @@ server.registerTool(
   } },
   ({ budgetId, month }) =>
     run(async () => {
-      const { data } = await api.months.getBudgetMonth(resolveBudgetId(budgetId), month);
+      const { data } = await api.months.getPlanMonth(resolveBudgetId(budgetId), month);
       const m = data.month;
       const out = {
         month: m.month,
@@ -962,7 +1394,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 }) =>
@@ -972,7 +1404,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)"),
@@ -985,7 +1417,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 }) =>
@@ -995,7 +1427,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)"),
@@ -1057,11 +1489,12 @@ 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: {
+  { 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. YNAB now defaults omitted sinceDate to one year ago; pass an explicit older sinceDate to retrieve older history. Note: large date ranges (6+ months on a busy budget) can return 50KB+ of data; narrow with categoryId/payeeId/month/sinceDate/untilDate 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)"),
+    sinceDate: z.string().optional().describe("Only return transactions on or after this date (YYYY-MM-DD). If omitted, YNAB defaults to one year ago."),
+    untilDate: z.string().optional().describe("Only return transactions on or before this date (YYYY-MM-DD)"),
     type: z.enum(["unapproved", "uncategorized"]).optional().describe("Filter by approval/categorization status"),
     accountId: z.string().optional().describe("Filter by account ID"),
     categoryId: z.string().optional().describe("Filter by category ID"),
@@ -1069,38 +1502,30 @@ server.registerTool(
     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, lastKnowledgeOfServer }) =>
+  ({ budgetId, sinceDate, untilDate, 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) {
-        ({ data } = await api.transactions.getTransactionsByAccount(bid, accountId, sinceDate, type, lastKnowledgeOfServer));
-        transactions = data.transactions;
-      } else if (categoryId) {
-        ({ data } = await api.transactions.getTransactionsByCategory(bid, categoryId, sinceDate, type, lastKnowledgeOfServer));
-        transactions = data.transactions;
-      } else if (payeeId) {
-        ({ data } = await api.transactions.getTransactionsByPayee(bid, payeeId, sinceDate, type, lastKnowledgeOfServer));
-        transactions = data.transactions;
-      } else if (month) {
-        ({ data } = await api.transactions.getTransactionsByMonth(bid, month, sinceDate, type, lastKnowledgeOfServer));
-        transactions = data.transactions;
-      } else {
-        ({ data } = await api.transactions.getTransactions(bid, sinceDate, type, lastKnowledgeOfServer));
-        transactions = data.transactions;
-      }
-
+      const data = await fetchTransactions({
+        budgetId,
+        sinceDate,
+        untilDate,
+        type,
+        accountId,
+        categoryId,
+        payeeId,
+        month,
+        lastKnowledgeOfServer,
+      });
+      const transactions = data.transactions;
       return ok(collection(data, "transactions", transactions.map(formatTransaction), lastKnowledgeOfServer));
     })
 );
 
-server.registerTool(
+registerTool(
   "get_transaction",
   { 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)"),
@@ -1140,7 +1565,7 @@ server.registerTool(
     })
 );
 
-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)"),
@@ -1172,7 +1597,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)"),
@@ -1209,7 +1634,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)"),
@@ -1234,7 +1659,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)"),
@@ -1247,7 +1672,7 @@ 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, 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)"),
@@ -1307,19 +1732,28 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+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: {
+  { 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. Requires confirmed:true after explicit user confirmation.", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    confirmed: z.literal(true).describe("Required. Pass true only after the user explicitly confirms this approval action."),
+    expectedMatchedCount: z.number().int().nonnegative().optional().describe("Optional safety check. If provided and the current match count differs, no transactions are approved."),
+    sinceDate: z.string().optional().describe("Only inspect unapproved transactions on or after this date (YYYY-MM-DD). Defaults to all history."),
+    untilDate: z.string().optional().describe("Only inspect unapproved transactions on or before this date (YYYY-MM-DD)."),
     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 }) =>
+  ({ budgetId, expectedMatchedCount, sinceDate, untilDate, payeeId, categoryId, accountId, includeUncategorized }) =>
     run(async () => {
       const bid = resolveBudgetId(budgetId);
-      const { data } = await api.transactions.getTransactions(bid, undefined, "unapproved");
+      const data = await fetchTransactions({
+        budgetId: bid,
+        sinceDate: sinceDate || allHistorySinceDate(),
+        untilDate,
+        type: "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);
@@ -1327,6 +1761,9 @@ server.registerTool(
       if (!includeUncategorized) {
         txns = txns.filter((t) => (t.category_id && t.category_name !== "Uncategorized") || t.transfer_account_id);
       }
+      if (expectedMatchedCount !== undefined && expectedMatchedCount !== txns.length) {
+        throw new Error(`approve_transactions matched ${txns.length} transactions, but expectedMatchedCount was ${expectedMatchedCount}; no transactions were approved.`);
+      }
       if (txns.length === 0) {
         return ok({ approved_count: 0, matched: 0, message: "No matching unapproved transactions to approve." });
       }
@@ -1350,19 +1787,30 @@ server.registerTool(
     })
 );
 
-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: {
+  { 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. Requires confirmed:true after explicit user confirmation.", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    confirmed: z.literal(true).describe("Required. Pass true only after the user explicitly confirms this payee reassignment."),
+    expectedMatchedCount: z.number().int().nonnegative().optional().describe("Optional safety check. If provided and the current match count differs, no transactions are reassigned."),
     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"),
+    sinceDate: z.string().optional().describe("Only move transactions on or after this date (YYYY-MM-DD); defaults to all history"),
+    untilDate: z.string().optional().describe("Only move transactions on or before this date (YYYY-MM-DD)"),
   } },
-  ({ budgetId, fromPayeeId, toPayeeId, sinceDate }) =>
+  ({ budgetId, expectedMatchedCount, fromPayeeId, toPayeeId, sinceDate, untilDate }) =>
     run(async () => {
       const bid = resolveBudgetId(budgetId);
-      const { data } = await api.transactions.getTransactionsByPayee(bid, fromPayeeId, sinceDate);
+      const data = await fetchTransactions({
+        budgetId: bid,
+        payeeId: fromPayeeId,
+        sinceDate: sinceDate || allHistorySinceDate(),
+        untilDate,
+      });
       const txns = data.transactions.filter((t) => !t.deleted);
+      if (expectedMatchedCount !== undefined && expectedMatchedCount !== txns.length) {
+        throw new Error(`reassign_payee_transactions matched ${txns.length} transactions, but expectedMatchedCount was ${expectedMatchedCount}; no transactions were reassigned.`);
+      }
       if (txns.length === 0) {
         return ok({ reassigned_count: 0, message: "No transactions found for fromPayeeId in the given range." });
       }
@@ -1387,7 +1835,7 @@ server.registerTool(
     })
 );
 
-server.registerTool(
+registerTool(
   "import_transactions",
   { description: "Trigger import of linked account transactions", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
   ({ budgetId }) =>
@@ -1439,7 +1887,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)"),
@@ -1453,7 +1901,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)"),
@@ -1466,7 +1914,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)"),
@@ -1499,7 +1947,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)"),
@@ -1542,7 +1990,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)"),
@@ -1557,7 +2005,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)"),
@@ -1589,7 +2037,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)"),
@@ -1607,7 +2055,7 @@ 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 — 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)"),
@@ -1747,7 +2195,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)"),
@@ -1755,7 +2203,7 @@ server.registerTool(
   } },
   ({ budgetId, month }) =>
     run(async () => {
-      const { data } = await api.months.getBudgetMonth(resolveBudgetId(budgetId), month);
+      const { data } = await api.months.getPlanMonth(resolveBudgetId(budgetId), month);
       const overspent = (data.month.categories || [])
         .filter((c) => !c.deleted && c.balance < 0 && c.category_group_name !== "Internal Master Category")
         .map((c) => ({
@@ -1776,6 +2224,104 @@ server.registerTool(
     })
 );
 
+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: "mcp-server-for-ynab",
+    package: "@oliverames/ynab-mcp-server",
+    auth: ynabAuthStatus(),
+    writes_enabled: writesEnabled(),
+    writes_available: writesEnabled() && !!API_TOKEN,
+    tools: listRegisteredYnabTools(),
+    execute_with: "ynab_tool_execute",
+    write_execute_with: writesEnabled() && !!API_TOKEN ? "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 requires confirmed:true after explicit user confirmation.",
+    inputSchema: {
+      confirmed: z.literal(true).describe("Required. Pass true only after the user explicitly confirms this write action."),
+      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);
+    }
+    const confirmedInput = ["approve_transactions", "reassign_payee_transactions"].includes(toolName) && input.confirmed === undefined
+      ? { ...input, confirmed: true }
+      : input;
+    return tool.handler(confirmedInput);
+  }
+);
+
 // --- Start ---
 
 process.on("uncaughtException", (err) => {