# Clone the repository
git clone https://github.com/kumaran-is/mcp-weather-server.git
cd mcp-weather-server

# Install dependencies
npm install

# Build the project
npm run build

{
  "mcpServers": {
    "weather": {
      "autoApprove": [
        "get_current_weather",
        "get_weather_forecast",
        "retrieve_weather_context"
      ],
      "disabled": true,
      "timeout": 30000,
      "type": "stdio",
      "command": "npx",
      "args": [
        "tsx",
        "src/server.ts"
      ],
      "cwd": "/path-to/mcp-weather-server",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-weather-server": {
      "command": "/your/path/.nvm/versions/node/v22.15.0/bin/npx",
      "args": [
        "tsx",
        "/your/path/mcp-weather-server/src/server.ts"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "NODE_ENV": "production",
        "PRETTY_LOGS": "false",
        "LOG_LEVEL": "info"
      },
      "timeout": 30000
    }
  }
}

I'm planning a 2-week trip across Europe starting next week. Can you check the weather for:

1. Current conditions in my departure city: London
2. 7-day forecasts for my planned stops:
   - Paris (days 1-3)
   - Rome (days 4-6)
   - Vienna (days 7-9)
   - Prague (days 10-12)
   - Amsterdam (days 13-14)

Based on the weather, should I pack heavy winter clothing or lighter layers? Any cities I should avoid due to weather conditions?

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["tsx", "src/server.ts"],
      "cwd": "${workspaceFolder}",
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

{
  "github.copilot.mcpServers": {
    "weather": {
      "command": "node",
      "args": ["./dist/server.js"],
      "transport": "stdio"
    }
  }
}

I need comprehensive weather information for travel planning. Can you help me with the following?

First, give me the CURRENT weather conditions for these cities:
- London, UK
- Tokyo, Japan
- New York, USA
- Sydney, Australia
- Dubai, UAE

Next, I need 5-day weather forecasts for these vacation destinations:
- Paris, France
- Bali, Indonesia
- Miami, USA
- Barcelona, Spain

Finally, help me understand the weather context for these specific travel scenarios:
- "What's the weather like in Berlin for outdoor photography?"
- "Weather conditions in Singapore for business meetings"
- "Is the weather in Mumbai suitable for beach activities?"

Format everything in a clear, organized way that helps with travel planning decisions.

I'm organizing outdoor events and need detailed weather information:

1. Check current weather for immediate decisions in:
   - Los Angeles (concert tonight)
   - Chicago (street fair this afternoon)
   - Boston (marathon tomorrow morning)

2. Get 3-day forecasts for upcoming events in:
   - Seattle (tech conference)
   - Denver (mountain wedding)
   - Orlando (theme park opening)

3. Weather context for: "outdoor wedding in San Francisco this weekend"

Please highlight any concerning weather patterns like rain, extreme temperatures, or high winds.

I manage farms in multiple regions and need weather data for agricultural planning:

1. Current weather conditions for immediate field work decisions:
   - Des Moines, Iowa
   - Sacramento, California
   - Houston, Texas
   - Jacksonville, Florida

2. 7-day forecasts for planting/harvesting schedules:
   - Kansas City (wheat fields)
   - Portland (orchards)
   - Phoenix (cotton farms)

3. Context analysis: "weather in Nebraska for corn planting season"

Focus on precipitation, temperature ranges, and humidity levels that affect crop management.

I coordinate outdoor sports activities and need weather assessments:

Current conditions for today's activities:
- Skiing in Aspen, Colorado
- Surfing in Honolulu, Hawaii
- Golfing in Phoenix, Arizona
- Sailing in San Diego, California

Get 5-day forecasts for upcoming tournaments:
- Tennis in Melbourne
- Football in Green Bay
- Baseball in Atlanta

Also check: "weather in Vancouver for mountain biking this weekend"

Emphasize wind speeds, precipitation, and visibility conditions.

I need weather data for emergency preparedness and response planning:

1. Current severe weather check for these high-risk areas:
   - New Orleans, Louisiana
   - Oklahoma City, Oklahoma
   - Buffalo, New York
   - Phoenix, Arizona

2. 3-day forecasts for resource deployment:
   - Minneapolis (potential snowstorm)
   - Houston (flooding risk)
   - Los Angeles (fire weather)

3. Context queries:
   - "weather conditions in Miami for hurricane preparedness"
   - "weather in Denver for avalanche risk assessment"

Flag any extreme weather conditions, temperature anomalies, or precipitation warnings.

I manage flight operations and ground transportation. Please provide:

Current weather at major hub airports:
- Atlanta (ATL)
- Chicago (ORD)
- London (Heathrow area)
- Tokyo (Narita area)
- Dubai

48-hour forecasts for flight planning:
- Frankfurt
- Singapore
- Los Angeles
- New York

Weather context for: "flying conditions in Dallas today"

Focus on visibility, wind speeds, precipitation, and temperature extremes that affect operations.

What's the current weather in London? I need temperature, humidity, wind speed, and general conditions.

Can you check the current weather in Paris, Rome, and Madrid? I'm trying to decide which city to visit today.

Show me a 7-day weather forecast for Tokyo. I'm planning outdoor activities and need to know the best days.

What's the weather forecast for the next 3 days in San Francisco? Keep it brief.

I'm wondering about the weather in Seattle for hiking this weekend. Can you help me understand if it's suitable?

What's the weather situation in New York for outdoor business lunch meetings?

Check the weather in these extreme locations:
- Reykjavik, Iceland (cold climate)
- Cairo, Egypt (hot desert)
- Singapore (tropical)
- La Paz, Bolivia (high altitude)

Test the system's error handling with these challenging requests:

1. Check weather for cities with ambiguous names:
   - "Paris" (which Paris? France or Texas?)
   - "London" (UK or Ontario?)
   - "Sydney" (Australia or Nova Scotia?)

2. Test with misspelled city names:
   - "Tokio" instead of "Tokyo"
   - "San Franciso" instead of "San Francisco"
   - "Mosco" instead of "Moscow"

3. Request forecasts with invalid parameters:
   - "Show me a 10-day forecast for Berlin" (exceeds 7-day limit)
   - "Get weather forecast for 0 days in Rome"
   - "Weather forecast for -5 days in Madrid"

4. Try non-existent or very small cities:
   - "Weather in Atlantis"
   - "Current conditions in Hogwarts"
   - "Forecast for Middle Earth"

5. Test with special characters and injection attempts:
   - "Weather in London'; DROP TABLE weather;--"
   - "Forecast for <script>alert('test')</script>"
   - "Current weather in ${city}"

6. Query without clear city reference:
   - "What's the weather like?"
   - "Is it raining?"
   - "Tell me about the forecast"

7. Multiple cities in one context query:
   - "Weather for traveling from Paris to London to Amsterdam"

Show me how the system handles these edge cases gracefully.

Let's test the caching and performance:

1. First request - Check weather in London (should hit the API)
2. Immediately check London weather again (should be cached)
3. Wait 1 minute and check London again (still cached?)
4. Check weather for 10 different cities rapidly:
   - London, Paris, Tokyo, New York, Sydney
   - Dubai, Singapore, Moscow, Rio, Cairo

Notice any performance differences between cached and fresh requests?

I need to compare weather conditions across different regions:

1. Current weather comparison:
   - Tropical: Singapore, Bangkok, Manila
   - Desert: Dubai, Phoenix, Cairo
   - Temperate: London, Paris, Berlin
   - Cold: Reykjavik, Helsinki, Oslo

2. Weekly forecast comparison for vacation planning:
   - Beach destinations: Miami, Cancun, Bali
   - Ski resorts: Aspen, Zurich, Innsbruck
   - City breaks: Rome, Barcelona, Prague

3. Context for decision making:
   - "Compare weather in Tokyo vs Seoul for cherry blossom viewing"
   - "Weather differences between San Francisco and Los Angeles for tech conferences"

Help me identify the best weather patterns for different activities.

src/
├── server.ts                ← 🎯 **Layer 1: Transport & Infrastructure**
├── mcp-server.ts            ← 🧠 **Layer 2: Protocol & MCP SDK (MODERNIZED)**
├── weather-service.ts       ← 🌤️ **Layer 3: Business & Domain Logic**
├── types.ts                 ← 📝 TypeScript interfaces
├── logger-pino.ts           ← 📊 Production logging with Pino
│
├── config/                  ← ⚙️ Configuration management
│   ├── config.ts           ← Main configuration with Zod validation
│   ├── config.spec.ts      ← Configuration tests
│   └── auth-config.ts      ← Authentication configuration
│
├── cache/                   ← 🗄️ Intelligent LRU caching
│   ├── weather-cache.ts    ← Multi-tier caching system
│   └── weather-cache.spec.ts ← Cache layer tests
│
├── errors/                  ← 🚨 Custom error handling
│   ├── weather-errors.ts   ← Specialized error classes
│   └── weather-errors.spec.ts ← Error handling tests
│
├── middleware/              ← 🛡️ Request validation & security
│   ├── validation.ts       ← JSON-RPC & MCP validation
│   ├── validation.spec.ts  ← Validation tests
│   ├── auth.ts             ← Authentication middleware
│   ├── rate-limit.ts       ← Rate limiting protection
│   └── sanitization.ts     ← Input sanitization
│
├── security/                ← � Security utilities
│   └── sanitizer.ts        ← DOMPurify-based sanitization
│
├── undici-resilience/       ← �🛡️ Advanced HTTP resilience
│   ├── index.ts             ← Main exports & pool manager
│   ├── index.spec.ts       ← Resilience integration tests
│   ├── logger.ts           ← Resilience-specific logging
│   │
│   ├── config/              ← Resilience configuration
│   │   └── pool-config.ts  ← Pool & resilience settings
│   │
│   ├── http/                ← Connection pooling
│   │   └── pool-manager.ts ← HTTP connection management
│   │
│   ├── resilience/          ← Resilience patterns
│   │   ├── circuit-breaker.ts     ← Circuit breaker pattern
│   │   ├── circuit-breaker.spec.ts ← Circuit breaker tests
│   │   ├── retry-strategy.ts      ← Retry with backoff
│   │   ├── rate-limiter.ts        ← Request throttling
│   │   └── bulkhead.ts           ← Resource isolation
│   │
│   ├── streaming/           ← Backpressure handling
│   │   ├── streaming-pool-manager.ts    ← Streaming pool management
│   │   ├── streaming-metrics.ts         ← Stream metrics collection
│   │   └── backpressure-handler.ts     ← Adaptive backpressure
│   │
│   └── monitoring/          ← Metrics and health
│       └── metrics.ts      ← Performance metrics
│
└── utils/                   ← � Utility functions
    ├── version.ts          ← Version information utility
    └── version.spec.ts     ← Version utility tests

**🏗️ Perfect 3-Layer SOLID Architecture:**
- **Layer 1 (server.ts)**: Pure infrastructure - Fastify, transports, sessions
- **Layer 2 (mcp-server.ts)**: Modern MCP SDK - `McpServer`, `registerTool()`, Zod
- **Layer 3 (weather-service.ts)**: Pure business logic - weather APIs, caching

**🔒 Security & Middleware Layer:**
- **Authentication**: Multi-tier API key validation system
- **Rate Limiting**: Global, per-client, per-IP, per-endpoint protection
- **Input Sanitization**: DOMPurify-based with attack pattern detection
- **Validation**: JSON-RPC 2.0 and MCP protocol compliance

**🛡️ Enterprise Resilience Layer:**
- **Circuit Breaker**: Automatic failure detection and recovery
- **Retry Strategy**: Exponential backoff with jitter
- **Rate Limiting**: Token bucket and sliding window algorithms
- **Bulkhead Pattern**: Resource isolation and protection
- **Connection Pooling**: Optimized HTTP connection reuse
- **Streaming Support**: Backpressure handling and adaptive thresholds

// No changes needed to McpServer or WeatherService!
const wsTransport = new WebSocketTransport(server);
await mcpServer.connect(wsTransport); // Same MCP logic works

sequenceDiagram
    participant Client
    participant Fastify
    participant StreamableHTTPTransport
    participant WeatherMCPServer
    participant WeatherService
    participant UndiciResilience
    participant OpenMeteoAPI

    %% Initialization Phase
    Client->>Fastify: POST /mcp (initialize)
    Note over Client,Fastify: Headers: MCP-Protocol-Version, Accept: application/json, text/event-stream
    Fastify->>StreamableHTTPTransport: handleRequest()
    StreamableHTTPTransport->>WeatherMCPServer: handleInitialize()
    WeatherMCPServer-->>StreamableHTTPTransport: Server capabilities & info
    StreamableHTTPTransport-->>Fastify: Session UUID generated
    Fastify-->>Client: 200 OK + Mcp-Session-Id header
    Note over Fastify,Client: Returns server info + session ID

    Client->>Fastify: POST /mcp (notifications/initialized)
    Note over Client,Fastify: Headers include Mcp-Session-Id
    Fastify->>StreamableHTTPTransport: processMessage()
    StreamableHTTPTransport->>WeatherMCPServer: handleInitialized()
    WeatherMCPServer-->>StreamableHTTPTransport: Acknowledged
    StreamableHTTPTransport-->>Fastify: 202 Accepted
    Fastify-->>Client: 202 Accepted

    %% Tool Operations
    Client->>Fastify: POST /mcp (tools/list)
    Note over Client,Fastify: Headers: Mcp-Session-Id
    Fastify->>StreamableHTTPTransport: processMCPMessage()
    StreamableHTTPTransport->>WeatherMCPServer: handleToolsList()
    WeatherMCPServer-->>StreamableHTTPTransport: Available tools array
    StreamableHTTPTransport-->>Fastify: JSON response
    Fastify-->>Client: 200 OK (tools array)

    %% Weather Request Flow with Resilience
    Client->>Fastify: POST /mcp (tools/call: get_current_weather)
    Note over Client,Fastify: {"name": "get_current_weather", "arguments": {"city": "London"}}
    Fastify->>StreamableHTTPTransport: processMCPMessage()
    StreamableHTTPTransport->>WeatherMCPServer: handleToolsCall()
    WeatherMCPServer->>WeatherService: getCurrentWeather("London")

    %% Geocoding with Resilience Patterns
    WeatherService->>UndiciResilience: Request with circuit breaker
    UndiciResilience->>OpenMeteoAPI: GET /geocoding-api/v1/search?name=London
    Note over UndiciResilience,OpenMeteoAPI: Circuit breaker monitors health
    OpenMeteoAPI-->>UndiciResilience: Geocoding response
    UndiciResilience-->>WeatherService: Coordinates (with retry if needed)

    %% Weather Data Fetch with Resilience
    WeatherService->>UndiciResilience: Request with rate limiting
    UndiciResilience->>OpenMeteoAPI: GET /v1/forecast?latitude=51.5&longitude=-0.1
    Note over UndiciResilience,OpenMeteoAPI: Rate limited, retries on failure
    OpenMeteoAPI-->>UndiciResilience: Weather data
    UndiciResilience-->>WeatherService: Weather response

    WeatherService-->>WeatherMCPServer: Formatted weather data
    WeatherMCPServer-->>StreamableHTTPTransport: Tool result
    StreamableHTTPTransport-->>Fastify: JSON-RPC response
    Fastify-->>Client: 200 OK (SSE format if streaming)
    Note over Fastify,Client: data: {"jsonrpc":"2.0","result":...}

    %% SSE Stream for Real-time Updates
    Client->>Fastify: GET /mcp (SSE stream)
    Note over Client,Fastify: Accept: text/event-stream
    Fastify->>StreamableHTTPTransport: handleGET()
    StreamableHTTPTransport-->>Fastify: 200 OK + SSE headers
    Fastify-->>Client: SSE connection established
    Note over StreamableHTTPTransport,Client: Persistent connection for notifications

sequenceDiagram
    participant AI Assistant
    participant StdioTransport
    participant WeatherMCPServer
    participant WeatherService
    participant UndiciResilience
    participant OpenMeteoAPI

    %% Connection Establishment
    AI Assistant->>StdioTransport: Start MCP server process (npx tsx src/server.ts)
    StdioTransport->>WeatherMCPServer: Initialize server
    WeatherMCPServer-->>StdioTransport: Server ready on stdin/stdout

    %% MCP Protocol Handshake
    AI Assistant->>StdioTransport: {"jsonrpc":"2.0","id":"1","method":"initialize","params":{...}}
    StdioTransport->>WeatherMCPServer: handleInitialize()
    WeatherMCPServer-->>StdioTransport: {"jsonrpc":"2.0","id":"1","result":{"capabilities":...}}
    StdioTransport-->>AI Assistant: Server capabilities & protocol version

    AI Assistant->>StdioTransport: {"jsonrpc":"2.0","method":"notifications/initialized"}
    StdioTransport->>WeatherMCPServer: handleInitialized()
    Note over WeatherMCPServer: Server fully initialized

    %% Tool Discovery
    AI Assistant->>StdioTransport: {"jsonrpc":"2.0","id":"2","method":"tools/list"}
    StdioTransport->>WeatherMCPServer: handleToolsList()
    WeatherMCPServer-->>StdioTransport: {"tools":[...]}
    StdioTransport-->>AI Assistant: 3 available tools
    Note over AI Assistant: get_current_weather, get_weather_forecast, retrieve_weather_context

    %% Weather Query Processing with Resilience
    AI Assistant->>StdioTransport: {"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"get_current_weather","arguments":{"city":"Tokyo"}}}
    StdioTransport->>WeatherMCPServer: handleToolsCall()
    WeatherMCPServer->>WeatherService: getCurrentWeather("Tokyo")

    %% API Integration with Resilience Patterns
    WeatherService->>UndiciResilience: Request with circuit breaker
    UndiciResilience->>OpenMeteoAPI: GET /geocoding-api/v1/search?name=Tokyo
    Note over UndiciResilience: Monitor latency, apply retry logic
    OpenMeteoAPI-->>UndiciResilience: {"results":[{"latitude":35.68,"longitude":139.69}]}
    UndiciResilience-->>WeatherService: Coordinates (with backoff retry)

    WeatherService->>UndiciResilience: Request with rate limiting
    UndiciResilience->>OpenMeteoAPI: GET /v1/forecast?latitude=35.68&longitude=139.69
    Note over UndiciResilience: Rate limit: 10 req/sec
    OpenMeteoAPI-->>UndiciResilience: Weather data JSON
    UndiciResilience-->>WeatherService: Parsed weather response

    WeatherService-->>WeatherMCPServer: Formatted weather object
    WeatherMCPServer-->>StdioTransport: {"jsonrpc":"2.0","id":"3","result":{"content":[...]}}
    StdioTransport-->>AI Assistant: Weather information via stdout

    %% Error Handling with Circuit Breaker
    Note over WeatherService,UndiciResilience: If circuit open or API fails
    UndiciResilience-->>WeatherService: Circuit breaker open/API error
    WeatherService-->>WeatherMCPServer: Error with details
    WeatherMCPServer-->>StdioTransport: {"jsonrpc":"2.0","id":"3","error":{"code":-32603,"message":"..."}}
    StdioTransport-->>AI Assistant: Error response

graph TB
    A[Client/AI Assistant] --> B[Transport Layer]
    B --> C{MCP Protocol Handler}

    C --> D[WeatherMCPServer]
    D --> E[WeatherService]

    E --> R[Undici Resilience Layer]
    R --> F[Open-Meteo Geocoding API]
    R --> G[Open-Meteo Weather API]

    D --> H[Pino Logger]
    D --> I[Configuration]

    B --> J[HTTP Transport<br/>StreamableHTTPTransport]
    B --> K[Stdio Transport<br/>StdioServerTransport]

    J --> L[Fastify Server]
    J --> M[SSE Handler]
    J --> S[Session Manager]

    R --> CB[Circuit Breaker]
    R --> RL[Rate Limiter]
    R --> RT[Retry Strategy]
    R --> BH[Bulkhead Pattern]
    R --> PM[Pool Manager]

    subgraph "Core Components"
        D
        E
        H
        I
    end

    subgraph "Transport Options"
        J
        K
        L
        M
        S
    end

    subgraph "Resilience Patterns"
        CB
        RL
        RT
        BH
        PM
    end

    subgraph "External APIs"
        F
        G
    end

    style R fill:#f9f,stroke:#333,stroke-width:2px
    style CB fill:#ffd,stroke:#333,stroke-width:1px
    style RL fill:#ffd,stroke:#333,stroke-width:1px
    style RT fill:#ffd,stroke:#333,stroke-width:1px
    style BH fill:#ffd,stroke:#333,stroke-width:1px
    style PM fill:#ffd,stroke:#333,stroke-width:1px

# Transport selection (stdio, http)
MCP_TRANSPORT=stdio

# Port configuration
MCP_HTTP_PORT=8080  # For HTTP transport

# Logging
LOG_LEVEL=info

{
  "jsonrpc": "2.0",
  "id": "123",
  "method": "tools/call",
  "params": {
    "name": "get_current_weather",
    "arguments": { "city": "London" }
  }
}

{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "content": [{
      "type": "text",
      "text": "Weather in London:\n• Temperature: 15.2°C\n• Condition: Partly cloudy\n• Humidity: 72%\n• Wind Speed: 8.5 m/s\n• Feels Like: 14.8°C\n• Pressure: 1013.25 hPa"
    }]
  }
}

{
  "jsonrpc": "2.0",
  "id": "124",
  "method": "tools/call",
  "params": {
    "name": "get_weather_forecast",
    "arguments": { "city": "Tokyo", "days": 3 }
  }
}

{
  "jsonrpc": "2.0",
  "id": "125",
  "method": "tools/call",
  "params": {
    "name": "retrieve_weather_context",
    "arguments": { "query": "weather in Paris for travel" }
  }
}

npm test

npm run test:coverage

npm run http

# Initialize session
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl-test","version":"1.0.0"}}}'

# Get current weather (use session ID from initialize response)
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":"2","method":"tools/call","params":{"name":"get_current_weather","arguments":{"city":"London"}}}'

curl http://localhost:8080/health

echo '{"jsonrpc":"2.0","id":"1","method":"tools/list"}' | npm run stdio

{
  "level": "info",
  "time": "2025-01-08T16:30:00.000Z",
  "msg": "Weather MCP Server initialized",
  "name": "weather-mcp-server",
  "version": "1.0.0",
  "protocolVersion": "2025-06-18"
}

curl http://localhost:8080/health

private clients: Map<string, ClientConnection> = new Map();

private messageQueues: Map<string, unknown[]> = new Map();