# expense-mcp

A minimal [FastMCP](https://github.com/jlowin/fastmcp) server that exposes demo tools for arithmetic and dice rolls. Use it to learn MCP wiring with Claude Desktop or other MCP clients.

## Requirements

- Python **3.13+** (see `.python-version` / `pyproject.toml`)
- [uv](https://docs.astral.sh/uv/) for environments and dependency management

## Setup with uv (step by step)

Follow these in order on a machine that does not have the project set up yet.

### 1. Install uv

Pick the [official installer](https://docs.astral.sh/uv/getting-started/installation/) for your OS. Common one-liners:

**Windows (PowerShell):**

```powershell
irm https://astral.sh/uv/install.ps1 | iex
```

**macOS / Linux:**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Close and reopen the terminal (or reload your shell profile) so `uv` is on your `PATH`.

### 2. Confirm uv

```bash
uv --version
```

### 3. Get the code

Clone the repository and move into it (use your real clone URL or path):

```bash
git clone <repository-url> expense-mcp
cd expense-mcp
```

If you already have the folder unpacked, just `cd` to the repo root (where `pyproject.toml` lives).

### 4. (Optional) Install a matching Python with uv

If you do not have Python 3.13 available, uv can fetch one:

```bash
uv python install 3.13
```

The repo’s `.python-version` pins **3.13**; `uv sync` will respect that when creating the environment.

### 5. Create the virtual environment and install dependencies

From the repo root:

```bash
uv sync
```

This will:

- Create `.venv` if it is missing (or update it to match the lockfile)
- Install packages from `pyproject.toml` using versions from `uv.lock`

If you prefer to create the venv yourself first (optional):

```bash
uv venv --python 3.13
uv sync
```

### 6. (Optional) Activate the virtual environment

You do **not** need activation if you always use `uv run …` (recommended). To activate:

- **Windows (PowerShell):** `.venv\Scripts\Activate.ps1`
- **Windows (cmd):** `.venv\Scripts\activate.bat`
- **macOS / Linux:** `source .venv/bin/activate`

### 7. Verify the install

```bash
uv run fastmcp --version
uv run python --version
```

You should see a FastMCP version and Python 3.13.x.

### Quick reference (after setup)

| Goal                         | Command                    |
| ---------------------------- | -------------------------- |
| Reinstall deps from lockfile | `uv sync`                  |
| Add a new dependency         | `uv add <package>`         |
| Refresh `uv.lock` after editing `pyproject.toml` | `uv lock` |
| Run a one-off command in the project env | `uv run <command>` |

## Run the server

**Development / inspector** (useful for debugging tools in the browser):

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

**Production-style run** (stdio transport for MCP clients):

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

**Direct Python** (stdio, same entry as `if __name__ == "__main__"`):

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

## Tools (API)

Defined in `main.py`:

| Tool               | Description                                      |
| ------------------ | ------------------------------------------------ |
| `roll_dice`        | Rolls `n_dice` six-sided dice; returns integers. |
| `add_numbers`      | `a + b`                                          |
| `subtract_numbers` | `a - b`                                          |
| `multiply_numbers` | `a * b`                                          |

Docstrings on each function are what MCP clients show as tool descriptions.

## Install into Claude Desktop

```bash
uv run fastmcp install claude-desktop main.py
```

Then:

1. **Restart** Claude Desktop fully (quit the app, not only the window).
2. In settings, ensure the **expense-mcp** (or similarly named) server is **enabled**.
3. If the install command errors (especially on Windows), see [Claude Desktop: config path / install fails](#claude-desktop-config-path-or-install-fails-windows-store-and-paths).

## Troubleshooting

Use this section when something fails or behaves unexpectedly. Work from the top of each subsection that matches your symptom.

### uv and Python

| Symptom | What to try |
| ------- | ----------- |
| `uv` is not recognized | Install uv (see [Setup](#setup-with-uv-step-by-step)), then **restart the terminal**. Confirm install docs for your OS put `uv` on `PATH`. |
| `uv sync` fails or wrong Python | Run `uv python install 3.13`, then `uv sync` again from the **repo root** (folder that contains `pyproject.toml`). |
| Packages seem missing | From repo root: `uv sync`. Prefer `uv run <command>` so the project `.venv` is used; avoid mixing in a global `python` without the venv. |
| “No `pyproject.toml`” or wrong deps | `cd` to the repository root before `uv sync` / `uv run`. |

### Windows: PowerShell and scripts

| Symptom | What to try |
| ------- | ----------- |
| Running `.venv\Scripts\Activate.ps1` fails (“running scripts is disabled”) | For your user only: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` in PowerShell, then retry. Or use **cmd** and `.\venv\Scripts\activate.bat`. |
| Activation not needed | Using `uv run …` from the repo root avoids activation entirely. |

### Server / dev inspector

| Symptom | What to try |
| ------- | ----------- |
| `ModuleNotFoundError` or wrong `fastmcp` | Run with `uv run` (e.g. `uv run fastmcp dev inspector main.py`), not a system-wide `python` that never had deps installed. |
| Inspector / dev command errors | Run from **repo root**; pass `main.py` or a path that exists. If a port is busy, close other inspector sessions or see FastMCP docs for port options. |
| Stdio server exits immediately | In a terminal: `uv run fastmcp run main.py` or `uv run python main.py` and read the traceback. Fix any import or config error before wiring Claude again. |

### Claude Desktop: MCP does not connect or server errors

| Symptom | What to try |
| ------- | ----------- |
| Server disabled | Settings → MCP: turn **on** the expense-mcp entry; restart Claude. |
| Wrong working directory | The MCP process must run with **`cwd`** (or equivalent) set to this repo so `main.py` and `.venv` resolve. Re-run `uv run fastmcp install claude-desktop main.py` or edit `claude_desktop_config.json` so the launched command’s working directory is the project root. |
| `uv` not found when Claude starts | Use the **full path** to `uv.exe` in config, or ensure the user PATH seen by the desktop app includes uv (often differs from your interactive terminal). |
| JSON config mistakes | Open `claude_desktop_config.json` in an editor with JSON validation. One missing comma breaks the whole file. |

**Manual config shape (illustrative)** — names and keys follow your Claude Desktop version; adjust paths:

```json
"mcpServers": {
  "expense-mcp": {
    "command": "C:\\Users\\you\\AppData\\Local\\Programs\\uv\\uv.exe",
    "args": ["run", "fastmcp", "run", "main.py"],
    "cwd": "C:\\path\\to\\expense-mcp"
  }
}
```

On macOS/Linux use forward slashes and typical `uv` location from `which uv`. Re-installing via `fastmcp install` is usually easier than hand-editing.

### Claude Desktop: config path or install fails (Windows Store and paths)

**Classic path (many installers):** `%APPDATA%\Claude` (contains `claude_desktop_config.json`).

**Microsoft Store build** often uses:

`%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude`

If `fastmcp install claude-desktop` says Claude has no config folder or cannot find it:

1. **Environment variable** — set the directory that **actually** holds `claude_desktop_config.json` (names depend on FastMCP version):
   - `FASTMCP_CLAUDE_DESKTOP_CONFIG_DIR`, or  
   - `CLAUDE_DESKTOP_CONFIG_DIR`  
   Then run `uv run fastmcp install claude-desktop main.py` again in the same terminal session.

2. **Patch in `.venv` (advanced)** — Patching `fastmcp\cli\install\claude_desktop.py` under `.venv` can teach the installer to scan `Packages\Claude_*\LocalCache\Roaming\Claude`. **Any later `uv sync` or fresh venv removes that patch** — re-apply or use option 1 or 3.

3. **Directory junction** — If `%APPDATA%\Claude` does **not** already exist as a real folder, junction it to the Store path (adjust `<your-id>`; may need an elevated **cmd**):

   ```cmd
   mklink /J "%APPDATA%\Claude" "%LOCALAPPDATA%\Packages\Claude_<your-id>\LocalCache\Roaming\Claude"
   ```

   Then run `uv run fastmcp install claude-desktop main.py` again.

Upstream FastMCP may add first-class support for the Store layout so patching or junctions are unnecessary.

### Assistant answers without using your tools

A normal-looking answer (e.g. “8 + 10 = 18”) **does not** prove the MCP ran. Check for **tool-use** in the UI or force a unique tool.

1. **UI** — Look for a tool / “used …” step, not only the final message.
2. **Explicit instruction** — e.g. “Use the `add_numbers` tool from expense-mcp for 8 and 10 and state that you used the tool.”
3. **Unique tool** — e.g. “Call `roll_dice` with `n_dice=4`.” Matching tool name and die results implicates this server (unless another MCP defines the same tool name).
4. **Proof tool** — Add a tiny tool in `main.py` that returns a string only this project would emit; call it once and compare the tool output.

### Patches or local edits under `.venv` disappeared

Anything changed only inside `.venv` (including hand-patched FastMCP files) is **replaced** when you run `uv sync`, delete `.venv`, or reinstall deps. Prefer env vars, junctions, or documented config over long-lived venv edits; otherwise re-apply the patch after each sync.

## Project layout

| Path           | Role                        |
| -------------- | --------------------------- |
| `main.py`      | FastMCP server and `@mcp.tool` definitions |
| `pyproject.toml` | Package metadata and dependencies |
| `uv.lock`      | Locked dependency versions  |