# Weather MCP Server

A Model Context Protocol (MCP) server that provides weather data tools for AI assistants and applications. This server integrates with the National Weather Service (NWS) API to deliver real-time weather forecasts and alerts for locations within the United States.

## Features

- **Weather Forecasts**: Get detailed weather forecasts for any US location using latitude/longitude coordinates
- **Weather Alerts**: Retrieve active weather alerts for any US state
- **NWS Integration**: Direct integration with the official National Weather Service API
- **MCP Protocol**: Built using the Model Context Protocol SDK for seamless AI assistant integration

## Installation

### Prerequisites

- Node.js 18+ 
- npm or yarn

### Setup

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

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build:server
```

## Usage

### Running the MCP Server

Start the server:
```bash
npm run start:server
```

The server runs on stdio and is designed to be used with MCP-compatible AI assistants like Claude Desktop.

### Available Tools

The server provides two main tools:

#### 1. `get-forecast`
Retrieve weather forecast for a specific location.

**Parameters:**
- `latitude` (number): Latitude of the location (-90 to 90)
- `longitude` (number): Longitude of the location (-180 to 180)

**Example Usage:**
```javascript
// Get forecast for San Francisco
{
  "tool": "get-forecast",
  "parameters": {
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}
```

#### 2. `get-alerts`
Retrieve active weather alerts for a US state.

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

**Example Usage:**
```javascript
// Get alerts for California
{
  "tool": "get-alerts", 
  "parameters": {
    "state": "CA"
  }
}
```

## Integration with AI Assistants

### Claude Desktop Integration

To integrate with Claude Desktop, add the following to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/weather-mcp/dist/core/server/index.js"]
    }
  }
}
```

### Other MCP-Compatible Applications

This server follows the Model Context Protocol specification and can be integrated with any MCP-compatible application. The server communicates via stdio using the MCP protocol.

## API Data Sources

This server uses the following National Weather Service endpoints:

- **Forecasts**: `https://api.weather.gov/points/{lat},{lon}` and associated forecast URLs
- **Alerts**: `https://api.weather.gov/alerts?area={STATE}`

### Coverage

- **Forecasts**: All US territories and locations
- **Alerts**: All US states and territories (using two-letter state codes)

## Development

### Project Structure

```
src/
├── core/
│   ├── constants/     # API endpoints and configuration
│   ├── interfaces/    # TypeScript type definitions
│   ├── utils/         # Utility functions for API calls and formatting
│   ├── server/        # Server bootstrap and transport setup
│   └── index.ts       # Main MCP server implementation
└── client/            # (Empty - for future client implementations)
```

### Building

The project uses TypeScript and compiles to the `dist/` directory:

```bash
npm run build:server
```

### Adding New Tools

To add new weather-related tools:

1. Define the tool schema in `src/core/index.ts`
2. Implement the tool handler function
3. Add any necessary interfaces in `src/core/interfaces/index.ts`
4. Add utility functions in `src/core/utils/index.ts` if needed

Example:
```typescript
server.tool(
  "tool-name",
  "Tool description",
  {
    param1: z.string().describe("Parameter description"),
  },
  async ({ param1 }) => {
    // Implementation
    return {
      content: [
        {
          type: "text",
          text: "Result",
        },
      ],
    };
  }
);
```

## Error Handling

The server includes comprehensive error handling:

- **API Failures**: Graceful handling of NWS API errors with informative messages
- **Invalid Coordinates**: Validation for latitude/longitude bounds
- **Missing Data**: Proper handling when forecast or alert data is unavailable
- **Network Issues**: Timeout and connection error handling

## Dependencies

- **@modelcontextprotocol/sdk**: MCP server implementation
- **@anthropic-ai/sdk**: Anthropic SDK (for potential future features)
- **zod**: Runtime type validation
- **dotenv**: Environment variable management

## License

ISC License

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## Support

For issues and questions:
- Check the National Weather Service API documentation for data availability
- Ensure your coordinates are within US territories for forecasts
- Verify state codes are valid two-letter abbreviations for alerts

## Limitations

- **US Only**: The NWS API only provides data for US territories
- **Rate Limits**: Subject to National Weather Service API rate limits
- **Data Availability**: Some remote locations may not have detailed forecast data