Weather MCP Server

A weather MCP (Model Context Protocol) server developed with TypeScript, providing simulated weather data and related functionality.

Features

• 🌤️ Get current weather information
• 📅 Multi-day weather forecast
• ⚠️ Weather alert system
• 🔍 Location search functionality
• 📊 Weather statistics
• 🎭 Mock data support

Install Dependencies

pnpm install

🚀 Usage

Installation and Build

# Install dependencies
pnpm install

# Build project
pnpm run build

Startup Methods

1. MCP Protocol (stdio)

# For MCP client integration
pnpm start

2. HTTP API Server 🆕

# Start HTTP server (default port 8080)
pnpm run start:http

# Start HTTP server (specified port 3001)
pnpm run start:http:3001

# Or specify port directly
node dist/http-server.js 8080

3. Simple HTTP Server (Recommended) 🚀

# Start with default port 8080
pnpm run start:simple

# Start with specific ports
pnpm run start:simple:3000  # Development port
pnpm run start:simple:5000  # Alternative port
pnpm run start:simple:9000  # High port

# Or use the serve commands
pnpm run serve              # Default port 8080
pnpm run serve:dev          # Development port 3000
pnpm run serve:prod         # Production port 8080

# Or specify any port directly
node dist/simple-http-server.js 4000

Dynamic Port Support

The simple HTTP server supports dynamic port configuration:

# Use any port you want
node dist/simple-http-server.js 3000
node dist/simple-http-server.js 5000
node dist/simple-http-server.js 9000
node dist/simple-http-server.js 12345

The server will automatically:

• Use port 8080 as default if no port is specified
• Accept any valid port number as a command line argument
• Display the actual port in the startup message and documentation

HTTP API Usage Examples

Once the HTTP server is started, you can use it in the following ways:

Browser Access

• Open http://localhost:8080 to view API documentation
• Click links directly to test various APIs

curl Commands

# Get current weather for Hong Kong
curl "http://localhost:8080/weather?location=Hong Kong"

# Get 5-day weather forecast for Tokyo
curl "http://localhost:8080/forecast?location=Tokyo&days=5"

# Get weather alerts
curl "http://localhost:8080/alerts?location=Hong Kong"

# Search locations
curl "http://localhost:8080/locations?q=kong"

# Get statistics
curl "http://localhost:8080/stats"

JavaScript/Fetch

// Get weather data
const response = await fetch('http://localhost:8080/weather?location=Tokyo');
const weather = await response.json();
console.log(weather);

Development Mode

# Watch mode compilation
pnpm run dev

Available Tools

1. get_current_weather

Get current weather information for a specified location

Parameters:

• location (string): Location name

Example:

{
  "location": "Hong Kong"
}

2. get_weather_forecast

Get weather forecast for a specified location

Parameters:

• location (string): Location name
• days (number, optional): Forecast days (1-7 days, default 3 days)

Example:

{
  "location": "Tokyo",
  "days": 5
}

3. get_weather_alerts

Get weather alert information

Parameters:

• location (string, optional): Location name

Example:

{
  "location": "Hong Kong"
}

4. search_locations

Search supported locations

Parameters:

• query (string): Search keyword

Example:

{
  "query": "kong"
}

5. get_weather_stats

Get weather statistics

Parameters: None

Supported Locations

Currently supports detailed weather data for the following locations:

• Hong Kong
• Tokyo, Osaka, Kyoto, Hiroshima, Sapporo, Fukuoka (Japan)
• London (UK)
• New York (USA)
• Sydney (Australia)

Other locations will return randomly generated mock data.

Technical Specifications

• Language: TypeScript
• Package Manager: pnpm
• MCP SDK: @modelcontextprotocol/sdk
• Node.js: >=18

Project Structure

src/
├── index.ts              # MCP server main file (stdio)
├── http-server.ts        # HTTP API server
├── simple-http-server.ts # Simple HTTP server
├── weather-service.ts    # Weather service logic
├── mock-data.ts          # Mock data
└── types.ts              # TypeScript type definitions

HTTP API Endpoints

Endpoint	Method	Parameters	Description
/	GET	-	API documentation page
/mcp	POST	JSON-RPC 2.0	MCP protocol endpoint
/weather	GET	location (required)	Get current weather
/forecast	GET	location (required), days (optional)	Get weather forecast
/alerts	GET	location (optional)	Get weather alerts
/locations	GET	q (required)	Search locations
/stats	GET	-	Get statistics

License

MIT License