# Expenses Tracker

A local-first expense tracking app built with FastAPI, SQLite, React, and Vite.

The backend stores transactions in a local SQLite database, serves the API under `/api`, and serves the built React frontend from the FastAPI app. The project also includes an MCP server for querying and classifying transactions from compatible coding agents.

## Features

- Import bank statement CSV files
- Add, edit, delete, filter, and classify transactions
- Maintain accounts and account groups
- View monthly overview, category totals, and daily reports
- Run a local MCP server for agents to automatically classify your transactions

## Project structure

```text
src/expenses_tracker/
  cli.py                  Command-line entry point
  web.py                  FastAPI app and web-server runner
  database.py             SQLite setup and seed accounts
  transactions.py         Transaction data operations
  import_statement.py     CSV statement import logic
  api/routes.py           API routes
  mcp/server.py           MCP server for expense tools
  static/                 Built frontend served by FastAPI

frontend/
  index.html              Vite entry HTML
  src/                    React source
  vite.config.js          Builds into src/expenses_tracker/static
```

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- Node.js and npm

## Setup

Install Python dependencies:

```bash
uv sync
```

Install frontend dependencies:

```bash
cd frontend
npm install
```

## Build the frontend

The FastAPI app serves the compiled frontend from `src/expenses_tracker/static`.

```bash
cd frontend
npm run build
```

## Run the Web App

```bash
uv run expenses web
```

The app starts on `http://127.0.0.1:8125` and opens the default browser automatically.

## Bank statement imports

The transaction screen imports a CSV file selected through the browser. The API requires the selected file's name and content in the request body.

Expected CSV columns:

- `Transaction Date` in `DD/MM/YYYY` format
- `Transaction Description`
- `Debit Amount`
- `Credit Amount`

Debit amounts are stored as negative pence values. Credit amounts are stored as positive pence values. Imported transactions are assigned to the `Pending` account by default.

## API overview

- `GET /api/health`
- `GET /api/account-groups`
- `GET /api/accounts`
- `POST /api/accounts`
- `GET /api/transactions`
- `POST /api/transactions`
- `PATCH /api/transactions/{transaction_id}`
- `DELETE /api/transactions/{transaction_id}`
- `POST /api/import-bank-statement`

## MCP server

Run the MCP server with:

```bash
uv run expenses mcp
```

Available tools include:

- guarded read-only SQL queries
- transaction listing with filters
- account listing
- pending transaction grouping
- classification summaries
- account assignment for selected transactions or filtered batches

Use dry-run mode before bulk classification changes.

## Development notes

- Frontend source lives in `frontend/src`.
- Frontend build output is committed under `src/expenses_tracker/static` so the FastAPI app can serve the UI directly.
- Local runtime data is stored outside the repository in the operating system's user-data directory.