get-category-spending

Analyze spending patterns for a specific category over a selected time period to track expenses and monitor budget performance.

Instructions

Get spending in a category

Input Schema

TableJSON Schema

Name	Required	Description	Default
`category`	Yes	Category name
`days`	No	Number of days to look back

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,
                },
            ],
        };
    },
);

lunchmoney-mcp