ynab-mcp

Instructions

Implementation Reference

• src/tools/categories.ts:7-36 (handler)

  The tool "list_categories" is registered and handled within the `registerCategoryTools` function. The handler function uses `getClient().categories.getCategories` to fetch and format the category list.

  server.registerTool("list_categories", {
    title: "List Categories",
    description: "[1 API call] List all categories grouped by category group for a budget",
    inputSchema: {
      budget_id: z.string().default("last-used").describe("Budget ID or 'last-used'"),
      last_knowledge_of_server: z.number().optional().describe("Delta request token"),
    },
    annotations: { readOnlyHint: true },
  }, async ({ budget_id, last_knowledge_of_server }) => {
    try {
      const response = await getClient().categories.getCategories(budget_id, last_knowledge_of_server);
      const groups = response.data.category_groups;
      const lines: string[] = [];
      for (const group of groups) {
        lines.push(`\n## ${group.name} (ID: ${group.id})`);
        if (group.categories) {
          for (const cat of group.categories) {
            if (cat.hidden) continue;
            const budgeted = formatCurrency(cat.budgeted);
            const activity = formatCurrency(cat.activity);
            const balance = formatCurrency(cat.balance);
            lines.push(`  - ${cat.name}: Budgeted ${budgeted} | Activity ${activity} | Balance ${balance} [ID: ${cat.id}]`);
          }
        }
      }
      return textResult(`Categories:${lines.join("\n")}\n\nServer Knowledge: ${response.data.server_knowledge}`);
    } catch (e: any) {
      return errorResult(e.message);
    }
  });