# Weather MCP Server

A Model Context Protocol (MCP) server that provides weather information and alerts using the National Weather Service (NWS) API. This server enables AI assistants to access real-time weather data for US locations.

## 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**: Uses the official National Weather Service API for reliable, up-to-date weather data
- **MCP Compatible**: Works with any MCP-compatible AI assistant or application

## Available Tools

### `get_forecast`

Get 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)

**Returns:** Detailed weather forecast including temperature, wind conditions, and weather descriptions for multiple periods.

### `get_alerts`

Get active weather alerts for a US state.

**Parameters:**

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

**Returns:** List of active weather alerts including severity, affected areas, and descriptions.

## Prerequisites

- Node.js (version 14 or higher)
- npm or yarn
- An MCP-compatible client (like VS Code with GitHub Copilot)

## Installation

1. Clone the repository:

   ```bash
   git clone <repository-url>
   cd weather-mcp-server
   ```

2. Install dependencies:

   ```bash
   npm install
   ```

## Building the Server

Build the TypeScript code to JavaScript:

```bash
npm run build
```

This will:

- Compile TypeScript files from `src/` to `build/`
- Make the main executable file executable (`chmod 755 build/index.js`)

## Usage with VS Code GitHub Copilot

To use this weather MCP server with VS Code GitHub Copilot, you need to update your MCP configuration:

### Step 1: Update MCP Configuration

Edit your `mcp.json` file (usually located in your VS Code settings directory) and add the weather server:

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/Users/gshanka/Documents/ReactDev/weather-mcp-server/build/index.js"]
    }
  }
}
```

**Note:** Replace the path in `args` with the absolute path to your built `index.js` file.

### Step 2: Restart VS Code

After updating the configuration, restart VS Code to load the new MCP server.

### Step 3: Use Weather Tools

Once configured, you can ask GitHub Copilot for weather information:

- "What's the weather forecast for San Francisco?" (Copilot will ask for coordinates or you can provide: latitude 37.7749, longitude -122.4194)
- "Are there any weather alerts in California?" (Use state code "CA")
- "Get me the forecast for latitude 40.7128, longitude -74.0060" (New York City)

## Example Usage

### Getting Weather Forecast

```text
User: "What's the weather forecast for Seattle?"
Assistant: I'll get the weather forecast for Seattle (latitude: 47.6062, longitude: -122.3321).

[The server will return a detailed forecast with temperature, wind, and conditions for multiple periods]
```

### Getting Weather Alerts

```text
User: "Are there any weather alerts in Florida?"
Assistant: I'll check for weather alerts in Florida.

[The server will return any active weather alerts for the state of FL]
```

## Development

### Project Structure

```text
weather-mcp-server/
├── src/
│   ├── index.ts          # Main MCP server implementation
│   └── weather-utils.ts  # Weather API utilities and types
├── build/                # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md
```

### Running in Development

```bash
# Build and run
npm run build
node build/index.js
```

### Debugging

The server logs errors to stderr, which you can monitor when running the server directly or check in your MCP client's logs.

## API Limitations

- **US Only**: The National Weather Service API only provides data for US locations
- **Rate Limiting**: The NWS API has rate limits; avoid making excessive requests
- **Data Availability**: Some remote or maritime locations may not have forecast data available

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Build and test the server
5. Submit a pull request

## License

ISC License - see package.json for details.

## Troubleshooting

### Server Not Loading

- Ensure the path in `mcp.json` points to the correct `build/index.js` file
- Verify the server was built successfully with `npm run build`
- Check VS Code's MCP logs for error messages

### No Weather Data

- Verify you're using valid US coordinates
- Check that the NWS API is accessible from your network
- Ensure you're using valid two-letter state codes for alerts

### Permission Errors

- Make sure the `build/index.js` file is executable
- The build script should handle this automatically with `chmod 755`