# Weather MCP Server

An MCP (Model Context Protocol) server that provides weather tools for **US locations** (via NWS API) and **India / global locations** (via Open-Meteo API).

## MCP Tools

| Tool | Description |
|------|-------------|
| `get_alerts` | Weather alerts for a US state (e.g. `CA`, `NY`) |
| `get_forecast` | Forecast by latitude/longitude (NWS for US, Open-Meteo elsewhere) |
| `get_india_weather` | Current weather + 7-day forecast for an Indian city by name |

## Project Structure

```
src/
├── index.ts              # Entry point — starts the MCP server
├── server.ts             # Creates MCP server and registers all tools
│
├── config/
│   └── constants.ts      # API URLs, app name, timezone
│
├── types/
│   ├── nws.ts            # TypeScript types for US (NWS) API
│   └── open-meteo.ts     # TypeScript types for Open-Meteo API
│
├── utils/
│   ├── fetch.ts          # HTTP request helper
│   ├── location.ts       # US location detection
│   └── weather-codes.ts  # WMO weather code → readable text
│
├── formatters/
│   ├── alerts.ts         # Formats alert data into readable text
│   └── open-meteo.ts     # Formats forecast data into readable text
│
├── services/
│   ├── nws.service.ts        # US weather API calls
│   └── open-meteo.service.ts # India/global weather API + geocoding
│
└── tools/
    ├── index.ts                  # Registers all MCP tools
    ├── get-alerts.tool.ts        # US alerts tool
    ├── get-forecast.tool.ts      # Coordinates-based forecast tool
    └── get-india-weather.tool.ts # Indian city weather tool
```

## Folder Responsibilities

| Folder | Purpose |
|--------|---------|
| `config/` | App settings and constants |
| `types/` | TypeScript interfaces and types |
| `utils/` | Small reusable helper functions |
| `formatters/` | Convert API responses into human-readable text |
| `services/` | Talk to external weather APIs |
| `tools/` | MCP tool definitions (what the AI calls) |

## Request Flow

```
User / AI
   │
   ▼
index.ts          → starts server on stdio
   │
   ▼
server.ts         → creates McpServer, calls registerTools()
   │
   ▼
tools/            → handles MCP tool request (e.g. get_india_weather)
   │
   ▼
services/         → calls external API (NWS or Open-Meteo)
   │
   ▼
formatters/       → converts raw JSON into readable text
   │
   ▼
Response          → sent back to AI via MCP
```

```mermaid
flowchart TD
    A[User / AI] --> B[index.ts]
    B --> C[server.ts]
    C --> D[tools/]
    D --> E[services/]
    E --> F[External APIs]
    F --> G[formatters/]
    G --> H[MCP Response]
```

## Setup

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

## Run

```bash
npm start
```

## Cursor MCP Config

Add to `~/.cursor/mcp.json`:

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

After changing config or code, restart the MCP server in **Cursor Settings → MCP**.

## APIs Used

- **NWS** — [api.weather.gov](https://api.weather.gov) — US forecasts and alerts only
- **Open-Meteo** — [open-meteo.com](https://open-meteo.com) — Free global weather, no API key required