# Weather MCP Server

A Model Context Protocol (MCP) server that provides weather information and alerts from the National Weather Service (NWS).

## Features

- **get_alerts**: Retrieve active weather alerts for a US state
- **get_forecast**: Get weather forecasts for a specific location (latitude/longitude)

## Prerequisites

- Python 3.10 or higher
- Docker and Docker Compose (for containerized deployment)

## Installation

### Local Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/weather-mcp.git
cd weather-mcp

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Run the server
weather-mcp
```

### Docker Setup

```bash
# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f weather-mcp
```

## Configuration

### Claude Desktop Integration

To use this server with Claude Desktop, add the following to `~/.config/Claude/claude_desktop_config.json` (Linux/macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

#### Option 1: Local Installation
```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/weather-mcp",
        "run",
        "-m",
        "weather.main"
      ]
    }
  }
}
```

#### Option 2: Docker Container
```json
{
  "mcpServers": {
    "weather": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "weather-mcp-server"
      ]
    }
  }
}
```

## Development

### Running Tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/weather
```

### Code Formatting and Linting

```bash
# Format code with Black
black src tests

# Lint with Ruff
ruff check src tests
```

## Project Structure

```
weather-mcp/
├── src/weather/              # Main package
│   ├── __init__.py
│   ├── main.py              # Entry point
│   └── server.py            # Server implementation
├── config/                   # Configuration files
│   ├── __init__.py
│   └── settings.py
├── tests/                    # Test suite
├── Dockerfile               # Docker image definition
├── docker-compose.yml       # Docker Compose configuration
├── pyproject.toml          # Project metadata and dependencies
├── README.md               # This file
└── DOCKER_SETUP.md         # Docker setup guide
```

## API Reference

### get_alerts(state: str) -> str

Get active weather alerts for a US state.

**Parameters:**
- `state`: Two-letter US state code (e.g., CA, NY, TX)

**Returns:** Formatted string containing active weather alerts or a message if none found.

### get_forecast(latitude: float, longitude: float) -> str

Get weather forecast for a specific location.

**Parameters:**
- `latitude`: Location latitude (up to 4 decimal places recommended)
- `longitude`: Location longitude (up to 4 decimal places recommended)

**Returns:** Formatted string with the next 5 forecast periods including temperature, wind, and conditions.

## Troubleshooting

### Server won't start
- Check Python version: `python --version` (requires 3.10+)
- Ensure dependencies are installed: `pip install -e .`
- Check logs for detailed error messages

### Docker issues
- Rebuild image: `docker-compose build --no-cache`
- View logs: `docker-compose logs weather-mcp`
- Ensure Docker daemon is running

### Claude Desktop not detecting server
- Verify the path in `claude_desktop_config.json`
- Restart Claude Desktop after configuration changes
- Check the MCP server settings in Claude Desktop

## Logging

The server logs to stderr to avoid interfering with the MCP protocol's use of stdout. Logs are automatically sent to stderr and include timestamps and severity levels.

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues, questions, or suggestions, please open an issue on GitHub.