MCP Weather Server

MCP 天气服务

一个基于 FastAPI 的天气服务，使用 Model Context Protocol（MCP）与 Home Assistant 集成。该服务使用 OpenWeatherMap 的 One Call API 3.0，为任意地点提供全面的天气信息，包括当前天气状况、每日预报和每小时预报。

前提条件

• Python 3.7+
• OpenWeatherMap API 密钥（需具有 One Call API 3.0 访问权限）

设置

1. 克隆此代码仓库

2. 安装依赖：

   pip install -r requirements.txt
   

3. 使用以下任一方法配置 OpenWeather API 密钥：

   • 设置环境变量（推荐）：

     export OPENWEATHER_API_KEY=your_api_key_here
     

   • 或将其添加到 config.yaml：

     settings:
       api_key: your_api_key_here
     

   注意：环境变量的优先级高于配置文件。

4. （可选）在 config.yaml 中配置其他设置：

   # General settings
   settings:
     units: "imperial"  # Optional: "metric" (default) or "imperial"
     api_key: "your_api_key_here"  # Alternative to environment variable
     server:
       host: "0.0.0.0"  # Optional: Interface to listen on (default: "0.0.0.0")
       port: 8000       # Optional: Port to listen on (default: 8000)
   
   # Location overrides (optional)
   overrides:
     "lafayette": "Lafayette, CA, US"
     # Add more overrides as needed
   

配置

API 密钥

OpenWeather API 密钥可以通过两种方式配置：

1. 环境变量 OPENWEATHER_API_KEY（出于安全考虑，推荐使用）
2. config.yaml 中的 settings.api_key

服务设置

在 config.yaml 中配置服务的监听接口和端口：

settings:
  server:
    host: "0.0.0.0"  # Listen on all interfaces (default)
    port: 8000       # Port number (default)

• host：要监听的网络接口
  • "0.0.0.0"：监听所有接口（默认）
  • "127.0.0.1"：仅监听本地主机
  • "192.168.1.100"：监听指定接口
• port：要监听的端口号（默认值：8000）

单位

你可以在 config.yaml 中选择公制或英制单位：

• metric（未指定时的默认值）：
  • 温度：摄氏度
  • 风速：米/秒
• imperial：
  • 温度：华氏度
  • 风速：英里/小时

位置覆盖

config.yaml 中可选的 overrides 部分允许你为有歧义的城市名称指定默认位置。例如：

overrides:
  "lafayette": "Lafayette, CA, US"
  "springfield": "Springfield, IL, US"

默认配置

如果不存在 config.yaml 文件，服务将：

• 使用公制单位
• 监听所有接口（0.0.0.0:8000）
• 不设置位置覆盖
• 要求在环境中设置 API 密钥

运行服务

使用以下命令启动服务：

python server.py

服务将在配置的主机和端口上运行（默认值：http://0.0.0.0:8000）

API 端点

旧版 REST API

这些端点提供传统的 HTTP 访问方式：

当前天气

GET /api/current-weather/{location}

返回当前天气信息，包括温度、体感温度、湿度、风速、紫外线指数和云量。

每日预报

GET /api/daily-forecast/{location}?days={number_of_days}

返回最多 7 天的每日预报，包括日间/最低/最高气温、降水概率和紫外线指数。

每小时预报

GET /api/hourly-forecast/{location}?hours={number_of_hours}

返回最多 48 小时的逐小时预报，包括温度、体感温度、降水概率和紫外线指数。

MCP 集成

该服务实现了 Model Context Protocol（MCP），可与 Home Assistant 无缝集成。MCP 端点为：

/mcp/sse

可用的 MCP 工具：

• current_weather(location: str)：获取当前天气状况
• hourly_forecast(location: str, hours: int = 24)：获取逐小时预报
• daily_forecast(location: str, days: int = 7)：获取每日预报

位置解析

该服务采用灵活的位置解析系统：

1. 如果位置与 overrides 配置中的条目匹配，则使用相应的覆盖项
2. 对于没有州/国家信息的城市名称，尝试直接解析
3. 对于 “City, State” 格式，默认所属国家为美国（例如，“Portland, OR” → “Portland, Oregon, US”）
4. 始终按原样处理完整的 “City, State, Country” 格式

示例：

• “London” → “London, England, GB”
• “Lafayette” → “Lafayette, California, US”（如果已在 overrides 中配置）
• “Portland, OR” → “Portland, Oregon, US”
• “Melbourne, AU” → “Melbourne, Victoria, AU”

API 响应格式

天气数据会根据配置，以公制或英制单位返回：

公制（默认）：

• 温度：摄氏度
• 风速：米/秒
• 湿度：百分比
• 紫外线指数：0-11+ 量表
• 降水概率：0-1（0-100%）
• 云量：百分比

英制：

• 温度：华氏度
• 风速：英里/小时
• 其他单位与公制相同

当前天气响应示例：

{
    "resolved_location": "London, England, GB",
    "temperature": 17.88,
    "feels_like": 17.29,
    "description": "few clouds",
    "humidity": 60,
    "wind_speed": 5.14,
    "uvi": 0,
    "clouds": 11,
    "timestamp": "2024-04-30T13:10:15"
}

每日预报响应示例：

{
    "resolved_location": "London, England, GB",
    "forecast": [
        {
            "date": "2024-04-30",
            "temp_day": 20.3,
            "temp_min": 15.1,
            "temp_max": 22.4,
            "description": "scattered clouds",
            "humidity": 70,
            "wind_speed": 4.2,
            "precipitation_probability": 0.3,
            "uvi": 6.1
        }
    ]
}