Weather MCP Ts

🚀 Weather MCP Server

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

✨ Features

• 🌤️ Retrieve current weather information
• 📅 Obtain multi - day weather forecasts
• ⚠️ Benefit from a weather alert system
• 🔍 Use the location search functionality
• 📊 Access weather statistics
• 🎭 Enjoy mock data support

📦 Installation

Install Dependencies

pnpm install

💻 Usage Examples

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

📚 Documentation

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 Details

• 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

📄 License

MIT License