@oliverames/ynab-mcp-server 2.1.1 → 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,45 +15,361 @@ 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`);
-    }
-    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(
-      "op", ["read", process.env.YNAB_OP_PATH],
-      { encoding: "utf-8", timeout: 10000, stdio: ["pipe", "pipe", "pipe"] }
-    ).trim();
-  } catch (e) {
-    tokenLookupError = `Could not read YNAB_OP_PATH via 1Password CLI: ${e.stderr?.toString().trim() || e.message || "unknown 1Password CLI error"}`;
-  }
-}
+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}.`
-    : " 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.`);
+    : " 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 };
-const DEFAULT_BUDGET_ID = process.env.YNAB_BUDGET_ID;
 
 // --- 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)}`);
+    }
+  }
+
+  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) {
+    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: [],
+  }));
+}
+
+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 {
+    settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+  } catch (e) {
+    return {
+      ...source,
+      available: false,
+      errors: isMissingFileError(e) ? [] : [`Could not read ${settingsPath}: ${e.message || String(e)}`],
+    };
+  }
+
+  return {
+    ...source,
+    available: true,
+    values: pickYnabValues(settings?.env || {}),
+    errors: [],
+  };
+}
+
+function configSource(id, label, filePath, section) {
+  return {
+    id,
+    label,
+    path: filePath,
+    section,
+    available: false,
+    values: {},
+    errors: [],
+  };
+}
+
+function pickYnabValues(source) {
+  return Object.fromEntries(
+    YNAB_RUNTIME_KEYS
+      .filter((key) => hasNonEmptyString(source?.[key]))
+      .map((key) => [key, String(source[key])])
+  );
+}
+
+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) {
@@ -344,8 +715,8 @@ async function ynabFetch(path, { method = "GET", body, query } = {}) {
 // --- Server ---
 
 const server = new McpServer({
-  name: "ynab-mcp-server",
-  version: "2.1.1",
+  name: "mcp-server-for-ynab",
+  version: "3.0.0",
 });
 
 const registeredTools = new Map();
@@ -366,6 +737,12 @@ function listRegisteredYnabTools() {
     .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,
@@ -373,7 +750,7 @@ function listRegisteredYnabTools() {
         has_input_schema: !!config?.inputSchema,
         is_write: isWrite,
         registered: registeredTools.has(name),
-        status: isWrite && !writesEnabled() ? "hidden_requires_YNAB_ALLOW_WRITES_1" : "available",
+        status,
       };
     });
 }
@@ -402,17 +779,28 @@ 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: !!API_TOKEN,
+    authenticated,
     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.",
+    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.",
   };
 }
 
@@ -485,12 +873,14 @@ registerTool(
   { 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);
   })
@@ -501,8 +891,8 @@ registerTool(
   { 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,
@@ -523,7 +913,7 @@ registerTool(
   { 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);
     })
 );
@@ -919,7 +1309,7 @@ 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(
             {
@@ -948,7 +1338,7 @@ 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,
@@ -1101,9 +1491,10 @@ function formatTransaction(t) {
 
 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"),
@@ -1111,33 +1502,25 @@ 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));
     })
 );
@@ -1351,17 +1734,26 @@ 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);
@@ -1369,6 +1761,9 @@ 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." });
       }
@@ -1394,17 +1789,28 @@ 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." });
       }
@@ -1797,7 +2203,7 @@ 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) => ({
@@ -1836,13 +2242,14 @@ registerTool(
     inputSchema: {},
   },
   () => ok({
-    server: "ynab-mcp-server",
+    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() ? "ynab_write_tool_execute" : null,
+    write_execute_with: writesEnabled() && !!API_TOKEN ? "ynab_write_tool_execute" : null,
   })
 );
 
@@ -1884,8 +2291,9 @@ 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.",
+    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."),
     },
@@ -1907,7 +2315,10 @@ registerTool(
     if (!tool) {
       return writeDisabledResult(toolName);
     }
-    return tool.handler(input);
+    const confirmedInput = ["approve_transactions", "reassign_payee_transactions"].includes(toolName) && input.confirmed === undefined
+      ? { ...input, confirmed: true }
+      : input;
+    return tool.handler(confirmedInput);
   }
 );