get_budget_summary

Instructions

Args:
    budget_id: The ID of the budget (use 'last-used' for default budget)
    month: Month in YYYY-MM-DD format (e.g., 2025-01-01 for January 2025)

Returns:
    JSON string with budget summary including income, budgeted amounts, and category details

Implementation Reference

• src/ynab_mcp/server.py:125-139 (handler)

  MCP tool handler function for get_budget_summary. Registers the tool via @mcp.tool() decorator, validates inputs via type hints and docstring, delegates to YNABClient, and serializes response to JSON.

  @mcp.tool()
  async def get_budget_summary(budget_id: str, month: str) -> str:
      """Get budget summary for a specific month.
  
      Args:
          budget_id: The ID of the budget (use 'last-used' for default budget)
          month: Month in YYYY-MM-DD format (e.g., 2025-01-01 for January 2025)
  
      Returns:
          JSON string with budget summary including income, budgeted amounts, and category details
      """
      client = get_ynab_client()
      result = await client.get_budget_summary(budget_id, month)
      return json.dumps(result, indent=2)

• src/ynab_mcp/ynab_client.py:443-524 (helper)

  Core helper function in YNABClient that implements the business logic: validates inputs, fetches month data from YNAB API endpoint /budgets/{budget_id}/months/{month}, maps categories to groups, filters hidden/deleted, calculates aggregate totals (income, budgeted, activity, balance, to_be_budgeted), and returns structured dictionary with category details.

  async def get_budget_summary(self, budget_id: str, month: str) -> dict[str, Any]:
      """Get budget summary for a specific month.
  
      Uses direct API to get month-specific data since SDK doesn't support it.
  
      Args:
          budget_id: The budget ID or 'last-used'
          month: Month in YYYY-MM-DD format (e.g., 2025-01-01)
  
      Returns:
          Budget summary dictionary
  
      Raises:
          YNABValidationError: If parameters are invalid
          YNABAPIError: If API request fails
      """
      logger.debug(f"Getting budget summary for {budget_id}, month {month}")
  
      # Validate inputs
      budget_id = validate_budget_id(budget_id)
      month = validate_date(month, "month")
  
      # Use direct API call to get month-specific budget data
      url = f"{self.api_base_url}/budgets/{budget_id}/months/{month}"
      result = await self._make_request_with_retry("get", url)
  
      month_data = result["data"]["month"]
  
      # Debug: Check what keys are available
      if "categories" not in month_data:
          raise YNABAPIError(f"Month data keys: {list(month_data.keys())}")
  
      # Get category groups to map category IDs to group names
      categories_response = self.client.categories.get_categories(budget_id)
      category_group_map = {}
      for group in categories_response.data.category_groups:
          for cat in group.categories:
              category_group_map[cat.id] = group.name
  
      # Calculate totals and collect category details
      total_budgeted = 0
      total_activity = 0
      total_balance = 0
      categories = []
  
      # Month data has a flat list of categories, not grouped
      # Filter out hidden and deleted categories
      filtered_categories = self._filter_categories(month_data.get("categories", []))
  
      for category in filtered_categories:
          budgeted = category["budgeted"] / MILLIUNITS_FACTOR if category["budgeted"] else 0
          activity = category["activity"] / MILLIUNITS_FACTOR if category["activity"] else 0
          balance = category["balance"] / MILLIUNITS_FACTOR if category["balance"] else 0
  
          total_budgeted += budgeted
          total_activity += activity
          total_balance += balance
  
          category_group_name = category_group_map.get(category["id"], "Unknown")
  
          categories.append(
              {
                  "category_group": category_group_name,
                  "category_name": category["name"],
                  "budgeted": budgeted,
                  "activity": activity,
                  "balance": balance,
              }
          )
  
      return {
          "month": month,
          "income": month_data["income"] / MILLIUNITS_FACTOR if month_data.get("income") else 0,
          "budgeted": total_budgeted,
          "activity": total_activity,
          "balance": total_balance,
          "to_be_budgeted": month_data["to_be_budgeted"] / MILLIUNITS_FACTOR
          if month_data.get("to_be_budgeted")
          else 0,
          "categories": categories,
      }

• src/ynab_mcp/server.py:125-125 (registration)

  The @mcp.tool() decorator registers the get_budget_summary function as an MCP tool with FastMCP, automatically generating schema from signature and docstring.

  @mcp.tool()

• src/ynab_mcp/server.py:127-135 (schema)

  Docstring provides input schema description (budget_id str, month str in YYYY-MM-DD) and output format (JSON string with summary details). Type hints reinforce schema.

  """Get budget summary for a specific month.
  
  Args:
      budget_id: The ID of the budget (use 'last-used' for default budget)
      month: Month in YYYY-MM-DD format (e.g., 2025-01-01 for January 2025)
  
  Returns:
      JSON string with budget summary including income, budgeted amounts, and category details
  """