# Weather Prediction MCP Server + Agent

Homework submission for 2026-08-08: a FastMCP weather server, a grounded
Databricks Agent Bricks configuration, and an optional weather dashboard. The
project follows the architectural pattern of Day 3's paper-trading project but
uses original weather-domain code and Open-Meteo instead of copying the trading
implementation.

Open-Meteo was selected because its public non-commercial API needs no signup,
API key, paid tier, or Databricks secret. Place and postal-code lookup uses
Open-Meteo's GeoNames-backed geocoding endpoint.

## Architecture

```text
Natural-language question
          |
          v
Databricks Agent Bricks
  (agent/system_prompt.md)
          |
          | streamable HTTP tool call
          v
MCP Databricks App                    Optional dashboard Databricks App
mcp_server/weather_mcp_server.py      dashboard/app.py
          |                                      |
          +---------- weather adapter -----------+
                              |
                              | HTTPS + normalized dicts
                              v
                    Open-Meteo Forecast + Geocoding APIs
```

`mcp_server/` and `dashboard/` are independently deployable Databricks Apps.
Each contains its own adapter copy because an App is deployed from one source
subfolder. A contract test prevents those copies from drifting.

## MCP tools

| Tool | Purpose |
|---|---|
| `get_current_weather(location)` | Temperature, apparent temperature, conditions, humidity, precipitation, and wind for a place/postal code or `lat,lon`. |
| `get_forecast(location, days=7)` | 1–16 daily forecasts with high/low, precipitation chance and total, conditions, wind, sunrise, and sunset. |
| `get_travel_recommendation(location, date)` | Derived umbrella, jacket, heat, wind, and outdoor-planning guidance for a `YYYY-MM-DD` date. |
| `compare_current_weather(locations)` | Stretch tool comparing current weather for 2–5 places and identifying the warmest and windiest. |

The recommendation is deliberately transparent: umbrella at at least 40%
precipitation probability or 1 mm precipitation, jacket below an 18°C high or
10°C low, heat precautions at a 30°C high, and wind caution at 40 km/h. It
returns both the decision and the values/rules that caused it.

All HTTP, retry, location resolution, response parsing, and decision logic is in
`weather_adapter.py`. Decorated functions only call the adapter and translate
errors into safe `{"status": "error", ...}` results. No stack trace, secret, or
raw upstream exception is returned to the agent.

## Repository layout

```text
mcp_server/
  weather_mcp_server.py    FastMCP tools and streamable-HTTP entry point
  weather_adapter.py       Open-Meteo HTTP adapter and recommendation logic
  app.yaml                 MCP Databricks App command
  requirements.txt
dashboard/
  app.py                   Optional Streamlit dashboard
  weather_adapter.py       Independent App copy of the adapter
  app.yaml
  requirements.txt
agent/
  system_prompt.md         Agent Bricks instructions and guardrails
  external_mcp.json        Endpoint/tool registration checklist
  demo_questions.md        Three required demonstration scenarios
docs/evidence/             Safe place for redacted deployment screenshots
tests/                     Unit and project-contract tests (no live API required)
```

## Local development

Use Python 3.10 or later:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
pytest -q
```

Run the MCP server:

```bash
cd mcp_server
python weather_mcp_server.py
```

It listens on `http://localhost:8000`; the streamable-HTTP endpoint is
`http://localhost:8000/mcp`. Use MCP Inspector or another MCP client to list and
call tools. In another terminal, run the optional dashboard:

```bash
cd dashboard
pip install -r requirements.txt
streamlit run app.py
```

No `.env` or credential is required. The tests use fake HTTP sessions and are
repeatable without network access.

## Deploy the MCP server App

The commands below use the current Databricks Apps flow. You can perform the
same steps in **Compute > Apps** and point the App at the `mcp_server/` source
folder.

```bash
databricks auth login --host https://<workspace-hostname>
databricks apps create mcp-weather-prediction

DATABRICKS_USERNAME=$(databricks current-user me | jq -r .userName)
databricks sync mcp_server "/Users/$DATABRICKS_USERNAME/mcp-weather-prediction"
databricks apps deploy mcp-weather-prediction \
  --source-code-path "/Workspace/Users/$DATABRICKS_USERNAME/mcp-weather-prediction"
```

Wait for the App to reach **Running**, copy its URL, and use
`https://<app-url>/mcp` as the MCP endpoint. Access is controlled by the
Databricks App's permissions. No weather secret or resource binding is needed.

Official references:

- [Host your own MCP server as a Databricks App](https://docs.databricks.com/aws/en/agents/mcp/custom-mcp)
- [Use MCP servers in agents](https://docs.databricks.com/aws/en/agents/mcp/use-mcp-in-agents)
- [Open-Meteo forecast API](https://open-meteo.com/en/docs)
- [Open-Meteo geocoding API](https://open-meteo.com/en/docs/geocoding-api)

## Register and build the Agent Bricks agent

Workspace UI labels can vary by preview version. Following the Day 3 workflow:

1. Open **AI Gateway > MCPs** and add/register a custom MCP server.
2. Enter `weather-prediction` as its name and the deployed
   `https://<app-url>/mcp` endpoint. If the UI asks for the backing Databricks
   App instead, select `mcp-weather-prediction`.
3. Confirm that all four tools in `agent/external_mcp.json` are discovered and
   grant the agent/user permission to invoke the App or governed MCP service.
4. Open **Agents > Agent Bricks > Create agent**, choose the available custom
   tool-calling agent type, and add the registered MCP server under **Tools**.
5. Paste the full contents of `agent/system_prompt.md` into the system prompt.
   The prompt requires weather tool calls, defines tool order, handles ambiguous
   locations and errors, and forbids guessed weather.
6. Evaluate with the three prompts in `agent/demo_questions.md`, then deploy the
   agent only after its tool traces and answers are grounded.

Do not replace the evidence placeholders with invented output. Capture actual
Agent Bricks tool calls/final answers after workspace deployment and add redacted
screenshots under `docs/evidence/` or paste transcripts into the demo file.

## Deploy the optional dashboard App

```bash
databricks apps create weather-planner-dashboard
databricks sync dashboard "/Users/$DATABRICKS_USERNAME/weather-planner-dashboard"
databricks apps deploy weather-planner-dashboard \
  --source-code-path "/Workspace/Users/$DATABRICKS_USERNAME/weather-planner-dashboard"
```

The dashboard shows current conditions, a multi-day forecast, one transparent
planning recommendation, and the last ten checks in the current browser session.
It does not claim to persist or display Agent Bricks traces.

## Error handling and limitations

- Ambiguous or missing places return a location error and invite clarification.
- Coordinates are range-checked; forecast days are limited to Open-Meteo's
  16-day window; recommendation dates must be present in the returned forecast.
- HTTP requests use timeouts and retry rate limits/transient 5xx responses.
- Forecasts are predictions, not guarantees. This project does not expose
  severe-weather alerts; users should consult their official local authority for
  safety decisions.
- A place-name lookup selects Open-Meteo's first geocoding result. Include a
  region/country or coordinates when a name is ambiguous.
- The optional dashboard history is browser-session state, not durable storage.

## Submission checklist

- [x] FastMCP server with streamable HTTP
- [x] Separate HTTP/parsing adapter
- [x] Current conditions tool
- [x] 1–16 day forecast tool
- [x] Derived recommendation with documented thresholds
- [x] Stretch city-comparison tool
- [x] Clean errors and no committed API keys
- [x] `requirements.txt` and `app.yaml` for both Apps
- [x] Agent tool list and specific system prompt
- [x] Three demonstration prompts prepared
- [ ] MCP App URL added after deployment
- [ ] Agent Bricks tool-call/final-answer evidence added after deployment
- [ ] Optional dashboard URL/screenshot added after deployment

## Reference pattern

Architecture and deployment flow were informed by
[databricks-lakebase-app-day-3](https://github.com/halloran123/databricks-lakebase-app-day-3)
and the local `weather-intelligence` / `dbbc-helpdesk` repositories. This repo is
an original implementation: the trading broker was replaced with a focused
Open-Meteo adapter, the MCP surface is weather-specific, and the tests and
guardrails are written for weather planning.