Merge pull request #3 from madebygps/main

Adds debugging instructions, config, and htp mcp example

Author: madebygps

.vscode/launch.json

@@ -0,0 +1,20 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Attach to MCP Server",
+      "type": "debugpy",
+      "request": "attach",
+      "connect": {
+        "host": "localhost",
+        "port": 5678
+      },
+      "pathMappings": [
+        {
+          "localRoot": "${workspaceFolder}",
+          "remoteRoot": "${workspaceFolder}"
+        }
+      ]
+    }
+  ]
+}

.vscode/mcp.json

@@ -7,7 +7,32 @@
       "args": [
         "run",
         "main.py"
-      ]
+      ],
+      "env": {
+        "PYTHONUNBUFFERED": "1"
+      }
+    },
+    "expenses-mcp-debug": {
+      "type": "stdio",
+      "command": "uv",
+      "cwd": "${workspaceFolder}",
+      "args": [
+        "run",
+        "--",
+        "python",
+        "-m",
+        "debugpy",
+        "--listen",
+        "0.0.0.0:5678",
+        "main.py"
+      ],
+      "env": {
+        "PYTHONUNBUFFERED": "1"
+      }
+    },
+    "expenses-mcp-http": {
+      "type": "http",
+      "url": "http://localhost:8000/mcp"
     }
   },
   "inputs": []

README.md

@@ -4,9 +4,20 @@ This repository implements a **minimal MCP expense tracker**.
 
 The Model Context Protocol (MCP) is an open standard that enables LLMs to connect to external data sources and tools.
 
-## Getting Started
+## Table of Contents
 
-### Environment Setup
+- [Getting Started](#getting-started)
+  - [Environment Setup](#environment-setup)
+  - [Run the MCP Server in VS Code](#run-the-mcp-server-in-vs-code)
+  - [GitHub Copilot Chat Integration](#github-copilot-chat-integration)
+  - [MCP Inspector](#mcp-inspector)
+- [Debugging](#debugging)
+  - [Debugging with VS Code and debugpy](#debugging-with-vs-code-and-debugpy)
+  - [Testing with MCP Inspector](#testing-with-mcp-inspector)
+- [Contributing](#contributing)
+
+
+## Environment Setup
 
 #### 1. GitHub Codespaces 
 
@@ -31,57 +42,56 @@ If you prefer a plain local environment, use **uv** for dependency management:
 uv sync
 ```
 
-### Run the MCP Server in VS Code
-
-1. Open `.vscode/mcp.json` in the editor
-2. Click the **Start** button (▶) above the server name `expenses-mcp`
-3. Confirm in the output panel that the server is running
-
-### GitHub Copilot Chat Integration
+## Using the Expenses MCP Server
 
-Make sure the MCP server is running, then:
+### Run the MCP Server in VS Code with GitHub Copilot (Codespace/Local Dev Container/Local)
 
+1. Open `.vscode/mcp.json` in the editor
+1. Click the **Start** button (▶) above the server name `expenses-mcp`
+1. Confirm in the output panel that the server is running
 1. Open the GitHub Copilot Chat panel (bottom right, or via Command Palette: `GitHub Copilot: Focus Chat`)
-2. Click the **Tools** icon (wrench) at the bottom of the chat panel
-3. Ensure `expenses-mcp` is selected in the list of available tools
-4. Ask Copilot to invoke the tool:
+1. Click the **Tools** icon (wrench) at the bottom of the chat panel
+1. Ensure `expenses-mcp` is selected in the list of available tools
+1. Ask Copilot to invoke the tool:
    - "Use add_expense to record a $12 lunch today paid with visa"
-   - "Read the expenses resource"
 
 ### MCP Inspector
 
-The MCP Inspector is a browser-based visual testing and debugging tool for MCP servers.
+The MCP Inspector is a browser-based visual testing and debugging tool for MCP servers. At the moment it does not work great with non STDIO MCP Servers when working inside of a Codespace.
 
-**Launch the inspector in GitHub Codespaces:**
+#### Launch the MCP Inspector and connect to STDIO MCP Server in GitHub Codespace
 
 1. Run the following command in the terminal:
    ```bash
-   .devcontainer/launch-inspector.sh
+   .devcontainer/launch-inspector-codespace.sh
    ```
-
 2. Note the **Inspector Proxy Address** and **Session Token** from the terminal output
 
 3. In the **Ports** view, set port **6277** to **PUBLIC** visibility
 
 4. Access the Inspector UI and configure:
-   - **Transport Type**: `SSE`
-   - **Inspector Proxy Address**: (from terminal output)
-   - **Proxy Session Token**: (from terminal output)
+   - **Transport Type**: `STDIO`
    - **Command**: `uv`
    - **Arguments**: `run main.py`
+   - Expand configuration area
+   - **Inspector Proxy Address**: (from terminal output)
+   - **Proxy Session Token**: (from terminal output)
 
-**Launch the inspector inside of a Dev Container:**
+#### Launch the MCP Inspector and connect to STDIO MCP Server in VS Code and Dev Container
 
 1. Run the following command in the terminal:
    ```bash
-   HOST=0.0.0.0 DANGEROUSLY_OMIT_AUTH=true npx -y @modelcontextprotocol/inspector uv run main.py
+   HOST=0.0.0.0 DANGEROUSLY_OMIT_AUTH=true npx -y @modelcontextprotocol/inspector
    ```
-2. Open `http://localhost:6274` in your browser
-3. The Inspector should now connect to your MCP server
+1. Open `http://localhost:6274` in your browser
+1. Access the Inspector UI and configure:
+   - **Transport Type**: `STDIO`
+   - **Command**: `uv`
+   - **Arguments**: `run main.py`
 
 > **Note:** `HOST=0.0.0.0` is required in devcontainer environments to bind the Inspector to all network interfaces, allowing proper communication between the UI and proxy server. `DANGEROUSLY_OMIT_AUTH=true` disables authentication - only use in trusted development environments.
 
-**Launch the inspector locally without Dev Container:**
+#### Launch the inspector locally:**
 
 1. Run the following command in the terminal:
    ```bash
@@ -90,6 +100,42 @@ The MCP Inspector is a browser-based visual testing and debugging tool for MCP s
 2. The Inspector will automatically open in your browser at `http://localhost:6274`
 
 
+---
+
+## Debugging
+
+You can attach the VS Code debugger to the running MCP server to set breakpoints and inspect code execution.
+
+### Debugging STDIO MCP server with GitHub Copilot in Codespace/Dev Container/locally
+
+
+1. Open `.vscode/mcp.json` in the editor
+
+2. Start the **expenses-mcp-debug** server (instead of expenses-mcp)
+
+3. In VS Code, open the Run and Debug panel (Ctrl+Shift+D / Cmd+Shift+D)
+
+4. Select **"Attach to MCP Server"** from the dropdown and click the play button (or press F5)
+
+5. In GitHub Copilot Chat, make sure **expenses-mcp-debug** is selected in the tools menu
+
+6. Set breakpoints in `main.py` and use the server from GitHub Copilot Chat. Breakpoints will be hit when tools are invoked.
+
+### Debugging HTTP MCP server with GitHub Copilot in Codespace/Dev Container/locally
+
+1. Run the HTTP MCP Server in the terminal with `uv run -- python -m debugpy --listen 0.0.0.0:5678 main_http.py`
+
+1. Open `.vscode/mcp.json` in the editor
+
+1. Start the **expenses-mcp-debug** server (instead of expenses-mcp)
+
+1. In VS Code, open the Run and Debug panel (Ctrl+Shift+D / Cmd+Shift+D)
+
+1. Select **"Attach to MCP Server"** from the dropdown and click the play button (or press F5)
+
+1. In GitHub Copilot Chat, make sure **expenses-mcp-debug** is selected in the tools menu
+
+1. Set breakpoints in `main_http.py` and use the server from GitHub Copilot Chat. Breakpoints will be hit when tools are invoked.
 
 ---
 

main_http.py

@@ -0,0 +1,130 @@
+import csv
+import logging
+from datetime import date
+from enum import Enum
+from pathlib import Path
+from typing import Annotated
+
+from fastmcp import FastMCP
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(message)s")
+logger = logging.getLogger("ExpensesMCP")
+
+
+SCRIPT_DIR = Path(__file__).parent
+EXPENSES_FILE = SCRIPT_DIR / "expenses.csv"
+
+
+mcp = FastMCP("Expenses Tracker")
+
+
+class PaymentMethod(Enum):
+  AMEX = "amex"
+  VISA = "visa"
+  CASH = "cash"
+
+
+class Category(Enum):
+  FOOD = "food"
+  TRANSPORT = "transport"
+  ENTERTAINMENT = "entertainment"
+  SHOPPING = "shopping"
+  GADGET = "gadget"
+  OTHER = "other"
+
+
+@mcp.tool
+async def add_expense(
+  date: Annotated[date, "Date of the expense in YYYY-MM-DD format"],
+  amount: Annotated[float, "Positive numeric amount of the expense"],
+  category: Annotated[Category, "Category label"],
+  description: Annotated[str, "Human-readable description of the expense"],
+  payment_method: Annotated[PaymentMethod, "Payment method used"],
+):
+  """Add a new expense to the expenses.csv file."""
+  if amount <= 0:
+    return "Error: Amount must be positive"
+
+  date_iso = date.isoformat()
+  logger.info(f"Adding expense: ${amount} for {description} on {date_iso}")
+
+  try:
+    file_exists = EXPENSES_FILE.exists()
+
+    with open(EXPENSES_FILE, "a", newline="", encoding="utf-8") as file:
+      writer = csv.writer(file)
+
+      if not file_exists:
+        writer.writerow(
+          ["date", "amount", "category", "description", "payment_method"]
+        )
+
+      writer.writerow(
+        [date_iso, amount, category.value, description, payment_method.name]
+      )
+
+    return f"Successfully added expense: ${amount} for {description} on {date_iso}"
+
+  except Exception as e:
+    logger.error(f"Error adding expense: {str(e)}")
+    return "Error: Unable to add expense"
+
+
+@mcp.resource("resource://expenses")
+async def get_expenses_data():
+  """Get raw expense data from CSV file"""
+  logger.info("Expenses data accessed")
+
+  try:
+    with open(EXPENSES_FILE, "r", newline="", encoding="utf-8") as file:
+      reader = csv.DictReader(file)
+      expenses_data = list(reader)
+
+    csv_content = f"Expense data ({len(expenses_data)} entries):\n\n"
+    for expense in expenses_data:
+      csv_content += (
+        f"Date: {expense['date']}, "
+        f"Amount: ${expense['amount']}, "
+        f"Category: {expense['category']}, "
+        f"Description: {expense['description']}, "
+        f"Payment: {expense['payment_method']}\n"
+      )
+
+    return csv_content
+
+  except FileNotFoundError:
+    logger.error("Expenses file not found")
+    return "Error: Expense data unavailable"
+  except Exception as e:
+    logger.error(f"Error reading expenses: {str(e)}")
+    return "Error: Unable to retrieve expense data"
+
+
+@mcp.prompt
+def create_expense_prompt(
+  date: str, 
+  amount: float, 
+  category: str, 
+  description: str, 
+  payment_method: str
+) -> str:
+    
+  """Generate a prompt to add a new expense using the add_expense tool."""
+
+  logger.info(f"Expense prompt created for: {description}")
+
+  return f"""
+      Please add the following expense:
+        - Date: {date}
+        - Amount: ${amount}
+        - Category: {category}
+        - Description: {description}
+        - Payment Method: {payment_method}
+      Use the `add_expense` tool to record this transaction.
+      """
+
+
+if __name__ == "__main__":
+  logger.info("MCP Expenses server starting (HTTP mode on port 8000)")
+  # Run in HTTP mode on port 8000
+  mcp.run(transport="http", host="0.0.0.0", port=8000)

pyproject.toml

@@ -6,4 +6,5 @@ readme = "README.md"
 requires-python = ">=3.13"
 dependencies = [
     "fastmcp>=2.12.5",
+    "debugpy>=1.8.0",
 ]