# Weather-Prediction MCP Server + Agent

Day 3 homework: a weather-forecast MCP server (pattern borrowed from
`databricks-lakebase-app-day-3`'s Alpaca paper-trading MCP server) wired to
a Databricks Agent Bricks agent.

## Architecture

Agent Bricks agent  --(MCP tool calls)-->  mcp_server/weather_mcp_server.py  --(REST)-->  Open-Meteo (+ NWS alerts, US only)

- `mcp_server/weather_mcp_server.py` - FastMCP server exposing 5 tools over
  streamable HTTP (the transport Databricks' MCP gateway expects).
- `mcp_server/weather_broker.py` - adapter module: all HTTP calls and
  response parsing for Open-Meteo (geocoding + forecast) and the NWS
  alerts API. No API key required for either.
- `mcp_server/app.yaml` / `mcp_server/requirements.txt` - Databricks App
  config.

## Weather API + auth

**Open-Meteo** (https://open-meteo.com/) - free, no signup, no API key,
~10,000 calls/day (non-commercial use). No Databricks secret needed.
NWS alerts (https://api.weather.gov/) - also free, no key, US-only.

## Tools

| Tool | Purpose |
|---|---|
| `get_current_weather(location)` | Current temperature, humidity, wind, conditions |
| `get_forecast(location, days)` | Multi-day forecast (temp high/low, precip %, conditions) |
| `predict_umbrella_needed(location, date)` | Judgment call: recommends an umbrella if precipitation probability > 40% (tunable via `UMBRELLA_THRESHOLD_PCT`) |
| `get_severe_weather_alerts(location)` *(stretch)* | Active NWS alerts, US only |
| `compare_weather(locations, date)` *(stretch)* | Side-by-side forecast comparison across cities |

## Setup steps

1. `cd mcp_server && pip install -r requirements.txt`
2. `python weather_mcp_server.py` - serves MCP on `:8000` locally.
3. Sanity-check with an MCP Inspector or `curl` before deploying.
4. Push this repo to your own Git remote.
5. In Databricks: create a Git folder pointing at this repo, then
   **Compute > Apps > Create app > Custom**, name it e.g.
   `weather-forecast-mcp`, source = the Git folder's `mcp_server/`
   subfolder. Deploy, copy the app URL.
6. **AI Gateway > MCPs > Add MCP** - register the app URL as an external
   MCP server (streamable HTTP).
7. **Agents > Agent Bricks > Create agent** - add the registered MCP
   server as a tool, paste in the system prompt below, deploy, and chat
   with it.

## Agent system prompt

You are a weather assistant. Always call a weather tool before answering
any question about current conditions or forecasts - never guess or make
up weather data. Use get_current_weather for "what's it like right now"
questions, get_forecast for future-looking questions, and
predict_umbrella_needed when the user asks whether they need an umbrella,
jacket, or similar. If a location can't be resolved or a tool returns an
error, tell the user plainly and ask them to clarify the location rather
than guessing. Only use get_severe_weather_alerts for US locations.

## Demo

1. "Will it rain in Chicago tomorrow?"
2. "Should I bring a jacket to Austin this weekend?"
3. "Compare the weather in Miami and Denver on 2026-08-15."
4. "What's the weather right now in Dakar?"

*(see attached transcripts/screenshots for full tool-call traces and
answers)*

## Test Transcripts

### 7. Severe-weather alerts: US vs non-US

**Test 7a: US City - Miami, Florida**

```python
>>> get_severe_weather_alerts('Miami')
```

Response:
```json
{
  "location": "Miami",
  "country": "United States",
  "alerts": [
    {
      "event": "Heat Advisory",
      "severity": "Moderate",
      "headline": "Heat Advisory issued August 9 at 1:15AM EDT until August 9 at 6:00PM EDT by NWS Miami FL",
      "effective": "2026-08-09T01:15:00-04:00",
      "expires": "2026-08-09T18:00:00-04:00"
    }
  ]
}
```

**Result:** ✓ Returns active alerts from NWS API (when alerts exist)

---

**Test 7b: Non-US City - Dakar, Senegal**

```python
>>> get_severe_weather_alerts('Dakar')
```

Response:
```json
{
  "location": "Dakar",
  "country": "Senegal",
  "alerts": [],
  "note": "NWS alerts only cover US locations; this location is outside the US."
}
```

**Result:** ✓ Returns empty alerts with explanatory note for non-US locations

---

**Test 7c: US City with no active alerts - Chicago, Illinois**

```python
>>> get_severe_weather_alerts('Chicago')
```

Response:
```json
{
  "location": "Chicago",
  "country": "United States",
  "alerts": []
}
```

**Result:** ✓ Returns empty list when no alerts are active (still queries NWS API)

---

**Run the tests yourself:**
```bash
python test_severe_weather_alerts.py
```

**For your agent playground, try asking:**
- "Are there any weather alerts in Miami?"
- "Check for severe weather in Dakar, Senegal"
- "What weather alerts are active in San Francisco?"

## Notes

- No secrets committed; Open-Meteo and NWS need no auth. If you swap in a
  key-requiring API (e.g. WeatherAPI.com), store the key as a Databricks
  secret following the `_secret()` / `WorkspaceClient().secrets.get_secret()`
  pattern from the Day 3 reference repo's `alpaca_broker.py` - never
  hardcode it.