# Weather MCP Server & Client

A Model Context Protocol (MCP) implementation that exposes weather alerts from the [National Weather Service API](https://api.weather.gov) as tools. Includes an interactive chat client powered by Groq LLM and test scripts for both STDIO and SSE transports.

## Table of Contents

- [Prerequisites](#prerequisites)
- [Setup](#setup)
- [Configuration Files](#configuration-files)
- [Use Cases & How to Run](#use-cases--how-to-run)
- [Project Structure](#project-structure)
- [Troubleshooting](#troubleshooting)

---

## Prerequisites

- **Python 3.13+** (see pyproject.toml)
- **uv** – Python package manager ([install](https://docs.astral.sh/uv/))
- **Groq API Key** – for the LLM ([get one](https://console.groq.com/))

## Setup

1. **Clone or navigate to the project:**
   ```bash
   cd /path/to/MCP
   ```

2. **Create a `.env` file** with your Groq API key:
   ```
   GROQ_API_KEY=your_groq_api_key_here
   ```

3. **Install dependencies with uv:**
   ```bash
   uv sync
   ```

   This creates a `.venv` and installs all dependencies from `pyproject.toml`.
   The project uses `langchain>=1.2.0,<2.0.0` for compatibility with mcp-use.

---

## Configuration Files

| File | Purpose |
|------|---------|
| `server/weather_mcp.json` | Default config for stdio: spawns `uv run server/weather.py` |
| `server/weather_stdio_config.json` | Same as above; used by stdio test script |
| `server/weather_sse_config.json` | SSE config: connects to `http://127.0.0.1:8000/sse` |

### Config Format

**STDIO (command-based):**
```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["run", "server/weather.py"]
    }
  }
}
```

**SSE (URL-based):**
```json
{
  "mcpServers": {
    "weather": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}
```

---

## Use Cases & How to Run

All commands use `uv run` to execute scripts with the project's virtual environment and dependencies.

### Case 1: Interactive Chat Client (STDIO)

Run an interactive chat that connects to the weather MCP server. The agent can call `get_alerts` when you ask about weather.

**Run:**
```bash
uv run client_chatbot.py
```

**Commands:**
- Type any question (e.g., "What are the weather alerts for California?")
- `exit` or `quit` – end the session
- `clear` – clear conversation history

**What happens:**
- Client reads `server/weather_mcp.json`
- Spawns `uv run server/weather.py` as a subprocess
- Communicates via stdin/stdout (stdio transport)
- Agent uses Groq LLM and calls `get_alerts` when needed



---

### Case 2: STDIO Transport Test

Explicit test of the stdio transport. Same behavior as Case 2 but uses a dedicated config file.

**Run:**
```bash
uv run test_weather_stdio.py
```

**What happens:**
- Uses `server/weather_stdio_config.json`
- Client spawns `uv run server/weather.py`
- Runs one query and exits

---

### Case 3: SSE Transport Test

Test the SSE (HTTP) transport. The script starts the server in HTTP mode, connects via URL, runs a query, then shuts down the server.

**Run:**
```bash
uv run test_weather_sse.py
```

**What happens:**
1. Starts `server/weather_sse.py` in the background (listens on port 8000)
2. Waits for the server to be ready
3. Connects to `http://127.0.0.1:8000/sse`
4. Runs one query
5. Terminates the server process

---

### Case 4: Run Weather Server Manually (SSE)

Run the weather server as a standalone HTTP process. Useful for debugging or when multiple clients need to connect.

**Run:**
```bash
# Terminal 1: Start the server
uv run server/weather_sse.py
```

Then in another terminal, use a client configured with `url: "http://127.0.0.1:8000/sse"` (e.g., `test_weather_sse.py` or a custom client with `weather_sse_config.json`).

---

### Case 6: Run Weather Server Manually (STDIO)

Running the stdio server directly is rarely useful because it expects JSON-RPC on stdin. It's normally spawned by the client.

For debugging:
```bash
uv run server/weather.py
# Server waits for stdin; won't do anything useful without a client
```

---

## Project Structure

```
MCP/
├── README.md                 # This file
├── .env                      # GroQ API key (create this)
├── pyproject.toml            # Project dependencies
├── client_chatbot.py         # Interactive chat client (stdio)
├── test_weather.py           # Quick one-shot test (stdio)
├── test_weather_stdio.py     # STDIO transport test
├── test_weather_sse.py       # SSE transport test
├── server/
│   ├── weather.py            # MCP server (STDIO transport)
│   ├── weather_sse.py        # MCP server (SSE transport)
│   ├── weather_mcp.json      # Default client config (stdio)
│   ├── weather_stdio_config.json
│   └── weather_sse_config.json
└── src/
    └── app_mcp/
        └── __init__.py       # Package init
```

### MCP Tools Exposed

| Tool | Description | Args |
|------|-------------|------|
| `get_alerts` | Get active weather alerts for a US state | `state` (e.g., "CA", "NY") |

### MCP Resources

| URI | Description |
|-----|-------------|
| `echo://{message}` | Echo a message (for testing) |

---

## Troubleshooting

### "No module named 'mcp_use'"
Run `uv sync` to install dependencies, then use `uv run` for all scripts:
```bash
uv sync
uv run client_chatbot.py
```

### "ModuleNotFoundError: No module named 'httpx'"
Dependencies are in `pyproject.toml`. Run `uv sync` to install.

### "qwen-qwq-32b has been decommissioned"
The project uses `llama-3.3-70b-versatile`. If you see references to `qwen-qwq-32b`, update the model in the client/test scripts.

### "Connection closed" or "Invalid JSON"
Avoid printing to stdout from code that runs in the MCP server process. Stdio uses stdin/stdout for JSON-RPC; any extra output breaks the protocol.

### Port 8000 already in use
Stop the process using port 8000, or change the port in `server/weather_sse.py`:
```python
mcp = FastMCP("weather", host="127.0.0.1", port=8001)
```
Then update `SSE_SERVER_PORT` in `test_weather_sse.py` and the URL in `weather_sse_config.json`.

### Sandbox / uv cache errors
Run with full permissions if you see "Operation not permitted" for uv cache:
```bash
uv run client_chatbot.py  # may need to run outside sandbox
```