# MCP Weather Demo

A demo-ready **Model Context Protocol (MCP)** project that connects a **Google Gemini** agent to a weather MCP server. The agent discovers weather tools automatically and answers natural-language questions using live data from the free [wttr.in](https://wttr.in) API — no weather API key required.

## What This Demo Shows

- **MCP Server** (`server.py`) — exposes 4 weather tools (current weather, daily/hourly forecasts, city comparison).
- **MCP Client** (`client.py`) — a Gemini-powered agent that calls those tools and summarizes results in plain English.
- **Flexible transport** — switch between **HTTP** (default) and **stdio** via `.env`.
- **Clean configuration** — secrets in `.env`, dependencies in `requirements.txt`.

## Architecture / Pseudo-flow

```mermaid
flowchart LR
    User -->|prompt| Client
    Client -->|generate_content tools=[session]| Gemini
    Gemini -->|tool call| Client
    Client -->|MCP call_tool| Server
    Server -->|HTTP| WTTR
    WTTR --> Server --> Client --> Gemini
    Gemini -->|final answer| User
```

**Request lifecycle:**

1. You type a question in the client REPL.
2. The client sends your prompt to **Google Gemini** along with the live MCP session as a tool.
3. Gemini decides which weather tool(s) to call.
4. The client forwards tool calls to the **MCP server** over HTTP or stdio.
5. The server fetches data from **wttr.in** and returns structured JSON.
6. Gemini synthesizes a natural-language answer and prints it back to you.

## Project Structure

```
MCP/
├── client.py          # Gemini agent + MCP client (interactive REPL)
├── server.py          # MCP server with weather tools
├── weather_api.py     # wttr.in API wrapper (no API key needed)
├── requirements.txt   # Python dependencies
├── .env.example       # Environment variable template
├── .gitignore
└── README.md
```

## Prerequisites

- **Python 3.10+**
- A **Google Gemini API key** (free tier available at [Google AI Studio](https://aistudio.google.com/apikey))

## Setup

### 1. Create a virtual environment

```powershell
cd MCP
python -m venv .venv
.venv\Scripts\activate
```

### 2. Install dependencies

```powershell
pip install -r requirements.txt
```

### 3. Configure environment variables

```powershell
copy .env.example .env
```

Edit `.env` and set your Gemini API key:

```dotenv
GEMINI_API_KEY=your_actual_api_key_here
GEMINI_MODEL=gemini-2.5-flash

MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=8000
MCP_HTTP_PATH=/mcp
```

| Variable | Description | Default |
|---|---|---|
| `GEMINI_API_KEY` | Google Gemini API key (**required**) | — |
| `GEMINI_MODEL` | Gemini model name | `gemini-2.5-flash` |
| `MCP_TRANSPORT` | `http` or `stdio` | `http` |
| `MCP_HTTP_HOST` | HTTP server bind address | `127.0.0.1` |
| `MCP_HTTP_PORT` | HTTP server port | `8000` |
| `MCP_HTTP_PATH` | MCP HTTP endpoint path | `/mcp` |

## Running the Demo

### Option A — HTTP mode (default, two terminals)

**Terminal 1 — start the MCP server:**

```powershell
python server.py
```

You should see:

```
[Weather MCP Server] Starting with HTTP transport at http://127.0.0.1:8000/mcp
```

**Terminal 2 — start the Gemini client:**

```powershell
python client.py
```

### Option B — stdio mode (single terminal)

Set in `.env`:

```dotenv
MCP_TRANSPORT=stdio
```

Then run only the client (it launches the server as a subprocess):

```powershell
python client.py
```

## Example Prompts

Try these once the client is running:

- `What's the weather in Tokyo, Japan right now?`
- `Compare the weather between Mumbai, India and London, UK.`
- `Will it rain in Paris in the next 12 hours?`
- `Give me a 3-day forecast for New York, US.`

Type `quit` or `exit` to leave the REPL.

## Available MCP Tools

| Tool | Description |
|---|---|
| `get_current_weather` | Current temperature, humidity, wind, conditions |
| `get_daily_forecast` | Daily min/max temps (up to 3 days) |
| `get_hourly_forecast` | 3-hourly forecast slots (up to 24 slots / 3 days) |
| `compare_weather` | Side-by-side current weather for two cities |

## wttr.in Limitations

- **No API key** required — free for non-commercial use.
- **Daily forecast**: up to **3 days**.
- **Hourly forecast**: **3-hourly** intervals (8 slots per day).
- Requires a `curl`-style User-Agent (handled automatically in `weather_api.py`).
- For best location accuracy, use **"City, Country"** format (e.g. `Tokyo, Japan`) or `City@cc` (e.g. `London@uk`).

## Troubleshooting

| Issue | Fix |
|---|---|
| `Set GEMINI_API_KEY in your .env file` | Copy `.env.example` → `.env` and add your key |
| Client can't connect (HTTP mode) | Make sure `server.py` is running in another terminal |
| `City not found` | Try a more specific name, e.g. "Paris, France" |
| wttr.in timeout | Check internet connection; wttr.in may be temporarily slow |
| Port already in use | Change `MCP_HTTP_PORT` in `.env` (e.g. `8001`) |
| Gemini model error | Try `GEMINI_MODEL=gemini-2.5-flash-lite` in `.env` |

## License

Demo code — free to use and share.