# Weather-Prediction MCP Server + Agent Bricks Agent

A custom **MCP server** (FastMCP, streamable HTTP) exposing weather tools backed
by **Open-Meteo**, plus a **Databricks Agent Bricks** agent that uses those tools
to answer natural-language weather questions and make simple predictions.

Built on the Day-3 pattern (Alpaca paper-trading MCP server): thin `@mcp.tool`
functions delegating all HTTP/parsing to an adapter module, deployed as a
Databricks App and registered as an external MCP for an agent.

## Architecture

```
Agent Bricks agent  --(MCP tool calls, streamable HTTP)-->  weather_mcp_server.py
                                                                   |
                                                                   v
                                                             weather_broker.py  --(HTTPS)-->  Open-Meteo API
```

- `weather_mcp_server.py` — FastMCP server; thin tools, served over streamable
  HTTP at `/mcp`.
- `weather_broker.py` — adapter: all HTTP calls + JSON parsing live here (same
  role as `alpaca_broker.py`). No MCP knowledge.
- The agent calls tools; the server calls Open-Meteo; results flow back as JSON.

## Weather API + auth

**Open-Meteo** (https://open-meteo.com) — **no signup, no API key**, ~10,000
calls/day for non-commercial use. Chosen because it needs zero credentials, so
there are **no Databricks secrets to manage** for this project, and it bundles
geocoding + current conditions + multi-day forecast in one keyless API. Works
globally (not US-only). Endpoints used:

- Geocoding: `https://geocoding-api.open-meteo.com/v1/search`
- Forecast/current: `https://api.open-meteo.com/v1/forecast`

Because there is no key, there is nothing secret in this repo.

## Tools

| tool | type | what it does |
|---|---|---|
| `get_current_weather(location)` | required | current temp, feels-like, humidity, wind, precipitation, conditions |
| `get_forecast(location, days=3)` | required | daily high/low, precip chance + amount, wind, conditions (1–16 days) |
| `predict_umbrella_needed(location, when="today")` | required (derived) | decides umbrella yes/no from a threshold rule, with an explained reason |
| `get_travel_recommendation(location, when="today")` | stretch (derived) | combines temp/precip/wind into a travel judgment + packing list |
| `compare_cities(locations)` | stretch | compares current conditions across cities; picks warmest + driest |

`location` accepts a city name (`"Chicago"`, `"Austin, TX"`, `"London"`) or a raw
`"lat,lon"` pair. `when` accepts `"today"`, `"tomorrow"`, or an ISO date.

### The prediction tool does real reasoning (not a passthrough)

`predict_umbrella_needed` applies an explicit rule to the target day's forecast:

> **umbrella_needed = True** if `precipitation_probability >= 40%` **OR**
> `precipitation_sum >= 1.0 mm`.

The probability catches "might rain" days; the millimetre floor catches days
where the chance looks modest but meaningful rain is still expected. The tool
returns the boolean **and** a `reason` string naming which threshold fired, so
the agent (and the user) can see *why*. `get_travel_recommendation` layers on
temperature and wind thresholds (hot ≥ 35 °C, freezing ≤ 0 °C, windy ≥ 40 km/h,
wet ≥ 60% or 10 mm) to produce a headline plus a `bring` list.

## Error handling

A bad location or an API outage returns a clean `{"error": "..."}` dict, never a
stack trace, so the agent can react (ask the user to clarify, or report the
outage) instead of failing. Example: `get_current_weather("notaplace")` →
`{"error": "Could not find a location named 'notaplace'."}`.

## Files

- `weather_mcp_server.py` — FastMCP server (5 tools; 3 required + 2 stretch)
- `weather_broker.py` — Open-Meteo adapter (all HTTP/parsing)
- `test_weather.py` — local sanity test (no MCP/Databricks needed)
- `requirements.txt` / `app.yaml` — Databricks App config
- `AGENT_SYSTEM_PROMPT.md` — the agent's system prompt + tool guidance

## Setup

### 1. Test locally (optional, no credentials)

```bash
pip install -r requirements.txt
python test_weather.py           # hits Open-Meteo directly, prints results
python weather_mcp_server.py     # serves MCP at http://localhost:8000/mcp
```

### 2. Deploy the MCP server as a Databricks App

Push this folder to a Git repo, add it as a Git folder in Databricks, then:
**Compute → Apps → Create app → Custom**, name it starting with **`mcp-`**
(e.g. `mcp-weather`), and point it at this folder (which contains `app.yaml`).
Databricks apps listen on port 8000 by default and expose the MCP endpoint at
`https://<app-url>/mcp`. No secret configuration is needed (Open-Meteo is
keyless).

### 3. Register it as an external MCP

**AI Gateway → MCPs → Add MCP**, paste the app's `/mcp` URL (streamable HTTP),
name it `weather-tools`, and save. Databricks introspects and lists the 5 tools.

### 4. Build the Agent Bricks agent

**Agents → Agent Bricks → Create agent** (Custom LLM). Under **Tools**, add the
`weather-tools` MCP server. Paste the system prompt from
`AGENT_SYSTEM_PROMPT.md`. Evaluate, then deploy and chat.

## Demo — 3 natural-language questions

These are the questions to ask the deployed agent (screenshot the tool-calling +
final answers). Sample tool outputs below are from a real run.

**1. "Will it rain in Seattle today — should I bring an umbrella?"**
→ agent calls `predict_umbrella_needed("Seattle", "today")` →
`{"umbrella_needed": false, "precipitation_probability": 0, "precipitation_mm": 0.0,
"reason": "No umbrella needed: only 0% chance and 0.0 mm expected, both below the
thresholds (40% / 1.0 mm)..."}` → agent answers: *"No umbrella needed in Seattle
today — 0% chance of rain, overcast but dry."*

**2. "What's the 3-day forecast for Austin, and is it a good idea to travel there tomorrow?"**
→ `get_forecast("Austin, TX", 3)` then `get_travel_recommendation("Austin, TX", "tomorrow")`
→ recommendation *"Very hot — hydrate and avoid prolonged midday sun"* with
`bring: ["water"]` (highs near 37 °C) → agent summarizes the three days and the
heat advice.

**3. "Which is warmer right now, Chicago, Miami, or Denver?"**
→ `compare_cities(["Chicago","Miami","Denver"])` →
`warmest: "Denver"` (33.6 °C vs Miami 28.0 °C, Chicago 22.2 °C) → agent answers
with the ranking and current conditions.

## Notes / limitations

- Open-Meteo forecasts are model output; the prediction tools apply simple,
  transparent thresholds rather than a trained model — the point is explainable
  reasoning, easily tuned in `weather_mcp_server.py`.
- Temperatures are °C and wind km/h (Open-Meteo defaults); add `temperature_unit`
  / `wind_speed_unit` params in the adapter for Fahrenheit/mph if desired.
- Stretch ideas: severe-weather alerts (layer in the NWS `/alerts` API for US
  locations), historical lookup (Open-Meteo archive API), or a small dashboard
  app that logs agent queries.