# ExpenseTracker MCP Server

An [MCP](https://modelcontextprotocol.io) server for tracking personal expenses, built with
[FastMCP](https://gofastmcp.com) 3.x. Expenses are stored in a local SQLite database and
accessed asynchronously via `aiosqlite`.

## Requirements

- Python >= 3.12
- [uv](https://docs.astral.sh/uv/)
- Node.js (only for the MCP Inspector during development)

## Setup

```bash
git clone <repo-url>
cd Test-Remote-Server
uv sync
```

## Running

Start the server over HTTP:

```bash
uv run main.py
```

The server listens on `http://0.0.0.0:8000/mcp`. To use a different port, edit the
`mcp.run(...)` call at the bottom of `main.py`.

## Development

Run the server with the MCP Inspector UI:

```bash
uv run fastmcp dev inspector main.py
```

If the default Inspector ports (`6274`/`6277`) are taken, pick your own:

```bash
uv run fastmcp dev inspector main.py --ui-port 6280 --server-port 6281
```

Note that `uv run` is required — the Inspector spawns `fastmcp` as a child process, and
without `uv run` the virtualenv's `Scripts`/`bin` directory is not on `PATH`.

## Tools

| Tool | Parameters | Description |
| --- | --- | --- |
| `add_expense` | `date`, `amount`, `category`, `subcategory=""`, `note=""` | Add a new expense entry |
| `list_expenses` | `start_date`, `end_date` | List entries in an inclusive date range |
| `summarize` | `start_date`, `end_date`, `category=None` | Total and count per category |

Dates are `YYYY-MM-DD` strings.

## Resources

| URI | Description |
| --- | --- |
| `expense:///categories` | Category list as JSON |

Categories are read from `categories.json` next to `main.py`. If that file is absent, a
built-in default list is served instead.

## Storage

The SQLite database lives at `expenses.db` inside the system temp directory; the path is
printed at startup. It is created automatically on first run.