# SpendWise MCP 📊

[![CI](https://github.com/mrmohdmaaz0786-cell/spendwise-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mrmohdmaaz0786-cell/spendwise-mcp/actions/workflows/ci.yml)

**SpendWise** is a secure, multi-tenant expense-tracking server exposed through the **Model Context Protocol (MCP)**. It allows AI agents (like Claude, Grok, or Cursor) to manage personal finances, analyze spending habits, enforce budgets, and send real-time Telegram alerts.

Built with a focus on production-grade security, strict data validation, and multi-tenant data isolation.

## ✨ Key Features

### 🧾 Core Expense Management
- **Full CRUD**: Create, read, update, and soft-delete expenses.
- **Idempotency & Safety**: Prevents accidental duplicate entries and safely handles network retries using idempotency keys.
- **Multi-Currency Support**: Tracks expenses in any 3-letter currency code (INR, USD, EUR, etc.) without mixing them.

### 📈 Financial Analytics
- **Spending Summaries**: Aggregate active spending by category, month, or merchant over custom date ranges.
- **Period Comparison**: Compare spending across two date ranges with absolute and percentage changes.

### 💰 Budget Management & Alerts
- **Dynamic Budgets**: Set weekly or monthly spending limits per category (upsert logic).
- **Status Tracking**: Automatically calculates budget health (🟢 Healthy, 🟡 Warning at 80%, 🔴 Over Budget at 100%).
- **Telegram Alerts**: Sends real-time notifications via the **CallMeBot API** when budgets are at risk.

### 🔐 Multi-Tenant Security
- **Strict Isolation**: Every expense and budget is scoped to the authenticated user.
- **Dual Auth**: Supports Auth0 RS256 JWTs for production and legacy API keys for local testing.
- **Server-Side Identity**: User identity is derived strictly from verified JWT claims, preventing client-side spoofing.

---

## 🛠 Tech Stack

- **Core**: Python 3.12, MCP SDK (Streamable HTTP), Starlette, Uvicorn
- **Database**: SQLAlchemy 2.0, Alembic (Migrations), SQLite (Local), PostgreSQL (Production)
- **Validation**: Pydantic V2 (Strict schemas, custom validators)
- **Auth**: Auth0 (OAuth2 / JWT RS256)
- **Notifications**: CallMeBot (Telegram API), httpx
- **Testing & CI**: Pytest, Ruff (Lint/Format), GitHub Actions

---

## 🚀 Quick Start

### Requirements
- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (Python package manager)

### Local Setup

1. **Install dependencies:**
   ```powershell
   uv sync


### PROJECT STRUCTURE

spendwise-mcp/
├── .github/workflows/     # CI/CD pipeline (lint, test, migration checks)
├── alembic/versions/      # Database schema migrations
├── src/spendwise/
│   ├── app.py             # Starlette ASGI app & Auth middleware
│   ├── auth.py            # Auth0 JWT & API key verification
│   ├── db.py              # SQLAlchemy engine & session management
│   ├── models.py          # Expense & Budget ORM models
│   ├── notifications.py   # CallMeBot Telegram client
│   ├── schemas.py         # Pydantic V2 validation schemas
│   └── server.py          # MCP server & 14 tool definitions
├── tests/                 # 66 isolated Pytest cases
├── render.yaml            # Infrastructure as Code for Render
└── pyproject.toml         # Project metadata & dependencies