# Weather MCP server

An MCP server that exposes three weather tools to a Databricks Agent Bricks
agent. It runs as a Databricks App at

    https://weather-mcp-7474645136578041.aws.databricksapps.com

with the MCP endpoint at `/mcp`. That URL is what gets registered with the
agent as an external MCP server.

The source lives at <https://github.com/gisaf22/weather-mcp>, which is where
the commit history is — this zip carries none.

The app sits behind Databricks workspace authentication, so that URL is not
reachable from outside the workspace: opening it returns a login page rather
than the server. That is expected, not a broken deployment. The
[demonstration screenshots](#demonstration) below are what show it running.

## Data source and auth

Weather data comes from [Open-Meteo](https://open-meteo.com/). I picked it
because it needs no API key and no signup — there are no secrets to manage at
all.

That is a visible difference from the Alpaca paper-trading server this was
patterned on. There, every call had to fetch credentials from a Databricks
secret scope through a `_secret()` helper, and `app.yaml` needed an `env`
block to point at the scope. Here `app.yaml` has no `env` block and
`weather_broker.py` has no `_secret()` equivalent, because there is nothing to
authenticate.

Locations are resolved through Open-Meteo's geocoding endpoint, so any place
name the geocoder knows will work. There is no hardcoded list of supported
cities.

## Files

| File | What it holds |
| --- | --- |
| `weather_mcp_server.py` | The three MCP tools and their docstrings. No `requests` calls live here. |
| `weather_broker.py` | Every HTTP call and all response parsing, plus the WMO weather-code table and the `LocationNotFound` exception. |
| `app.yaml` | Databricks App entrypoint. No `env` block — see above. |
| `requirements.txt` | `fastmcp` and `requests`. |
| `agent/system_prompt.md` | The system prompt configured on the agent, with notes on which rules came from observed failures. |

The split matters: the tool functions compose broker calls and shape the
result, and that is all they do. Swapping Open-Meteo for another provider
means rewriting `weather_broker.py` and leaving the MCP surface alone.

## Tools

### `get_current_weather(location: str) -> dict`

Current conditions for a place name. Returns the resolved location alongside
`temperature_f`, `feels_like_f`, `humidity_pct`, `wind_mph`, `conditions`, and
`observed_at`.

### `get_forecast(location: str, days: int = 3) -> dict`

Daily forecast, 1–7 days. Returns the resolved location plus one entry per day
with `date`, `high_f`, `low_f`, `precipitation_chance_pct`, `max_wind_mph`, and
`conditions`.

### `get_outdoor_recommendation(location: str, date: str | None = None) -> dict`

Judges whether a day suits outdoor plans and says which weather factors drove
the judgment. `date` is ISO `YYYY-MM-DD` and defaults to today at the location.

A factor fires when its condition holds:

| Factor | Condition |
| --- | --- |
| `rain likely` | `precipitation_chance_pct` >= 50 |
| `possible rain` | `precipitation_chance_pct` 30–49 |
| `heat` | `high_f` >= 90 |
| `cold` | `low_f` <= 45 |
| `wind` | `max_wind_mph` >= 25 |
| `thunderstorm` | WMO weather code 95–99 |

The verdict combines them:

| Verdict | When |
| --- | --- |
| `poor` | a thunderstorm is forecast, **or** precipitation >= 50%, **or** high >= 95F |
| `caution` | none of those, but at least one other factor fired |
| `good` | no factor fired |

Each factor carries the **actual value that triggered it**, not just the rule
name:

```json
{"rule": "possible rain", "value": 43, "note": "43% chance of precipitation"}
```

That is the point of the tool. It is the single factor that fired in
demonstration (b) below, on a day with a high of 80.0F: the agent can answer
"a 43% chance of precipitation" instead of only "caution", and the number it
cites is the one the threshold actually tested.

All three tools return `{"status": "error", "message": ...}` on failure — an
unrecognized place, a date outside the forecast range, or an API problem. A
stack trace never reaches the agent; the traceback goes to the app logs.

## Setup

```bash
git clone <this repo>
cd weather-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Run it locally:

```bash
python weather_mcp_server.py     # serves on :8000, MCP at /mcp
```

`weather_broker.py` also runs standalone and exercises the API directly, which
is the fastest way to check the data layer without the MCP wrapper:

```bash
python weather_broker.py
```

## Deploy

Deploy as a Databricks App using this repo as the source, with `app.yaml` as
the entrypoint. Then register `https://<app-url>/mcp` with the Agent Bricks
agent as an external MCP server, and paste `agent/system_prompt.md` into the
agent's instructions.

**Redeploying:** pushing to GitHub does not update the app. The Databricks Git
folder has to pull the new commits first, and only then does a redeploy pick
them up. Pushing and redeploying without the pull in between silently ships the
old code — worth knowing before debugging a fix that appears not to have taken
effect.

## Demonstration

Four exchanges from the Agent Bricks playground, each showing the question, the
tool call the agent made, and its reply.

### (a) "What's the weather in Chicago right now?"

![Agent calling get_current_weather for Chicago](docs/screenshots/chicago-weather-trace.png)

Routes to `get_current_weather` and reports the resolved location as Chicago,
Illinois — so the user can tell it did not answer for Chicago, Jalisco.

### (b) "Should I plan a picnic in Chicago tomorrow?"

![Agent calling get_outdoor_recommendation for Chicago](docs/screenshots/chicago-forecast-trace.png)

Routes to `get_outdoor_recommendation`, which returns a `caution` verdict, and
the agent cites the 43% precipitation figure carried in `factors` rather than
repeating the verdict alone.

### (c) "What's the forecast for Austin this weekend?"

![Agent calling get_forecast for Austin](docs/screenshots/austin-forecast-trace.png)

Routes to `get_forecast` and reports each day by date — "August 9", "August 10",
"August 11" — rather than computing weekday names.

### (d) "What's the weather in Zzyzxville?"

![Agent calling get_current_weather for an unrecognized location](docs/screenshots/invalid-location-trace.png)

Calls `get_current_weather` anyway rather than refusing on its own judgment, and
relays the tool's own error message back to the user as a request to confirm the
spelling.

The earlier failure this replaced — the agent skipping the tool entirely and
declaring the place fictional — no longer reproduces with the system prompt in
place, so there is no screenshot of it. It is described in
[Findings](#the-system-prompt-fixed-the-factual-failures-but-not-the-stylistic-one).

## Findings

Three things I measured rather than assumed.

### FastMCP shows the agent less of the docstring than I wrote

FastMCP builds a tool's description from **only the first prose section** of
its docstring. Everything from the first section header onward is dropped.
`Args:` survives, but as per-parameter descriptions inside the input schema,
not as part of the description. `Returns:` is discarded entirely.

A bare `Header:` line followed by an indented block also parses as a section.
That silently swallowed my verdict rules — the agent could see the factor
thresholds but not how they combined into `poor` / `caution` / `good`. Renaming
the header to `Verdict rules (how the fired factors combine):` was enough to
stop the parser treating it as a section, because the parentheses break the
pattern.

I found this by dumping the live tool descriptions over an MCP client
connection and diffing them against the source, not by reading documentation.
Before the fix, `get_forecast` was sending the agent 205 characters; after
hoisting everything above `Args:`, 1,535. Everything the agent needs — resolved
location semantics, field meanings, the thresholds, the error contract — now
lives in that first prose section.

### Two Open-Meteo fields answer different questions

`weather_code` and `precipitation_probability_max` are not two views of the
same thing. The daily weather code is the most significant weather expected at
*any point* in the day; the probability is the likelihood of measurable rain
*across* the day. They routinely disagree.

Austin returned WMO code 82 — "violent rain showers" in the official table —
next to a 3% precipitation chance. The mapping was correct; the pairing is just
what a daily maximum looks like next to a daily likelihood. The agent reported
it as a contradiction until the docstring explained the difference.

Two fixes. The docstrings now state what each field measures and that a low
percentage beside a stormy label means brief and unlikely, not contradictory.
And the shower labels were softened from the official slight/moderate/violent
wording — "violent rain showers" reads as a severe-weather warning and badly
oversells a 3% day, so codes 80/81/82 now render as "scattered showers",
"rain showers", and "heavy showers possible".

### The system prompt fixed the factual failures but not the stylistic one

Two failures went away once the prompt addressed them directly: inventing
weekday names that did not match the dates, and skipping the tool call
entirely to declare a place fictional. Both are now explicit rules, and both
held.

The second one held in action but not in narration, which is the more
interesting result. In demonstration (d) the agent calls the tool and relays
its error message, exactly as instructed — but its reasoning line reads "I am
going to use the get_current_weather tool... however I anticipate the tool will
return an error because Zzyzxville does not appear to be a real location." The
rule reliably stopped it from *acting* on its own judgment about whether a
place exists. It did not stop it forming that judgment, or saying so out loud.
An instruction can govern which tool call happens; it does not govern what the
model believes on the way there.

One rule did not hold at all. The prompt says not to add generic advice the
tools did not produce, naming hydration reminders and tents specifically. The
agent still appends them: demonstration (c) closes with "Make sure to stay
hydrated and plan for the heat", and (b) with "consider bringing umbrellas or a
tent" — both visible in the screenshots above, neither traceable to anything a
tool returned. I left it. The factual accuracy rules are what matter here, and
chasing the padding with more prompt text was not worth the added instruction
surface.

## Known limitations

- **The thresholds are chosen, not derived.** 90F for heat, 25 mph for wind,
  50% for rain likely — these are my judgment calls, not any published
  standard. They are stated numerically in the tool docstring so the agent can
  explain them, but a different set would be equally defensible.
- **Ambiguous names resolve silently to the largest match.** Open-Meteo orders
  geocoding results by population and the broker takes the first. "Chicago"
  gets Chicago, Illinois, not the real Chicago in Jalisco, Mexico. The resolved
  name, region, and country are returned so the agent can state which one it
  used, but nothing prompts the user to disambiguate before answering.
- **Seven days is the ceiling.** Requests beyond that are clamped, a limit of
  the free Open-Meteo forecast endpoint.