# Weather MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides weather forecasts and alerts for US locations using the [National Weather Service (NWS) API](https://www.weather.gov/documentation/services-web-api).

## Features

- **Weather Alerts** — Retrieve active NWS weather alerts for any US state
- **Weather Forecast** — Get a detailed forecast for any US location by latitude/longitude
- **Weather Briefing Prompt** — A pre-built prompt that combines alerts and forecast into a comprehensive briefing

## Prerequisites

- [Node.js](https://nodejs.org/) v18 or later
- An MCP-compatible client (e.g. [Claude Desktop](https://www.anthropic.com/claude))

> **Note:** The NWS API only supports locations within the United States.

## Installation

```bash
npm install
npm run build
```

## Usage

Run the server directly via stdio (the standard MCP transport):

```bash
node build/index.js
```

Or use the `weather` bin alias after a global/local install:

```bash
npx weather
```

### Integrating with Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-poc/build/index.js"]
    }
  }
}
```

## Tools

### `get_alerts`

Retrieves active weather alerts for a US state.

| Parameter | Type   | Description                             |
| --------- | ------ | --------------------------------------- |
| `state`   | string | Two-letter state code (e.g. `CA`, `NY`) |

### `get_forecast`

Retrieves the weather forecast for a specific US location.

| Parameter   | Type   | Description                          |
| ----------- | ------ | ------------------------------------ |
| `latitude`  | number | Latitude of the location (-90–90)    |
| `longitude` | number | Longitude of the location (-180–180) |

## Prompts

### `weather-briefing`

Generates a comprehensive weather briefing for a US state.

| Argument    | Type   | Description                                               |
| ----------- | ------ | --------------------------------------------------------- |
| `state`     | string | Two-letter US state code (e.g. `CA`, `NY`)                |
| `latitude`  | string | Latitude of a location within the state for the forecast  |
| `longitude` | string | Longitude of a location within the state for the forecast |

## Development

```bash
# Build TypeScript
npm run build

# Source files
src/index.ts    # MCP server, tools, and prompts
src/helpers.ts  # NWS API client and shared types
```

## License

ISC