Weather Information Service

気象情報サービス

このプロジェクトは、米国国立気象局（NWS）API から警報や予報などの気象情報を取得するサービスを提供します。

プロジェクトの構成

• main.py：プロジェクトのシンプルなエントリーポイントです（現在は、hello メッセージを出力するだけです）。
• weather.py：プロジェクトの中核です。FastMCP フレームワークを使用して気象データを取得するツールを公開する WeatherService を実装しています。構造化 JSON ログを出力し、NWS API と通信します。
• smithery.yaml：WeatherService の実行方法や操作方法を定義するツール、Smithery の設定ファイルです。
• Dockerfile：このプロジェクトを Docker でコンテナ化できることを示しています。
• pyproject.toml：Python プロジェクトのメタデータと依存関係を定義します。
• .gitignore：Git が無視する、意図的に追跡対象から外したファイルを指定します。
• .python-version：プロジェクトで使用する Python のバージョンを指定します（pyenv などのツールで使用すると思われます）。
• uv.lock：uv Python パッケージインストーラー兼リゾルバーが生成するロックファイルです。ビルドの再現性を確保します。

（WeatherService のツール、プロジェクトの実行方法、ログに関するセクションは、後続の手順で追加されます）。

WeatherService のツール

weather.py スクリプトは、以下のツールを備えた WeatherService を提供します。

get_alerts(state: str) -> str

• **目的：**指定された米国の州に発令中の気象警報を取得します。
• 引数：
  • state（str）：米国の州を表す 2 文字のコード（例：CA、NY）。
• **出力：**書式設定された気象警報を含む文字列。警報が見つからない場合やエラーが発生した場合は、メッセージを返します。
  • 例（警報の取得に成功した場合）：

    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: ...
    

  • 例（警報がない場合）：

    No active alerts for this state.
    

  • 例（エラー）：

    Unable to fetch alerts or no alerts found.
    

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

• **目的：**特定の地理的位置の気象予報を取得します。
• 引数：
  • latitude（float）：位置の緯度。
  • longitude（float）：位置の経度。
• **出力：**次の 5 期間の書式設定された気象予報を含む文字列。予報を取得できない場合は、メッセージを返します。
  • 例（予報の取得に成功した場合）：

    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)
    

  • 例（エラー）：

    Unable to fetch forecast data for this location.
    

プロジェクトの実行

このプロジェクトはサービスとして実行するように設計されており、FastMCP フレームワークと提供されている smithery.yaml 設定を使用することを想定しています。

1. 前提条件：

   • Python 3.x
   • httpx ライブラリ（および pyproject.toml で定義されているその他の依存関係）。通常は pip を使って次のようにインストールできます。

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

2. サービスの実行： weather.py スクリプトを直接実行すると、サービスが起動します。smithery.yaml ファイルがあることから、次の方法で実行することを想定しています。

   python weather.py
   

   これにより、FastMCP サーバーが起動し、リクエストを受け付けます（たとえば、smithery.yaml で設定されている stdio 経由）。

   Smithery がインストールされている場合は、Smithery のコマンドを使って実行できることもありますが、ローカルでの開発やテストには weather.py を直接実行すれば問題ありません。

   main.py スクリプトはシンプルなエントリーポイントであり、メインの天気サービスは実行しません。

ログ

weather.py の WeatherService は、構造化 JSON ログを使用します。ログがログ管理システムに取り込まれる可能性がある本番環境で、特に役立ちます。

ログ実装の主な機能：

• JSON 形式（本番環境）： ENV 環境変数が production に設定されている場合、ログは JSON 形式で出力されます。各ログエントリーには次の情報が含まれます。
  • timestamp
  • level（例：INFO、ERROR）
  • logger（ロガー名。例：WeatherService）
  • message
  • correlation_id（論理的な操作やフローを追跡します）
  • request_id（個々のリクエストを追跡します）
  • user_id
  • file および lineno（ログの発生元）
  • function（ログが記録された関数名）
  • process および thread
  • environment（ENV 変数の値）
  • app_version（APP_VERSION 変数の値）
  • host（HOSTNAME 変数の値）
  • duration（該当する場合、処理にかかった時間）
  • error_details（例外が発生した場合のスタックトレース）
• 読みやすい形式（開発環境）： ENV が production に設定されていない場合（または development など別の値に設定されている場合）、ログはより人が読みやすいプレーンテキスト形式で出力されます。
• 設定可能なログレベル： LOG_LEVEL 環境変数を使って、ログレベルを設定できます（例：INFO、DEBUG、ERROR）。デフォルトは INFO です。
• コンテキスト情報： ログには correlation_id、request_id、user_id が含まれ、システム内での処理の追跡に役立ちます。

ログ用の環境変数：

• LOG_LEVEL：ログの詳細度を設定します（例：DEBUG、INFO、WARNING、ERROR）。デフォルトは INFO です。
• ENV：JSON ログを有効にするには production に設定します。読みやすいログのデフォルトは development です。
• APP_VERSION：ログに記録するアプリケーションのバージョンを設定します。デフォルトは 0.1.0 です。
• HOSTNAME：ログに記録するホスト名を設定します。デフォルトは localhost です。