# Weather MCP Server

A Model Context Protocol (MCP) server implementation that provides weather alerts and forecasts for US locations using the National Weather Service (NWS) API.

## Features

### Tools
- **`get_alerts(state: str)`**: Get active weather alerts for a US state (e.g., "CA", "NY")
  - Returns formatted alerts with event type, area, severity, description, and instructions
  
- **`get_forecast(latitude: float, longitude: float)`**: Get detailed weather forecast for a specific location
  - Returns temperature, wind conditions, and detailed forecast for the next 5 periods

### Resources
- **`echo://{message}`**: Echo resource that returns a formatted message

## Project Structure

```
.
├── server/
│   ├── weather.py          # Main weather MCP server implementation
│   ├── weather.json        # MCP server configuration file
│   └── client.py           # Client example using MCPAgent with memory
├── mcpserver/
│   ├── server.py           # Alternative server implementation with SSE transport
│   ├── client-sse.py       # SSE transport client example
│   ├── client-stdio.py     # STDIO transport client example
│   ├── Dockerfile          # Docker configuration
│   └── requirements.txt    # Python dependencies
├── main.py                 # Project entry point
├── pyproject.toml          # Project configuration and dependencies
└── README.md               # This file
```

## Prerequisites

- Python 3.13 or higher
- [uv](https://github.com/astral-sh/uv) package manager

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd MCPCRASHCoursemain
```

2. Create and activate virtual environment:
```bash
uv venv
.venv\Scripts\activate  # Windows
# or
source .venv/bin/activate  # Linux/Mac
```

3. Install dependencies:
```bash
uv sync
```

Or install specific packages:
```bash
uv add "mcp[cli]"
uv add httpx
uv add langchain-groq
uv add mcp-use
uv add python-dotenv
```

## Usage

### Running the Weather Server

#### Option 1: Using the server in `server/weather.py` (STDIO transport)
```bash
uv run mcp dev server/weather.py
```

#### Option 2: Using the server in `mcpserver/server.py` (SSE transport)
```bash
cd mcpserver
uv run server.py
```

The SSE server will run on `http://localhost:8000`

### Running Client Examples

#### Using MCPAgent Client (with memory)
```bash
# Make sure to set GROQ_API_KEY in your .env file
uv run server/client.py
```

#### Using SSE Client
```bash
# First, start the SSE server in one terminal
cd mcpserver
uv run server.py

# Then in another terminal, run the client
uv run mcpserver/client-sse.py
```

#### Using STDIO Client
```bash
uv run mcpserver/client-stdio.py
```

### Installing in Claude Desktop

To install the server in Claude Desktop app:
```bash
uv run mcp install server/weather.py
```

You'll need to configure it in Claude Desktop's settings. The configuration file is located at `server/weather.json`.

### VS Code Integration

1. Open the project folder in VS Code
2. Open terminal and run:
```bash
uv run server/weather.py
```
3. Press `Ctrl+Shift+I` to launch chat in VS Code
4. Login with GitHub and setup MCP configuration in VS Code user settings

## Configuration

### Environment Variables

Create a `.env` file in the root directory:
```env
GROQ_API_KEY=your_groq_api_key_here
```

### MCP Server Configuration

The server configuration is in `server/weather.json`. Update the path to match your system:
```json
{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "mcp[cli]",
                "mcp",
                "run",
                "path/to/server/weather.py"
            ]
        }
    }
}
```

## Docker Support

Build and run using Docker:
```bash
cd mcpserver
docker build -t weather-mcp-server .
docker run -p 8000:8000 weather-mcp-server
```

## API Information

This server uses the [National Weather Service API](https://www.weather.gov/documentation/services-web-api), which is free and doesn't require an API key. The server includes:
- Proper User-Agent headers as required by NWS
- Error handling for API requests
- Formatted responses for easy reading

## Development

### Running in Development Mode

For development with MCP Inspector:
```bash
uv run mcp dev server/weather.py
```

### Testing

Test the server by running the client examples:
- `server/client.py` - Full-featured client with conversation memory
- `mcpserver/client-sse.py` - SSE transport example
- `mcpserver/client-stdio.py` - STDIO transport example

## Dependencies

- `mcp[cli]` - Model Context Protocol framework
- `httpx` - Async HTTP client for API requests
- `langchain-groq` - LLM integration (for client examples)
- `mcp-use` - MCP utilities
- `python-dotenv` - Environment variable management
- `nest-asyncio` - Async support for interactive Python

## License

See [LICENSE](LICENSE) file for details.

## Contributing

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

## Support

For issues and questions, please open an issue on GitHub.