weather-signal

# Weather Signal [](LICENSE) [](https://www.rust-lang.org/) [](https://joe-broadhead.github.io/weather-signal/) [](https://github.com/joe-broadhead/weather-signal/actions/workflows/ci.yml) <pre> _ __ __ __ _____ _ __ | | / /__ ____ _/ /_/ /_ ___ _____ / ___/(_)___ _____ ____ _/ / | | /| / / _ \/ __ `/ __/ __ \/ _ \/ ___/ \__ \/ / __ `/ __ \/ __ `/ / | |/ |/ / __/ /_/ / /_/ / / / __/ / ___/ / / /_/ / / / / /_/ / / |__/|__/\___/\__,_/\__/_/ /_/\___/_/ /____/_/\__, /_/ /_/\__,_/_/ /____/ Weather context for forecasting agents. </pre> Weather Signal is an **agent-first weather data CLI and MCP server** for turning Open-Meteo forecasts into stable, scriptable demand signals. It is built for forecasting flows that need more than a pretty terminal forecast: consistent JSON, saved business locations, local caching, MCP tools, and demand-friendly features such as rain likelihood, warm days, windy days, sunshine, and UV. ## What It Does - **Fetches Open-Meteo forecasts** with no key required for local development. - **Resolves city names** through Open-Meteo geocoding, with optional country hints. - **Stores saved places** so business locations can be referenced by alias. - **Outputs agent-ready JSON by default**, plus table and CSV modes. - **Caches responses locally** to keep repeated agent runs fast and predictable. - **Adds agent workflow commands** for summaries, thresholds, batch locations, historical context, and shell completions. - **Supports commercial endpoints** through configurable base URLs and API keys. ## 30-Second Example ```bash weather-signal signal london --country GB --days 3 ``` Example output shape (abridged): ```json { "source": "open-meteo", "location": { "name": "London", "country_code": "GB", "latitude": 51.50853, "longitude": -0.12574 }, "cache": "miss", "profile": "demand", "days": [ { "date": "2026-04-27", "temp_max_c": 20.4, "precip_probability_max_pct": 46, "precipitation_mm": 0.1, "flags": { "rain_likely": false, "warm_day": true, "sunny_day": true } } ] } ``` ## Installation ```bash curl -fsSL https://raw.githubusercontent.com/joe-broadhead/weather-signal/HEAD/scripts/install.sh | bash ``` Install the binary and Weather Signal agent skills: ```bash curl -fsSL https://raw.githubusercontent.com/joe-broadhead/weather-signal/HEAD/scripts/install.sh | bash -s -- --install-skills ``` ### Prebuilt Binaries Release assets are published from the GitHub Release workflow with checksums, SBOMs, and provenance attestations. ```bash # macOS Apple Silicon curl -L -o weather-signal.tar.gz \ https://github.com/joe-broadhead/weather-signal/releases/download/v0.0.1/weather-signal-macos-arm64.tar.gz tar -xzf weather-signal.tar.gz ./weather-signal-macos-arm64/weather-signal --version ``` Choose the asset for your platform from [Releases](https://github.com/joe-broadhead/weather-signal/releases). ### From Source ```bash git clone https://github.com/joe-broadhead/weather-signal.git cd weather-signal cargo build --locked --release # Try the main agent signal command cargo run -- signal london --country GB --days 7 # Human-readable table cargo run -- daily london --country GB --days 3 --table # CSV for spreadsheets or feature stores cargo run -- hourly "51.5072,-0.1276" --hours 24 --output csv ``` ## Quick Start ```bash weather-signal signal london --country GB --days 7 weather-signal daily london --country GB --days 3 --table weather-signal hourly "51.5072,-0.1276" --hours 24 --output csv ``` ## CLI Usage ```bash weather-signal geocode <query> [--country GB] [--count 5] weather-signal places add <alias> <query> [--country GB] weather-signal places list weather-signal places remove <alias> weather-signal current <location> weather-signal daily <location> [--days 7] weather-signal hourly <location> [--hours 48] weather-signal signal <location> [--days 7] [--profile demand] weather-signal summary <location> [--days 7] weather-signal threshold <location> --rain-prob-gte 60 weather-signal batch signal --places all weather-signal historical <location> --start YYYY-MM-DD --end YYYY-MM-DD weather-signal server start --transport stdio weather-signal server start --transport streamable-http --http-port 8768 weather-signal completions zsh weather-signal cache status weather-signal cache prune --max-age 7d weather-signal cache clear ``` Global options: ```bash --output json|table|csv --table --refresh --cache-ttl 30m --timeout 30s --api-key <key> --forecast-base-url <url> --geocode-base-url <url> --historical-base-url <url> --config <path> ``` ## Saved Places Saved places make repeatable business workflows less brittle: ```bash weather-signal places add london "London" --country GB weather-signal signal london --days 7 ``` Config lives at: ```text ~/.config/weather-signal/config.toml ``` Cache lives at: ```text ~/.cache/weather-signal ``` Use `weather-signal cache prune --max-age 7d` for routine cache maintenance, or `weather-signal cache clear` when you need to remove every cached response. ## Commercial Open-Meteo Usage The public Open-Meteo endpoint is the default. For commercial or self-hosted usage, configure an API key or endpoint override: ```bash export OPEN_METEO_API_KEY="..." export OPEN_METEO_FORECAST_BASE_URL="https://customer-api.open-meteo.com/v1/forecast" export OPEN_METEO_GEOCODING_BASE_URL="https://geocoding-api.open-meteo.com/v1/search" export OPEN_METEO_HISTORICAL_BASE_URL="https://archive-api.open-meteo.com/v1/archive" ``` ## MCP Server Weather Signal can run as an MCP server over stdio or streamable HTTP: ```bash weather-signal server start --transport stdio weather-signal server start --transport streamable-http --http-host 127.0.0.1 --http-port 8768 --http-path /mcp ``` The MCP surface exposes tools such as `weather_summary`, `demand_signal`, `threshold_days`, `historical_weather`, `daily_forecast`, and `geocode`. Streamable HTTP is stateless by default and should stay on loopback unless an authenticating proxy controls access. Use `--http-stateful-mode` only for trusted legacy MCP protocol clients ("< 2026-07-28")because stateful sessions are held in process memory; newer protocol versions are always served statelessly. ## Documentation - [Getting Started](docs/getting-started/quickstart.md) - [CLI Reference](docs/reference/cli.md) - [MCP Reference](docs/reference/mcp.md) - [Signal Reference](docs/reference/signals.md) - [Configuration](docs/reference/configuration.md) - [Agent Skills](docs/development/agent-skills.md) - [Agent Development Guide](AGENTS.md) - [Contributing](CONTRIBUTING.md) ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, quality gates, documentation checks, and PR expectations. ## License MIT. See [LICENSE](LICENSE).