# Rain Check

A remote MCP server that answers whether an Australian field-service job can be
worked at a place on a day, for a given trade, from live forecast, daylight and
public holiday data.

Live: https://rain-check-mu.vercel.app
MCP endpoint: https://rain-check-mu.vercel.app/mcp
OpenAPI: https://rain-check-mu.vercel.app/openapi.json
Health: https://rain-check-mu.vercel.app/health

## Connect it

```bash
claude mcp add --transport http rain-check https://rain-check-mu.vercel.app/mcp
```

Any MCP client that speaks Streamable HTTP can use the same URL. It is POST
only: the server is stateless, so GET and DELETE answer 405 by design.

For anything that does not speak MCP, the identical operations are at
`/v1/<operation>` and described by `/openapi.json`, which is generated from the
same constants the MCP tools use so the two cannot drift.

## Run it locally

```bash
npm install
npm run typecheck     # tsc, no emit
npm run smoke         # every operation against the real upstreams
npm run smoke:mcp     # every endpoint over a real node:http server
npm run smoke:live -- https://rain-check-mu.vercel.app        # the deployed server
npm run adversarial -- https://rain-check-mu.vercel.app       # tries to break it
npm run prove -- https://rain-check-mu.vercel.app             # independent evidence
```

There are no mocks anywhere. The point of these is to catch an upstream changing
shape, and a mock never will.

`npm run adversarial` is the one that finds things. It throws nonsense ranges,
hostile strings, wrong types, foreign coordinates and malformed protocol frames
at the deployed server; a refusal with a usable message passes, a 500 or a
confident answer to a question it should not answer fails. It found three real
bugs the happy-path suites had missed.

## Checking it without trusting this repository

`npm run prove` exists because my own tests passing proves very little to
someone who did not write them. It connects with the official MCP client SDK,
then takes every number the server reported and re-fetches the same day straight
from Open-Meteo, comparing field by field, and prints the upstream URL it used
so you can open it yourself.

Three more ways, needing nothing from here:

```bash
# Anthropic's own inspector, not my code
npx @modelcontextprotocol/inspector --cli https://rain-check-mu.vercel.app/mcp --transport http --method tools/list

# raw JSON-RPC, no client, no session, because it is stateless
curl -s -X POST https://rain-check-mu.vercel.app/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# let your own client run its health check against it
claude mcp add --transport http rain-check https://rain-check-mu.vercel.app/mcp
claude mcp list
```

And the version that needs only a browser: open both of these and compare the
dates. `rain_mm` in the first equals `precipitation_sum` in the second.

- https://rain-check-mu.vercel.app/v1/workability?location=Bendigo&trade=concreting&days=3
- https://api.open-meteo.com/v1/forecast?latitude=-36.75818&longitude=144.28024&daily=precipitation_sum&timezone=Australia/Melbourne

## Deploy

```bash
vercel deploy --prod
```

## How it is laid out

```
src/core.ts          the six operations, with no transport in them
src/mcpServer.ts     the MCP tool surface
src/lib/             http, dates, geocoding, forecast, holidays, thresholds, verdicts
api/mcp.ts           Streamable HTTP, stateless
api/v1/[op].ts       the same operations over REST
api/openapi.ts       the OpenAPI document, generated from the same constants
api/health.ts        calls every upstream and reports real latency
public/index.html    the landing page, including the build log
scripts/             the three verification runs
```

Both front doors import `src/core.ts`. That is the only way the custom GPT and
the MCP client can be trusted to give the same answer, and it means a threshold
fixed once is fixed everywhere.

## What it will not do

- Present a threshold as a safety clearance. They are planning defaults, shown
  in every answer and overridable per call.
- Guess past the sixteen-day forecast. Later dates come back in `out_of_range`
  with the reason and no data.
- Let third-party holiday data pass as authoritative. It is state level only,
  carries no regional or show days, and every response links the official state
  government page.
- Fill a gap with a guess. When an upstream is unreachable the tool says which
  one and what to do, and tells the model not to substitute an opinion.
- Pick between two Richmonds. Ambiguity comes back as candidates.

## Data sources

- Weather and geocoding: [Open-Meteo](https://open-meteo.com), CC BY 4.0.
- Public holidays: [Nager.Date](https://date.nager.at), third party, state level
  only.

The Bureau of Meteorology's API is not used: its own terms say "You must not
use, copy or share it".