# Weather MCP Agent

This project builds a natural-language weather assistant with Databricks Agent
Bricks and an external Model Context Protocol (MCP) server.

## What we are building

### 1. Weather MCP server

Expose weather tools from a FastMCP server, following the same pattern as
`mcp_server/alpaca_mcp_server.py`. The tools will be backed by a free weather
API such as [Open-Meteo](https://open-meteo.com/), which does not require a
paid tier, API key, or credit card to get started.

### 2. Weather broker/adapter

Add a broker module with the same responsibility as `alpaca_broker.py`. It
will:

- Call the external weather API.
- Handle HTTP requests and response parsing.
- Return clean, predictable dictionaries to the MCP server.

MCP tool functions should remain thin and delegate API and parsing logic to
this adapter.

### 3. Databricks Agent Bricks agent

Create a Databricks Agent Bricks agent that uses the MCP server as an external
tool. The agent should answer natural-language questions such as:

- “Will it rain in Chicago tomorrow?”
- “Should I bring a jacket to Austin this weekend?”

The agent will translate the user’s question into the appropriate weather
tool call and present the result in a useful, conversational response.

### 4. Dashboard

Provide a small application similar to the reference `dashboard/` that calls
the weather MCP server and shows current conditions, a multi-day forecast, and
the explainable umbrella recommendation in one view.

## Intended architecture

```text
User question
     |
     v
Databricks Agent Bricks agent
     |
     v
FastMCP weather server
     |
     v
Weather broker/adapter
     |
     v
Free weather API (Open-Meteo)

Weather MCP server
     ^
     |
Weather dashboard (FastMCP client)
```

The separation between the MCP server and the broker keeps tool definitions
simple, makes the HTTP integration easier to test, and leaves room to change
the weather provider later.

## MCP server implementation

The server is in [`mcp/`](mcp/) and uses FastAPI as the ASGI host for a
streamable-HTTP FastMCP application. The MCP endpoint is `/mcp/`; `/healthz`
is a lightweight liveness endpoint for Databricks Apps.

### Available tools

| Tool | Purpose |
| --- | --- |
| `get_current_weather` | Current temperature, conditions, humidity, precipitation, and wind |
| `get_forecast` | Daily high/low temperatures, conditions, precipitation, and wind for 1-16 days |
| `predict_umbrella_needed` | Explainable umbrella recommendation using 40% precipitation probability or 1 mm expected precipitation thresholds |

Locations can be city names, postal codes, or coordinates in
`"latitude,longitude"` form. The adapter resolves locations and performs all
HTTP calls; MCP functions only delegate to it. Open-Meteo is used without an
API key, paid tier, or credit card, and supports roughly 10,000 calls per day
for non-commercial use.

### Run locally

```bash
uv sync
cd mcp
uv run python weather_mcp_server.py
```

Then check `http://localhost:8000/healthz`. An MCP client should register
`http://localhost:8000/mcp/` as the external MCP URL.

### Deploy and register with Agent Bricks

Deploy [`mcp/app.yaml`](mcp/app.yaml) as its own Databricks App. Register the
deployed app's `/mcp/` URL as an external MCP server in Agent Bricks, then use
the system prompt in
[`mcp/AGENT_SYSTEM_PROMPT.md`](mcp/AGENT_SYSTEM_PROMPT.md). The prompt
requires tool-backed answers, asks for location clarification when needed, and
prevents the agent from guessing during API failures.

Suggested validation questions after registration:

1. “What is the weather in Chicago right now?”
2. “Will it rain in Chicago tomorrow?”
3. “Should I bring an umbrella to Austin this weekend?”

## Dashboard implementation

The dashboard in [`dashboard/`](dashboard/) is a separate FastAPI Databricks
App. It calls the deployed MCP endpoint with FastMCP's client, so its current
conditions, forecast, and recommendation panels use the same tools as Agent
Bricks and do not duplicate Open-Meteo parsing.

Run both apps locally:

```bash
# Terminal 1
PORT=8000 uv run python mcp/weather_mcp_server.py

# Terminal 2
WEATHER_MCP_URL=http://127.0.0.1:8000/mcp/ PORT=8001 \
  uv run python dashboard/app.py
```

Open `http://localhost:8001`. For Databricks deployment, deploy
[`dashboard/app.yaml`](dashboard/app.yaml) as a separate App and set
`WEATHER_MCP_URL` to the deployed MCP App's `/mcp/` URL.