# 🌤️ MCP Weather Server

A production-grade Model Context Protocol (MCP) server providing comprehensive real-time weather data using the free **Open-Meteo API**.

[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/your-repo/mcp-weather)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen)](package.json)

## ✨ Features

### 🌦️ Weather Data
- **Current Weather**: Real-time conditions with 20+ meteorological parameters
- **5-Day Forecast**: Detailed daily predictions with solar, UV, and precipitation data
- **Comprehensive Metrics**: Temperature, humidity, wind, pressure, UV index, visibility, cloud cover
- **Solar Data**: Sunshine duration, daylight hours, solar radiation, evapotranspiration

### 🚀 Performance & Reliability
- **Redis Caching**: Intelligent caching with configurable TTL (15min current, 1h forecast)
- **Metrics & Monitoring**: Real-time performance tracking and error logging
- **Graceful Degradation**: Continues working without Redis/cache if unavailable
- **Type-Safe**: Full Zod validation for all inputs and API responses

### 🏗️ Architecture
- **Multiple Transports**: Stdio (MCP Inspector) + HTTP/SSE streaming
- **Factory Pattern**: Isolated server instances per session
- **Layered Design**: Services, Tools, Server separation
- **ESM Modules**: Modern JavaScript with full ES2022 support

### 🔧 Developer Experience
- **64 Unit Tests**: Comprehensive Jest test suite
- **Hot Reload**: Development mode with file watching
- **Debug Support**: Integrated debugging for both transports
- **Rich Logging**: Structured logs with performance metrics

## 📊 Data Sources

### Open-Meteo API (Free Tier)
- **No API Key Required** - Unlimited calls for non-commercial use
- **Global Coverage** - Weather models for every location worldwide
- **Multiple Models** - ECMWF, NOAA GFS, Météo-France, DWD ICON, and more
- **Real-time Updates** - 15-minute to hourly resolution

### Available Weather Variables

#### Current Conditions
- Temperature & "Feels Like" (2m & apparent)
- Humidity, Dew Point, Vapour Pressure Deficit
- Wind Speed/Direction/Gusts (10m, 80m, 120m, 180m altitudes)
- Pressure (MSL & Surface), Cloud Cover (Total/Low/Mid/High)
- Visibility, UV Index, Precipitation
- Evapotranspiration & Reference ET₀

#### Forecast Data
- Daily min/max temperatures (actual & apparent)
- Precipitation (total, rain, showers, snow)
- Wind (speed, gusts, dominant direction)
- Solar (sunrise/sunset, sunshine/daylight duration, UV index)
- Radiation (shortwave solar radiation sum)

## 🏛️ Architecture

```
src/
├── index.js                    # Entry point & transport orchestration
├── server/
│   ├── weatherMcpFactory.js    # Server factory with cache init
│   └── streamableHttpServer.js # HTTP/SSE transport server
├── services/
│   ├── weatherApi.js          # Open-Meteo API client with caching
│   ├── weatherCodes.js        # WMO weather code mappings
│   ├── cache.js               # Redis cache service
│   └── metrics.js             # Performance monitoring
└── tools/
    ├── schemas.js             # Zod validation schemas
    ├── getWeatherTool.js      # Current weather MCP tool
    ├── getWeatherForecast5DaysTool.js # Forecast MCP tool
    └── getServerStatsTool.js  # Server metrics tool
```

### Design Patterns

| Pattern | Implementation | Purpose |
|---------|---|---|
| **Factory** | `createWeatherMcpServer()` | Isolated server instances per session |
| **Strategy** | Stdio vs HTTP transport strategies | Multiple deployment modes |
| **Adapter** | MCP SDK transport wrapping | Unified interface for different transports |
| **Decorator** | Response formatting with emojis | Enhanced user experience |
| **Observer** | Metrics collection | Performance monitoring |
| **Proxy** | Cache layer | API call optimization |

## 📋 Installation

### Prerequisites
- **Node.js** ≥16.0.0 (with `--experimental-vm-modules` for Jest)
- **Redis** (optional, for caching) - Install from [redis.io](https://redis.io)

### Setup
```bash
# Clone repository
git clone <repository-url>
cd mcp-weather

# Install dependencies
npm install

# Run tests
npm test

# Start server (stdio mode)
npm start
```

### Environment Variables
```bash
# Redis configuration (optional)
REDIS_URL=redis://localhost:6379

# HTTP server configuration
MCP_HTTP_PORT=3333
MCP_HTTP_HOST=127.0.0.1
```

## 🚀 Usage

### MCP Inspector (Recommended)
```bash
# Start in stdio mode for MCP Inspector
npm start

# Then open MCP Inspector and connect to the server
```

### HTTP/SSE Mode
```bash
# Start HTTP server with SSE transport
npm run start:http

# Server runs on http://127.0.0.1:3333
# MCP endpoint: http://127.0.0.1:3333/mcp
```

### Development Mode
```bash
# With hot reload
npm run dev

# With debugging
npm run debug:http  # HTTP mode
npm run debug       # Stdio mode
```

## 🔧 API Reference

### Tools

#### `get_weather`
Get current weather conditions for coordinates.

**Input:**
```json
{
  "latitude": 48.8566,
  "longitude": 2.3522
}
```

**Output:**
```
🌤️ Current Weather

📍 Location: 48.8566, 2.3522
🌡️ Temperature: 22.5°C (feels like 24.1°C)
💧 Humidity: 65%
🌫️ Dew Point: 15.8°C
💨 Wind: 12 km/h from WSW
🌪️ Wind Gusts: 18 km/h
☁️ Conditions: Partly cloudy
☁️ Cloud Cover: 45% (Low: 20%, Mid: 15%, High: 10%)
👁️ Visibility: 24 km
🧭 Pressure: 1013 hPa (MSL) / 1011 hPa (Surface)
☀️ UV Index: 6
💧 Evapotranspiration: 0.15 mm/h
🌱 Reference ET₀: 0.22 mm/h
🌡️ Vapor Pressure Deficit: 0.85 kPa
🌍 Timezone: Europe/Paris
🕐 Updated: 2024-03-29T14:30:00Z
```

#### `get_weather_forecast`
Get 5-day weather forecast for coordinates.

**Input:**
```json
{
  "latitude": 48.8566,
  "longitude": 2.3522
}
```

**Output:**
```
📅 5-Day Forecast

📍 Coordinates : 48.8566, 2.3522
🌍 Timezone    : Europe/Paris

📅 2024-03-29
   🌡️  18°C – 24°C (feels 16°C – 26°C)
   ☁️  Partly cloudy
   💧 Precipitation: 0.2 mm (0 rain + 0.1 showers + 0 snow)
   🌧️ Chance: 15% over 0.5h
   🌅 Sunrise: 06:45 | Sunset: 19:32
   ☀️  Sunshine: 8.2h / Daylight: 12.8h
   ☀️  UV Index: 6 (Clear sky: 7)
   💨 Wind: 15 km/h gusts to 22 km/h from W
   ⚡ Solar Radiation: 18.5 MJ/m²
   🌱 Reference ET₀: 4.2 mm
```

#### `get_server_stats`
Get server performance metrics and cache statistics.

**Input:** (no parameters required)

**Output:**
```
📊 Server Statistics

⏱️  Uptime: 45 minutes
🔄 API Calls: 127
💾 Cache Hits: 89 (70.1%)
❌ Errors: 2
⚡ Avg Response Time: 245ms

🔧 Tool Usage:
   • get_weather: 95 calls
   • get_weather_forecast: 32 calls

📋 Cache Status:
   • Connected: ✅
   • Keys: 23
   • Memory: 2.4MB
```

## 🧪 Testing

### Run Test Suite
```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch
```

### Test Architecture
- **64 unit tests** covering all services and server components
- **Mocked API calls** for reliable testing without network dependencies
- **Cache testing** with Redis mock
- **Schema validation** testing with Zod
- **Error handling** coverage

### Test Files
```
tests/
├── services/
│   ├── weatherApi.test.js     # API client tests
│   └── weatherCodes.test.js   # Weather code mapping tests
└── server/
    └── weatherMcpFactory.test.js # Server factory tests
```

## 📈 Monitoring & Metrics

### Built-in Metrics
- **API Call Tracking**: Count, response times, cache hit rates
- **Tool Usage**: Per-tool invocation counts
- **Error Tracking**: Error types and frequencies
- **Cache Performance**: Hit rates, memory usage, connection status
- **Server Health**: Uptime, active sessions

### Logs
Structured logging with:
- Request/response timing
- Cache operations
- API call details
- Error context
- Performance metrics

### Cache Configuration
```javascript
// Current weather: 15 minutes TTL
// Forecasts: 1 hour TTL
// Automatic expiration and cleanup
```

## 🔒 Security & Reliability

### Data Validation
- **Zod schemas** for all inputs
- **Coordinate bounds** checking (-90/+90, -180/+180)
- **API response** validation
- **Error sanitization** (no sensitive data leakage)

### Error Handling
- **Graceful degradation** (continues without cache)
- **Structured error responses** with appropriate HTTP codes
- **Timeout handling** for API calls
- **Connection retry** logic for Redis

### Performance
- **Connection pooling** for Redis
- **Request deduplication** via caching
- **Memory-efficient** data structures
- **Background cleanup** of expired cache entries

## 🤝 Contributing

### Development Setup
```bash
# Install dependencies
npm install

# Run tests
npm test

# Start development server
npm run dev

# Debug mode
npm run debug
```

### Code Quality
- **ESLint** configuration for code style
- **Prettier** for consistent formatting
- **Jest** for comprehensive testing
- **TypeScript definitions** for better IDE support

### Architecture Guidelines
- **Layer separation**: Services, Tools, Server layers
- **Dependency injection**: Injectable fetch/cache for testing
- **Error boundaries**: Comprehensive error handling
- **Logging standards**: Structured logging throughout

## 📄 License

**MIT License** - Free for personal and commercial use.

### Open-Meteo Terms
- Non-commercial use: Unlimited API calls
- Commercial use: Contact Open-Meteo for licensing
- Attribution required for public deployments

## 🙏 Acknowledgments

- **Open-Meteo** for providing free, high-quality weather data
- **Anthropic** for the Model Context Protocol specification
- **Weather model providers**: ECMWF, NOAA, Météo-France, DWD, and others

## 📞 Support

### Issues & Bugs
- GitHub Issues: Report bugs and request features
- Documentation: Check this README first

### Community
- **MCP Discord**: Join the Model Context Protocol community
- **Open-Meteo Forum**: Weather API discussions

---

**Built with ❤️ using the Model Context Protocol**

### Stdio Mode (Default)
```bash
npm start
# or: node src/index.js
```
Perfect for direct MCP client integration (Claude Desktop, IDEs, etc.)

### HTTP/SSE Mode
```bash
# Via CLI flag
npm run start:http
# or: node src/index.js --http

# Via environment variables
TRANSPORT=http PORT=8080 node src/index.js

# Default HTTP port: 3001
```

**HTTP Endpoints:**
- `GET /health` - Health check endpoint
- `GET /sse` - Server-Sent Events stream
- `POST /messages` - Tool request endpoint

### Demo Script
```bash
node demo.js
```
Shows real-world example calls to weather service for multiple cities.

### Run Tests
```bash
npm test
```
Validates input schemas and weather code mappings.

## 🛠️ Available Tools

### Tool: `get_weather`
Get current weather for a location.

**Parameters:**
```json
{
  "latitude": -90 to 90,
  "longitude": -180 to 180
}
```

**Example:**
```bash
# Request current weather for Paris
{
  "latitude": 48.8566,
  "longitude": 2.3522
}
```

**Response Example:**
```
☀️ **CURRENT WEATHER**

📍 Location: 48.8566°N, 2.3522°E
🌡️  Temperature: 15°C
☁️  Condition: Partly cloudy
💧 Humidity: 65%
💨 Wind Speed: 12 km/h
🕐 Time: 2024-03-29T10:30:00Z
🌍 Timezone: Europe/Paris
```

### Tool: `get_forecast`
Get 5-day weather forecast.

**Parameters:**
```json
{
  "latitude": -90 to 90,
  "longitude": -180 to 180
}
```

**Response Example:**
```
📅 **5-DAY WEATHER FORECAST**

📍 Location: 48.8566°N, 2.3522°E
🌍 Timezone: Europe/Paris

**Day 1** - 2024-03-29
☁️ Partly cloudy
🔺 Max: 18°C | 🔻 Min: 12°C

**Day 2** - 2024-03-30
🌧️ Slight rain
🔺 Max: 16°C | 🔻 Min: 10°C

...
```

## 🌍 Popular Coordinates

| City | Latitude | Longitude |
|------|----------|-----------|
| Paris | 48.8566 | 2.3522 |
| London | 51.5074 | -0.1278 |
| New York | 40.7128 | -74.0060 |
| Tokyo | 35.6762 | 139.6503 |
| Sydney | -33.8688 | 151.2093 |
| Berlin | 52.5200 | 13.4050 |
| Los Angeles | 34.0522 | -118.2437 |

## 🔗 Data Source

- **API**: [Open-Meteo](https://open-meteo.com/) - Free, open-source weather API
- **Documentation**: https://open-meteo.com/en/docs
- **Weather Codes**: [WMO Weather Interpretation Codes](https://www.noaa.gov/media/e1906d56-9acc-4ea6-a60c-4e214a01b47f/WMO-Weather-interpretation-codes.pdf)

## 📦 Module System

Uses **ES Modules (ESM)** with `"type": "module"` for modern JavaScript features:
- Clean import/export syntax
- Top-level await support
- Better tree-shaking compatibility

## 🧪 Testing

```bash
npm test
```

**Test Coverage:**
- Input coordinate validation (bounds checking)
- Weather code mapping (WMO codes)
- Schema validation with Zod
- Edge cases and error handling

## 📝 Project Structure

```
MCP-Weather/
├── src/
│   ├── index.js           # Main entry point
│   ├── server.js          # MCP server factory
│   ├── weatherService.js  # Weather API service
│   └── weatherTools.js    # MCP tools
├── package.json
├── demo.js                # Demo script
├── test.js                # Test suite
├── README.md
└── .env.example
```

## 🔧 Environment Variables

| Variable | Values | Default | Purpose |
|----------|--------|---------|---------|
| `TRANSPORT` | `stdio`, `http` | `stdio` | Transport mode |
| `PORT` | `1-65535` | `3001` | HTTP server port (HTTP mode only) |

**Example:**
```bash
# Run in HTTP mode on custom port
TRANSPORT=http PORT=8080 npm start
```

## 🐛 Troubleshooting

| Issue | Solution |
|-------|----------|
| `MODULE_NOT_FOUND` | Ensure `"type": "module"` in package.json |
| Port 3001 in use | Set custom port: `PORT=3002 npm run start:http` |
| Invalid coordinates error | Check bounds: latitude [-90, 90], longitude [-180, 180] |
| "Unknown weather condition" | WMO code mapping - check Open-Meteo documentation |
| ESM import errors | Verify all imports have `.js` file extension |

## 📜 License

ISC

## 🤝 Contributing

This project follows the MCP specification and best practices for Node.js server development.