get_budget_summary

Instructions

Implementation Reference

• src/travel_mcp/server.py:155-163 (handler)

  MCP tool handler for 'get_budget_summary'. Decorated with @mcp.tool(), takes a trip_id string and delegates to budget.get_summary(trip_id).

  @mcp.tool()
  def get_budget_summary(trip_id: str) -> dict:
      """
      Get a full budget summary: total spent, remaining balance, and per-category breakdown.
  
      Args:
          trip_id: The trip identifier used when creating the budget
      """
      return budget.get_summary(trip_id)

• src/travel_mcp/server.py:229-233 (registration)

  HTTP API registration for 'get_budget_summary' via @mcp.custom_route at POST /api/tools/get_budget_summary. Extracts trip_id from JSON body and calls budget.get_summary().

  @mcp.custom_route("/api/tools/get_budget_summary", methods=["POST"])
  async def api_get_budget_summary(request: Request) -> JSONResponse:
      body = await request.json()
      result = budget.get_summary(body["trip_id"])
      return JSONResponse(result)

• src/travel_mcp/tools/budget.py:44-77 (helper)

  Core helper function 'get_summary' that computes the full budget summary: total spent, remaining balance, budget used percentage, and per-category breakdown with spending and percentage.

  def get_summary(trip_id: str) -> dict:
      if trip_id not in _budgets:
          return {"error": f"No budget found for trip_id '{trip_id}'."}
  
      record = _budgets[trip_id]
      category_totals: dict[str, float] = {cat: 0.0 for cat in CATEGORIES}
      for expense in record.expenses:
          cat = expense.category if expense.category in CATEGORIES else "misc"
          category_totals[cat] += expense.amount
  
      total_spent = sum(category_totals.values())
      remaining = record.total_budget - total_spent
  
      breakdown = {}
      for cat, spent in category_totals.items():
          pct = (spent / record.total_budget * 100) if record.total_budget > 0 else 0.0
          breakdown[cat] = {
              "spent": round(spent, 2),
              "percentage_of_budget": round(pct, 1),
          }
  
      return {
          "trip_id": trip_id,
          "currency": record.currency,
          "total_budget": record.total_budget,
          "total_spent": round(total_spent, 2),
          "remaining_balance": round(remaining, 2),
          "budget_used_pct": round(total_spent / record.total_budget * 100, 1) if record.total_budget > 0 else 0.0,
          "category_breakdown": breakdown,
          "expenses": [
              {"category": e.category, "amount": e.amount, "description": e.description}
              for e in record.expenses
          ],
      }

• src/travel_mcp/tools/budget.py:1-22 (schema)

  Schema definitions: Expense and BudgetRecord Pydantic models, CATEGORIES constant, and the _budgets in-memory store used by get_summary.

  from __future__ import annotations
  
  from pydantic import BaseModel
  
  CATEGORIES = ["flights", "hotels", "food", "activities", "transport", "shopping", "misc"]
  
  
  class Expense(BaseModel):
      category: str
      amount: float
      description: str
  
  
  class BudgetRecord(BaseModel):
      trip_id: str
      total_budget: float
      currency: str
      expenses: list[Expense] = []
  
  
  _budgets: dict[str, BudgetRecord] = {}

• src/travel_mcp/tools/itinerary.py:120-126 (helper)

  Reference to get_budget_summary in a note generated by the itinerary planner, directing users to use the trip_id with add_expense and get_budget_summary.

  result["budget"] = {
      "trip_id": trip_id,
      "total_budget": total_budget,
      "currency": "USD",
      "suggested_allocation": allocation,
      "note": f"Use trip_id '{trip_id}' with add_expense and get_budget_summary to track spending.",
  }