mcp-atmospheric-data-gateway

Atmospheric Data Provisioning Service (MCP Implementation)

This implementation serves as a Model Context Protocol (MCP) conduit, engineered to interface with the QWeather (和风天气) platform. It exposes methods for querying real-time climate conditions and future weather simulations.

Key Capabilities

• Present Condition Retrieval: Obtain the most recent environmental metrics for any specified location.
• Prognostic Modeling: Access weather projections spanning from 3 days up to a 30-day horizon.
• Near-Term Hourly Simulation: Retrieve granular weather predictions for the subsequent 24 hours.
• Geographical Indexing: Perform lookups to resolve city identifiers crucial for precise data targeting.
• User Preference Mapping: Allow tailoring of output parameters, including thermometric scale selection and response language.
• QWeather Integration: Reliable data sourcing exclusively from the 和风天气 platform.

Deployment Instructions

Installation via npm package manager:

npm install mcp-weather-api

Alternatively, direct execution is feasible:

npx mcp-weather-api

Application Interface Specification

The gateway exposes four distinct operational tools callable within the MCP framework:

1. Fetching Current State (getWeather)

// Tool Identifier: getWeather
{
  location: "San Francisco, CA",  // City name, geographical pair (e.g., "-122.41,37.77"), or QWeather ID
  options: {
    units: "imperial",        // System: "metric" (Celsius) or "imperial" (Fahrenheit)
    language: "es",           // Locale designator (e.g., en, zh, es)
  }
}

2. Retrieving Forecast Trajectory (getWeatherForecast)

// Tool Identifier: getWeatherForecast
{
  location: "Paris, FR",
  options: {
    units: "metric",
    days: 7,                  // Scope: 3, 7, 10, 15, or 30 days
    language: "fr"
  }
}

3. Obtaining Hourly Evolution (getHourlyWeather)

// Tool Identifier: getHourlyWeather
{
  location: "Sydney, AU",
  options: {
    units: "imperial",
    hours: 24,                // Temporal scope (fixed maximum of 24)
    language: "en"
  }
}

4. Location Code Resolution (lookupCity)

// Tool Identifier: lookupCity
{
  location: "Shanghai",
  options: {
    language: "zh"          // Output language for location metadata
  }
}

Parameter Definitions

General Climate Options: Applicable to observation and prediction tools.

interface WeatherOptions {
  units?: "metric" | "imperial"; // Scale selection (default: metric)
  language?: string; // Desired output locale
}

Projection Parameters: Specific to forecast tools.

interface ForecastOptions {
  units?: "metric" | "imperial";
  days?: number; // Forecast duration (default: 3)
  language?: string;
}

Diurnal Slice Parameters: Specific to the hourly tool.

interface HourlyForecastOptions {
  units?: "metric" | "imperial";
  hours?: number; // Count of hours to project (default/max: 24)
  language?: string;
}

Geospatial Resolution Parameters:

interface CityLookupOptions {
  language?: string; // Locale for result descriptions
}

Output Structure

All tool invocation results adhere to this uniform structural contract:

{
  content: Array<{
    type: "text";
    text: string;
  }>;
}

Example Outputs (Condensed)

Instantaneous Data Report

Climate Report for New York:

Timestamp: 2023-11-15T12:30:00+08:00
State: Partially Overcast (Code: 101)
Temperature: 18.5°C
Perceived Temp: 19.2°C
Wind Vector:
- Orientation: Northeast (45°)
- Beaufort Scale Equivalent: 3
- Velocity: 15 km/h
Atmospheric Metrics:
- Relative Moisture: 65%
- Precipitation Volume: 0.0 mm
- Barometric Pressure: 1013 hPa
- Horizon Clarity: 25 km
- Cloud Coverage: 30%
- Dew Point: 12.1°C

Data Origin: QWeather

Future Weather Projection

Forecast Series for London:

Date: 2023-11-15
Celestial Events:
- Solar Rise: 07:12, Solar Set: 16:30

Daytime Metrics:
- Condition: Rain Showers (Icon: 305)
- Thermal Span: 12.0°F (Max) / 7.0°F (Min)
- Air Flow: Northwest (315°), Speed: 18 km/h

Nighttime Metrics:
- Condition: Overcast (Icon: 101)
- Air Flow: North (0°), Speed: 10 km/h

... subsequent daily entries ...

Data Origin: QWeather

MCP Integration

To enable this module within your MCP environment, update the configuration:

{
  "mcpServers": {
    "weather_service": {
      "command": "npx",
      "args": ["-y", "mcp-weather-api"]
    }
  }
}

QWeather Underlying Infrastructure

This service relies upon authenticated access to the QWeather (和风天气) service endpoints. Production deployment mandates the configuration of a private API key.

Core API Interfaces Invoked

1. Current Status: /weather/now
2. Multi-Day Simulation: /weather/3d, /weather/7d, etc.
3. Hourly Dynamics: /weather/24h
4. Geospatial Resolution: /city/lookup

Configuration Variables

Operational parameters can be customized via environment variables:

export QWEATHER_API_KEY=YOUR_SECRET_KEY
export WEATHER_DEFAULT_UNITS=imperial     # Overrides default scale
export WEATHER_FORECAST_DAYS=10          # Sets default projection length

Or directly embedded in the MCP configuration block, utilizing the env mapping.

Geographical Input Modalities

Location specification accepts three distinct input formats:

1. Designated Place Name: E.g., "Berlin".
2. Geodetic Pair: Specified as longitude,latitude (e.g., "13.40,52.52").
3. Platform Identifier: The unique numerical ID assigned by QWeather (e.g., "101010100").

Utilize the lookupCity tool to ascertain the optimal, unambiguous numerical identifier for any specific locale.