# Weather Prediction MCP Server + Agent Bricks

A Model Context Protocol (MCP) server that exposes weather forecast tools, integrated with Databricks Agent Bricks for natural-language weather queries.

## Architecture

```
┌─────────────────────────────────────┐
│  User Question                      │
│  "Will it rain in Chicago tomorrow?"│
└───────────────┬─────────────────────┘
                │
                v
┌─────────────────────────────────────┐
│  Agent Bricks Agent                 │
│  (Databricks AI)                    │
│  - Interprets question              │
│  - Selects appropriate tools        │
│  - Formats natural-language answer  │
└───────────────┬─────────────────────┘
                │
                v
┌─────────────────────────────────────┐
│  Weather MCP Server                 │
│  (FastMCP, Databricks App)          │
│  Tools:                             │
│  - get_current_weather()            │
│  - get_forecast()                   │
│  - predict_umbrella_needed()        │
└───────────────┬─────────────────────┘
                │
                v
┌─────────────────────────────────────┐
│  Open-Meteo API                     │
│  (Free weather data, no auth)       │
│  - Geocoding                        │
│  - Current conditions               │
│  - Forecast data                    │
└─────────────────────────────────────┘
```

## Components

### 1. Weather MCP Server (`weather_mcp_server/`)

A FastMCP server deployed as a Databricks App that exposes three weather tools:

**Tools:**

* **`get_current_weather(location)`** - Real-time weather conditions
  * Returns: temperature, humidity, wind speed, conditions
  * Example: `get_current_weather("Chicago")`

* **`get_forecast(location, days=7)`** - Multi-day forecast (1-16 days)
  * Returns: daily high/low temps, precipitation chance, conditions
  * Example: `get_forecast("Austin, TX", days=5)`

* **`predict_umbrella_needed(location, target_date=None)`** - Smart recommendation
  * Decision logic: Umbrella needed if precipitation > 40% OR rain-related conditions
  * Returns: boolean recommendation + reasoning
  * Example: `predict_umbrella_needed("Seattle", "2026-08-10")`

### 2. Weather Broker (`weather_broker.py`)

Adapter module for Open-Meteo API:
* `get_current_conditions()` - Fetches current weather
* `get_multi_day_forecast()` - Fetches forecast data
* `_geocode_location()` - Converts city names to lat/lon
* `_map_weather_code()` - Translates WMO codes to human-readable conditions

**API Choice: Open-Meteo**
* Free and open source
* No API key required
* ~10,000 calls/day
* High-quality data from official weather services

### 3. Agent Bricks Agent

A Databricks AI agent configured with:
* System prompt explaining weather-answering capabilities
* External MCP tool registration pointing to the deployed MCP server
* Natural-language interface for weather questions

## Setup Instructions

### Step 1: Deploy MCP Server

1. **Create Databricks secret (if not exists):**
   ```bash
   databricks secrets create-scope mcp_server
   databricks secrets put-secret mcp_server databricks_token
   ```
   (Paste your Databricks token when prompted)

2. **Deploy the app from GitHub:**
   ```bash
   databricks apps create weather-mcp-server \
     --source-code-url https://github.com/amalphonse/weather-mcp-server.git
   ```

3. **Start the app:**
   ```bash
   databricks apps start weather-mcp-server
   ```

4. **Get the app URL:**
   ```bash
   databricks apps get weather-mcp-server
   ```
   Note the `url` field - you'll need this for Agent Bricks.

### Step 2: Register MCP Server with Agent Bricks

1. Navigate to the Agent Bricks UI in Databricks
2. Create a new agent or edit an existing one
3. Under "External Tools", add a new MCP server:
   * **Name:** Weather Forecast Server
   * **URL:** `<your-app-url>` (from Step 1)
   * **Description:** Provides weather forecasts and recommendations

### Step 3: Configure Agent System Prompt

Add this system prompt to your agent:

```
You are a helpful weather assistant with access to real-time weather data through an MCP server.

Your capabilities:
- Get current weather conditions for any location
- Provide multi-day weather forecasts (up to 16 days)
- Make practical recommendations about umbrellas and weather preparation

Available tools:
1. get_current_weather(location) - Use for "now", "current", or "today" questions
2. get_forecast(location, days) - Use for future dates or multi-day forecasts
3. predict_umbrella_needed(location, target_date) - Use when asked about rain gear or travel preparation

Guidelines:
- ALWAYS use the weather tools to get real data - never guess or make up weather information
- If a location cannot be found, ask the user to clarify or try a more specific location
- If the API fails, inform the user clearly and suggest trying again
- When making recommendations, explain your reasoning based on the data
- For precipitation, consider both the percentage chance and the forecasted conditions
- Be conversational and helpful, but always ground your responses in the actual weather data

Example interactions:
- "What's the weather in Chicago?" → Use get_current_weather
- "Will it rain in Seattle this weekend?" → Use get_forecast for the next few days
- "Should I bring an umbrella to Austin tomorrow?" → Use predict_umbrella_needed
```

### Step 4: Test the Agent

Try these example queries:

1. **Current conditions:** "What's the weather like in Chicago right now?"
2. **Forecast:** "Will it be hot in Austin this weekend?"
3. **Recommendation:** "Should I bring an umbrella to Seattle tomorrow?"

## Example Agent Conversations

### Example 1: Current Weather Query

**User:** "What's the weather like in Chicago right now?"

**Tool Call:** `get_current_weather("Chicago")`

**Tool Response:**
```json
{
  "success": true,
  "data": {
    "location": "Chicago",
    "temperature_f": 68.5,
    "temperature_c": 20.3,
    "conditions": "Partly cloudy",
    "humidity": 62,
    "wind_speed_mph": 8.2,
    "last_updated": "2026-08-09T15:30:00"
  }
}
```

**Agent Response:** "In Chicago right now, it's 68.5°F (20.3°C) with partly cloudy skies. The humidity is 62% and there's a light breeze at 8.2 mph. Pleasant conditions overall!"

---

### Example 2: Multi-Day Forecast

**User:** "Will it rain in Seattle this weekend?"

**Tool Call:** `get_forecast("Seattle", days=5)`

**Tool Response:**
```json
{
  "success": true,
  "data": {
    "location": "Seattle",
    "forecast": [
      {
        "date": "2026-08-10",
        "temp_high_f": 69,
        "temp_low_f": 56,
        "precipitation_chance": 65,
        "conditions": "Moderate rain"
      },
      {
        "date": "2026-08-11",
        "temp_high_f": 67,
        "temp_low_f": 55,
        "precipitation_chance": 45,
        "conditions": "Light drizzle"
      }
    ]
  }
}
```

**Agent Response:** "Yes, it will likely rain in Seattle this weekend. Saturday (Aug 10) shows a 65% chance of moderate rain with temperatures between 56-69°F. Sunday (Aug 11) also has a 45% chance of light drizzle. I'd definitely recommend bringing rain gear if you have outdoor plans!"

---

### Example 3: Practical Recommendation

**User:** "Should I bring an umbrella to Austin tomorrow?"

**Tool Call:** `predict_umbrella_needed("Austin", target_date="2026-08-10")`

**Tool Response:**
```json
{
  "success": true,
  "data": {
    "location": "Austin",
    "date": "2026-08-10",
    "umbrella_needed": false,
    "reasoning": "No umbrella needed. Precipitation chance is only 15% and conditions are 'Mainly clear'.",
    "precipitation_chance": 15,
    "conditions": "Mainly clear",
    "temp_high_f": 95,
    "temp_low_f": 76
  }
}
```

**Agent Response:** "No need for an umbrella in Austin tomorrow. The forecast shows mainly clear skies with only a 15% chance of precipitation. It will be hot though - expect temperatures to reach 95°F with a low of 76°F, so you might want to bring sunscreen and stay hydrated instead!"

---

### Example 4: Error Handling

**User:** "What's the weather in Atlantis?"

**Tool Call:** `get_current_weather("Atlantis")`

**Tool Response:**
```json
{
  "success": false,
  "error": "Location 'Atlantis' not found"
}
```

**Agent Response:** "I couldn't find a location called 'Atlantis' in the weather database. Could you please clarify the location? If you meant a specific city, try providing more details like the state or country (e.g., 'Atlanta, Georgia' or 'Atlantic City, New Jersey')."

## Files

* `app.yaml` - Databricks App configuration
* `requirements.txt` - Python dependencies
* `weather_mcp_server.py` - FastMCP server with tool definitions
* `weather_broker.py` - Open-Meteo API adapter
* `README.md` - This file
* `.gitignore` - Git ignore rules

## Dependencies

* `fastmcp>=0.4.0` - MCP server framework
* `fastapi>=0.115.0` - Web framework
* `uvicorn>=0.32.0` - ASGI server
* `requests>=2.32.0` - HTTP client
* `databricks-sdk>=0.35.0` - Secrets management

## Error Handling

* **Location not found:** Returns clear error asking user to clarify
* **API outage:** Returns error message explaining the service is unavailable
* **Invalid date range:** Returns error with valid date range
* **Network timeout:** 10-second timeout with error message

## Notes

* Open-Meteo is free for non-commercial use (~10k calls/day)
* No API key required - zero credentials to manage
* Data sourced from official weather services (NOAA, DWD, etc.)
* Forecast accuracy: Best within 7 days, still useful up to 16 days