spending_summary

Instructions

Implementation Reference

• src/tools/spending-summary.ts:26-78 (handler)

  The main handler function for the spending_summary tool. Calls listTransactions to fetch debit transactions, groups them by merchant or category, sorts by total spent descending, and returns an object with groups, totalSpent, currency, and period.

  export async function spendingSummary(
    args: z.infer<typeof spendingSummarySchema>,
  ): Promise<{ groups: SpendingGroup[]; totalSpent: number; currency: string; period: string }> {
    const transactions = await listTransactions({
      connectionId: args.connectionId,
      dateFrom: args.dateFrom,
      dateTo: args.dateTo,
      type: "debit",
    });
  
    const groupBy = args.groupBy || "merchant";
    const limit = args.limit || 20;
  
    // Group expenses
    const groups = new Map<string, { total: number; count: number; currency: string }>();
  
    for (const tx of transactions) {
      const key =
        groupBy === "merchant"
          ? tx.merchantName || tx.description || "Unknown"
          : tx.category || "uncategorized";
  
      const existing = groups.get(key) || { total: 0, count: 0, currency: tx.currency };
      existing.total += Math.abs(tx.amount);
      existing.count += 1;
      groups.set(key, existing);
    }
  
    // Sort by total spent descending
    const sorted = [...groups.entries()]
      .map(([name, data]) => ({
        name,
        totalSpent: Math.round(data.total * 100) / 100,
        transactionCount: data.count,
        currency: data.currency,
      }))
      .sort((a, b) => b.totalSpent - a.totalSpent)
      .slice(0, limit);
  
    const totalSpent =
      Math.round(transactions.reduce((sum, t) => sum + Math.abs(t.amount), 0) * 100) / 100;
  
    const currency = transactions[0]?.currency || "PLN";
    const dateFrom = args.dateFrom || defaultDateFrom(90);
    const dateTo = args.dateTo || today();
  
    return {
      groups: sorted,
      totalSpent,
      currency,
      period: `${dateFrom} to ${dateTo}`,
    };
  }

• src/tools/spending-summary.ts:5-17 (schema)

  Zod schema defining the input parameters for spending_summary: optional connectionId, dateFrom, dateTo, groupBy (merchant/category), and limit.

  export const spendingSummarySchema = z.object({
    connectionId: z.string().optional(),
    dateFrom: z.string().optional(),
    dateTo: z.string().optional(),
    groupBy: z
      .enum(["merchant", "category"])
      .optional()
      .describe('Group expenses by "merchant" (default) or "category".'),
    limit: z
      .number()
      .optional()
      .describe("Max groups to return (default 20, sorted by total spent)."),
  });

• src/server.ts:49-54 (registration)

  Tool registration in the TOOLS array: name 'spending_summary' with description and inputSchema mapped to spendingSummarySchema.

  {
    name: "spending_summary",
    description:
      'Group expenses by merchant or category with totals. Shows where money is being spent. Use groupBy "merchant" for vendor breakdown, "category" for category breakdown.',
    inputSchema: z.toJSONSchema(spendingSummarySchema),
  },

• src/server.ts:66-68 (registration)

  Handler mapping: spending_summary routes args through spendingSummarySchema.parse and calls the spendingSummary function.

    spending_summary: (args) =>
      spendingSummary(spendingSummarySchema.parse(args)),
  };

• src/tools/spending-summary.ts:80-88 (helper)

  Helper functions defaultDateFrom and today used to compute default date range (90 days back from today).

  function defaultDateFrom(days: number): string {
    const d = new Date();
    d.setDate(d.getDate() - days);
    return d.toISOString().slice(0, 10);
  }
  
  function today(): string {
    return new Date().toISOString().slice(0, 10);
  }