baseline-mcp 0.1.0__tar.gz

baseline_mcp-0.1.0/.env.example

@@ -0,0 +1,2 @@
+BASELINE_API_URL=http://127.0.0.1:5050
+BASELINE_API_KEY=

baseline_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+dist/
+*.egg-info/

baseline_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chad McNutt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

baseline_mcp-0.1.0/METHODOLOGY.md

@@ -0,0 +1,64 @@
+# Methodology
+
+Every number Baseline returns — a percentile rank, a "wetter than normal" label, a water year total — comes from a specific, fixed process described here. Nothing in Baseline's output is generated or estimated by a language model. This document exists so anyone using Baseline, or building on top of it, can check that claim rather than take it on faith.
+
+## The data: ERA5-Land reanalysis
+
+Baseline's historical numbers come from **ERA5-Land**, a reanalysis dataset produced by the European Centre for Medium-Range Weather Forecasts (ECMWF). Reanalysis is not a network of weather stations — it's a physically consistent, gridded reconstruction of the atmosphere built by combining decades of observations (stations, satellites, weather balloons, ships, aircraft) with a fixed numerical weather model, run once, over the whole historical period.
+
+That matters for a specific reason: station records are uneven. Stations open, close, move, get new instruments, or simply don't exist in a lot of the world's more sparsely monitored places. Comparing "this week vs. 1995" at a single station can mean comparing against a different instrument, a different location, or a gap in the record. A reanalysis grid doesn't have that problem — every grid cell has a complete, consistently-produced record for the full period, computed the same way in 2026 as it was for 1996. That consistency, more than raw accuracy at any single point, is why Baseline uses it as its historical baseline.
+
+**Coverage:** 1991–2025, 0.1° resolution (roughly 11 km at the equator), land areas only. ERA5-Land doesn't produce values for ocean grid cells, so locations resolve to the nearest valid land point — this occasionally matters for small islands or immediate coastlines.
+
+## Climatology normals vs. historical ranking — two different periods, on purpose
+
+Baseline uses two different windows of the ERA5-Land record, for two different jobs:
+
+- **"Normal" (the expected value for a given place and date)** is computed over **1991–2020** — the 30-year period the World Meteorological Organization (WMO) designates as the current standard climatological normal. This is the same convention national weather services use, so a Baseline "normal" means the same thing a meteorologist means by it.
+- **Historical ranking** ("3rd driest since 1991," "wetter than 91% of years") is computed over the **full 1991–2025 record** — all years currently available, not just the 30-year normals window. A 35-year ranking window gives a more meaningful answer to "how unusual is this" than a 30-year one would, and it lets the most recent years be ranked against history at all, which a fixed 1991–2020 window couldn't do.
+
+In short: Baseline tells you what's *normal* using the WMO standard, and tells you how *unusual* something is using the fullest record available. Both numbers are labeled with their source period in Baseline's response provenance.
+
+## How rank and percentile are computed
+
+For a given location, date, and variable (precipitation or temperature), Baseline pulls the matching value for every year in the ranking window and compares the current value against that full set:
+
+- **Rank** ("3rd driest," "7th wettest") counts how many years in the record had a more extreme value, plus one. If two other years were wetter than this one, this one ranks 3rd wettest.
+- **Percentile** ("wetter than 83% of years") is the share of years in the record at or below the current value. It answers "where does this year fall in the distribution," independent of how many years are in the record.
+
+Both numbers describe the same underlying comparison from two different angles — rank is easier to say in a sentence, percentile is easier to compare across locations with different record lengths.
+
+## Water year vs. calendar year
+
+Baseline frames cumulative precipitation context two ways, depending on the user's location:
+
+- **Water year** (Oct 1 – Sep 30), used for North American users. This is the standard US hydrological accounting year — it starts in the fall so a full winter snowpack season falls inside a single year, rather than being split across two calendar years.
+- **Calendar year** (Jan 1 – Dec 31), used everywhere else.
+
+This is a real limitation worth being upfront about: the Oct 1 water year start is a US-specific convention, not a global hydrological standard — other countries define their own water years differently, or don't use the concept at all. Baseline currently applies the US convention to North American locations and calendar year everywhere else; the rankings themselves are valid globally, but the Oct 1 start date for North America is a convention choice, not a universal one.
+
+## Forecast data
+
+Baseline's forward-looking numbers (the next 10 days) come from a separate source — **Open-Meteo** — and are never blended with, or used to adjust, the historical ranking. Forecast and historical context are always computed and reported independently.
+
+## Known limitations
+
+- **Land-only, 0.1° grid.** No ocean cells; locations near coastlines or on small islands resolve to the nearest valid land grid point, which may be a few kilometers away.
+- **Archive lag.** The most recent 1–2 months of ERA5-Land data can arrive with precipitation before temperature is finalized. When that gap occurs, Baseline falls back to Open-Meteo's historical archive for temperature and flags the response accordingly — it does not leave the gap unfilled or guess.
+- **Reanalysis vs. a specific station.** ERA5-Land is a model-assimilated reconstruction, not a direct instrument reading. It's built to be highly accurate and, critically, *consistent* across the full record — but a nearby station could show a somewhat different number for any single day.
+- **Oct 1 water year is a US convention**, applied to North American locations by default (see above).
+
+## Provenance line
+
+Every Baseline response ends with a line like:
+
+```
+Source: Baseline v0.1.0 | ERA5-Land reanalysis 1991-2025 (35-yr daily climatology,
+WMO 1991-2020 normals), 0.1-degree resolution, land-only | Forecast: Open-Meteo
+```
+
+Read left to right: the Baseline version that produced this answer (methodology changes bump the version), the historical dataset and the two windows described above, the spatial resolution, and the separate forecast source. If you're relaying a Baseline answer to someone else, this line is the citation.
+
+## About this document
+
+Baseline is built by someone with a background in operational climate services, including work with NOAA. That background is why the reanalysis-vs-station distinction and the "normal" vs. "ranking" period split above are treated as first-class product decisions rather than implementation details — they're the same distinctions a working climate scientist has to get right. Baseline's audience isn't limited to any one field; this methodology holds the same whether the question comes from a ski resort operator, an insurance analyst, a journalist, or a rancher.

baseline_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: baseline-mcp
+Version: 0.1.0
+Summary: MCP server exposing Baseline's statistically rigorous weather and climate context as agent tools.
+Author-email: Chad McNutt <chadmcnutt@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-tools,climate,era5,mcp,weather
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]>=1.28.1
+Requires-Dist: python-dotenv>=1.0
+Description-Content-Type: text/markdown
+
+# baseline-mcp
+
+MCP server exposing Baseline as agent tools — statistically rigorous weather and climate context, not just current conditions. Thin translation layer only: no climate logic lives here, every tool call is an HTTP request to the Baseline API. See `baseline_mcp_server_plan.md` in the Baseline project for the full design, and [`METHODOLOGY.md`](./METHODOLOGY.md) for how the underlying data and rankings are computed.
+
+## Tools
+
+- `get_climate_context` — natural-language weather and climate questions, full context back (forecast + 35-year historical percentile ranking).
+- `get_context_for_coordinates` — same, for an exact lat/lon rather than a place name.
+- `get_water_year_status` — precipitation/temperature status since the start of the water year (Oct 1 US / Jan 1 elsewhere), ranked against 35 years.
+- `compare_to_normal` — how unusual current or forecast conditions are at one location.
+- `compare_locations` — rank precipitation or temperature across 2-10 locations (or a curated category like `colorado_ski_resorts`) in a single call.
+
+## Installation
+
+Requires a Baseline API key. **Self-serve signup isn't available yet** — during this early period, contact Chad McNutt (chadmcnutt@gmail.com) for a key.
+
+```bash
+pip install baseline-mcp
+# or: uvx baseline-mcp
+```
+
+Then add it to your MCP client's config, with your API key:
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "baseline": {
+      "command": "uvx",
+      "args": ["baseline-mcp"],
+      "env": {
+        "BASELINE_API_URL": "https://api.baseline.example",
+        "BASELINE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+**Claude Code**: `claude mcp add baseline --env BASELINE_API_URL=https://api.baseline.example --env BASELINE_API_KEY=your-key-here -- uvx baseline-mcp`
+
+**Cursor** (`.cursor/mcp.json` or global MCP settings): same shape as the Claude Desktop config above, under whatever key Cursor's MCP settings use for server name.
+
+## Local development
+
+The venv lives outside this directory (`~/.venvs/baseline-mcp`) rather than in `.venv/` here, because this project sits under iCloud-synced `~/Documents` — iCloud evicts/re-materializes files inside large venvs unpredictably, which causes intermittent `ModuleNotFoundError`s. Keep it that way.
+
+```bash
+python3 -m venv ~/.venvs/baseline-mcp
+~/.venvs/baseline-mcp/bin/pip install -e .
+cp .env.example .env   # fill in BASELINE_API_URL and a free_api-tier BASELINE_API_KEY
+```
+
+Run against a local Baseline instance (`python3 app.py` in `../baseline`), then:
+
+```bash
+~/.venvs/baseline-mcp/bin/mcp dev src/baseline_mcp/server.py
+```
+
+## Status
+
+All 5 tools built and tested against a live local Baseline instance, including tool-selection validation in Claude Desktop. `METHODOLOGY.md` (trust collateral) complete. See `baseline_mcp_server_plan.md` in the Baseline project for full task history. **Not yet published to PyPI or any MCP registry** — packaging is staged but the publish step is intentionally on hold.

baseline_mcp-0.1.0/README.md

@@ -0,0 +1,62 @@
+# baseline-mcp
+
+MCP server exposing Baseline as agent tools — statistically rigorous weather and climate context, not just current conditions. Thin translation layer only: no climate logic lives here, every tool call is an HTTP request to the Baseline API. See `baseline_mcp_server_plan.md` in the Baseline project for the full design, and [`METHODOLOGY.md`](./METHODOLOGY.md) for how the underlying data and rankings are computed.
+
+## Tools
+
+- `get_climate_context` — natural-language weather and climate questions, full context back (forecast + 35-year historical percentile ranking).
+- `get_context_for_coordinates` — same, for an exact lat/lon rather than a place name.
+- `get_water_year_status` — precipitation/temperature status since the start of the water year (Oct 1 US / Jan 1 elsewhere), ranked against 35 years.
+- `compare_to_normal` — how unusual current or forecast conditions are at one location.
+- `compare_locations` — rank precipitation or temperature across 2-10 locations (or a curated category like `colorado_ski_resorts`) in a single call.
+
+## Installation
+
+Requires a Baseline API key. **Self-serve signup isn't available yet** — during this early period, contact Chad McNutt (chadmcnutt@gmail.com) for a key.
+
+```bash
+pip install baseline-mcp
+# or: uvx baseline-mcp
+```
+
+Then add it to your MCP client's config, with your API key:
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "baseline": {
+      "command": "uvx",
+      "args": ["baseline-mcp"],
+      "env": {
+        "BASELINE_API_URL": "https://api.baseline.example",
+        "BASELINE_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+**Claude Code**: `claude mcp add baseline --env BASELINE_API_URL=https://api.baseline.example --env BASELINE_API_KEY=your-key-here -- uvx baseline-mcp`
+
+**Cursor** (`.cursor/mcp.json` or global MCP settings): same shape as the Claude Desktop config above, under whatever key Cursor's MCP settings use for server name.
+
+## Local development
+
+The venv lives outside this directory (`~/.venvs/baseline-mcp`) rather than in `.venv/` here, because this project sits under iCloud-synced `~/Documents` — iCloud evicts/re-materializes files inside large venvs unpredictably, which causes intermittent `ModuleNotFoundError`s. Keep it that way.
+
+```bash
+python3 -m venv ~/.venvs/baseline-mcp
+~/.venvs/baseline-mcp/bin/pip install -e .
+cp .env.example .env   # fill in BASELINE_API_URL and a free_api-tier BASELINE_API_KEY
+```
+
+Run against a local Baseline instance (`python3 app.py` in `../baseline`), then:
+
+```bash
+~/.venvs/baseline-mcp/bin/mcp dev src/baseline_mcp/server.py
+```
+
+## Status
+
+All 5 tools built and tested against a live local Baseline instance, including tool-selection validation in Claude Desktop. `METHODOLOGY.md` (trust collateral) complete. See `baseline_mcp_server_plan.md` in the Baseline project for full task history. **Not yet published to PyPI or any MCP registry** — packaging is staged but the publish step is intentionally on hold.

baseline_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "baseline-mcp"
+version = "0.1.0"
+description = "MCP server exposing Baseline's statistically rigorous weather and climate context as agent tools."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Chad McNutt", email = "chadmcnutt@gmail.com" },
+]
+requires-python = ">=3.10"
+keywords = ["mcp", "weather", "climate", "era5", "agent-tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = [
+    "mcp[cli]>=1.28.1",
+    "httpx>=0.27",
+    "python-dotenv>=1.0",
+]
+
+[project.scripts]
+baseline-mcp = "baseline_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/baseline_mcp"]

baseline_mcp-0.1.0/src/baseline_mcp/server.py

@@ -0,0 +1,402 @@
+"""Baseline MCP server.
+
+Thin translation layer between the MCP protocol and the Baseline HTTP API.
+Contains zero Baseline logic — every tool is a POST to the Baseline API and
+a reformat of the JSON response into agent-readable text. If a feature needs
+new climate logic, it belongs in Baseline, not here.
+
+See baseline_mcp_server_plan.md (companion doc, in the Baseline project dir)
+for the full design rationale.
+"""
+
+import json
+import os
+import re
+
+import httpx
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+
+load_dotenv()
+
+BASELINE_API_URL = os.environ.get("BASELINE_API_URL", "http://127.0.0.1:5050").rstrip("/")
+BASELINE_API_KEY = os.environ.get("BASELINE_API_KEY", "")
+
+# Documented cold start is 8-12s on the production Droplet (local tile cache).
+# 60s gives real margin above that without leaving a genuinely-hung API pending forever.
+REQUEST_TIMEOUT_SECONDS = 60.0
+
+# /api/compare processes up to 10 locations at 2 concurrent workers server-side, so its
+# cold-start cost is not the single-location figure above — measured 2:57 for a cold
+# 10-location call in dev. This is a real latency problem (see baseline_mcp_server_plan.md
+# follow-up), not something to treat as settled; the longer timeout here just keeps the
+# tool from failing outright on large categories until that gets fixed.
+COMPARE_TIMEOUT_SECONDS = 240.0
+
+_PROVENANCE_LINE = (
+    "Source: Baseline | ERA5-Land reanalysis 1991-2025 (35-yr daily climatology, "
+    "WMO 1991-2020 normals), 0.1-degree resolution, land-only | Forecast: Open-Meteo"
+)
+
+mcp = FastMCP("Baseline")
+
+
+def _headers() -> dict:
+    headers = {"Content-Type": "application/json"}
+    if BASELINE_API_KEY:
+        headers["X-Api-Key"] = BASELINE_API_KEY
+    return headers
+
+
+def _post(path: str, payload: dict, timeout: float = REQUEST_TIMEOUT_SECONDS) -> dict:
+    """POST to a Baseline API path. Raises RuntimeError with an actionable
+    message on any failure — callers should catch this and hand it back to the
+    agent as the tool result, not let it surface as a stack trace."""
+    url = f"{BASELINE_API_URL}{path}"
+    try:
+        response = httpx.post(url, json=payload, headers=_headers(), timeout=timeout)
+    except httpx.ConnectError as error:
+        raise RuntimeError(
+            f"Could not reach the Baseline API at {url}. Is the server running? ({error})"
+        )
+    except httpx.TimeoutException:
+        raise RuntimeError(f"Baseline API at {url} timed out after {timeout:.0f}s.")
+
+    if response.status_code == 401:
+        raise RuntimeError(
+            "Baseline API rejected the request (401 Unauthorized). "
+            "Check that BASELINE_API_KEY is set and valid."
+        )
+    if response.status_code == 429:
+        body = response.json() if response.headers.get("content-type", "").startswith("application/json") else {}
+        raise RuntimeError(
+            f"Baseline API rate limit exceeded (daily_limit={body.get('daily_limit')}, "
+            f"resets at {body.get('reset_at')})."
+        )
+    if response.status_code >= 400:
+        try:
+            detail = response.json().get("error", response.text)
+        except Exception:
+            detail = response.text
+        raise RuntimeError(f"Baseline API returned {response.status_code}: {detail}")
+
+    return response.json()
+
+
+def _post_context(payload: dict) -> dict:
+    return _post("/api/context", payload)
+
+
+def _format_clarification(data: dict) -> str:
+    question = data.get("question", "The location is ambiguous.")
+    candidates = data.get("candidates") or []
+    lines = [question, ""]
+    for c in candidates:
+        label = c.get("label") or c.get("name") or "Unknown"
+        lat, lon = c.get("lat"), c.get("lon")
+        if lat is not None and lon is not None:
+            lines.append(f"- {label} ({lat}, {lon})")
+        else:
+            lines.append(f"- {label}")
+    lines.append("")
+    lines.append(
+        "Call this tool again with a more specific location string, or with "
+        "exact coordinates, to resolve the ambiguity."
+    )
+    return "\n".join(lines)
+
+
+def _format_context_result(data: dict) -> str:
+    lines = []
+
+    location_name = data.get("location_name")
+    if location_name:
+        lines.append(f"Location: {location_name}")
+
+    short_answer = data.get("short_answer") or {}
+    if short_answer.get("show"):
+        title = short_answer.get("title") or "Short Answer"
+        answer = short_answer.get("answer") or ""
+        lines.append(f"\n{title}: {answer}")
+
+    summary = data.get("summary")
+    if summary:
+        lines.append(f"\nOverview: {summary}")
+
+    water_year_context = data.get("water_year_context")
+    if water_year_context:
+        lines.append(f"\n{water_year_context}")
+
+    metrics = data.get("metrics") or []
+    if metrics:
+        lines.append("\nKey signals:")
+        for metric in metrics[:6]:
+            label = metric.get("label") if isinstance(metric, dict) else None
+            value = metric.get("value") if isinstance(metric, dict) else None
+            if label is not None:
+                lines.append(f"- {label}: {value}")
+
+    lines.append(f"\n{_PROVENANCE_LINE}")
+
+    lines.append("\n```json")
+    lines.append(json.dumps(data, indent=2, default=str))
+    lines.append("```")
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def get_climate_context(query: str) -> str:
+    """Get statistically rigorous weather and climate context for any location
+    on Earth (land only). Answers natural-language questions with 10-day
+    forecast data and historical percentile rankings against a 35-year ERA5
+    daily climatology (1991-2025, WMO 1991-2020 normals). Use this when you
+    need to know not just what conditions are or will be, but how unusual
+    they are relative to history.
+
+    query MUST be phrased as a question in one of these forms (the location
+    goes where LOCATION is shown; the underlying parser matches these
+    patterns specifically and will fail on other phrasings, e.g. "weather
+    context for LOCATION" does not work):
+    - "Will LOCATION be warmer/wetter than normal this week?"
+    - "Has LOCATION been dry this water year?" / "this year?"
+    - "How cold/warm/wet was last winter/spring/summer/fall in LOCATION?"
+    - "What is the wettest/driest month in LOCATION?"
+    """
+    try:
+        data = _post_context({"query": query})
+    except RuntimeError as error:
+        return str(error)
+
+    if data.get("status") == "clarification_needed":
+        return _format_clarification(data)
+
+    return _format_context_result(data)
+
+
+@mcp.tool()
+def get_context_for_coordinates(latitude: float, longitude: float, label: str = "") -> str:
+    """Get 10-day forecast and 35-year historical climate context for exact
+    coordinates. Use when you have a specific latitude/longitude (a
+    property, field, trailhead, or site) rather than a place name — this
+    skips geocoding entirely. Land locations only.
+    """
+    location_explicit = {"lat": latitude, "lon": longitude}
+    if label:
+        location_explicit["label"] = label
+
+    try:
+        data = _post_context({"location_explicit": location_explicit})
+    except RuntimeError as error:
+        return str(error)
+
+    if data.get("status") == "clarification_needed":
+        return _format_clarification(data)
+
+    return _format_context_result(data)
+
+
+_COORD_RE = re.compile(r"^\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*$")
+
+
+def _parse_coords(text: str):
+    match = _COORD_RE.match(text)
+    if not match:
+        return None
+    lat, lon = float(match.group(1)), float(match.group(2))
+    if -90 <= lat <= 90 and -180 <= lon <= 180:
+        return lat, lon
+    return None
+
+
+@mcp.tool()
+def get_water_year_status(location: str) -> str:
+    """Get water year precipitation and temperature status for a location:
+    totals since the start of the water/calendar year (Oct 1 for North
+    America, Jan 1 elsewhere), percentile rank against the same period
+    across 35 historical years, and whether conditions are notably wet,
+    dry, warm, or cold. Built for drought monitoring, water resource,
+    agricultural, and fire-planning contexts. location can be a place name
+    ("Casper WY") or "lat,lon" coordinates.
+    """
+    coords = _parse_coords(location)
+    if coords:
+        lat, lon = coords
+        payload = {
+            "location_explicit": {"lat": lat, "lon": lon, "label": location},
+            "query": "Has this location been dry this water year?",
+        }
+    else:
+        payload = {"query": f"Has {location} been dry this water year?"}
+
+    try:
+        data = _post_context(payload)
+    except RuntimeError as error:
+        return str(error)
+
+    if data.get("status") == "clarification_needed":
+        return _format_clarification(data)
+
+    return _format_context_result(data)
+
+
+@mcp.tool()
+def compare_to_normal(location: str, variable: str, time_window: str = "") -> str:
+    """Compare current or forecast conditions at a location to 35-year
+    historical normals. Returns percentile rankings, not vague comparisons.
+    Use for questions like "is this week unusually warm" or "will it be
+    wetter than normal this month". variable must be "temperature" or
+    "precipitation". time_window is optional free text (e.g. "this week",
+    "this month") — defaults to "this week".
+    """
+    variable = variable.strip().lower()
+    if variable not in ("temperature", "precipitation"):
+        return f'variable must be "temperature" or "precipitation" (got {variable!r}).'
+
+    adjective = "warmer" if variable == "temperature" else "wetter"
+    window = time_window.strip() or "this week"
+    query = f"Will {location} be {adjective} than normal {window}?"
+
+    try:
+        data = _post_context({"query": query})
+    except RuntimeError as error:
+        return str(error)
+
+    if data.get("status") == "clarification_needed":
+        return _format_clarification(data)
+
+    return _format_context_result(data)
+
+
+def _resolve_location(text: str) -> dict:
+    """Resolve a place name or 'lat,lon' string to {lat, lon, label} via
+    Baseline's /api/resolve. Raises RuntimeError on failure or ambiguity."""
+    coords = _parse_coords(text)
+    if coords:
+        lat, lon = coords
+        return {"lat": lat, "lon": lon, "label": text}
+
+    data = _post("/api/resolve", {"location": text})
+
+    if data.get("status") == "ambiguous":
+        candidates = ", ".join(
+            c.get("label") or c.get("name", "?") for c in data.get("candidates", [])
+        )
+        raise RuntimeError(
+            f"{text!r} is ambiguous. Candidates: {candidates}. "
+            "Use a more specific name or exact coordinates."
+        )
+
+    return {"lat": data["lat"], "lon": data["lon"], "label": data.get("name", text)}
+
+
+def _format_compare_result(data: dict) -> str:
+    comparison = data.get("comparison", {})
+    lines = [
+        f"Compared {comparison.get('n_locations')} locations — "
+        f"{comparison.get('variable_label')}, {comparison.get('period_label')} "
+        f"(vs. {comparison.get('baseline_years')} baseline)",
+        "",
+    ]
+
+    for entry in comparison.get("ranked", []):
+        label = entry.get("label", "Unknown")
+        if entry.get("status") not in ("ok", "partial"):
+            lines.append(f"- {label}: no data ({entry.get('reason', 'unknown error')})")
+            continue
+
+        rank = entry.get("rank")
+        value = entry.get("value_display")
+        rank_label = entry.get("rank_label", "")
+        if entry.get("percent_of_normal") is not None:
+            lines.append(
+                f"{rank}. {label}: {value} ({entry['percent_of_normal']}% of normal) — {rank_label}"
+            )
+        else:
+            lines.append(
+                f"{rank}. {label}: {value} ({entry.get('departure_display')} vs. normal) — {rank_label}"
+            )
+
+    lines.append(f"\n{_PROVENANCE_LINE}")
+
+    lines.append("\n```json")
+    lines.append(json.dumps(data, indent=2, default=str))
+    lines.append("```")
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def compare_locations(
+    locations: list[str] | None = None,
+    category: str = "",
+    variable: str = "precipitation",
+    period: str = "water_year",
+    season: str = "",
+    year: int = 0,
+    month: int = 0,
+) -> str:
+    """Compare precipitation or temperature across 2-10 locations in a single
+    ranked comparison, computed directly by Baseline. Use this instead of
+    calling get_climate_context or get_water_year_status once per location
+    and comparing the answers yourself — the ranking and percent-of-normal
+    figures in the result come from Baseline, not from your own arithmetic
+    over several separate answers.
+
+    Provide EITHER `locations` (a list of 2-10 place names and/or "lat,lon"
+    strings) OR `category` (a curated group name) — not both.
+
+    Valid category values: colorado_ski_resorts, wyoming_ski_resorts,
+    utah_ski_resorts, wyoming_watersheds, colorado_river_basin_states,
+    great_plains_ag, major_us_cities, major_european_cities,
+    us_national_parks.
+
+    variable: "precipitation" (default) or "temperature".
+    period: "water_year" (default, Oct 1 / Jan 1 to date), "season" (also
+    set season="winter"/"spring"/"summer"/"fall" and optionally year), or
+    "month" (also set month=1-12 and optionally year). Custom date ranges
+    are not supported by this tool — use "water_year", "season", or "month".
+    """
+    if locations and category:
+        return "Provide either locations or category, not both."
+    if not locations and not category:
+        return "Provide either locations (2-10 places) or category (a curated group name)."
+
+    payload: dict = {"variable": variable, "period": period}
+    if season:
+        payload["season"] = season
+    if year:
+        payload["year"] = year
+    if month:
+        payload["month"] = month
+
+    if category:
+        payload["category"] = category
+    else:
+        if len(locations) < 2 or len(locations) > 10:
+            return f"locations must have between 2 and 10 entries (got {len(locations)})."
+        resolved = []
+        for text in locations:
+            try:
+                resolved.append(_resolve_location(text))
+            except RuntimeError as error:
+                return str(error)
+        payload["locations"] = resolved
+
+    try:
+        data = _post("/api/compare", payload, timeout=COMPARE_TIMEOUT_SECONDS)
+    except RuntimeError as error:
+        return str(error)
+
+    if data.get("status") == "error":
+        return data.get("error", "Unknown error from Baseline API.")
+
+    return _format_compare_result(data)
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()