# Weather MCP Server

A Model Context Protocol (MCP) server that provides weather data and intelligent travel recommendations through the OpenMeteo API. This server enables AI agents in Databricks Agent Bricks to access real-time weather information and forecasts for any city worldwide.

## Architecture

```
┌─────────────────┐      ┌──────────────────┐      ┌─────────────────────┐
│                 │      │                  │      │                     │
│  OpenMeteo API  │◄────►│  MCP Server App  │◄────►│ Agent Bricks Agent  │
│                 │      │  (Databricks)    │      │   (Databricks)      │
│  - Weather Data │      │  - FastMCP       │      │  - Natural Language │
│  - Geocoding    │      │  - Tool Exposure │      │  - Tool Invocation  │
│                 │      │                  │      │                     │
└─────────────────┘      └──────────────────┘      └─────────────────────┘
```

## Available Tools

The MCP server exposes four weather-related tools that can be invoked by AI agents:

### 1. `get_current_weather(location: str)`
Get current weather data for a specific city.

**Parameters:**
* `location`: City name (e.g., "Berlin", "New York", "Tokyo")

**Returns:**
* Current temperature (°C)
* Relative humidity (%)
* Precipitation (mm)
* Wind speed (km/h)
* Location coordinates (latitude, longitude)

### 2. `get_forecast(location: str, days: int)`
Get weather forecast for the next N days (up to 16 days).

**Parameters:**
* `location`: City name
* `days`: Number of forecast days (1-16)

**Returns:**
* Daily forecast including:
  * Min/max temperature (°C)
  * Precipitation probability (%)
  * Max wind speed (km/h)
  * Date timestamp

### 3. `get_cities_weather_comparison(locations: list[str], days: int)`
Compare weather across multiple cities and recommend the best weather conditions.

**Parameters:**
* `locations`: List of city names (minimum 2 cities)
* `days`: Number of days to analyze (0 for current weather, 1-16 for forecast)

**Returns:**
* Weather comparison data for all cities
* Weather scores based on temperature, precipitation, wind, and humidity
* Recommendation for the city with the best weather conditions

### 4. `get_travel_recommendation(location: str, days: int)`
Get practical travel recommendations based on weather conditions.

**Parameters:**
* `location`: City name
* `days`: Number of days to analyze (0 for current weather, 1-16 for forecast)

**Returns:**
* Weather summary
* Actionable recommendations (e.g., "Bring an umbrella", "Pack sunscreen")

## Architecture & Setup Guide

### Step 1: Create the Weather Broker Module
First, we created a `weather_broker.py` module that handles:
* **Geocoding**: Translates city names to coordinates using OpenMeteo's geocoding API
* **API Integration**: Connects to OpenMeteo's weather and forecast endpoints
* **Data Processing**: Formats weather data into structured responses

### Step 2: Implement the MCP Server
The `weather_mcp_server.py` file exposes weather tools using FastMCP:
* Defines four MCP tools with clear signatures and documentation
* Handles error cases (invalid locations, API failures)
* Implements weather scoring algorithms for comparisons
* Provides logging for debugging and monitoring

### Step 3: Deploy the MCP Server as a Databricks App
1. Create an `app.yaml` configuration file specifying:
   * Python dependencies (fastmcp, requests)
   * Entry point and command
   * Compute requirements
2. Deploy the app using Databricks Apps
3. The server becomes accessible at a unique URL endpoint

### Step 4: Create an Agent in Agent Bricks Playground
1. Navigate to the Agent Bricks Playground in Databricks
2. Create a new agent
3. Configure the MCP server connection:
   * Add the deployed app URL as an external MCP server
   * The agent automatically discovers the four weather tools

### Step 5: Configure the System Prompt
Set up the agent's system prompt to guide its behavior. For this project, we used:

**Custom System Prompt:**
```
Only answer for locations you can resolve; if the API call fails, say so rather than guessing. 
Ask the user to clarify in case of any error.
```

This prompt ensures the agent:
* Provides accurate information based only on successful API responses
* Avoids hallucinating weather data when locations cannot be resolved
* Clearly communicates API failures to the user
* Requests clarification for ambiguous or invalid locations
* Maintains transparency about data availability

### Step 6: Deploy the Agent as a Databricks App
1. Test the agent in the Playground
2. Once validated, deploy the agent as a production Databricks App
3. Users can now interact with the weather agent through:
   * Web interface
   * API endpoints
   * Integration with other Databricks workflows

## Why OpenMeteo API?

I chose the **OpenMeteo API** for several compelling reasons:

### 1. **Ease of Use and Setup**
* No API key required for basic usage
* Simple RESTful interface with intuitive parameters
* Straightforward JSON responses
* Quick integration without authentication complexity

### 2. **Well-Documented API**
* Comprehensive documentation with clear examples
* Detailed parameter descriptions
* Complete coverage of available data points
* Active community support

### 3. **Generous Request Limits**
* Free tier allows up to 10,000 requests per day
* No credit card required for development and testing
* Sufficient for prototyping and small-scale production use
* Predictable rate limiting policies

### 4. **Geocoding API Integration**
* Built-in geocoding API to translate city names into coordinates
* Eliminates the need for a separate geocoding service
* Handles multiple cities with the same name (returns most relevant)
* Supports international cities with various naming conventions

### 5. **Data Quality and Coverage**
* High-quality weather data from multiple meteorological sources
* Global coverage for virtually any location
* Reliable forecast accuracy up to 16 days
* Frequently updated data (current weather updated every 15 minutes)

## Usage Example

Once deployed, users can interact with the agent using natural language:

```
User: "What's the weather like in Paris right now?"
Agent: [Calls get_current_weather("Paris")]

User: "I'm planning a trip to Tokyo or Seoul next week. Which city has better weather?"
Agent: [Calls get_cities_weather_comparison(["Tokyo", "Seoul"], 7)]

User: "What should I pack for a 3-day trip to London?"
Agent: [Calls get_travel_recommendation("London", 3)]
```

## Technical Stack

* **MCP Framework**: FastMCP (Model Context Protocol)
* **Weather API**: OpenMeteo (free, no-auth weather API)
* **Deployment**: Databricks Apps
* **Agent Platform**: Databricks Agent Bricks
* **Language**: Python 3.x

## Project Structure

```
weather-mcp-server/
├── mcp-server/
│   ├── weather_mcp_server.py   # MCP server implementation
│   ├── weather_broker.py        # OpenMeteo API integration
│   ├── app.yaml                 # Databricks App configuration
│   └── README.md                # This file
```

## Future Enhancements

* Add historical weather data analysis
* Support for hourly forecasts
* Weather alerts and warnings
* Air quality index integration
* Extended forecast range (beyond 16 days)
* Multi-language support for city names
* Caching layer to reduce API calls