MCP WEATHER SERVER WRITTEN IN TYPESCRIPT

# Protocol Map

This weather MCP server implements the Model Context Protocol (MCP) to provide weather data through a standardized interface. Below is the complete protocol mapping showing how the server communicates with MCP clients.

## Server Information

- **Name**: `weather`
- **Version**: `1.0.0`
- **Transport**: STDIO (Standard Input/Output)
- **Protocol**: [Model Context Protocol](https://modelcontextprotocol.io)

## Capabilities

```json
{
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}
```

## Tools

The server exposes two tools for weather data retrieval:

### 1. `get_alerts`

Retrieves active weather alerts for a US state.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "description": "Two-letter US state code (e.g. CA, NY)",
      "minLength": 2,
      "maxLength": 2
    }
  },
  "required": ["state"]
}
```

**Example Request:**
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_alerts",
    "arguments": {
      "state": "CA"
    }
  }
}
```

**Example Response:**
```json
{
  "content": [
    {
      "type": "text",
      "text": "Event: Heat Advisory\nArea: Los Angeles County\nSeverity: Moderate\nDescription: Dangerously hot conditions...\nInstructions: Drink plenty of fluids..."
    }
  ]
}
```

**Error Response:**
```json
{
  "content": [
    {
      "type": "text",
      "text": "Unable to fetch alerts or no alerts found."
    }
  ]
}
```

### 2. `get_forecast`

Retrieves weather forecast for a specific location using latitude and longitude coordinates.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "description": "Latitude of the location",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "type": "number",
      "description": "Longitude of the location",
      "minimum": -180,
      "maximum": 180
    }
  },
  "required": ["latitude", "longitude"]
}
```

**Example Request:**
```json
{
  "method": "tools/call",
  "params": {
    "name": "get_forecast",
    "arguments": {
      "latitude": 38.5816,
      "longitude": -121.4944
    }
  }
}
```

**Example Response:**
```json
{
  "content": [
    {
      "type": "text",
      "text": "Tonight:\nTemperature: 65°F\nWind: 5 mph SW\nForecast: Partly cloudy with a slight chance of showers.\n---\nTomorrow:\nTemperature: 78°F\nWind: 10 mph W\nForecast: Sunny skies throughout the day."
    }
  ]
}
```

**Error Responses:**
```json
{
  "content": [
    {
      "type": "text",
      "text": "Failed to retrieve grid point data for coordinates: 38.5816, -121.4944. This location may not be supported by the NWS API (only US locations are supported)."
    }
  ]
}
```

## Communication Flow

```mermaid
sequenceDiagram
    participant Client as MCP Client (Claude)
    participant Server as Weather Server
    participant NWS as National Weather Service API

    Client->>Server: Initialize Connection (STDIO)
    Server->>Client: Server Info + Capabilities
    
    Client->>Server: List Tools
    Server->>Client: [get_alerts, get_forecast]
    
    Client->>Server: Call Tool: get_forecast(lat, lon)
    Server->>NWS: GET /points/{lat},{lon}
    NWS->>Server: Grid Point Data
    Server->>NWS: GET {forecast_url}
    NWS->>Server: Forecast Data
    Server->>Client: Formatted Forecast Text
    
    Client->>Server: Call Tool: get_alerts(state)
    Server->>NWS: GET /alerts/active/area/{state}
    NWS->>Server: Active Alerts
    Server->>Client: Formatted Alerts Text
```

## Protocol Messages

### Initialization

**Client → Server:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "Claude Desktop",
      "version": "1.0.0"
    }
  }
}
```

**Server → Client:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "weather",
      "version": "1.0.0"
    }
  }
}
```

### Tool Discovery

**Client → Server:**
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
```

**Server → Client:**
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_alerts",
        "description": "Get weather alerts for a US state.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "state": {
              "type": "string",
              "description": "Two-letter US state code (e.g. CA, NY)"
            }
          },
          "required": ["state"]
        }
      },
      {
        "name": "get_forecast",
        "description": "Get weather forecast for a location.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number",
              "description": "Latitude of the location"
            },
            "longitude": {
              "type": "number",
              "description": "Longitude of the location"
            }
          },
          "required": ["latitude", "longitude"]
        }
      }
    ]
  }
}
```

## External API Integration

### National Weather Service API

The server integrates with the following NWS API endpoints:

| Endpoint | Purpose | Rate Limit |
|----------|---------|------------|
| `GET /alerts/active/area/{state}` | Retrieve active alerts for a state | User-Agent required |
| `GET /points/{latitude},{longitude}` | Get grid point metadata | User-Agent required |
| `GET {forecast_url}` | Retrieve detailed forecast | User-Agent required |

**Required Headers:**
```
User-Agent: weather-app/1.0
Accept: application/geo+json
```

## Error Handling

The server implements graceful error handling for:

1. **Invalid coordinates**: Returns error message for non-US locations
2. **Network failures**: Returns "Unable to fetch..." messages
3. **Missing data**: Returns "No active alerts" or similar user-friendly messages
4. **API errors**: Catches and handles HTTP errors from NWS API

## Transport Layer

- **Type**: STDIO (Standard Input/Output)
- **Encoding**: UTF-8
- **Message Format**: JSON-RPC 2.0
- **Framing**: Newline-delimited JSON

## Security Considerations

1. **Input Validation**: All parameters are validated against schema
2. **Rate Limiting**: Respects NWS API rate limits
3. **Error Sanitization**: External API errors are sanitized before returning to client
4. **No Authentication**: Server uses public NWS API (no credentials required)

## Logging

- **STDIO Servers**: All logs written to `stderr` (never `stdout`)
- **Log Location**: Configured in MCP client (e.g., `~/Library/Logs/Claude/mcp-server-weather.log`)
- **Log Level**: Errors and warnings only (to avoid STDIO corruption)