Expenses Tracker (MCP Server)

This repository contains the backend for the Expenses Tracker application (MCP server). The README below provides step-by-step instructions for setting up the development environment, running the server, and troubleshooting common issues (including an MCP inspector port conflict which may cause "Dev server failed").

---

Table of Contents

• Project overview
• Prerequisites
• Installation
• Running the development server
• Running the MCP inspector
• Troubleshooting
  • "MCP Inspector PORT IS IN USE" / Dev server failed
  • Other common errors
• Contributing

---

Project overview

A short backend server for the Expenses Tracker app. It provides APIs for recording, retrieving, and reporting expenses used by the client application.

Prerequisites

• Windows (instructions assume PowerShell)
• Python 3.9+ (use the version required by this project)
• A virtual environment tool (venv is recommended)
• Node.js + npm (required by the MCP inspector launcher used by development tooling)
• Git (to clone and manage repository)

Installation (development)

1. Clone the repository:

   git clone <repository-url> cd Expenses_tracker_mcpserver

2. Create and activate a Python virtual environment:

   python -m venv .venv ..venv\Scripts\Activate.ps1 # PowerShell

3. Install project dependencies (using uv):

   uv install

4. (Optional) If the project uses additional frontend or inspector tooling, ensure Node.js packages are available. Typically the inspector launcher is run via npx and does not require a global install.

Running the development server

Start the development server and inspector using the project's dev command. An example (used in this project) is:

uv run fastmcp dev inspector main.py

Note: replace the command above with the project's documented dev command if different. This command will start the MCP server and also launch the inspector (a small Node-based process) that listens on a local port (commonly 6274).

Running the MCP inspector (notes)

The inspector launcher is a Node-based helper that starts alongside the Python dev server. It typically opens a local HTTP endpoint (for example http://localhost:6274) for developer use.

If the inspector fails to start because the port is already in use, the dev server may report:

MCP Inspector PORT IS IN USE at http://localhost:6274 [timestamp] ERROR Dev server failed

Follow the troubleshooting steps below to resolve this.

Troubleshooting

"MCP Inspector PORT IS IN USE" / Dev server failed

Step-by-step resolution (PowerShell):

1. Check which process is listening on the inspector port (replace 6274 with the port shown in your log if different):

   Get-NetTCPConnection -LocalPort 6274 -State Listen | Select-Object LocalAddress,LocalPort,OwningProcess,State

   If you prefer more readable process info include:

   $c = Get-NetTCPConnection -LocalPort 6274 -State Listen -ErrorAction SilentlyContinue if ($c) { Get-Process -Id $c.OwningProcess }

   Example output will show a PID and process name (for example node).

2. Inspect the full command line for that process (helps confirm it's the inspector launcher):

   Get-CimInstance Win32_Process -Filter "ProcessId=<PID>" | Select-Object ProcessId,CommandLine

   Replace <PID> with the OwningProcess value from step 1.

3. If the process is a leftover inspector/dev tool and safe to stop, stop it by PID (preferred to avoid killing unrelated processes by name):

   Stop-Process -Id <PID>

   Example:

   Stop-Process -Id 14536

   Notes:

   • Stop-Process requires appropriate permissions. If it fails, run PowerShell as Administrator.
   • The project-specific logs/command line from step 2 should help confirm it is safe to stop.

4. Restart the dev command after freeing the port:

   uv run fastmcp dev inspector main.py

Alternative options if you cannot stop the process:

• Reboot the machine to clear leftover processes.
• Run the inspector on a different port (if the tooling supports an option or environment variable to change the inspector port). Consult the inspector/fastmcp docs for a --port or similar flag.

Why this happens:

• The Node-based inspector may have been launched previously and not shut down cleanly. The port remains bound and the next attempt to start the inspector fails, which may cause the dev server to abort.

Other common errors

• "ModuleNotFoundError" or missing dependencies: ensure the virtual environment is activated and pip install -r requirements.txt has completed successfully.
• Syntax or runtime errors when starting the server: examine the full traceback printed to the console and fix the first error in the stack — subsequent errors are often caused by the first one.
• Permission errors when binding to ports <1024: avoid using privileged ports for development.

Contributing

• Create feature branches from main or dev per project conventions.
• Run existing tests (if any) before opening PRs.
• Keep changes small and well-documented.

Happy hacking!