# Day 3 Homework: Weather-Prediction MCP Server

A FastMCP server that exposes weather-forecast tools over the Model Context Protocol,
designed to be consumed by a Databricks Agent Bricks agent.

## Architecture

```
Agent Bricks agent  --(MCP tool calls)-->  weather_mcp_server.py  --(HTTP)-->  NWS API (free, no key)
                                                    |
                                                    +--> weather_broker.py (adapter: all HTTP/parsing logic)
```

## MCP Tools Exposed

| Tool | Description |
|------|-------------|
| `get_current_weather(location)` | Real-time temperature, humidity, wind, conditions from nearest NWS station |
| `get_forecast(location, days)` | Multi-day forecast (up to 7 days) with temp, wind, precip chance, conditions |
| `get_weather_alerts(location)` | Active warnings, watches, and advisories for the location |
| `get_travel_recommendation(location, days)` | Derived recommendations with threshold logic (umbrella, jacket, heat, outdoors) |

## Weather API

- **API**: National Weather Service (NWS) — https://www.weather.gov/documentation/services-web-api
- **Auth**: None required (free, public US government API)
- **Coverage**: United States only
- **Geocoding**: Nominatim/OpenStreetMap (free, no key) for resolving city names to coordinates

## Files

| File | Role |
|------|------|
| `weather_mcp_server.py` | FastMCP server with `@mcp.tool` decorators (thin wrappers) |
| `weather_broker.py` | Adapter module — all HTTP calls, parsing, and recommendation logic |
| `lakebase.py` | Lakebase connection helper (same pattern as Day 2/3, for extensibility) |
| `app.yaml` | Databricks App configuration |
| `requirements.txt` | Python dependencies |

## Secrets Required in Databricks

| Secret Scope | Secret Key | Value | Required For |
|---|---|---|---|
| `database` | `lakebase-url` | Base64-encoded Postgres connection URL | Lakebase (optional, for future use) |

> **Note**: The NWS API requires NO API key. No weather-related secrets needed.

## Deploy as Databricks App

1. Upload this entire folder (`day3-homework-mcpserver-weather/`) to your Databricks workspace
2. Create a new Databricks App pointing to this folder
3. The app will start via `python weather_mcp_server.py` (as defined in `app.yaml`)
4. Register the app URL as an external MCP server in Agent Bricks

## Register as External MCP in Agent Bricks

1. Go to your Databricks workspace → Agent Bricks
2. Add a new external MCP tool connection
3. Set the URL to your deployed app's endpoint (e.g. `https://<your-app-url>/mcp`)
4. The 4 tools will be auto-discovered by the agent

## Suggested Agent System Prompt

```
You are a weather assistant that helps users understand weather conditions
and make plans based on forecasts. You have access to real-time weather
data for US locations via the National Weather Service.

Rules:
- ALWAYS use the weather tools to get data. NEVER guess or hallucinate weather information.
- Use get_current_weather() for "what's the weather now?" questions.
- Use get_forecast() for "what will the weather be like?" questions.
- Use get_weather_alerts() when users ask about severe weather or safety.
- Use get_travel_recommendation() for planning questions ("should I bring an umbrella?", "is it a good day for hiking?").
- If a location cannot be resolved, ask the user to clarify with "City, State" format.
- Only US locations are supported. If asked about international locations, explain this limitation.
- If the API returns an error, tell the user honestly rather than making up data.
- When presenting forecasts, summarize the key points rather than dumping raw data.
```

## Local Development

```bash
pip install -r requirements.txt
python weather_mcp_server.py
# Server starts on http://0.0.0.0:8000
```