# 天气 MCP 接口说明

> 数据源：天行数据 Pro v2035  
> 地址：`https://mcp.xiaoyi-ai.com/weather/mcp`  
> 传输：streamable-http（POST）  
> 鉴权：`X-Api-Key: wx_985f8e122df8cbc8bc3668919849cfaf2b9bad34311c4245`

---

## 一、MCP 配置

```json
{
  "mcpServers": {
    "weather": {
      "url": "https://mcp.xiaoyi-ai.com/weather/mcp",
      "headers": {
        "X-Api-Key": "wx_985f8e122df8cbc8bc3668919849cfaf2b9bad34311c4245"
      }
    }
  }
}
```

---

## 二、定位参数（四个工具通用）

任选一个，优先级：

```
cityid > adcode > city > ip > lng+lat > 服务端 IP
```

| 参数 | 说明 |
|---|---|
| `city` | 城市名，不带“市/区”，如 `杭州`、`青岛` |
| `cityid` | 天行城市 ID，如 `101210101` |
| `adcode` | 行政区划码，如 `130200000000` |
| `ip` | 查 IP 所在城市 |
| `lng` + `lat` | 经纬度，如 `119.545023` / `36.044254` |

---

## 三、工具

### 1. `weather_current`

实况天气。

```json
{"city": "杭州"}
```

返回：

```json
{
  "city": "杭州",
  "cityid": "101210101",
  "update_time": "2026-11-04 09:10:33",
  "weather": "阴",
  "weather_img": "yu",
  "temperature": "16.5",
  "feels_like": "17.5",
  "wind": "北风",
  "wind_degree": "10",
  "wind_speed": "1级",
  "humidity": "96",
  "pressure": "1019",
  "visibility": "9",
  "rain": "1.45",
  "uv": "0.1",
  "uv_desc": "低",
  "aqi": "22",
  "aqi_level": "优",
  "pm25": "22",
  "sunrise": "06:15",
  "sunset": "05:09",
  "alarms": []
}
```

### 2. `weather_forecast`

逐日预报，`days` 1–14，默认 7。

```json
{"city": "杭州", "days": 7}
```

返回：

```json
{
  "city": "杭州",
  "days": 7,
  "forecast": [
    {
      "date": "2026-11-04",
      "weather": "小毛毛雨",
      "temp_min": "14.9",
      "temp_max": "18.3",
      "temp_avg": "16.1",
      "rain": "18.43",
      "humidity": "94",
      "uv": "0.9",
      "uv_desc": "低",
      "aqi": "48",
      "aqi_level": "优",
      "sunrise": "06:15",
      "sunset": "05:09"
    }
  ]
}
```

### 3. `weather_hourly`

逐小时，`limit` 1–24，默认 12；`date` 可选，默认第一天。

```json
{"city": "杭州", "limit": 6}
```

返回：

```json
{
  "city": "杭州",
  "date": "2026-11-04",
  "hours": [
    {
      "time": "2026-11-04 00:00",
      "timestamp": 1793721600,
      "weather": "小毛毛雨",
      "temperature": "15.2",
      "wind": "东南风",
      "wind_speed": "2级",
      "humidity": "91",
      "pressure": "1021",
      "rain": "0.38",
      "visibility": "2",
      "aqi": "90",
      "aqi_level": "良",
      "pm25": "41.6"
    }
  ]
}
```

### 4. `weather_alarm`

气象灾害预警。

```json
{"city": "杭州"}
```

返回：

```json
{
  "city": "杭州",
  "count": 0,
  "alarms": []
}
```

有预警时 `alarms` 每项：

```json
{
  "type": "海上大风",
  "level": "黄色",
  "title": "…",
  "content": "…"
}
```

---

## 四、错误

- 无 Key / Key 错误：HTTP 401
- 城市不存在：MCP `isError=true`，`天气接口错误：city不存在`
- 服务端未配置 appid/appsecret：`isError=true`

---

## 五、输出结构

4 个工具都已声明 `outputSchema`，`tools/call` 同时返回：

- `content[0].text`：JSON 字符串（兼容老客户端）
- `structuredContent`：同一份 JSON 对象（程序化消费）

`structuredContent` 与 `json.loads(content[0].text)` 完全一致。

嵌套数组（`alarms` / `forecast` / `hours`）使用 `$defs` 引用，字段均带 description。

---

## 六、缓存

同一查询参数 5 分钟内走内存缓存，减少天行接口调用次数。