WeatherWake MCP

Park a weather condition instead of polling for it. An agent calls register_wake with a site and a rule such as "gust < 30 km/h and no precipitation for 3 h, within the next 48 h". The call returns at once and the session can end. A small local worker checks the forecast on a budgeted cadence. When the forecast shows the window (or the deadline passes), it POSTs a signed webhook so a durable workflow resumes.

Forecast-based trigger, not a safety authority. A wake.met webhook means a forecast showed the window you asked for. Forecasts can be wrong. The receiving workflow and the responsible person decide whether work goes ahead.

The problem

Agents that wait on weather tend to poll it inside a long chat ("check again in an hour") and keep an expensive session open while the sky decides. The waiting belongs outside the model. Register the condition once, let a cheap process watch the forecast within an API budget, and wake the workflow with a webhook that the receiver can verify.

Related MCP server: Rain Check

How it works

agent --register_wake--> MCP server --writes--> .weatherwake/wakes/<id>.json   (returns in ~2 ms)
                                                     |
                          weatherwake worker (loop or cron) -- forecast: NWS / Google / synthetic
                                                     |   (daily call budget, per-site cache, 30-180 min cadence)
                          condition met or expired --+--> outbox (durable, retries)
                                                     |
                          POST WEATHERWAKE_WEBHOOK_URL   webhook-id / webhook-timestamp / webhook-signature
                                                     |
                          receiver: verify HMAC + timestamp + replay guard --> enqueue resume job (idempotent per wake)
                                                     |
                          resume worker / your workflow engine continues the parked run

A wake is met when the forecast shows at least for_hours consecutive hours where every rule holds. The window must end before expires_at and start within lead_hours of now, and it must be seen on confirmations consecutive checks (spaced at least 60 min apart). A wake expires once no such window can still fit before the deadline. That check makes no upstream call.

Cadence: with no window in the forecast, the worker checks again after the max interval (180 min). With a window further out, it checks again lead_hours before the window starts, clamped to 30-180 min, because forecasts move. While it waits for confirmations, the spacing is 60 min. Wakes on the same site share one cached forecast for 20 min. Every upstream request first takes a unit from a per-UTC-day budget (default 200). Errors that will not fix themselves (outside NWS coverage, a missing key, the API not enabled) back off to the max interval.

Quickstart

bun install --frozen-lockfile
bun run demo                       # keyless: simulated clock + synthetic forecast; real MCP, worker, HTTP, receiver, queue

Live (keyless, US only, via the National Weather Service):

cp .env.example .env
bun run src/cli.ts secret          # paste into .env as WEATHERWAKE_WEBHOOK_SECRET (do not share it)
bun run receiver                   # terminal 1: verifying receiver on 127.0.0.1:8787
bun run worker                     # terminal 2: checks due wakes every 60 s, delivers webhooks
bun run src/cli.ts preview  --lat 35.7796 --lng -78.6382 --rule "wind_gust_kmh < 30" --rule "precip_mm <= 0" --for-hours 3 --source nws
bun run src/cli.ts register --lat 35.7796 --lng -78.6382 --rule "wind_gust_kmh < 30" --rule "precip_mm <= 0" \
  --for-hours 3 --within-hours 48 --resume '{"run":"crane-lift-42","step":"schedule-crew"}' --key crane-lift-42

MCP server

{
  "mcpServers": {
    "weatherwake": {
      "command": "bun",
      "args": ["/abs/path/weatherwake-mcp/src/cli.ts", "serve"],
      "env": { "WEATHERWAKE_DATA_DIR": "/abs/path/state", "WEATHERWAKE_WEBHOOK_URL": "https://your-app.example/hooks/weatherwake" }
    }
  }
}

Put the signing secret (and an optional GOOGLE_MAPS_API_KEY) in the environment of both the server and the worker. Do not put them in the MCP config you share. The worker must use the same WEATHERWAKE_DATA_DIR.

The tools take no webhook URL: the target comes from WEATHERWAKE_WEBHOOK_URL, so a prompt cannot redirect wake-ups to another host.

Rule grammar: METRIC OP VALUE [missing ok|fail]. Every rule must hold in an hour. A missing value fails the hour unless the rule says missing ok. The numeric metrics are wind_gust_kmh, wind_speed_kmh, precip_mm, precip_probability_pct, thunderstorm_probability_pct, temperature_c, feels_like_c, cloud_cover_pct, relative_humidity_pct and visibility_km; they take < <= > >=. The metrics condition and precip_type take in / not_in with UPPER_CASE lists and come from Google only. "No precipitation for 3 h" is precip_mm <= 0 with for_hours: 3.

The webhook

Standard Webhooks format. Full field list and receiver contract: docs/WEBHOOK.md.

webhook-id:        msg_...            same id on every retry of one event
webhook-timestamp: 1793768400         unix seconds of this attempt
webhook-signature: v1,<base64 HMAC-SHA256(secret, "{id}.{timestamp}.{raw body}")>

• The body is canonical JSON (sorted keys, no whitespace). Its type is wake.met or wake.expired. It carries wake_id, webhook_id (equal to the header), window (start, end, the end of the clear run, and hour values), condition, resume, source, attribution and stats.

• The secret is whsec_ + base64 of 24-64 bytes. Several secrets can be configured for rotation: the first signs, all verify.

• The receiver (src/receiver.ts, examples/receiver.ts) verifies the raw body in constant time. It rejects timestamps more than 300 s off and remembers accepted ids on disk, so a replay gets 200 duplicate and does nothing. It then enqueues the resume job with idempotency key wake:<wake_id>.

• Interop: tests/unit/signing.test.ts checks that the reference standardwebhooks npm package (1.1.1) verifies our signatures and that we verify its signatures.

• Delivery: 2xx means done. 408, 429, 5xx and network errors are retried with the same id (backoff 30 s doubling, 8 attempts). Any other 4xx is permanent. The worker never sends an unsigned webhook.

Durable workflow engines

docs/WORKFLOW_MAPPING.md maps the park / resume steps onto Vercel Workflow (createHook + resumeHook from workflow/api), Trigger.dev (wait.createToken / wait.forToken / wait.completeToken) and Hatchet (ctx.waitForEvent + hatchet.events.push). The mapping was written from each package's published type declarations and docs (workflow 5.2.3, @trigger.dev/sdk 4.7.6, @hatchet-dev/typescript-sdk 1.38.0 on npm, 2026-10-21). None of them is a dependency, and the snippets were not executed here.

Measured

From bun run report (scripts/report.ts → reports/weatherwake-mcp.md, reports/weatherwake-mcp.json) on Bun 1.4.3, darwin/x64. The forecasts are synthetic (fixtures/sequences) and run under a simulated clock. The MCP server, worker, cadence, budget, cache, HTTP delivery, signature checks, replay guard and resume queue are the real code. "15-min polling" is arithmetic for comparison (settle time / 15 min), not a measurement.

What the runs show:

• storm-clears: early forecasts put the clearing 6 h too late. The worker spaces checks 3 h apart and wakes at hour 18 for a window starting at hour 19, after 7 checks. The receiver answered 503 twice first, and the third attempt was accepted with the same webhook-id.

• flapping: one forecast issuance shows a calm spell that never happens. With confirmations: 1 the wake fires on it, and the window does not hold in the synthetic truth. With confirmations: 2 it fires 21 h later, on a window that holds.

• shared-site: three wakes on one site made 21 checks with 9 upstream calls.

• budget-cap: with WEATHERWAKE_MAX_CALLS_PER_DAY=6, 3 checks were deferred to the next UTC day instead of overspending.

• After delivery in the storm-clears run, the receiver answered the following probes. Replaying the same request got 200 duplicate. A tampered body got 401 bad_signature, and so did a wrong secret. The same request 10 min later got 401 timestamp_too_old. A request with no signature got 401 missing_headers.

• register_wake through the in-memory MCP client: p50 1.94 ms over 20 calls, no upstream calls (this machine; see the report).

Timeline of the storm-clears run: reports/demo-timeline.md.

Local gate (bun run check, this machine): install, skills layout, strict YAML, Biome, tsc --noEmit, 71 unit + keyless e2e tests, 3 live tests, report, gitleaks. All green. The live tests: NWS preview and a worker tick against api.weather.gov passed. The Google Weather test skipped with 403 SERVICE_DISABLED, because the Weather API is not enabled in the key's project.

Configuration

All optional; see .env.example. Bun loads .env automatically.

Tests

bun run test        # unit + keyless e2e: simulated scenarios, MCP tools, stdio server + worker processes, CLI
bun run test:live   # NWS (keyless) + Google Weather (skips without a key or on 403 SERVICE_DISABLED); WEATHERWAKE_LIVE=0 skips all
bun run check       # the full local gate (CI runs the same script, keyless)

Limits

• The forecast is the signal. A wake fires on a forecast window, not on observed weather. The synthetic flapping run shows a false wake with confirmations: 1.

• Sources. NWS covers the US only; elsewhere you need a Google Maps Platform key with the Weather API enabled. The Google path is unit-tested against synthetic responses with the documented shape, but it was not verified live here: the Weather API is not enabled in the project used for this build (403 SERVICE_DISABLED). The rules condition / precip_type and thunderstorm probability need Google; NWS gives 6 h precipitation blocks, which are spread evenly per hour.

• Sites are lat/lng only. There is no geocoding.

• The worker must be running (a loop or cron worker --once). The MCP server alone never checks anything; wake_status warns when no worker has ticked.

• Single host. The state, outbox, replay guard and queues are files that rely on atomic rename on one filesystem.

• Delivery retries stop after 8 attempts (about an hour). That is shorter than the Standard Webhooks example schedule. After that the wake shows delivery.status: failed.

• Not measured here: token or dollar savings from ending the chat session, and whether Vercel Workflow, Trigger.dev or Hatchet bill a parked run. The idea's premise of an "idle 200K session" is not quantified by this repo.

• Not included: Gemini (named in the idea as optional; not used), adapters that call the workflow engines (the mapping doc only).

Not affiliated

Not affiliated with, endorsed by, or sponsored by Google LLC, the US National Weather Service, Vercel Inc., Trigger.dev, Hatchet, or the Standard Webhooks project. Google Maps Platform is a trademark of Google LLC.

License

Apache-2.0. See LICENSE and NOTICE (code reused from the SkilledDragonCorp labs weatherops-mcp and pausabudget-gate).

Built by SkilledDragon LLC as an educational minilab. Questions: hello@skilleddragon.com.