# Weather Forecast MCP Server + Databricks Agent Bricks

A Model Context Protocol (MCP) server that exposes weather forecast tools backed by the Open-Meteo API, integrated with Databricks Agent Bricks to answer natural-language weather questions and make intelligent predictions.

## 📦 Repository & Deployment

**GitHub Repository:** https://github.com/SanthoshKumar777/databricks-weather-predict-mcp-agent  
**Branch:** `main`

**Databricks App:**
- **App Name:** `mcp-weather-server`
- **Status:** ✅ RUNNING
- **App URL:** https://mcp-weather-server-7474646610904631.aws.databricksapps.com
- **MCP Endpoint:** https://mcp-weather-server-7474646610904631.aws.databricksapps.com/mcp

**Key Files:**
- [weather_mcp_server.py](https://github.com/SanthoshKumar777/databricks-weather-predict-mcp-agent/blob/main/weather_mcp_server.py) - FastMCP server with 3 tools
- [weather_broker.py](https://github.com/SanthoshKumar777/databricks-weather-predict-mcp-agent/blob/main/weather_broker.py) - HTTP adapter module
- [requirements.txt](https://github.com/SanthoshKumar777/databricks-weather-predict-mcp-agent/blob/main/requirements.txt) - Dependencies
- [app.yaml](https://github.com/SanthoshKumar777/databricks-weather-predict-mcp-agent/blob/main/app.yaml) - Databricks App config
- [SUBMISSION.md](https://github.com/SanthoshKumar777/databricks-weather-predict-mcp-agent/blob/main/SUBMISSION.md) - Complete submission documentation

## Architecture

```
┌─────────────────────────────────────────────┐
│      Databricks Agent Bricks Agent          │
│  (Natural language weather Q&A + routing)   │
└────────────────┬────────────────────────────┘
                 │ Tool calls
                 ↓
┌─────────────────────────────────────────────┐
│        Weather MCP Server (FastMCP)         │
│  ┌──────────────────────────────────────┐   │
│  │  @mcp.tool decorators (thin layer)   │   │
│  │  - get_current_weather               │   │
│  │  - get_forecast                      │   │
│  │  - predict_umbrella_needed           │   │
│  └──────────┬───────────────────────────┘   │
│             ↓                                │
│  ┌──────────────────────────────────────┐   │
│  │  weather_broker.py (adapter layer)   │   │
│  │  - HTTP calls to Open-Meteo API      │   │
│  │  - Response parsing                  │   │
│  │  - Error handling                    │   │
│  └──────────┬───────────────────────────┘   │
└─────────────┼───────────────────────────────┘
              ↓
     ┌────────────────────┐
     │  Open-Meteo API    │
     │  (Free, no API key)│
     └────────────────────┘
```

## Weather API

**Provider:** [Open-Meteo](https://open-meteo.com/)  
**Authentication:** None required (free tier, ~10,000 calls/day)  
**Data source:** Official government weather models (NOAA, DWD, etc.)  
**Coverage:** Global

### Why Open-Meteo?
* No signup, no API key, no credit card
* Simple REST API with JSON responses
* Reliable and well-documented
* Perfect for educational/demo projects

## MCP Tools (3 Required + Extras)

### 1. `get_current_weather(location: str)`
Returns real-time weather conditions for any location.

**Args:**
- `location`: City name or location string (e.g., "Chicago", "London, UK")

**Returns:**
```json
{
  "location": "Chicago, United States",
  "temperature_f": 45.2,
  "temperature_c": 7.3,
  "conditions": "Partly cloudy",
  "humidity": 72,
  "wind_speed_mph": 12.5,
  "wind_direction": "NW",
  "timestamp": "2026-08-10T14:30:00"
}
```

### 2. `get_forecast(location: str, days: int = 7)`
Returns multi-day weather forecast (up to 16 days).

**Args:**
- `location`: City name or location string
- `days`: Number of forecast days (1-16, default 7)

**Returns:**
```json
{
  "location": "Austin, United States",
  "forecast_days": [
    {
      "date": "2026-08-11",
      "temp_high_f": 92.1,
      "temp_low_f": 73.4,
      "conditions": "Clear sky",
      "precipitation_probability": 10,
      "precipitation_mm": 0.0
    },
    ...
  ]
}
```

### 3. `predict_umbrella_needed(location: str, date: str = None)`
**Smart prediction tool** - applies threshold logic to raw forecast data.

**Logic:**
- Precipitation probability **> 40%** OR precipitation **> 5mm** → "Yes, bring an umbrella"
- Precipitation probability **20-40%** → "Maybe, keep one handy"
- Precipitation probability **< 20%** → "No umbrella needed"

**Args:**
- `location`: City name or location string
- `date`: Target date in YYYY-MM-DD format (defaults to tomorrow if omitted)

**Returns:**
```json
{
  "location": "Seattle, United States",
  "date": "2026-08-11",
  "recommendation": "yes",
  "reason": "High chance of rain (65% probability, 8.2mm expected). Bring an umbrella.",
  "precipitation_probability": 65,
  "precipitation_mm": 8.2,
  "conditions": "Moderate rain"
}
```

## Project Structure

```
databricks-weather-predict-mcp-agent/
├── weather_broker.py          # Adapter: HTTP calls to Open-Meteo API
├── weather_mcp_server.py      # FastMCP server with @mcp.tool decorators
├── requirements.txt           # Python dependencies
├── app.yaml                   # Databricks App configuration
└── README.md                  # This file
```

## Setup & Deployment

### Step 1: Deploy the MCP Server as a Databricks App

```bash
# From your workspace, navigate to the project directory
cd /Workspace/Users/<your-email>/databricks-weather-predict-mcp-agent

# Deploy the app
databricks apps deploy mcp-weather-server \
  --source-code-path /Workspace/Users/<your-email>/databricks-weather-predict-mcp-agent

# Check deployment status
databricks apps get mcp-weather-server
```

Once deployed, note the app URL (e.g., `https://<workspace>.cloud.databricks.com/apps/<app-id>`).

### Step 2: Register the MCP Server as an External Tool

1. Navigate to **Databricks Workspace → Machine Learning → Agents**
2. Click **"+ New External Tool"**
3. Configure:
   - **Name:** `weather_forecast_mcp`
   - **Type:** `MCP Server (HTTP)`
   - **URL:** `https://<workspace>.cloud.databricks.com/apps/<app-id>/mcp`
   - **Authentication:** None (internal app-to-app)
4. Click **"Test Connection"** to verify
5. Save the tool

### Step 3: Create the Agent Bricks Agent

1. Navigate to **Databricks Workspace → Machine Learning → Agents**
2. Click **"+ Create Agent"**
3. Configure:
   - **Name:** `Weather Assistant`
   - **LLM:** Choose your preferred model (e.g., `databricks-dbrx-instruct`)
   - **System Prompt:**

```
You are a helpful weather assistant powered by real-time weather data.

Your capabilities:
1. Check current weather conditions for any location
2. Provide multi-day weather forecasts
3. Make smart predictions (e.g., umbrella recommendations)

Guidelines:
- Always call the appropriate weather tool to get real-time data
- Never guess or hallucinate weather information
- If a location cannot be resolved, ask the user to clarify
- For umbrella predictions, explain the threshold logic you used
- If the API fails, inform the user clearly and suggest trying again
- Be conversational and helpful, but precise about weather data

When answering weather questions:
1. First, call get_current_weather or get_forecast
2. Then, interpret the results in plain language
3. Provide specific numbers (temps, precipitation chance)
4. For predictions, use predict_umbrella_needed and explain the reasoning
```

4. **Add External Tool:**
   - Select `weather_forecast_mcp` from the dropdown
   - Enable all three tools: `get_current_weather`, `get_forecast`, `predict_umbrella_needed`

5. Click **"Create Agent"**

## Example Queries & Demonstrations

### Query 1: Current Weather
**User:** "What's the weather like in Chicago right now?"

**Agent's Tool Call:**
```json
{
  "tool": "get_current_weather",
  "args": {"location": "Chicago"}
}
```

**Agent's Response:**
> "In Chicago, United States, it's currently 45°F (7°C) with partly cloudy skies. The humidity is at 72%, and there's a moderate northwest wind at 12.5 mph."

---

### Query 2: Multi-Day Forecast
**User:** "Will it rain in Austin this weekend?"

**Agent's Tool Call:**
```json
{
  "tool": "get_forecast",
  "args": {"location": "Austin", "days": 3}
}
```

**Agent's Response:**
> "Looking at the 3-day forecast for Austin, United States:
> 
> - **Saturday (Aug 11):** Clear sky, high of 92°F, low of 73°F. Only 10% chance of rain.
> - **Sunday (Aug 12):** Partly cloudy, high of 89°F, low of 72°F. 15% chance of rain.
> - **Monday (Aug 13):** Clear sky, high of 91°F, low of 74°F. No rain expected.
> 
> Overall, it looks like a dry weekend with no rain. Perfect weather for outdoor plans!"

---

### Query 3: Smart Prediction
**User:** "Should I bring a jacket to Seattle tomorrow?"

**Agent's Tool Call:**
```json
{
  "tool": "get_forecast",
  "args": {"location": "Seattle", "days": 2}
}
```

**Agent's Response:**
> "Tomorrow in Seattle, the high will be 58°F with a low of 48°F and partly cloudy conditions. Yes, I'd recommend bringing a jacket—it's going to be quite cool, especially in the morning and evening."

---

### Query 4: Umbrella Prediction
**User:** "Do I need an umbrella in London tomorrow?"

**Agent's Tool Call:**
```json
{
  "tool": "predict_umbrella_needed",
  "args": {"location": "London"}
}
```

**Agent's Response:**
> "Yes, bring an umbrella for London tomorrow (Aug 11). There's a 65% chance of moderate rain with about 8.2mm of precipitation expected. My threshold logic says any precipitation probability over 40% or total rainfall over 5mm warrants an umbrella—and tomorrow exceeds both!"

---

## Error Handling

The MCP server gracefully handles common failure modes:

**Bad Location:**
```json
{
  "error": "Location 'Zzyzyx123' not found. Please check spelling or try a different format (e.g., 'City, Country')."
}
```

**Invalid Date:**
```json
{
  "error": "Invalid date format: 2026-13-99. Use YYYY-MM-DD."
}
```

**API Timeout:**
```json
{
  "error": "Failed to fetch current weather: Connection timeout"
}
```

The Agent Bricks agent then interprets these errors and responds helpfully (e.g., asking the user to clarify the location).

## Testing the MCP Server Directly

You can test the MCP server endpoints directly before wiring up the agent:

```bash
# Test get_current_weather
curl -X POST https://<workspace>.cloud.databricks.com/apps/<app-id>/mcp/call \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "get_current_weather",
      "arguments": {"location": "San Francisco"}
    }
  }'

# Test predict_umbrella_needed
curl -X POST https://<workspace>.cloud.databricks.com/apps/<app-id>/mcp/call \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "predict_umbrella_needed",
      "arguments": {"location": "Seattle", "date": "2026-08-11"}
    }
  }'
```

## Design Principles

✅ **Thin tool functions:** All HTTP/parsing logic lives in `weather_broker.py`, not in `@mcp.tool` functions  
✅ **Clear error messages:** API failures return actionable errors, not stack traces  
✅ **No secrets committed:** Open-Meteo requires no API key, avoiding secrets management  
✅ **Threshold logic:** `predict_umbrella_needed` applies explicit rules (40% threshold, 5mm threshold) and explains them in the docstring  
✅ **Specific system prompt:** The agent is instructed not to hallucinate weather data and always call tools first  

## Future Enhancements (Stretch Goals)

* **Severe Weather Alerts:** Add a tool that calls NWS API (US only) for active warnings/watches
* **Historical Lookups:** Add a tool for past weather data (e.g., "What was the weather like in Paris on Christmas last year?")
* **Multi-City Comparison:** Add a tool to compare weather across multiple cities (e.g., "Which is warmer this weekend, Miami or LA?")
* **Dashboard App:** Build a small Streamlit dashboard (like `dashboard/` in the reference repo) to visualize recent agent queries and predictions

## Troubleshooting

**Problem:** MCP server returns "Location not found"  
**Solution:** Try a different format (e.g., "London, UK" instead of "London"). Some small towns may not be indexed by the geocoding API.

**Problem:** Agent doesn't call the tool  
**Solution:** Check that the tool is enabled in the Agent Bricks configuration and that the system prompt encourages tool usage.

**Problem:** App deployment fails  
**Solution:** Verify `app.yaml` has correct file paths and that `requirements.txt` includes `fastmcp>=3.4.0`.

**Problem:** "Unexpected API response format" error  
**Solution:** Open-Meteo occasionally changes response schemas. Check the [API docs](https://open-meteo.com/en/docs) and update `weather_broker.py` accordingly.

## License

This project is provided as-is for educational purposes. Open-Meteo data is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

---

**Built with:** FastMCP, Open-Meteo API, Databricks Agent Bricks  
**Author:** Your Name  
**Date:** August 10, 2026