Weather Information Service

天气信息服务

本项目提供一项服务，可通过美国国家气象局（NWS）API 获取天气信息，包括警报和预报。

项目结构

• main.py：项目的简单入口。（目前仅打印一条问候信息）。
• weather.py：项目的核心。它实现了 WeatherService，该服务使用 FastMCP 框架提供用于获取天气数据的工具。它包含结构化 JSON 日志记录，并与 NWS API 通信。
• smithery.yaml：Smithery 的配置文件。Smithery 是一种用于定义如何运行 WeatherService 以及如何与之交互的工具。
• 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）：两位字母的美国州代码（例如，CA、NY）。
• **输出：**包含格式化天气警报的字符串；如果未找到警报或发生错误，则返回相应消息。
  • 示例（成功获取警报）：

    事件：特殊天气声明
    区域：旧金山湾海岸线
    严重程度：轻微
    描述：...
    指示：...
    ---
    事件：沿海洪水提示
    区域：北湾内陆山谷
    严重程度：中等
    描述：...
    指示：...
    

  • 示例（无警报）：

    此州没有有效警报。
    

  • 示例（错误）：

    无法获取警报或未找到警报。
    

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

• **用途：**获取特定地理位置的天气预报。
• 参数：
  • latitude（float）：该位置的纬度。
  • longitude（float）：该位置的经度。
• **输出：**包含未来 5 个时段天气预报的格式化字符串；如果无法获取预报，则返回相应消息。
  • 示例（成功获取预报）：

    今晚：
    温度：55°F
    风：西风，风速 5 至 10 mph
    预报：大多晴朗，最低气温约 55°F。西风，风速 5 至 10 mph。
    ---
    星期三：
    温度：70°F
    风：西风，风速 5 至 15 mph
    预报：晴朗，最高气温约 70°F。西风，风速 5 至 15 mph，阵风最高可达 20 mph。
    ...（最多 5 个时段）
    

  • 示例（错误）：

    无法获取该位置的预报数据。
    

运行项目

该项目设计为以服务形式运行，可能使用 FastMCP 框架和提供的 smithery.yaml 配置。

1. 前置条件：

   • Python 3.x
   • httpx 库（以及 pyproject.toml 中定义的其他依赖项）。通常可以使用 pip 安装这些依赖项：

     pip install httpx
     # 或者，如果使用完整的 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：设置为 production 时使用 JSON 日志。默认值为 development，此时日志易于阅读。
• APP_VERSION：设置日志中的应用版本。默认值为 0.1.0。
• HOSTNAME：设置日志中的主机名。默认值为 localhost。