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)
