# weatherport

weatherport brings OpenWeather to the terminal and to MCP clients.
It answers the questions people actually ask of that service: what
is it like in a city right now, what is coming over the next five
days in three-hour steps, what does the fuller One Call 3.0 view
say for a precise point on the map, how clean is the air there,
and where exactly is a place name? One binary serves both a
command-line interface and a stdio MCP server.

An OpenWeather API key is required for every call. Put it in the
`OPENWEATHER_API_KEY` environment variable; weatherport sends it
to `https://api.openweathermap.org` as the `appid` query
parameter and never prints it. When the variable is missing or
blank, calls fail with an error that names it, before any request
is made. Note that One Call 3.0 needs a separate upstream
subscription in reality, even though it uses the same key.

Units are optional everywhere they apply: `standard`, `metric`,
or `imperial`. Anything else is rejected before a request.

## Install

```bash
npx @reneturcios/weatherport current Paris --units metric
```

Or run the container image:

```bash
docker run -i -e OPENWEATHER_API_KEY ghcr.io/cloudcorprecords/weatherport
```

The container defaults to the MCP server. Pass CLI arguments to
use it as a CLI instead.

## CLI

```bash
export OPENWEATHER_API_KEY=<your key>

weatherport current Paris --units metric
weatherport forecast Berlin --units imperial --count 5
weatherport onecall 51.5 -0.12 --units metric
weatherport pollution 51.5 -0.12
weatherport geocode Paris --limit 3

weatherport --version
```

Each command prints the upstream JSON payload. Exit codes: `0`
on success, `1` when a call fails (including a missing
`OPENWEATHER_API_KEY` or an API error), `2` for usage errors.

## MCP server

```bash
npx -y @reneturcios/weatherport mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "weatherport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/weatherport", "mcp"],
      "env": { "OPENWEATHER_API_KEY": "..." }
    }
  }
}
```

### Tools

| Tool | Input | What it returns |
| --- | --- | --- |
| `get_current_weather` | `location` (required), `units` (optional) | Current weather for a city. |
| `get_forecast` | `location` (required), `units`, `count` (optional) | 5-day forecast in 3-hour steps. |
| `get_onecall_weather` | `lat`, `lon` (required), `units` (optional) | One Call 3.0 current, hourly, and daily summaries. |
| `get_air_pollution` | `lat`, `lon` (required) | Current AQI and pollutant components. |
| `geocode_location` | `query` (required), `limit` (optional) | Coordinate matches for a place name. |

Latitude must be in [-90, 90] and longitude in [-180, 180];
out-of-range values are rejected before any request. HTTP
failures surface the status plus OpenWeather's `message` field
when the upstream JSON provides one.

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx
```

## License

MIT — see `LICENSE`.