# weather-mcp

`weather-mcp` 是一个独立的 **Capability Service（能力服务）**，对外提供“天气查询”这一 MCP 能力。

## 为什么要拆成 weather-mcp

在已有后台系统中：

- `admin`：唯一的用户与认证来源（登录、签发 Token、`/api/v1/auth/me`）
- `weather-mcp`：只负责能力提供，不做用户系统

拆分的目标：

- 清晰边界：避免多套用户体系
- 能力可复用：MCP 层独立于 HTTP，可被编排/复用
- 可演进：未来接入更多 MCP（空气质量/预报/第三方数据源）

## 与 admin 的关系（文字关系图）

- Client -> `weather-mcp`：携带 `Authorization: Bearer <JWT>`
- `weather-mcp`：验证 Token 是否可信（第一版为本地 HS256 验签）
- `admin`：身份真实性与用户语义的权威来源

## 鉴权设计

第一版采用 **方案 A：本地 HS256 验签**（与 `admin` 使用同一套 `SECRET_KEY`）。

- Header 读取：`Authorization: Bearer <token>`
- 解析规则：
  - 算法：HS256
  - `sub`：`user_id`
  - 不依赖 `roles/scopes`

工程化要求：

- 鉴权逻辑在 `app/core/auth/` 与 `app/auth_client/` 中
- API 层通过 `Depends(get_auth_context)` 获取 `AuthContext`
- handler 不直接处理 token、不写鉴权逻辑

可替换性：

- 通过 `WEATHER_MCP_AUTH_MODE` 切换
  - `local_jwt`：本地验签
  - `admin_introspect`：调用 admin 的 `GET /api/v1/auth/me`（已预留实现）

## MCP 设计理念

MCP 是独立于 HTTP 的“能力协议层”：

- 输入输出是结构化 DTO（Pydantic Model）
- 不依赖 FastAPI `Request`
- 易于单测与复用

目录：

- `app/mcp/`：MCP 抽象与实现（例如 `WeatherMCP`）
- `app/schemas/`：MCP 输入输出结构（与 HTTP 无关）
- `app/api/`：HTTP API 层（校验/鉴权/调用 MCP）

## 运行

### 依赖

使用 `uv` 管理依赖：

- `uv sync`

### 环境变量

- `WEATHER_MCP_SECRET_KEY`：与 admin 一致的 HS256 对称密钥
- `WEATHER_MCP_AUTH_MODE`：默认 `local_jwt`

和风天气（QWeather）Web API：

- `WEATHER_MCP_QWEATHER_API_HOST`：你的 QWeather API Host（在 QWeather Console -> Setting 查看）
- `WEATHER_MCP_QWEATHER_API_KEY`：你的 QWeather API Key（务必只放在环境变量/密钥管理中）
- `WEATHER_MCP_QWEATHER_TIMEOUT_SECONDS`：HTTP 超时（秒）

### 启动

- `uv run uvicorn app.main:app --reload --port 9001`

## API

- `GET /health`

### MCP 能力：实时天气（Current Weather）

本服务通过 QWeather `GET /v7/weather/now` 提供实时天气能力，并将返回结构映射成统一的 MCP 输出。

#### 1) MCP 直连路由（兼容/调试）

- `GET /mcp/weather?location=...&lang=...&unit=m|i`

说明：

- `location` 支持多种输入形式（统一为一个字符串参数）：
  - 城市名称（例如 `北京` / `Beijing`）
  - 经纬度（格式 `longitude,latitude`，例如 `116.41,39.92`）
  - Location ID（和风天气城市码，例如 `101010100`）
- `lang`：天气描述语言（默认 `zh`，例如返回 `多云`）
- `unit`：单位（`m`=metric，`i`=imperial；默认 `m`）

城市名解析策略：

- 当 `location` 不是纯数字（LocationID）且不是 `lon,lat` 时，会先调用 QWeather GeoAPI `GET /geo/v2/city/lookup` 做解析，取 Top-1 结果。
- 解析时会使用英文 `geo_lang=en` 获取标准化地点名称（例如输出 `Beijing`），而天气接口仍使用 `lang=zh` 以保证天气状态中文显示。

#### 2) Tool 路由（推荐对外使用）

- `POST /tools/weather.current`

请求示例：

```
POST /tools/weather.current
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "location": "北京"
}
```

返回示例：

```json
{
  "location": "Beijing",
  "observed_at": "2025-12-13T15:00:00+08:00",
  "temperature": 12,
  "condition": "多云",
  "humidity": 55,
  "wind_speed": 5.4,
  "wind_dir": "西北风",
  "raw": { "code": "200", "now": { "...": "..." } }
}
```

字段映射说明（QWeather -> MCP）：

- `now.obsTime` -> `observed_at`
- `now.temp` -> `temperature`
- `now.text` -> `condition`
- `now.humidity` -> `humidity`
- `now.windSpeed` -> `wind_speed`
- `now.windDir` -> `wind_dir`
- 完整原始响应 -> `raw`

错误处理（HTTP 层）：

- 401：缺少/无效 JWT（由 `get_auth_context` 处理）
- 500：服务端缺少 QWeather 配置（host/key）
- 400：无效地点（上游返回 400/404）
- 429：上游限流
- 502：上游网络或权限问题（QWeather 返回 401/403 等）

### MCP 能力：每日天气预报（Daily Forecast）

本服务通过 QWeather `GET /v7/weather/{days}` 提供每日天气预报能力，并将返回结构映射成统一的 MCP 输出。

#### Tool 路由

- `POST /tools/weather.forecast.daily`

请求示例：

```
POST /tools/weather.forecast.daily
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "location": "北京",
  "days": 3,
  "lang": "zh",
  "unit": "m"
}
```

参数说明：

- `location`：城市名称 / `lon,lat` / LocationID
- `days`：仅支持 `3|7|10|15`（对应上游 `3d/7d/10d/15d`）
- `lang`：天气描述语言（默认 `zh`）
- `unit`：单位（`m`=metric，`i`=imperial；默认 `m`）

返回示例：

```json
{
  "location": "Beijing",
  "forecasts": [
    {
      "date": "2025-12-14",
      "temp_max": 8,
      "temp_min": -2,
      "condition_day": "多云",
      "condition_night": "晴",
      "humidity": 35,
      "wind_speed": 10,
      "wind_dir": "西北风"
    }
  ],
  "raw": { "code": "200", "daily": [{ "...": "..." }] }
}
```

字段映射说明（QWeather -> MCP）：

- `daily.fxDate` -> `forecasts[].date`
- `daily.tempMax` -> `forecasts[].temp_max`
- `daily.tempMin` -> `forecasts[].temp_min`
- `daily.textDay` -> `forecasts[].condition_day`
- `daily.textNight` -> `forecasts[].condition_night`
- `daily.humidity` -> `forecasts[].humidity`
- `daily.windSpeedDay` -> `forecasts[].wind_speed`
- `daily.windDirDay` -> `forecasts[].wind_dir`
- 完整原始响应 -> `raw`

### MCP 能力：每小时天气预报（Hourly Forecast）

本服务通过 QWeather `GET /v7/weather/{hours}` 提供每小时天气预报能力，并将返回结构映射成统一的 MCP 输出。

#### Tool 路由

- `POST /tools/weather.forecast.hourly`

请求示例：

```
POST /tools/weather.forecast.hourly
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "location": "北京",
  "hours": 24,
  "lang": "zh",
  "unit": "m"
}
```

参数说明：

- `location`：城市名称 / `lon,lat` / LocationID
- `hours`：仅支持 `24|72|168`（对应上游 `24h/72h/168h`）
- `lang`：天气描述语言（默认 `zh`）
- `unit`：单位（`m`=metric，`i`=imperial；默认 `m`）

返回示例：

```json
{
  "location": "Beijing",
  "hourly": [
    {
      "time": "2025-12-13T18:00:00+08:00",
      "temperature": 2,
      "condition": "多云",
      "wind_speed": 12,
      "wind_dir": "北风",
      "humidity": 40
    }
  ],
  "raw": { "code": "200", "hourly": [{ "...": "..." }] }
}
```

字段映射说明（QWeather -> MCP）：

- `hourly.fxTime` -> `hourly[].time`
- `hourly.temp` -> `hourly[].temperature`
- `hourly.text` -> `hourly[].condition`
- `hourly.windSpeed` -> `hourly[].wind_speed`
- `hourly.windDir` -> `hourly[].wind_dir`
- `hourly.humidity` -> `hourly[].humidity`
- 完整原始响应 -> `raw`

### MCP 能力：空气质量（Current Air Quality）

本服务通过 QWeather Air Quality v1 `GET /airquality/v1/current/{latitude}/{longitude}` 提供空气质量能力。

说明：

- 该能力需要经纬度。若传入的是城市名或 LocationID，会先调用 GeoAPI 获取 `lat/lon`。

#### Tool 路由

- `POST /tools/air_quality.current`

请求示例：

```
POST /tools/air_quality.current
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "location": "北京"
}
```

返回示例：

```json
{
  "location": "Beijing",
  "aqi": 46,
  "category": "Good",
  "primary_pollutant": "PM 2.5",
  "pm2p5": 11.0,
  "pm10": 12.0,
  "o3": 0.02,
  "no2": 6.77,
  "so2": 1.0,
  "co": 0.25,
  "raw": { "indexes": [{ "...": "..." }], "pollutants": [{ "...": "..." }] }
}
```

字段映射说明（QWeather -> MCP）：

- `indexes[0].aqi` -> `aqi`（优先选择 `code=us-epa`）
- `indexes[0].category` -> `category`
- `indexes[0].primaryPollutant.name`（或 `.code`）-> `primary_pollutant`
- `pollutants[].concentration.value`（按 `code` 匹配）-> `pm2p5/pm10/o3/no2/so2/co`
- 完整原始响应 -> `raw`

### MCP 能力：极端天气预警（Weather Alerts）

本服务通过 QWeather `GET /v7/warning/now` 提供天气预警能力。

说明：

- QWeather 文档中标注该接口为“弃用”，但目前仍可按现有返回结构使用。
- 当查询地区当前没有预警信息时，上游返回 `warning=[]`，本服务返回 `alerts=[]`。

#### Tool 路由

- `POST /tools/weather.alerts`

请求示例：

```
POST /tools/weather.alerts
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "location": "北京",
  "lang": "zh"
}
```

返回示例：

```json
{
  "location": "Beijing",
  "alerts": [
    {
      "type": "大风",
      "level": "Blue",
      "title": "发布大风蓝色预警",
      "description": "预计将出现大风",
      "start": "2025-12-13T10:30:00+08:00",
      "end": "2025-12-14T10:30:00+08:00"
    }
  ],
  "raw": { "code": "200", "warning": [{ "...": "..." }] }
}
```

字段映射说明（QWeather -> MCP）：

- `warning.typeName`（或 `warning.type`）-> `alerts[].type`
- `warning.severityColor`（或 `warning.severity`）-> `alerts[].level`
- `warning.title` -> `alerts[].title`
- `warning.text` -> `alerts[].description`
- `warning.startTime` -> `alerts[].start`
- `warning.endTime` -> `alerts[].end`
- 完整原始响应 -> `raw`

## 测试

依赖由 `uv` 管理，推荐直接运行：

- `uv run pytest -q`

## 后续演进方向

- 多 MCP：`AirQualityMCP`、`ForecastMCP`
- MCP 编排：一个请求触发多个 MCP，或链式执行
- 内部 RPC / Agent 化：HTTP 之外的复用入口
- 可观测性：日志/trace、限流、缓存与熔断