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

Capabilities

{
  "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:

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

Example Request:

{
  "method": "tools/call",
  "params": {
    "name": "get_alerts",
    "arguments": {
      "state": "CA"
    }
  }
}

Example Response:

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

Error Response:

{
  "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:

{
  "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:

{
  "method": "tools/call",
  "params": {
    "name": "get_forecast",
    "arguments": {
      "latitude": 38.5816,
      "longitude": -121.4944
    }
  }
}

Example Response:

{
  "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:

{
  "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

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:

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

Server → Client:

{
  "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:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Server → Client:

{
  "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)