# Weather MCP Server

A Model Context Protocol (MCP) server that provides weather data and predictions using the Open-Meteo API.

## Features

* **Current Weather** - Get real-time weather conditions for any location
* **Weather Forecast** - 7-day detailed forecast with temperatures, precipitation, and wind
* **Weather Predictions** - Analyze trends and provide natural language predictions
* **Smart Recommendations** - Personalized advice based on weather conditions

## Architecture

The project follows a clean separation of concerns:

* `weather_broker.py` - Adapter module that handles all HTTP/API interactions with Open-Meteo
* `weather_mcp_server.py` - FastMCP server that exposes weather capabilities as MCP tools
* `app.yaml` - Databricks App configuration for deployment
* Clean data flow: API → Broker → Dictionaries → MCP Tools → Formatted responses

## Installation

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

## Usage

### Running the Server

#### Local Development

```bash
python weather_mcp_server.py
```

#### Databricks App Deployment

```bash
# Deploy as a Databricks App
databricks apps deploy weather-mcp-server \
  --source-code-path /Workspace/Users/<your-email>/weather-mcp-agent

# Check app status
databricks apps get weather-mcp-server

```

### Available Tools

#### 1. get_current_weather(location: str)
Get current weather conditions for a location.

```python
get_current_weather("San Francisco")
```

#### 2. get_forecast(location: str, days: int = 7)
Get weather forecast for up to 16 days.

```python
get_forecast("London, UK", days=5)
```

#### 3. predict_weather_trend(location: str)
Analyze weather trends and provide predictions.

```python
predict_weather_trend("Tokyo")
```

#### 4. get_weather_recommendation(location: str)
Get personalized recommendations based on current and upcoming weather.

```python
get_weather_recommendation("New York")
```

## Data Source

Weather data is provided by [Open-Meteo](https://open-meteo.com/), a free weather API that requires no authentication.

## Example Outputs

### Current Weather
```
Current weather in San Francisco, United States:

Condition: Partly cloudy
Temperature: 18°C (feels like 17°C)
Humidity: 65%
Wind: 15 km/h from 270°
Precipitation: 0 mm
```

### Weather Prediction
```
Weather Analysis for London, United Kingdom:

Current Conditions: Overcast at 12°C

7-Day Outlook:
The weather is cooling down over the next week, with temperatures averaging 10.5°C.
You can expect frequent rain, with total precipitation around 45.2 mm.
```

### Recommendations
```
Weather Recommendations for Tokyo, Japan:

🧥 It's quite cold. A jacket and warm clothing recommended.
☔ High chance of rain in the next few days. Keep an umbrella handy!
✨ Great conditions for outdoor activities!
```

## Prediction & Recommendation Thresholds

The server uses the following thresholds for weather recommendations:

### Temperature Recommendations
* **Cold** (< 10°C): Jacket and warm clothing recommended
* **Cool** (10-15°C): Light jacket suggested
* **Comfortable** (15-25°C): No special clothing needed
* **Warm** (> 25°C): Light, breathable clothing suggested

### Precipitation Recommendations
* **High chance** (> 60% probability): Umbrella strongly recommended
* **Moderate chance** (30-60% probability): Consider bringing umbrella
* **Low chance** (< 30% probability): Umbrella not needed

### Wind Conditions
* **Strong wind** (> 30 km/h): Outdoor activity warnings
* **Moderate wind** (15-30 km/h): Normal conditions
* **Light wind** (< 15 km/h): Ideal outdoor conditions

## Technical Details

* Uses FastMCP for MCP server implementation
* HTTP requests handled via httpx with 30-second timeout
* Geocoding resolves location names to coordinates
* WMO weather codes interpreted to human-readable conditions
* Temperature in Celsius, wind speed in km/h
* Supports any location worldwide
* Request middleware with context tracking (host, port, user identity)
* Deployable as a Databricks App

## Error Handling

The server gracefully handles:
* Invalid location names
* API connection issues
* Invalid parameter ranges
* Missing data

## Project Structure

```
weather-mcp-agent/
├── weather_mcp_server.py   # Main FastMCP server
├── weather_broker.py        # Weather API adapter
├── app.yaml                 # Databricks App configuration
├── requirements.txt         # Python dependencies
├── setup_secrets.py         # Secret management helper
├── DEPLOYMENT_FIX.md        # Deployment troubleshooting
└── README.md                # This file
```

## Configuration

### Environment Variables

* `DATABRICKS_APP_PORT` - Server port (default: 8000)
* `DATABRICKS_APP_HOST` - Server host (default: 0.0.0.0)

### Secrets Management

Use `setup_secrets.py` to securely store credentials (lakebase url) in Databricks Secrets instead of hardcoding them in your configuration files.

## Dependencies

* `fastmcp>=0.2.0` - FastMCP server framework
* `httpx>=0.27.0` - HTTP client for API requests
* `typing_extensions>=4.12.0` - Type hints support

## Development Notes

* The server runs on host `0.0.0.0` and port `8000` by default
* FastMCP uses stdio transport for Model Context Protocol communication
* All weather data comes from the free Open-Meteo API (no API key required)
* Request middleware captures context using Python's `contextvars` for thread-safe operation

## Transcript of agent interactions

### Query 1: Recommendation Logic
- **Prompt:** "Should I bring a jacket to Austin this weekend?"
- **Tool Called:** `predict_umbrella_needed(location="Austin, TX", target_date_offset=1)`
- **Response:** "Based on the weather forecast, it's unlikely that you'll need a jacket in Austin this weekend. The temperatures are expected to be quite warm, ranging from 25.6°C to 40.1°C, with minimal chances of precipitation. You may want to consider packing light, breathable clothing and sunscreen instead."

### Query 2: Forecast
- **Prompt:** "What does the weather forecast look like for Austin, TX?"
- **Tool Called:** `get_forecast(location="Austin, TX", days=3)`
- **Response:** "The weather forecast for Austin, TX from August 10th to August 12th is as follows:\n
August 10th: Overcast with temperatures ranging from 26.5°C to 37.3°C and an 8% chance of precipitation.\n
August 11th: Overcast with temperatures ranging from 26.1°C to 38.5°C and a 6% chance of precipitation.\n
August 12th: Overcast with temperatures ranging from 25.6°C to 40.1°C and a 0% chance of precipitation.\n
It's expected to be quite warm and dry, with minimal chances of rain during this period."

### Query 3: Current Weather
- **Prompt:** "What is the current weather in NYC?"
- **Tool Called:** `get_current_weather(location="New York City")`
- **Response:** "The current weather in NYC is a clear sky with a temperature of 23.8°C (feeling like 26.1°C), humidity at 77%, and a wind speed of 8.9 km/h from the northwest. There is no precipitation at the moment. Please note that this information was last updated on August 10th, 2026, at 3:45 AM, so it's recommended to check for updates for the most current weather conditions."

### Query 4: Ask to clarify ambiguous location
- **Prompt:** "can you share the current weather for sjkdfshjdff?"
- **Response:** "I couldn't find any information on a location called "sjkdfshjdff". It's possible that it's a misspelling or a non-existent location. If you could provide a valid city or location name, I'd be happy to try and help you with the current weather."

## Troubleshooting

If you encounter deployment issues, see [DEPLOYMENT_FIX.md](DEPLOYMENT_FIX.md) for common problems and solutions.

## License

MIT License