bank-mcp

Instructions

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)),