# MCP Weather Server POC

A proof of concept MCP (Model Context Protocol) server that integrates with external REST APIs to provide weather information.

## Features

- **hello**: Simple greeting tool
- **get_weather**: Get weather by latitude and longitude coordinates
- **get_weather_by_location**: Get weather by city/location name

## Weather Data

This POC uses the **Open-Meteo API** (free, no API key required):
- Forecast data: https://api.open-meteo.com/v1/forecast
- Geocoding: https://geocoding-api.open-meteo.com/v1/search

## Setup

### 1. Create Virtual Environment (if not already created)

```bash
python -m venv venv
```

### 2. Activate Virtual Environment

**On Windows (PowerShell):**
```powershell
(Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned) ; (& .\venv\Scripts\Activate.ps1)
```

**On Windows (CMD):**
```cmd
venv\Scripts\activate
```

**On macOS/Linux:**
```bash
source venv/bin/activate
```

### 3. Install Dependencies

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

## Running the Server

```bash
python server.py
```

The server will start and be ready to receive requests from MCP clients.

## Usage Examples

### In an MCP Client

#### Get weather by location name
```
Tool: get_weather_by_location
Parameters:
  - location: "London"
```

Response:
```
Current Weather in London, United Kingdom:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Temperature: 15.2°C
Humidity: 72%
Condition: Partly cloudy
Wind Speed: 12.5 km/h
Time: 2024-06-25T14:30
```

#### Get weather by coordinates
```
Tool: get_weather
Parameters:
  - latitude: 51.5074
  - longitude: -0.1278
```

#### Simple greeting
```
Tool: hello
Parameters:
  - name: "World"
```

## Testing with curl (if exposed via HTTP)

```bash
curl http://localhost:8000/tools/call \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"tool": "get_weather_by_location", "params": {"location": "Tokyo"}}'
```

## Supported Weather Codes

The server uses WMO weather codes and interprets them as:
- 0: Clear sky
- 1-3: Various cloud coverage
- 45-48: Fog conditions
- 51-82: Various precipitation types
- 95-99: Thunderstorm conditions

## Architecture

```
┌──────────────────┐
│   MCP Client     │
└────────┬─────────┘
         │
         │ (MCP Protocol)
         │
┌────────▼─────────────────┐
│   MCP Server (FastMCP)   │
│  ┌──────────────────────┐│
│  │ Tools:               ││
│  │ - hello              ││
│  │ - get_weather        ││
│  │ - get_weather_...    ││
│  └──────────────────────┘│
└────────┬─────────────────┘
         │
         │ (REST API)
         │
┌────────▼──────────────────┐
│   Open-Meteo API          │
│   - Weather Data          │
│   - Geocoding             │
└───────────────────────────┘
```

## Error Handling

The server includes error handling for:
- Network timeouts
- Connection errors
- Invalid locations
- HTTP errors
- Malformed responses

## License

MIT License

## Future Enhancements

- Add historical weather data
- Add weather forecasts (multi-day)
- Add severe weather alerts
- Add precipitation probability
- Support multiple weather providers
- Add caching for repeated requests
- Add UV index information