expense-agent/
├── src/
│   ├── server.py          ← FastMCP entry point
│   ├── config.py          ← All constants & paths
│   ├── database/
│   │   ├── db.py          ← Connection manager (context-manager)
│   │   ├── models.py      ← 11 table definitions
│   │   └── migrations.py  ← Default categories seed
│   ├── schemas/
│   │   ├── expense.py     ← ExpenseCreate, ExpenseUpdate, ExpenseFilters
│   │   ├── category.py    ← CategoryCreate, SubcategoryCreate
│   │   ├── splitwise.py   ← FriendCreate, BalanceCreate, EventExpenseCreate
│   │   └── analytics.py   ← Response shapes
│   ├── services/
│   │   ├── expense_service.py    ← CRUD + dynamic filter engine
│   │   ├── analytics_service.py  ← Summary, budget tracking
│   │   ├── split_service.py      ← Balances + event splits
│   │   └── settlement_service.py ← Minimal transactions algorithm
│   └── tools/
│       ├── expense_tools.py      ← MCP: create, get, update, delete, restore, list
│       ├── category_tools.py     ← MCP: categories & subcategories
│       ├── analytics_tools.py    ← MCP: summaries, budgets, recurring
│       ├── splitwise_tools.py    ← MCP: friends, balances, settle
│       ├── event_tools.py        ← MCP: events, splits, settlements
│       └── search_tools.py       ← MCP: search, quick_stats, CSV, Excel
└── reports/               ← Generated CSV / Excel files

cd d:\Neev\expense-agent
uv run python src/server.py

{
  "mcpServers": {
    "smart-expense-mcp": {
      "command": "uv",
      "args": ["run", "python", "src/server.py"],
      "cwd": "d:\\Neev\\expense-agent"
    }
  }
}

You: "Add ₹450 expense at Domino's, Food category, paid via UPI, tags: dinner, friends"
→ create_expense(title="Domino's Pizza", amount=450, ...)

You: "How much did I spend on food this month?"
→ expense_summary(month=7, year=2026)

You: "I paid ₹600 for Rahul for petrol"
→ record_balance(friend_id=1, amount=600, direction="i_paid", reason="Petrol")

You: "Who owes me money?"
→ overall_balance()

You: "Create Girnar Trip event with Rahul, Prince, Jay"
→ create_event(title="Girnar Trip", member_ids=[1,2,3])

You: "Add ₹4000 hotel expense to Girnar Trip, paid by me, split equally"
→ add_event_expense(event_id=1, title="Hotel", amount=4000, paid_by_friend_id=0, split_type="equal")

You: "Who owes what in the Girnar trip?"
→ event_summary(event_id=1)  # computes minimum transactions automatically

You: "Set a ₹5000 budget for Food in July 2026"
→ set_budget(category_id=1, month=7, year=2026, amount=5000)

You: "Export July 2026 expenses to Excel"
→ generate_excel(year=2026, month=7)

A owes B ₹100,  B owes C ₹100
→ Instead of: A→B, B→C
→ Optimal:    A→C   (1 transaction instead of 2)

fastmcp>=3.4.4
pydantic>=2.0
openpyxl
python-dateutil