# Weather MCP Server

A Model Context Protocol (MCP) server for weather data with OpenAPI support. This server provides weather information from OpenWeatherMap API and can be used by LLM agents through MCP.

## Features

- **MCP stdio transport** for LLM agent integration
- **HTTP REST API** with OpenAPI 3.0 specification
- **4 weather tools**:
  1. Get current weather by city
  2. Get current weather by coordinates
  3. Get weather forecast (5-day, 3-hour intervals)
  4. Get temperature range summary
- **Mock data support** for testing without API key
- **TypeScript** implementation with full type safety

## Installation

```bash
cd weather-mcp-server
npm install
npm run build
```

## Usage

### 1. MCP Server (stdio transport)

Run the MCP server for LLM agents:

```bash
npm start
```

Or in development mode:
```bash
npm run dev
```

### 2. HTTP Server with OpenAPI

Run the HTTP server with REST API:

```bash
npm run dev:http
```

The server will start on `http://localhost:3000` with:
- `/health` - Health check endpoint
- `/openapi` - OpenAPI specification
- `/api/v1/weather/current/{city}` - Current weather by city
- `/api/v1/weather/current/coordinates` - Current weather by coordinates
- `/api/v1/weather/forecast/{city}` - Weather forecast

### 3. Configuration

Set your OpenWeatherMap API key (optional - mock data will be used if not provided):

```bash
export OPENWEATHER_API_KEY=your_api_key_here
```

Or create a `.env` file:
```
OPENWEATHER_API_KEY=your_api_key_here
```

## MCP Tools

The server provides the following MCP tools:

| Tool Name | Description | Parameters |
|-----------|-------------|------------|
| `weather_get_current_by_city` | Get current weather by city | `city: string` |
| `weather_get_current_by_coords` | Get current weather by coordinates | `latitude: number, longitude: number` |
| `weather_get_forecast` | Get weather forecast | `city: string, days?: number (1-10, default: 5)` |
| `weather_get_temperature_range` | Get temperature range summary | `city: string` |

## API Endpoints

### HTTP REST API

All endpoints return JSON with the following structure:
```json
{
  "success": true,
  "data": { ... }
}
```

#### 1. Current Weather by City
```
GET /api/v1/weather/current/{city}
```

Example:
```bash
curl http://localhost:3000/api/v1/weather/current/London
```

#### 2. Current Weather by Coordinates
```
GET /api/v1/weather/current/coordinates?lat={latitude}&lon={longitude}
```

Example:
```bash
curl "http://localhost:3000/api/v1/weather/current/coordinates?lat=51.5074&lon=-0.1276"
```

#### 3. Weather Forecast
```
GET /api/v1/weather/forecast/{city}?days={days}
```

Example:
```bash
curl "http://localhost:3000/api/v1/weather/forecast/New%20York?days=3"
```

## Testing

Run the test suite:
```bash
npm test
```

Run MCP inspector for debugging:
```bash
npm run inspect
```

## Project Structure

```
weather-mcp-server/
├── src/
│   ├── index.ts              # MCP stdio server
│   ├── http-server.ts        # HTTP server with OpenAPI
│   ├── types/
│   │   └── weather.ts        # TypeScript types and Zod schemas
│   ├── utils/
│   │   └── weather-client.ts # OpenWeatherMap API client
│   └── tools/
│       └── weather-tools.ts  # MCP tool definitions
├── dist/                     # Compiled JavaScript
├── test/
│   └── test.js              # Test suite
├── package.json
├── tsconfig.json
└── README.md
```

## Dependencies

- `@modelcontextprotocol/sdk` - MCP SDK for TypeScript
- `express` - HTTP server framework
- `axios` - HTTP client for API calls
- `zod` - Schema validation
- `typescript` - TypeScript compiler

## License

MIT