add_expense
Record a new expense with amount, category, and optional description and date. The data is saved locally for tracking personal or business spending.
Instructions
Add a new expense and persist it locally.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | ||
| category | Yes | ||
| description | No | ||
| expense_date | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| amount | Yes | ||
| category | Yes | ||
| description | Yes | ||
| expense_date | Yes | ||
| created_at | Yes |
Implementation Reference
- main.py:174-197 (handler)The 'add_expense' tool handler function. It is decorated with @mcp.tool, loads existing expenses, creates a new Expense with parsed/validated fields, appends it, saves, and returns it.
@mcp.tool def add_expense( amount: float, category: str, description: str = "", expense_date: str | None = None, ) -> Expense: """Add a new expense and persist it locally.""" expenses = _load_expenses() normalized_category = _normalize_text(category, "category") normalized_description = description.strip() expense = Expense( id=str(uuid4()), amount=_parse_amount(amount), category=normalized_category, description=normalized_description, expense_date=_parse_expense_date(expense_date), created_at=datetime.now(timezone.utc).replace(microsecond=0).isoformat(), ) expenses.append(expense) _save_expenses(expenses) return expense - main.py:18-25 (schema)The Expense Pydantic model that serves as the return type (and schema) for the add_expense tool.
class Expense(BaseModel): id: str amount: str category: str description: str expense_date: str created_at: str - main.py:174-175 (registration)The @mcp.tool decorator registers the add_expense function as a FastMCP tool.
@mcp.tool def add_expense( - main.py:122-132 (helper)Helper function _parse_amount used by add_expense to validate and format the amount to 2 decimal places.
def _parse_amount(amount: float) -> str: try: decimal_amount = Decimal(str(amount)) except InvalidOperation as exc: raise ValueError("amount must be a valid number.") from exc if decimal_amount <= 0: raise ValueError("amount must be greater than 0.") normalized = decimal_amount.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) return format(normalized, ".2f") - main.py:135-142 (helper)Helper function _parse_expense_date used by add_expense to parse or default the expense date.
def _parse_expense_date(expense_date: str | None) -> str: if expense_date is None: return date.today().isoformat() try: return date.fromisoformat(expense_date).isoformat() except ValueError as exc: raise ValueError("expense_date must use YYYY-MM-DD format.") from exc