🌀 Hurricane Tracker MCP Server

A production-grade LLM-friendly Model Context Protocol (MCP) server that provides real-time hurricane tracking, forecast cones, local alerts, and historical storm data through MCP tools for AI assistants like Cline.

📑 Table of Contents

• 🌀 Hurricane Tracker MCP Server
  • 📑 Table of Contents
  • 🌟 Features
    • Hurricane Tracking Capabilities
    • Technical Excellence
  • 🛠️ Technology Stack
  • Quick Start
    • Prerequisites
    • Installation & Setup
      • Option 1. Cline AI Assistant
      • Option 2. Claude Desktop
    • 🧪 MCP Inspector
    • Test All Hurricane Tools
      • Quick Test - All Capabilities:
      • Real-World Use Cases:
      • Individual Test Scenarios:
      • Expected Real Data Behavior:
      • Expected Results:
  • 🌀 Available Hurricane Tools
    • Detailed Examples
  • 📚 Documentation
  • 🚀 CI/CD Pipeline
    • Workflow Features
  • Running on Docker Container
    • 1. Build and Run with Docker Compose
    • 2. Verify the Service is Running
    • 3. Cline MCP Configuration for Docker
    • 4. Stop the service
  • 🔧 Development Commands
  • 📊 Expected Test Results
  • 🏗️ Architecture
    • 📊 Data Flow Architecture
    • 🔄 Component Interaction Diagram
    • 📋 Sequence Diagram - STDIO Transport
    • 📋 Sequence Diagram - Streamable HTTP Transport
    • Perfect 3-Layer Architecture (Gold Standard Implementation)
    • Core Components - SOLID Implementation
      • 🔧 server.ts - Transport Layer & Infrastructure Management
      • 🌐 hurricane-mcp-server.ts - Protocol Layer & MCP Compliance Engine
      • 🌀 hurricane-service.ts - Business Layer & Domain Logic Engine
  • 🤝 Contributing
  • 📄 License

🌟 Features

Hurricane Tracking Capabilities

• 🌀 Real-time Storm Tracking: Live tropical cyclone positions, wind speeds, pressure data from NOAA/NHC
• 📍 5 Specialized Hurricane Tools:
  • get_active_storms - Monitor all active tropical cyclones worldwide
  • get_storm_cone - 5-day forecast cone of uncertainty for storm paths
  • get_storm_track - Historical storm track data
  • get_local_hurricane_alerts - Location-based hurricane warnings and watches
  • search_historical_tracks - Query IBTrACS database for past hurricanes
• 🌊 Multi-Basin Coverage: Atlantic (AL), Eastern Pacific (EP), Western Pacific (WP), and more
• ⚠️ Real-time Alerts: Integration with NWS for hurricane warnings, watches, and advisories
• 📊 Historical Data: Access to IBTrACS historical hurricane database

Technical Excellence

• 🏗️ Perfect SOLID Architecture: Clean 3-layer separation with zero cross-contamination
• ⚡ Latest MCP SDK Patterns: Modern McpServer, registerTool(), and Zod validation
• 🤖 LLM-Friendly Design: Clear tool descriptions, structured responses, and intelligent error handling
• 🔄 Modern Dual Transport:
  • Official Stdio: Local development with Cline/Claude Desktop
  • Official Streamable HTTP: Production APIs with session management
• 🛡️ Enterprise Resilience: Circuit breaker, retry strategies, rate limiting, bulkhead isolation
• ⚡ Ultra Performance: Fastify + Undici with connection pooling and streaming
• 🔒 Security First: Input validation, CORS support, session management, audit logging
• 📊 Advanced Observability: Structured Pino logging, correlation IDs, performance metrics
• 🚀 Production Ready: Docker containerization, graceful shutdown, health monitoring

🛠️ Technology Stack

Technology	Version	Purpose
Node.js	>=22.0.0	JavaScript runtime environment
TypeScript	~5.9.0	Type-safe JavaScript development
@modelcontextprotocol/sdk	~1.17.5	Latest MCP SDK with modern patterns
Zod	~3.23.8	Runtime schema validation and TypeScript inference
Fastify	~5.6.0	High-performance web framework (transport layer)
Pino	~9.9.0	Production structured logging
Vitest	~3.2.0	Next-generation testing framework
undici	~7.16.0	High-performance HTTP client with resilience
NOAA/NHC APIs	N/A	Real-time hurricane data from National Hurricane Center
NWS API	N/A	Weather alerts and warnings
IBTrACS	N/A	Historical hurricane track database

Note: The project includes an advanced undici-resilience package that enhances the standard undici client with enterprise-grade resilience patterns including circuit breakers, retry strategies, rate limiting, and comprehensive monitoring. This ensures reliable hurricane API calls even under adverse conditions.

Quick Start

Prerequisites

• Node.js 22.x or higher
• npm or yarn package manager
• Cline (Claude for VS Code) or other MCP-compatible AI assistant

Installation & Setup

# Clone and navigate to the project
git clone https://github.com/kumaran-is/hurricane-tracker-mcp.git
cd hurricane-tracker-mcp

# Install dependencies
npm install

# Build the project
npm run build

Option 1. Cline AI Assistant

📖 For detailed setup instructions, see CLINE_SETUP.md

Add the following configuration to your Cline MCP settings file (cline_mcp_settings.json):

{
  "mcpServers": {
    "hurricane-tracker": {
      "command": "npm",
      "args": [
        "run",
        "stdio"
      ],
      "cwd": "/path/to/your/hurricane-tracker-mcp",
      "env": {
        "MCP_TRANSPORT": "stdio"
      },
      "autoApprove": [
        "get_active_storms",
        "get_storm_cone",
        "get_storm_track",
        "get_local_hurricane_alerts",
        "search_historical_tracks"
      ],
      "disabled": false,
      "timeout": 30000,
      "type": "stdio"
    }
  }
}

Important: Replace /path/to/your/hurricane-tracker-mcp with your actual project path.

After adding the configuration, restart Cline to load the Hurricane Tracker MCP Server.

Option 2. Claude Desktop

📖 For detailed setup instructions, see CLAUDE_DESKTOP_SETUP.md

Add the following configuration to your Claude Desktop MCP settings file (claude_desktop_config.json):

{
  "mcpServers": {
    "hurricane-tracker-mcp": {
      "command": "/path/to/your/.nvm/versions/node/v22.15.0/bin/node",
      "args": [
        "/path/to/your/hurricane-tracker-mcp/dist/server.js"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "NODE_ENV": "production",
        "PRETTY_LOGS": "false",
        "LOG_LEVEL": "info"
      },
       "timeout": 30000
    }
  }
}

Important: Replace /path/to/your/hurricane-tracker-mcp with your actual project path.

After adding the configuration, restart Claude Desktop to load the Hurricane Tracker MCP Server.

Copy and paste below prompts into Cline or Claude Desktop to test hurricane tracking MCP capabilities:

Cruise Ship Safety Check:

 I'm the safety officer for a cruise line. We have ships departing from Miami next week heading to Cozumel, Mexico.
 Check:
 1. Are there any active storms in the Atlantic or Caribbean?
 2. What's the forecast cone for any storms near our route?
 3. Check for alerts at our ports: Miami, Key West, and Cozumel
 4. Show me any major storms that hit this route in the past 2 years

 Should we consider rerouting or delaying departures?

🧪 MCP Inspector

To test and troubleshoot individual tool calls with specific parameters use MCP Inspector. For comprehensive testing with MCP Inspector, see MCP_INSPECTOR_TEST_GUIDE.md.

Note: You can't use Natural language prompt in MCP Inspector. For Natural language prompt use Claude Desktop or Cline or other MCP-compatible AI assistant

Test All Hurricane Tools

Copy and paste these natural language prompts into Cline or Claude Desktop to test hurricane tracking capabilities:

Quick Test - All Capabilities:

I'm planning a trip to the Caribbean and Gulf Coast region. Can you give me a complete hurricane safety briefing?

First, show me ALL currently active tropical storms and hurricanes globally - I want to see their names, categories, wind speeds, and current locations.

Next, check these specific cities for any hurricane warnings, watches, or tropical storm alerts:
- Miami, Florida (coordinates: 25.76, -80.19)
- New Orleans, Louisiana (29.95, -90.07)  
- Houston, Texas (29.76, -95.37)
- Cancun, Mexico (21.16, -86.85)

For any active storms you find, please show me:
- Their 5-day forecast cone and predicted path
- Where they've traveled so far (historical track)
- Which coastal areas might be impacted

Also, I'm curious about hurricane patterns - can you search for all major hurricanes (Category 3+) that passed through the Gulf of Mexico area between January 1, 2020 and December 31, 2024? The Gulf area roughly covers coordinates from -98 to -82 longitude and 18 to 31 latitude.

Finally, if there are NO active storms right now, that's useful to know too - just let me know the Atlantic is quiet.

Format the response in a clear, organized way that I can easily understand for travel planning.

Real-World Use Cases:

Emergency Preparedness Check:

My family lives along the US East Coast from Florida to North Carolina. Are there any active hurricanes or tropical storms that could affect this region in the next week? 

Check for:
- Any storms currently in the Atlantic Ocean
- Active weather alerts for major cities like Miami, Jacksonville, Charleston, and Wilmington
- If storms exist, show their predicted paths

This is for emergency preparedness planning, so please be thorough.

Emergency Evacuation Planning:

I'm the emergency manager for Monroe County, Florida. We need to decide on evacuations:
1. Show all active storms in the Gulf of Mexico
2. For any Gulf storms or Atlantic Hurricanes or Caribbean Storms what's their 5-day forecast cone?
3. Check hurricane alerts for Monroe County, Florida
4. When was the last major hurricane to hit our area? Search the past 10 years.

Give me a GO/NO-GO recommendation for mandatory evacuations.

Insurance Risk Assessment:

I work for an insurance company and need hurricane risk data for property assessments.

Please provide:
1. All currently active storms globally with their intensities
2. Specific alerts for these high-risk areas:
   - Southern Florida (Miami-Dade County area)
   - Louisiana Gulf Coast (New Orleans region)
   - Texas Coast (Houston/Galveston area)
3. Historical data: Find all hurricanes that made landfall in the Gulf states between 2020-2024

Include storm names, peak categories, and affected areas. This helps us assess regional risk patterns.

Marine Navigation Planning:

I'm sailing from Puerto Rico to Florida next week. What's the current hurricane situation?
I need to know:
- Are there any active tropical systems in the Atlantic or Caribbean?
- What's the forecast track for any storms between Puerto Rico (18.22, -66.59) and Florida Keys (24.55, -81.78)?
- Have there been any recent storms in this corridor in the past month?

Safety is my top priority, so please check thoroughly.

Scientific Research Query:

I'm studying climate patterns and hurricane intensification. Can you help me gather data?

Please find:
1. All active tropical cyclones worldwide - separate them by ocean basin (Atlantic, Pacific, Indian)
2. For the Atlantic basin specifically, show storms in order of intensity
3. Search for historical hurricane tracks in the Caribbean Sea region (bounded by 10-25°N, 60-90°W) from 2020 to present
4. If any current storms exist with "Rapid Intensification" noted, highlight those

Present the data in a structured format suitable for research analysis.

Travel Planning Assistant:

I'm booking a vacation to Cancun for next month. Should I be worried about hurricanes?

Can you:
- Check if there are any active storms that might head toward the Yucatan Peninsula
- Look for current weather alerts for Cancun and Cozumel
- Search for historical patterns - what hurricanes hit this area in the past 5 years during the same month?
- Give me a risk assessment in plain language

I need honest advice about whether to book travel insurance.

Edge Cases & Error Testing:

Test the system's error handling with these requests:

1. Check for hurricane alerts at these unusual coordinates:
   - North Pole: latitude 90, longitude 0
   - Middle of Pacific: latitude 0, longitude -180
   - Invalid location: latitude 95, longitude 200

2. Search for historical storms with impossible dates:
   - Future dates: January 2030 to December 2035
   - Very old dates: January 1800 to December 1850

3. Request storm data for a non-existent storm ID like "XX992099"

4. Ask for the forecast cone of a storm when no storms are active

Show me how the system handles these edge cases gracefully.

Individual Test Scenarios:

Test 1 - Current Storm Activity:

What tropical storms and hurricanes are currently active around the world? I'm particularly interested in any storms in the Atlantic basin.

Test 2 - Storm Forecast Information:

Are there any active hurricanes right now? If so, I'd like to see the forecast cone showing where the storm might go over the next 5 days.

Test 3 - Storm Movement History:

Can you show me the path that any currently active hurricanes have taken so far? I want to see where they've been.

Test 4 - Location-Specific Alerts:

Please check these cities for any hurricane-related warnings or watches:
- Miami, Florida
- New Orleans, Louisiana  
- Houston, Texas
Also test what happens with invalid coordinates like latitude 95, longitude 200.

Test 5 - Historical Hurricane Data:

I'm researching hurricanes in the Gulf of Mexico. Can you find all storms that passed through the Gulf between January 2020 and December 2024? Focus on Atlantic basin storms.

Expected Real Data Behavior:

All tools now use true real data patterns:

• ✅ Active Storms: Calls real NOAA NHC API → returns parsed live data or empty array if API unavailable
• ✅ Hurricane Alerts: Calls real NWS API → returns filtered live alerts or empty array if API unavailable
• ✅ Historical Search: Parses real IBTrACS CSV data → returns parsed storms or empty array if parsing fails
• ✅ Storm Cone: Attempts real NOAA GIS API → throws error if cone data unavailable from real sources
• ✅ Storm Track: Attempts real HURDAT2 database → throws error if track data unavailable from real sources

No hardcoded fallback data - the server returns real API responses or appropriate errors, never synthetic mock data.

Expected Results:

• ✅ Real API responses from NOAA/NWS/IBTrACS when available
• ✅ Empty arrays when APIs are temporarily unavailable (no hardcoded fallbacks)
• ✅ Appropriate errors when real data sources are unavailable (storm cone/track)
• ✅ CSV parsing logs showing successful IBTrACS data extraction
• ✅ Validation errors for invalid inputs with helpful messages
• ✅ Correlation IDs and performance metadata for all API calls
• ✅ Clean error messages with recovery hints

🌀 Available Hurricane Tools

Tool	Description	Required Parameters	Optional Parameters	Example Usage
get_active_storms	Lists all active tropical cyclones globally	None	basin (AL, EP, CP, WP, NP, SP, SI)	Get Atlantic storms: {"basin": "AL"}
get_storm_cone	Forecast cone of uncertainty & 5-day track	stormId (from active storms)	None	{"stormId": "AL012025"}
get_storm_track	Historical track data for a storm	stormId (from active storms)	None	{"stormId": "AL012025"}
get_local_hurricane_alerts	Active hurricane alerts by location	lat (-90 to 90)<br>lon (-180 to 180)	None	Miami: {"lat": 25.76, "lon": -80.19}
search_historical_tracks	Historical tracks by area & date	aoi (GeoJSON Polygon)<br>start (YYYY-MM-DD)<br>end (YYYY-MM-DD)	basin (AL, EP, etc.)	Gulf search: See detailed example below

Detailed Examples

Complex GeoJSON Example for search_historical_tracks:

{
  "aoi": {
    "type": "Polygon",
    "coordinates": [[[
      [-95.0, 25.0], [-85.0, 25.0], [-85.0, 31.0], [-95.0, 31.0], [-95.0, 25.0]
    ]]]
  },
  "start": "2020-01-01",
  "end": "2024-12-31",
  "basin": "AL"
}

📚 Documentation

• CLINE_SETUP.md - Complete setup guide for Cline (VS Code extension)
• CLAUDE_DESKTOP_SETUP.md - Complete setup guide for Claude Desktop
• MCP_INSPECTOR_TEST_GUIDE.md - Comprehensive testing guide with MCP Inspector
• GITHUB_ACTIONS_SETUP.md - CI/CD pipeline setup, billing, and troubleshooting guide

🚀 CI/CD Pipeline

The project uses comprehensive GitHub Actions workflows for continuous integration and deployment. See the build status badges at the top of this README for real-time workflow status.

Workflow Features

• Automated Testing: Unit, integration, and cross-platform tests (Node.js 22.x)
• Security Scanning: Dependency audits, secret detection, SAST analysis
• Docker Support: Multi-platform builds (amd64/arm64) with vulnerability scanning
• Performance Monitoring: Startup benchmarks, memory profiling, load testing
• Release Automation: Semantic versioning, changelog generation, Docker publishing
• Documentation: Automated API docs, architecture diagrams, GitHub Pages deployment
• Dependency Management: Weekly updates with automated PRs

See GitHub Actions Setup Guide for detailed workflow documentation.

Running on Docker Container

1. Build and Run with Docker Compose

Build the Docker image and start the container

docker-compose up --build

Or run in detached mode (background)

docker-compose up --build -d

2. Verify the Service is Running

Check if container is running

docker-compose ps

View logs

docker-compose logs -f

Test the health endpoint

curl http://localhost:8080/health

3. Cline MCP Configuration for Docker

Add the following configuration to your Cline MCP settings file (cline_mcp_settings.json) and test all hurricane tools

"hurricane-tracker-docker": {
      "autoApprove": [
        "get_active_storms",
        "get_storm_cone",
        "get_storm_track",
        "get_local_hurricane_alerts",
        "search_historical_tracks"
      ],
      "disabled": false,
      "timeout": 30000,
      "type": "stdio",
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "-e",
        "MCP_TRANSPORT=stdio",
        "hurricane-tracker-mcp",
        "node",
        "dist/server.js"
      ]
    }

4. Stop the service

docker-compose down

🔧 Development Commands

# Development mode (with hot reload)
npm run dev

# Build the project
npm run build

# Run with stdio transport (for Cline)
npm run stdio

# Run with Streamable HTTP transport
npm run http

# Run tests
npm run test

# Run linting
npm run lint

📊 Expected Test Results

When testing with the prompt above, you should see:

1. Active Storms: Structured JSON with storm data, basin filtering works
2. Storm Cone: GeoJSON polygon and forecast points for any active storm (or proper error if none active)
3. Storm Track: Historical track capability confirmation for any active storm (or proper error if none active)
4. Local Alerts:
   • Hurricane warnings for Miami/New Orleans areas when storms are nearby
   • No alerts for northern locations or when no storms are active
5. Historical Search: Results filtered by geography and date range from real IBTrACS data

🏗️ Architecture

📊 Data Flow Architecture

flowchart TB
    %% External Entities
    Client[["🖥️ MCP Client<br/>(Cline/Claude Desktop)"]]
    NOAA[["🌐 NOAA/NHC APIs<br/>(External Data Sources)"]]

    %% Transport Layer
    subgraph Transport["🚀 Transport Layer (server.ts)"]
        STDIO["📡 STDIO Transport<br/>Local AI Assistants"]
        HTTP["🌐 HTTP Transport<br/>Fastify Server"]
        Session["🔑 Session Manager<br/>Multi-client Support"]
        Health["❤️ Health Monitor<br/>/health endpoint"]
    end

    %% Protocol Layer
    subgraph Protocol["⚙️ Protocol Layer (hurricane-mcp-server.ts)"]
        MCP["🎯 MCP Server<br/>JSON-RPC 2.0 Handler"]
        Tools["🛠️ Tool Registry<br/>5 Hurricane Tools"]
        Validator["✅ Schema Validator<br/>Zod Schemas"]
        ErrorHandler["⚠️ Error Handler<br/>LLM-friendly Messages"]
    end

    %% Business Layer
    subgraph Business["💼 Business Layer (hurricane-service.ts)"]
        Service["🌀 Hurricane Service<br/>Domain Logic"]
        Transform["🔄 Data Transformer<br/>NOAA → Domain Models"]
        Correlator["🔗 Correlation Tracker<br/>Request Tracing"]
    end

    %% Supporting Components
    subgraph Support["🔧 Supporting Components"]
        Cache["💾 LRU Cache<br/>(hurricane-cache.ts)"]
        Logger["📝 Pino Logger<br/>(logger-pino.ts)"]
        Audit["🔍 Audit Logger<br/>(audit-logger.ts)"]
        Security["🔒 Security Monitor<br/>(security-monitor.ts)"]
        RateLimit["⏱️ Rate Limiter<br/>(rate-limit.ts)"]
    end

    %% Data Flow
    Client -->|"MCP Request<br/>JSON-RPC 2.0"| Transport
    Transport -->|"Route by<br/>Transport Type"| STDIO
    Transport -->|"Route by<br/>Transport Type"| HTTP

    STDIO -->|"Connect & Forward"| MCP
    HTTP -->|"Session-based<br/>Connection"| Session
    Session -->|"Forward Request"| MCP

    MCP -->|"Tool Dispatch"| Tools
    Tools -->|"Validate Input"| Validator
    Validator -->|"Execute Tool"| Service

    Service -->|"Fetch Data"| NOAA
    Service <-->|"Cache Check/<br/>Store"| Cache
    Service -->|"Log Operations"| Logger
    Service -->|"Track Security"| Security
    Service -->|"Audit Trail"| Audit

    NOAA -->|"Raw Data"| Transform
    Transform -->|"Domain Objects"| Service

    Service -->|"Business Response"| MCP
    MCP -->|"Format Response"| ErrorHandler
    ErrorHandler -->|"MCP Response"| Transport
    Transport -->|"JSON-RPC Response"| Client

    Health -->|"Status Check"| Transport
    RateLimit -->|"Throttle Requests"| Protocol
    Correlator -->|"Track Request"| Service

    %% Styling
    classDef transportStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef protocolStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef businessStyle fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    classDef supportStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef externalStyle fill:#fce4ec,stroke:#880e4f,stroke-width:2px

    class Transport transportStyle
    class Protocol protocolStyle
    class Business businessStyle
    class Support supportStyle
    class Client,NOAA externalStyle

🔄 Component Interaction Diagram

graph TB
    subgraph "🎯 Core Architecture Components"
        subgraph "Transport Infrastructure"
            TS[server.ts<br/>Transport Layer]
            STDT[StdioServerTransport]
            HTTPT[StreamableHTTPServerTransport]
            FAST[Fastify HTTP Server]
        end

        subgraph "Protocol Implementation"
            MCP[hurricane-mcp-server.ts<br/>MCP Protocol Handler]
            MCPS[McpServer Instance]
            TR[Tool Registry]
            VS[Validation Schemas]
        end

        subgraph "Business Logic"
            HS[hurricane-service.ts<br/>Hurricane Service]
            DM[Domain Models]
            AT[API Transformers]
        end

        subgraph "Cross-Cutting Concerns"
            subgraph "Caching"
                HC[hurricane-cache.ts]
                LRU[LRU Cache Manager]
            end

            subgraph "Logging"
                PL[logger-pino.ts]
                AL[audit-logger.ts]
            end

            subgraph "Security"
                SM[security-monitor.ts]
                SAN[sanitizer.ts]
            end

            subgraph "Middleware"
                AUTH[auth.ts]
                RL[rate-limit.ts]
                VAL[validation.ts]
                SANM[sanitization.ts]
            end

            subgraph "Resilience"
                CB[circuit-breaker.ts]
                RS[retry-strategy.ts]
                BH[bulkhead.ts]
            end

            subgraph "Configuration"
                CFG[config.ts]
                ACFG[auth-config.ts]
            end
        end
    end

    %% Interactions
    TS -->|initializes| STDT
    TS -->|initializes| HTTPT
    TS -->|creates| FAST

    STDT -->|connects to| MCPS
    HTTPT -->|connects to| MCPS

    MCP -->|creates| MCPS
    MCP -->|registers tools| TR
    MCP -->|defines| VS

    TR -->|delegates to| HS

    HS -->|uses| DM
    HS -->|applies| AT
    HS -->|caches with| HC
    HS -->|logs with| PL

    HC -->|manages| LRU

    MCP -->|audit logs| AL
    MCP -->|security checks| SM

    FAST -->|applies| AUTH
    FAST -->|applies| RL

    HS -->|validates with| VAL
    HS -->|sanitizes with| SANM

    HS -->|resilience via| CB
    HS -->|resilience via| RS

    ALL[All Components] -.->|read config| CFG
    AUTH -.->|uses| ACFG

    %% Styling
    style TS fill:#e3f2fd,stroke:#1565c0
    style MCP fill:#f3e5f5,stroke:#6a1b9a
    style HS fill:#e8f5e9,stroke:#2e7d32
    style HC fill:#fff3e0,stroke:#ef6c00
    style PL fill:#fce4ec,stroke:#c2185b
    style SM fill:#ffebee,stroke:#d32f2f

📋 Sequence Diagram - STDIO Transport

sequenceDiagram
    participant C as MCP Client<br/>(Cline/Claude)
    participant S as server.ts<br/>(Transport)
    participant ST as StdioServerTransport
    participant M as hurricane-mcp-server.ts<br/>(Protocol)
    participant MS as McpServer
    participant HS as hurricane-service.ts<br/>(Business)
    participant API as NOAA/NHC APIs
    participant Cache as LRU Cache
    participant Log as Pino Logger

    Note over C,API: STDIO Transport Flow - Direct Process Communication

    %% Initialization
    C->>+S: Launch Process (node dist/server.js)
    S->>S: Load Config (MCP_TRANSPORT=stdio)
    S->>+ST: new StdioServerTransport()
    S->>+M: hurricaneMcpServer.getMcpServer()
    M->>+MS: new McpServer({name, version})
    M->>MS: Register 5 Hurricane Tools
    M-->>-S: Return MCP Server Instance
    S->>ST: mcpServer.connect(transport)
    ST-->>C: Ready (via stdio)

    %% Tool Invocation
    C->>ST: JSON-RPC Request<br/>{"method": "tools/call",<br/>"params": {"name": "get_active_storms"}}
    ST->>MS: Handle Request
    MS->>M: Dispatch Tool Call
    M->>M: Validate with Zod Schema

    alt Validation Success
        M->>+HS: getActiveStorms(args)
        HS->>Log: Log Operation Start
        HS->>+Cache: Check Cache

        alt Cache Hit
            Cache-->>HS: Return Cached Data
        else Cache Miss
            HS->>+API: GET /CurrentStorms.json
            API-->>-HS: Storm Data (JSON)
            HS->>HS: Transform to Domain Model
            HS->>Cache: Store in Cache
        end

        Cache-->>-HS: Storm Data
        HS->>Log: Log Operation Complete
        HS-->>-M: HurricaneBasicInfo[]
        M->>M: Format for MCP Response
        M-->>MS: Tool Response
        MS-->>ST: JSON-RPC Response
        ST-->>C: {"result": {...}}
    else Validation Failed
        M->>M: Create LLM-friendly Error
        M-->>MS: Error Response
        MS-->>ST: JSON-RPC Error
        ST-->>C: {"error": {...}}
    end

    %% Shutdown
    C->>ST: SIGTERM/SIGINT
    ST->>S: Graceful Shutdown
    S->>M: hurricaneMcpServer.shutdown()
    S->>ST: Close Transport
    S->>Log: Log Shutdown
    S-->>C: Process Exit

    Note over C,API: Clean separation: Transport → Protocol → Business

📋 Sequence Diagram - Streamable HTTP Transport

sequenceDiagram
    participant C as MCP Client<br/>(Browser/Remote)
    participant F as Fastify Server<br/>(HTTP Endpoints)
    participant S as server.ts<br/>(Transport)
    participant HT as StreamableHTTPServerTransport
    participant SM as Session Manager
    participant M as hurricane-mcp-server.ts<br/>(Protocol)
    participant MS as McpServer
    participant HS as hurricane-service.ts<br/>(Business)
    participant API as NOAA/NHC APIs
    participant Cache as LRU Cache
    participant RL as Rate Limiter
    participant Audit as Audit Logger

    Note over C,API: HTTP Transport Flow - Session-based Communication

    %% Server Initialization
    F->>+S: Start HTTP Server (port 8080)
    S->>S: Load Config (MCP_TRANSPORT=http)
    S->>F: Register CORS Plugin
    S->>F: Setup Routes (/mcp POST/GET/DELETE, /health)
    S->>SM: Initialize Session Store
    F-->>S: Server Listening

    %% Client Initialization
    C->>+F: POST /mcp<br/>(No session ID)
    F->>S: Handle Initial Request
    S->>+HT: new StreamableHTTPServerTransport()
    HT->>HT: Generate Session ID (UUID)
    HT->>SM: Store Session
    S->>+M: hurricaneMcpServer.getMcpServer()
    M->>+MS: Get/Create MCP Server
    M-->>-S: MCP Server Instance
    S->>HT: mcpServer.connect(transport)
    HT-->>F: Session ID in Header
    F-->>-C: Response + Mcp-Session-Id Header

    %% Authenticated Tool Call
    C->>+F: POST /mcp<br/>Header: mcp-session-id: xyz<br/>Body: {"method": "tools/call",<br/>"params": {"name": "get_storm_cone",<br/>"arguments": {"stormId": "AL052024"}}}
    F->>RL: Check Rate Limit

    alt Rate Limit OK
        RL-->>F: Proceed
        F->>SM: Validate Session
        SM-->>F: Session Valid
        F->>HT: handleRequest(request, response, body)
        HT->>MS: Process JSON-RPC
        MS->>M: Dispatch Tool
        M->>M: Validate Input (Zod)
        M->>Audit: Log Tool Invocation

        M->>+HS: getStormCone({stormId: "AL052024"})
        HS->>+Cache: Check Cache Key

        alt Cache Miss
            HS->>+API: GET /storm/AL052024/cone
            API-->>-HS: Cone Data (GeoJSON)
            HS->>HS: Transform & Validate
            HS->>Cache: Store with TTL
        end

        Cache-->>-HS: Cone Data
        HS-->>-M: StormCone Object
        M->>M: Format MCP Response
        M->>Audit: Log Success
        M-->>MS: Tool Result
        MS-->>HT: JSON-RPC Response
        HT-->>F: Formatted Response
        F-->>-C: {"jsonrpc": "2.0", "result": {...}}
    else Rate Limit Exceeded
        RL-->>F: Reject (429)
        F-->>C: {"error": "Rate limit exceeded"}
    end

    %% Server-Sent Events (SSE)
    C->>+F: GET /mcp<br/>Header: mcp-session-id: xyz
    F->>SM: Get Session Transport
    SM-->>F: Transport Instance
    F->>HT: Setup SSE Stream
    HT-->>F: Event Stream
    F-->>C: SSE Connection Established

    Note over C,F: Keep-alive for notifications

    loop Server Notifications
        MS->>HT: Notification Event
        HT->>F: SSE Message
        F-->>C: data: {"notification": ...}
    end

    %% Session Termination
    C->>+F: DELETE /mcp<br/>Header: mcp-session-id: xyz
    F->>SM: Get Session
    F->>HT: handleRequest(DELETE)
    HT->>MS: Close Connection
    HT->>SM: Remove Session
    SM-->>F: Session Cleared
    F-->>-C: 204 No Content

    %% Health Check
    C->>+F: GET /health
    F->>S: Get Server Status
    S-->>F: {status: "healthy", uptime: 12345, sessions: 3}
    F-->>-C: Health Status JSON

    Note over C,API: Session-based, Rate-limited, Audited

The Hurricane Tracker MCP Server implements exemplary SOLID principles with perfect separation of concerns across 3 distinct layers:

Perfect 3-Layer Architecture (Gold Standard Implementation)

• server.ts: ONLY handles transport and infrastructure
• hurricane-mcp-server.ts: ONLY handles MCP protocol compliance
• hurricane-service.ts: ONLY handles hurricane business logic

Client (Cline) or AI Agent
    ↓ (MCP Protocol Messages)
server.ts (Transport Layer)
    ↓ (Clean Delegation)
hurricane-mcp-server.ts (Protocol Layer)
    ↓ (Plain Business Requests)
hurricane-service.ts (Business Layer)
    ↓ (HTTP Requests)
External APIs (NHC, NWS, IBTrACS)

Core Components - SOLID Implementation

🔧 server.ts - Transport Layer & Infrastructure Management

Role: Pure Infrastructure & Transport Orchestration

• Fastify-Powered HTTP Transport: High-performance with session management
• Dual Transport Support: stdio (4ms startup) + Streamable HTTP (58ms startup)
• Perfect Delegation: Zero protocol concerns - pure infrastructure focus
• Health Monitoring: /health endpoint showing 3-layer architecture status
• Graceful Shutdown: Proper resource cleanup and connection termination

🌐 hurricane-mcp-server.ts - Protocol Layer & MCP Compliance Engine

Role: Pure MCP Protocol Implementation & Tool Orchestration

• Complete MCP v2025-06-18 Compliance: Full JSON-RPC 2.0 specification
• JSON Schema Tool Registration: Corrected from Zod objects (architectural fix)
• All 5 Hurricane Tools: get_active_storms, get_storm_cone, get_storm_track, get_local_hurricane_alerts, search_historical_tracks
• Clean Business Delegation: Calls business layer, formats responses for MCP compliance
• Protocol-Level Validation: Input validation with LLM-friendly error messages
• Zero Business Logic: Pure protocol concerns only

🌀 hurricane-service.ts - Business Layer & Domain Logic Engine

Role: Pure Hurricane Domain Logic & API Integration

• Protocol-Free Implementation: ZERO MCP types in business layer
• Plain Domain Objects: All methods return clean business data structures
• Pure Business Focus: Hurricane tracking logic without transport/protocol contamination
• Comprehensive Error Handling: Domain-specific exceptions (NotFoundError, ValidationError)
• API Integration Ready: Structured for real NOAA/NHC API integration
• Performance Monitoring: Correlation ID tracking for all operations

🤝 Contributing

This project follows enterprise development standards:

• Strict TypeScript typing
• Comprehensive error handling
• Production-grade logging

📄 License

MIT License - see LICENSE file for details.

Server Status: Fully operational and ready for hurricane season! 🌀