lunchmoney-mcp

Instructions

Implementation Reference

• src/index.ts:218-258 (handler)

  The async handler function for the 'get-category-spending' tool. It fetches transactions over the specified days, filters by category name (case-insensitive), aggregates total spending by currency, generates a text summary of totals, and lists up to 5 recent matching transactions.

  async ({ category, days }) => {
      const endDate = new Date().toISOString().split('T')[0];
      const startDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000)
          .toISOString()
          .split('T')[0];
  
      const transactions = await this.fetchTransactions({
          start_date: startDate,
          end_date: endDate,
          limit: 1000,
      });
  
      const matchingTransactions = transactions.filter(
          (tx: Transaction) => tx.category_name.toLowerCase() === category.toLowerCase(),
      );
  
      const totals = matchingTransactions.reduce((acc: Record<string, number>, tx: Transaction) => {
          const currency = tx.currency.toUpperCase();
          acc[currency] = (acc[currency] || 0) + Number(tx.amount);
          return acc;
      }, {});
  
      let summary = `Spending in '${category}' over the past ${days} days:\n\n`;
      Object.entries(totals).forEach(([currency, total]) => {
          summary += `${currency}: ${total.toFixed(2)}\n`;
      });
  
      if (matchingTransactions.length > 0) {
          summary += "\nRecent transactions in this category:\n";
          summary += this.formatTransactions(matchingTransactions.slice(0, 5));
      }
  
      return {
          content: [
              {
                  type: "text",
                  text: summary,
              },
          ],
      };
  },

• src/index.ts:214-217 (schema)

  Zod input schema defining parameters: 'category' (string) and 'days' (number, default 30).

  {
      category: z.string().describe("Category name"),
      days: z.number().default(30).describe("Number of days to look back"),
  },

• src/index.ts:211-259 (registration)

  The full tool registration using McpServer.tool(), including name, description, input schema, and inline handler function.

  this.server.tool(
      "get-category-spending",
      "Get spending in a category",
      {
          category: z.string().describe("Category name"),
          days: z.number().default(30).describe("Number of days to look back"),
      },
      async ({ category, days }) => {
          const endDate = new Date().toISOString().split('T')[0];
          const startDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000)
              .toISOString()
              .split('T')[0];
  
          const transactions = await this.fetchTransactions({
              start_date: startDate,
              end_date: endDate,
              limit: 1000,
          });
  
          const matchingTransactions = transactions.filter(
              (tx: Transaction) => tx.category_name.toLowerCase() === category.toLowerCase(),
          );
  
          const totals = matchingTransactions.reduce((acc: Record<string, number>, tx: Transaction) => {
              const currency = tx.currency.toUpperCase();
              acc[currency] = (acc[currency] || 0) + Number(tx.amount);
              return acc;
          }, {});
  
          let summary = `Spending in '${category}' over the past ${days} days:\n\n`;
          Object.entries(totals).forEach(([currency, total]) => {
              summary += `${currency}: ${total.toFixed(2)}\n`;
          });
  
          if (matchingTransactions.length > 0) {
              summary += "\nRecent transactions in this category:\n";
              summary += this.formatTransactions(matchingTransactions.slice(0, 5));
          }
  
          return {
              content: [
                  {
                      type: "text",
                      text: summary,
                  },
              ],
          };
      },
  );