Hurricane Tracker MCP Server
by kumaran-is
README.md
# 🌀 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.
[](https://deepwiki.com/kumaran-is/hurricane-tracker-mcp)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://fastify.dev/)
[](https://modelcontextprotocol.io/)
[](https://zod.dev/)
[](https://en.wikipedia.org/wiki/SOLID)
[](https://opensource.org/licenses/MIT)
[](https://github.com/kumaran-is/hurricane-tracker-mcp/actions/workflows/ci.yml)
[](https://github.com/kumaran-is/hurricane-tracker-mcp/actions/workflows/integration-tests.yml)
[](https://github.com/kumaran-is/hurricane-tracker-mcp/actions/workflows/security.yml)
[](https://github.com/kumaran-is/hurricane-tracker-mcp/actions/workflows/docker.yml)
[](https://github.com/kumaran-is/hurricane-tracker-mcp/actions/workflows/performance.yml)
[](https://github.com/kumaran-is/hurricane-tracker-mcp/actions/workflows/release.yml)
## 📑 Table of Contents
- [🌀 Hurricane Tracker MCP Server](#-hurricane-tracker-mcp-server)
- [📑 Table of Contents](#-table-of-contents)
- [🌟 Features](#-features)
- [Hurricane Tracking Capabilities](#hurricane-tracking-capabilities)
- [Technical Excellence](#technical-excellence)
- [🛠️ Technology Stack](#️-technology-stack)
- [Quick Start](#quick-start)
- [Prerequisites](#prerequisites)
- [Installation \& Setup](#installation--setup)
- [Option 1. Cline AI Assistant](#option-1-cline-ai-assistant)
- [Option 2. Claude Desktop](#option-2-claude-desktop)
- [🧪 MCP Inspector](#-mcp-inspector)
- [Test All Hurricane Tools](#test-all-hurricane-tools)
- [**Quick Test - All Capabilities:**](#quick-test---all-capabilities)
- [**Real-World Use Cases:**](#real-world-use-cases)
- [**Individual Test Scenarios:**](#individual-test-scenarios)
- [**Expected Real Data Behavior:**](#expected-real-data-behavior)
- [**Expected Results:**](#expected-results)
- [🌀 Available Hurricane Tools](#-available-hurricane-tools)
- [Detailed Examples](#detailed-examples)
- [📚 Documentation](#-documentation)
- [🚀 CI/CD Pipeline](#-cicd-pipeline)
- [Workflow Features](#workflow-features)
- [Running on Docker Container](#running-on-docker-container)
- [1. Build and Run with Docker Compose](#1-build-and-run-with-docker-compose)
- [2. Verify the Service is Running](#2-verify-the-service-is-running)
- [3. Cline MCP Configuration for Docker](#3-cline-mcp-configuration-for-docker)
- [4. Stop the service](#4-stop-the-service)
- [🔧 Development Commands](#-development-commands)
- [📊 Expected Test Results](#-expected-test-results)
- [🏗️ Architecture](#️-architecture)
- [📊 Data Flow Architecture](#-data-flow-architecture)
- [🔄 Component Interaction Diagram](#-component-interaction-diagram)
- [📋 Sequence Diagram - STDIO Transport](#-sequence-diagram---stdio-transport)
- [📋 Sequence Diagram - Streamable HTTP Transport](#-sequence-diagram---streamable-http-transport)
- [**Perfect 3-Layer Architecture (Gold Standard Implementation)**](#perfect-3-layer-architecture-gold-standard-implementation)
- [**Core Components - SOLID Implementation**](#core-components---solid-implementation)
- [**🔧 server.ts** - Transport Layer \& Infrastructure Management](#-serverts---transport-layer--infrastructure-management)
- [**🌐 hurricane-mcp-server.ts** - Protocol Layer \& MCP Compliance Engine](#-hurricane-mcp-serverts---protocol-layer--mcp-compliance-engine)
- [**🌀 hurricane-service.ts** - Business Layer \& Domain Logic Engine](#-hurricane-servicets---business-layer--domain-logic-engine)
- [🤝 Contributing](#-contributing)
- [📄 License](#-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**](https://nodejs.org/) | `>=22.0.0` | JavaScript runtime environment |
| [**TypeScript**](https://github.com/microsoft/TypeScript) | `~5.9.0` | Type-safe JavaScript development |
| [**@modelcontextprotocol/sdk**](https://github.com/modelcontextprotocol/typescript-sdk) | `~1.17.5` | **Latest MCP SDK** with modern patterns |
| [**Zod**](https://zod.dev/) | `~3.23.8` | **Runtime schema validation** and TypeScript inference |
| [**Fastify**](https://fastify.dev/) | `~5.6.0` | High-performance web framework (transport layer) |
| [**Pino**](https://github.com/pinojs/pino) | `~9.9.0` | Production structured logging |
| [**Vitest**](https://github.com/vitest-dev/vitest)| `~3.2.0` | Next-generation testing framework |
| [**undici**](https://github.com/nodejs/undici) | `~7.16.0` | High-performance HTTP client with resilience |
| [**NOAA/NHC APIs**](https://www.nhc.noaa.gov/) | N/A | Real-time hurricane data from National Hurricane Center |
| [**NWS API**](https://www.weather.gov/documentation/services-web-api) | N/A | Weather alerts and warnings |
| [**IBTrACS**](https://www.ncei.noaa.gov/products/international-best-track-archive) | 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
```bash
# 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](docs/CLINE_SETUP.md)**
Add the following configuration to your Cline MCP settings file (`cline_mcp_settings.json`):
```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](docs/CLAUDE_DESKTOP_SETUP.md)**
Add the following configuration to your Claude Desktop MCP settings file (`claude_desktop_config.json`):
```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:**
```bash
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](docs/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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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`:**
```json
{
"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](docs/CLINE_SETUP.md)** - Complete setup guide for Cline (VS Code extension)
- **[CLAUDE_DESKTOP_SETUP.md](docs/CLAUDE_DESKTOP_SETUP.md)** - Complete setup guide for Claude Desktop
- **[MCP_INSPECTOR_TEST_GUIDE.md](docs/MCP_INSPECTOR_TEST_GUIDE.md)** - Comprehensive testing guide with MCP Inspector
- **[GITHUB_ACTIONS_SETUP.md](docs/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](docs/GITHUB_ACTIONS_SETUP.md) for detailed workflow documentation.
## Running on Docker Container
#### 1. Build and Run with Docker Compose
Build the Docker image and start the container
```bash
docker-compose up --build
```
Or run in detached mode (background)
```bash
docker-compose up --build -d
```
#### 2. Verify the Service is Running
Check if container is running
```bash
docker-compose ps
```
View logs
```bash
docker-compose logs -f
```
Test the health endpoint
```bash
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
```json
"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
```bash
docker-compose down
```
## 🔧 Development Commands
```bash
# 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
```mermaid
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
```mermaid
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
```mermaid
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
```mermaid
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! 🌀
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues