@oliverames/ynab-mcp-server 1.4.0 → 1.7.1

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://api.ynab.com/papi/logo_api_meadow.svg" alt="YNAB API" width="200">
+  <img src="assets/icon.png" width="80" height="80" alt="YNAB">
 </p>
 
 <h1 align="center">YNAB MCP Server</h1>
@@ -17,12 +17,14 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@oliverames/ynab-mcp-server"><img src="https://img.shields.io/npm/v/%40oliverames%2Fynab-mcp-server?style=flat-square&color=f5a542" alt="npm"></a>
+  <a href="https://github.com/oliverames/ynab-mcp-server/releases/tag/v1.4.0"><img src="https://img.shields.io/github/v/release/oliverames/ynab-mcp-server?style=flat-square&color=f5a542&label=MCPB" alt="MCPB release"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-f5a542?style=flat-square" alt="License"></a>
   <a href="https://www.buymeacoffee.com/oliverames"><img src="https://img.shields.io/badge/Buy_Me_a_Coffee-support-f5a542?style=flat-square&logo=buy-me-a-coffee&logoColor=white" alt="Buy Me a Coffee"></a>
 </p>
 
 <p align="center">
   <a href="#quick-start">Quick Start</a> &bull;
+  <a href="#install-with-mcpb">MCPB Download</a> &bull;
   <a href="#what-you-can-do">What You Can Do</a> &bull;
   <a href="#tools-reference">All 44 Tools</a> &bull;
   <a href="#environment-variables">Configuration</a>
@@ -40,6 +42,14 @@ This server gives your AI assistant full access to YNAB's API, turning natural l
 
 ## Quick Start
 
+### Install with MCPB
+
+For Claude Desktop and other MCPB-compatible clients, download the local bundle from the [v1.4.0 release](https://github.com/oliverames/ynab-mcp-server/releases/tag/v1.4.0):
+
+[Download `ynab-mcp-server-1.4.0.mcpb`](https://github.com/oliverames/ynab-mcp-server/releases/download/v1.4.0/ynab-mcp-server-1.4.0.mcpb)
+
+The bundle includes the YNAB favicon, production runtime dependencies, and setup prompts for your personal access token and optional default budget ID.
+
 ### 1. Get a YNAB Personal Access Token
 
 Go to [YNAB Developer Settings](https://app.ynab.com/settings/developer) and create a new personal access token.
@@ -144,7 +154,7 @@ That's it. Your AI can now talk to YNAB.
 - **Bulk operations** - `create_transactions` and `update_transactions` handle arrays in a single API call.
 - **Fetch-then-merge updates** - scheduled transaction updates (which use PUT semantics) automatically fetch the current state and merge your changes, so you only specify what changed.
 - **Fuzzy search** - `search_categories` and `search_payees` do case-insensitive partial matching across all entries.
-- **Approval workflow** - `review_unapproved` groups transactions into "ready to approve" (categorized, split, or transfer) and "needs attention" (uncategorized), with a built-in warning against approving uncategorized entries.
+- **Approval workflow with anomaly flags** - `review_unapproved` groups transactions into "ready to approve" (categorized, split, or transfer) and "needs attention" (uncategorized), and attaches a `flags` array to each transaction surfacing anomalies: `manually_entered` (not bank-imported), `match_broken` (stale match reference), `scheduled_transaction_realized`, `new_payee`, `no_prior_amount_match` (novel amount for this payee), and `category_drift:was_X` (payee categorized differently in the prior 60 days). Group-level flags aggregate the union of all transaction flags.
 - **Nullable updates** - update tools accept `null` for clearable fields (`memo`, `payeeName`, `categoryId`, `flagColor`) to distinguish "don't change" (omit) from "clear this field" (`null`).
 - **Target behavior support** - category create/update tools expose `goalNeedsWholeAmount` for YNAB's "Set aside another" vs. "Refill up to" goal behavior.
 - **Delta request support** - high-volume list tools accept `lastKnowledgeOfServer` and return `server_knowledge` when that parameter is provided.
@@ -226,7 +236,7 @@ That's it. Your AI can now talk to YNAB.
 | Tool | Description |
 |------|-------------|
 | `get_transactions` | Get transactions with filters: by account, category, payee, month, or status (`unapproved`/`uncategorized`) |
-| `get_transaction` | Get a single transaction by ID (includes subtransactions) |
+| `get_transaction` | Get a single transaction by ID (includes subtransactions). Auto-handles composite scheduled-transaction IDs like `uuid_YYYY-MM-DD`. |
 | `create_transaction` | Create a transaction with optional split (subtransactions must sum to total) |
 | `create_transactions` | Bulk create multiple transactions in a single API call (supports split transactions) |
 | `update_transaction` | Partial update - only specified fields change |
@@ -250,7 +260,7 @@ That's it. Your AI can now talk to YNAB.
 
 | Tool | Description |
 |------|-------------|
-| `review_unapproved` | Get unapproved transactions grouped by readiness: "ready to approve" (categorized, split, or transfer) vs. "needs category first" (uncategorized). Includes a warning against blind approval. |
+| `review_unapproved` | Get unapproved transactions grouped by readiness: "ready to approve" (categorized, split, or transfer) vs. "needs category first" (uncategorized). Each transaction includes a `flags` array highlighting anomalies (manually_entered, match_broken, no_prior_amount_match, category_drift, new_payee, scheduled_transaction_realized) computed against 60 days of payee history. Includes a warning against blind approval. |
 
 ---
 

package/index.js

@@ -101,6 +101,12 @@ function mapTransactionUpdate(t) {
   return out;
 }
 
+// YNAB scheduled transactions that realize get composite IDs like `uuid_YYYY-MM-DD`.
+// Strip the date suffix so API lookups work correctly.
+function normalizeTransactionId(id) {
+  return id.replace(/_\d{4}-\d{2}-\d{2}$/, "");
+}
+
 function ok(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
@@ -151,7 +157,7 @@ async function ynabFetch(path, { method = "GET", body, query } = {}) {
 
 const server = new McpServer({
   name: "ynab-mcp-server",
-  version: "1.3.0",
+  version: "1.6.0",
 });
 
 // ==================== User & Budgets ====================
@@ -787,7 +793,7 @@ function formatTransaction(t) {
 
 server.registerTool(
   "get_transactions",
-  { description: "Get transactions with optional filters. Use type='unapproved' or type='uncategorized' to filter. Optionally filter by account, category, payee, or month.", inputSchema: {
+  { description: "Get transactions with optional filters. Use type='unapproved' or type='uncategorized' to filter. Optionally filter by account, category, payee, or month. Each returned transaction includes 'import_payee_name_original' — the raw merchant string from the bank import (e.g. 'AplPay LS ONION RIVEMONTPELIER VT') — which encodes processor flag, merchant name (often longer than the cleaned payee_name), and city+state. This is the primary disambiguation field when payee_name is truncated or ambiguous. Note: large date ranges (6+ months on a busy budget) can return 50KB+ of data; narrow with categoryId/payeeId/month filters when possible.", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
     sinceDate: z.string().optional().describe("Only return transactions on or after this date (YYYY-MM-DD)"),
     type: z.enum(["unapproved", "uncategorized"]).optional().describe("Filter by approval/categorization status"),
@@ -830,13 +836,13 @@ server.registerTool(
 
 server.registerTool(
   "get_transaction",
-  { description: "Get a single transaction by ID", inputSchema: {
+  { description: "Get a single transaction by ID. Automatically handles composite scheduled-transaction IDs (e.g. uuid_YYYY-MM-DD).", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
     transactionId: z.string().describe("Transaction ID"),
   } },
   ({ budgetId, transactionId }) =>
     run(async () => {
-      const { data } = await api.transactions.getTransactionById(resolveBudgetId(budgetId), transactionId);
+      const { data } = await api.transactions.getTransactionById(resolveBudgetId(budgetId), normalizeTransactionId(transactionId));
       return ok(formatTransaction(data.transaction));
     })
 );
@@ -950,7 +956,7 @@ server.registerTool(
 
 server.registerTool(
   "update_transactions",
-  { description: "Batch update multiple transactions. Each transaction object must include its id and the fields to update.", inputSchema: {
+  { description: "Batch update multiple transactions. Each transaction object must include its id and the fields to update. IMPORTANT: only use transaction IDs extracted from get_transactions / review_unapproved results — never compose IDs by hand (fabricated IDs return 'transaction does not exist in this budget' errors). For combined category+approval changes 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: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
     transactions: z
       .array(
@@ -1037,7 +1043,7 @@ function formatScheduledTransaction(t) {
 
 server.registerTool(
   "list_scheduled_transactions",
-  { description: "List all scheduled (recurring) transactions", inputSchema: {
+  { description: "List all scheduled (recurring) transactions. NOTE: only manually-created recurring entries appear here — auto-imported recurring charges (subscriptions, utilities, insurance) are NOT included. Use prior-month transaction history to identify recurring charge timing instead.", inputSchema: {
     budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
     lastKnowledgeOfServer: z.number().int().nonnegative().optional().describe("Delta request server knowledge. When provided, returns { scheduled_transactions, server_knowledge }."),
   } },
@@ -1205,27 +1211,157 @@ server.registerTool(
 
 server.registerTool(
   "review_unapproved",
-  { description: "Get all unapproved transactions grouped by status: those already categorized (ready to approve) and those still uncategorized (need category first). Never approve uncategorized transactions without explicit user instruction.", inputSchema: { budgetId: z.string().optional().describe("Budget ID (uses default if not provided)") } },
-  ({ budgetId }) =>
+  { description: "Get all unapproved transactions grouped by status: those already categorized (ready to approve) and those still uncategorized (need category first). Each transaction includes a 'flags' array: manually_entered (not bank-imported), match_broken (matched reference is stale — 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: {
+    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."),
+  } },
+  ({ budgetId, summary }) =>
     run(async () => {
-      const { data } = await api.transactions.getTransactions(resolveBudgetId(budgetId), undefined, "unapproved");
-      const txns = data.transactions.map(formatTransaction);
+      const bid = resolveBudgetId(budgetId);
+
+      // Fetch unapproved transactions
+      const { data: unapprovedData } = await api.transactions.getTransactions(bid, undefined, "unapproved");
+      const txns = unapprovedData.transactions.map(formatTransaction);
+      const unapprovedIds = new Set(txns.map((t) => t.id));
+
+      // Fetch 60 days of approved history for context
+      const since60 = new Date(Date.now() - 60 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+      const { data: histData } = await api.transactions.getTransactions(bid, since60);
+      const histTxns = histData.transactions.filter((t) => t.approved && !unapprovedIds.has(t.id));
+
+      // Build payee history lookups (using raw milliunits for history, convert to dollars for the set)
+      const payeeAmounts = {}; // payeeId -> Set of dollar amounts seen
+      const payeeCategories = {}; // payeeId -> Map of categoryId -> categoryName
+      for (const h of histTxns) {
+        if (!h.payee_id) continue;
+        const pid = h.payee_id;
+        const amt = dollars(h.amount);
+        const cid = h.category_id;
+        const cname = h.category_name;
+        if (!payeeAmounts[pid]) payeeAmounts[pid] = new Set();
+        payeeAmounts[pid].add(amt);
+        if (cid) {
+          if (!payeeCategories[pid]) payeeCategories[pid] = new Map();
+          payeeCategories[pid].set(cid, cname);
+        }
+      }
+
+      // Attach flags to each unapproved transaction
+      function flagTransaction(t) {
+        const flags = [];
+        const isTransfer = !!t.transfer_account_id;
+        if (!t.import_id && !isTransfer) flags.push("manually_entered");
+        if (t.matched_transaction_id && !t.import_id) flags.push("match_broken");
+        if (/_\d{4}-\d{2}-\d{2}$/.test(t.id)) flags.push("scheduled_transaction_realized");
+        if (t.payee_id) {
+          const hasHistory = !!payeeAmounts[t.payee_id];
+          if (!hasHistory) {
+            flags.push("new_payee");
+          } else {
+            if (!payeeAmounts[t.payee_id].has(t.amount)) flags.push("no_prior_amount_match");
+            if (t.category_id && payeeCategories[t.payee_id] && !payeeCategories[t.payee_id].has(t.category_id)) {
+              const priorNames = [...payeeCategories[t.payee_id].values()].join(", ");
+              flags.push(`category_drift:was_${priorNames}`);
+            }
+          }
+        }
+        return { ...t, flags };
+      }
+
+      const flaggedTxns = txns.map(flagTransaction);
+
       const isCategorized = (t) => (t.category_id && t.category_name !== "Uncategorized")
-        || (t.subtransactions && t.subtransactions.length > 0) // split transactions are categorized via subtransactions
-        || t.transfer_account_id; // transfers don't need categories
+        || (t.subtransactions && t.subtransactions.length > 0)
+        || t.transfer_account_id;
       const categorized = [], uncategorized = [];
-      for (const t of txns) (isCategorized(t) ? categorized : uncategorized).push(t);
+      for (const t of flaggedTxns) (isCategorized(t) ? categorized : uncategorized).push(t);
+
+      // Group categorized transactions by payee for easier per-group review
+      const byPayee = {};
+      for (const t of categorized) {
+        const key = t.payee_name || "Unknown Payee";
+        if (!byPayee[key]) byPayee[key] = { payee: key, category_name: t.category_name, transactions: [] };
+        byPayee[key].transactions.push(t);
+      }
+      const groups = Object.values(byPayee).map((g) => {
+        // Aggregate flags across all transactions in the group (deduplicated)
+        const allFlags = [...new Set(g.transactions.flatMap((t) => t.flags))];
+        const base = {
+          payee: g.payee,
+          category_name: g.category_name,
+          count: g.transactions.length,
+          total: g.transactions.reduce((sum, t) => sum + t.amount, 0),
+          flags: allFlags,
+        };
+        return summary ? base : { ...base, transactions: g.transactions };
+      });
+
+      // Build uncategorized payload — full transactions by default, by-payee aggregates when summary:true
+      const uncategorizedPayload = (() => {
+        if (!summary) return uncategorized;
+        const byPayeeUncat = {};
+        for (const t of uncategorized) {
+          const key = t.payee_name || "Unknown Payee";
+          if (!byPayeeUncat[key]) byPayeeUncat[key] = { payee_name: key, count: 0, total: 0, flags: new Set() };
+          byPayeeUncat[key].count += 1;
+          byPayeeUncat[key].total += t.amount;
+          for (const f of t.flags) byPayeeUncat[key].flags.add(f);
+        }
+        return Object.values(byPayeeUncat).map((g) => ({
+          payee_name: g.payee_name,
+          count: g.count,
+          total: g.total,
+          flags: [...g.flags],
+        }));
+      })();
+
+      const needsCategoryFirst = {
+        count: uncategorized.length,
+        warning: "Do NOT approve these without assigning a category first",
+      };
+      if (summary) {
+        needsCategoryFirst.payees = uncategorizedPayload;
+      } else {
+        needsCategoryFirst.transactions = uncategorizedPayload;
+      }
+
       return ok({
-        total: txns.length,
+        total: flaggedTxns.length,
+        summary: !!summary,
         ready_to_approve: {
           count: categorized.length,
-          transactions: categorized,
-        },
-        needs_category_first: {
-          count: uncategorized.length,
-          warning: "Do NOT approve these without assigning a category first",
-          transactions: uncategorized,
+          by_payee: groups,
         },
+        needs_category_first: needsCategoryFirst,
+      });
+    })
+);
+
+server.registerTool(
+  "get_overspent_categories",
+  { description: "Get all categories with a negative balance for a given month. Use this to find prior-month overspends that are silently reducing the current month's Ready to Assign.", inputSchema: {
+    budgetId: z.string().optional().describe("Budget ID (uses default if not provided)"),
+    month: z.string().describe("Month in YYYY-MM-DD format (first of month)"),
+  } },
+  ({ budgetId, month }) =>
+    run(async () => {
+      const { data } = await api.months.getBudgetMonth(resolveBudgetId(budgetId), month);
+      const overspent = (data.month.categories || [])
+        .filter((c) => !c.deleted && c.balance < 0 && c.category_group_name !== "Internal Master Category")
+        .map((c) => ({
+          id: c.id,
+          name: c.name,
+          category_group_name: c.category_group_name,
+          budgeted: dollars(c.budgeted),
+          activity: dollars(c.activity),
+          balance: dollars(c.balance),
+        }))
+        .sort((a, b) => a.balance - b.balance);
+      return ok({
+        month,
+        overspent_count: overspent.length,
+        total_overspent: overspent.reduce((sum, c) => sum + c.balance, 0),
+        categories: overspent,
       });
     })
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oliverames/ynab-mcp-server",
-  "version": "1.4.0",
+  "version": "1.7.1",
   "description": "YNAB MCP server with full API coverage",
   "type": "module",
   "main": "index.js",
@@ -12,6 +12,7 @@
   ],
   "scripts": {
     "start": "node index.js",
+    "pretest": "[ -d node_modules ] || npm ci --silent --no-audit --no-fund",
     "test": "node test.js"
   },
   "dependencies": {