MCP-Weather-Server

Weather Information Service

This project provides a service to fetch weather information, including alerts and forecasts, from the National Weather Service (NWS) API.

Project Structure

• main.py: A simple entry point for the project. (Currently, it only prints a hello message).
• weather.py: This is the core of the project. It implements the WeatherService which uses the FastMCP framework to expose tools for fetching weather data. It includes structured JSON logging and communicates with the NWS API.
• smithery.yaml: This is a configuration file for Smithery, a tool used to define how to run and interact with the WeatherService.
• Dockerfile: Suggests that the project can be containerized using Docker.
• pyproject.toml: Defines project metadata and dependencies for Python projects.
• .gitignore: Specifies intentionally untracked files that Git should ignore.
• .python-version: Specifies the Python version for the project (likely for use with tools like pyenv).
• uv.lock: A lock file generated by the uv Python package installer and resolver, ensuring reproducible builds.

(Further sections on WeatherService tools, running the project, and logging will be added in subsequent steps).

WeatherService Tools

The weather.py script provides a WeatherService with the following tools:

get_alerts(state: str) -> str

• Purpose: Fetches active weather alerts for a given US state.
• Arguments:
  • state (str): A two-letter US state code (e.g., CA, NY).
• Output: A string containing formatted weather alerts, or a message if no alerts are found or an error occurs.
  • Example (successful alert fetch):

    Event: Special Weather Statement
    Area: San Francisco Bay Shoreline
    Severity: Minor
    Description: ...
    Instructions: ...
    ---
    Event: Coastal Flood Advisory
    Area: North Bay Interior Valleys
    Severity: Moderate
    Description: ...
    Instructions: ...
    

  • Example (no alerts):

    No active alerts for this state.
    

  • Example (error):

    Unable to fetch alerts or no alerts found.
    

get_forecast(latitude: float, longitude: float) -> str

• Purpose: Fetches the weather forecast for a specific geographical location.
• Arguments:
  • latitude (float): The latitude of the location.
  • longitude (float): The longitude of the location.
• Output: A string containing the formatted weather forecast for the next 5 periods, or a message if the forecast cannot be fetched.
  • Example (successful forecast fetch):

    Tonight:
    Temperature: 55°F
    Wind: 5 to 10 mph W
    Forecast: Mostly clear, with a low around 55. West wind 5 to 10 mph.
    ---
    Wednesday:
    Temperature: 70°F
    Wind: 5 to 15 mph W
    Forecast: Sunny, with a high near 70. West wind 5 to 15 mph, with gusts as high as 20 mph.
    ... (up to 5 periods)
    

  • Example (error):

    Unable to fetch forecast data for this location.
    

Running the Project

The project is designed to be run as a service, likely using the FastMCP framework and the provided smithery.yaml configuration.

1. Prerequisites:

   • Python 3.x
   • The httpx library (and other dependencies as defined in pyproject.toml). You can typically install these using pip:

     pip install httpx
     # Or, if using a full project setup with pyproject.toml
     pip install .
     

2. Running the Service: The weather.py script can be executed directly to start the service. Given the smithery.yaml file, the intended way to run this is likely:

   python weather.py
   

   This will start the FastMCP server, which will listen for requests (e.g., via stdio as configured in smithery.yaml).

   If you have Smithery installed, you might also be able to run it using Smithery commands, but running weather.py directly should work for local development and testing.

   The main.py script is a simple entry point and does not run the main weather service.

Logging

The WeatherService in weather.py uses structured JSON logging. This is particularly useful for production environments where logs might be ingested by log management systems.

Key features of the logging implementation:

• JSON Format (Production): When the ENV environment variable is set to production, logs are output in JSON format. Each log entry includes:
  • timestamp
  • level (e.g., INFO, ERROR)
  • logger (logger name, e.g., WeatherService)
  • message
  • correlation_id (tracks a logical operation or flow)
  • request_id (tracks individual requests)
  • user_id
  • file and lineno (source of the log)
  • function (function name where the log occurred)
  • process and thread
  • environment (from ENV variable)
  • app_version (from APP_VERSION variable)
  • host (from HOSTNAME variable)
  • duration (for operations, if applicable)
  • error_details (stack trace if an exception occurred)
• Readable Format (Development): If ENV is not set to production (or is set to something else like development), logs are output in a more human-readable, plain text format.
• Configurable Log Level: The log level can be configured using the LOG_LEVEL environment variable (e.g., INFO, DEBUG, ERROR). The default is INFO.
• Contextual Information: Logging includes correlation_id, request_id, and user_id to help trace operations through the system.

Environment Variables for Logging:

• LOG_LEVEL: Sets the logging verbosity (e.g., DEBUG, INFO, WARNING, ERROR). Defaults to INFO.
• ENV: Set to production for JSON logging. Defaults to development for readable logs.
• APP_VERSION: Sets the application version in logs. Defaults to 0.1.0.
• HOSTNAME: Sets the hostname in logs. Defaults to localhost.