spending_summary
Analyze spending patterns by grouping expenses into merchant or category breakdowns with totals to identify where money is being spent.
Instructions
Group expenses by merchant or category with totals. Shows where money is being spent. Use groupBy "merchant" for vendor breakdown, "category" for category breakdown.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| connectionId | No | ||
| dateFrom | No | ||
| dateTo | No | ||
| groupBy | No | Group expenses by "merchant" (default) or "category". | |
| limit | No | Max groups to return (default 20, sorted by total spent). |
Implementation Reference
- src/tools/spending-summary.ts:26-78 (handler)Main handler function that fetches debit transactions, groups them by merchant or category, calculates totals, sorts by amount, and returns a spending summary with grouped expenses, total spent, 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)Input schema defined with zod, specifying optional parameters: connectionId, dateFrom, dateTo, groupBy (enum: 'merchant' or 'category'), and limit (default 20).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/tools/spending-summary.ts:19-24 (schema)Output interface definition for SpendingGroup containing name, totalSpent, transactionCount, and currency fields.interface SpendingGroup { name: string; totalSpent: number; transactionCount: number; currency: string; }
- src/server.ts:50-54 (registration)Tool registration in the TOOLS array, defining the tool name 'spending_summary', description, and inputSchema.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-67 (registration)Handler mapping in the handlers object that connects the 'spending_summary' tool name to the spendingSummary function with schema validation.spending_summary: (args) => spendingSummary(spendingSummarySchema.parse(args)),