Weather MCP

# 歷史天氣查詢功能說明

## 🎯 核心特性

系統會根據 `target_date` 自動判斷是過去、今天還是未來，並自動處理所需參數：

- **過去日期**：自動設定 `past_days`（最多 92 天）
- **今天**：返回今天的數據
- **未來日期**：自動設定 `forecast_days`（最多 16 天）
- **不提供 target_date**：自動使用今天日期

**用戶只需提供日期，系統自動處理一切！**

## 📊 API 參數

### get_weather()
```python
def get_weather(
    lat: float,
    lon: float,
    hours: int = 12,
    target_date: str = ""  # YYYY-MM-DD 格式
) -> Dict[str, Any]:
```

### get_city_weather()
```python
def get_city_weather(
    city: str,
    hours: int = 12,
    target_date: str = ""  # YYYY-MM-DD 格式
) -> Dict[str, Any]:
```

## 🚀 使用範例

### 範例 1：查詢昨天的天氣

```python
from datetime import datetime, timedelta
from weather_mcp import WeatherMCPClient

client = WeatherMCPClient()

# 計算昨天日期
yesterday = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")

# 查詢昨天東京的天氣
result = client.get_city_weather(
    city="Tokyo",
    target_date=yesterday
)

# 系統自動設定 past_days=1
```

### 範例 2：查詢今天的天氣（不提供 target_date）

```python
from weather_mcp import WeatherMCPClient

client = WeatherMCPClient()

# 不提供 target_date，自動使用今天
result = client.get_city_weather(city="Taipei", hours=12)

# 系統自動設定 target_date=今天日期
```

### 範例 3：查詢明天的天氣

```python
from datetime import datetime, timedelta
from weather_mcp import WeatherMCPClient

client = WeatherMCPClient()

# 計算明天日期
tomorrow = (datetime.now() + timedelta(days=1)).strftime("%Y-%m-%d")

# 查詢明天倫敦的天氣
result = client.get_city_weather(
    city="London",
    target_date=tomorrow
)

# 系統自動設定 forecast_days=2
```

### 範例 4：Agent 自然語言查詢

```python
from weather_mcp import WeatherAgent

agent = WeatherAgent()

# Agent 自動計算日期，Server 自動判斷參數
agent.ask_weather("昨天東京天氣如何？")
agent.ask_weather("今天台北天氣？")
agent.ask_weather("明天倫敦會下雨嗎？")
agent.ask_weather("3天前巴黎的天氣")
```

## 🔍 自動計算邏輯

```python
# Server 端自動計算
today = 2025-10-02

target_date = "2025-10-01"  # 昨天
→ delta = -1
→ past_days = 1, forecast_days = 1

target_date = "2025-10-02"  # 今天
→ delta = 0
→ past_days = 0, forecast_days = 1

target_date = "2025-10-03"  # 明天
→ delta = 1
→ past_days = 0, forecast_days = 2

target_date = "2025-09-29"  # 3天前
→ delta = -3
→ past_days = 3, forecast_days = 1
```

## 📡 Open-Meteo API

### 參數限制
- `past_days`：0-92 天
- `forecast_days`：1-16 天

### 時間軸
```
←─── 過去 ───|─── 今天 ───|─── 未來 ───→

past_days=2, forecast_days=3:
  [前天] [昨天] [今天] [明天] [後天]
```

## 🤖 Agent 時間理解

Agent 會自動理解以下時間表達：

| 使用者輸入 | Agent 計算 | Server 處理 |
|----------|----------|-----------|
| 「昨天東京天氣」 | target_date = 2025-10-01 | past_days=1 |
| 「前天台北天氣」 | target_date = 2025-09-30 | past_days=2 |
| 「3天前倫敦天氣」 | target_date = 2025-09-29 | past_days=3 |
| 「今天巴黎天氣」 | target_date = 2025-10-02 | past_days=0, forecast_days=1 |
| 「明天東京天氣」 | target_date = 2025-10-03 | forecast_days=2 |
| 「後天台北天氣」 | target_date = 2025-10-04 | forecast_days=3 |

## 📝 日誌記錄

所有查詢都會記錄計算結果：

```
🌤️  get_weather(lat=35.6895, lon=139.69171, hours=12, target_date='2025-10-01', calculated: past_days=1, forecast_days=1)
```

可以在 `mcp_server.log` 中追蹤每次查詢的自動計算結果。

## ✅ 向後兼容

### 行為保持一致
```python
# 舊代碼（仍然有效）
result = client.get_city_weather("Tokyo", hours=12)

# 新行為：target_date 自動設為今天
# 等同於：
today = datetime.now().strftime("%Y-%m-%d")
result = client.get_city_weather("Tokyo", hours=12, target_date=today)
```

### 無需修改現有代碼
- 不提供 `target_date` → 自動使用今天
- 所有現有代碼無需修改
- 功能完全向後兼容

## 🧪 測試範例

```python
import sys
from pathlib import Path
from datetime import datetime, timedelta

sys.path.insert(0, str(Path(__file__).parent.parent / "src"))

from weather_mcp import WeatherMCPClient

client = WeatherMCPClient()

# 測試昨天
yesterday = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")
result = client.get_city_weather("Tokyo", target_date=yesterday)
print(f"昨天東京天氣：{result}")

# 測試今天（不提供 target_date）
result = client.get_city_weather("Taipei")
print(f"今天台北天氣：{result}")

# 測試明天
tomorrow = (datetime.now() + timedelta(days=1)).strftime("%Y-%m-%d")
result = client.get_city_weather("London", target_date=tomorrow)
print(f"明天倫敦天氣：{result}")
```

## 🎯 實際應用場景

### 場景 1：歷史數據分析
```python
# 分析過去一週的天氣趨勢
for i in range(7):
    date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
    result = client.get_city_weather("Tokyo", target_date=date)
    # 分析溫度、降雨等數據
```

### 場景 2：比較歷史與預測
```python
# 比較昨天實際天氣 vs 今天預測
yesterday = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")
yesterday_data = client.get_city_weather("Tokyo", target_date=yesterday)

today_data = client.get_city_weather("Tokyo")
# 比較數據差異
```

### 場景 3：行程規劃
```python
# 查詢未來一週的天氣，規劃活動
for i in range(7):
    date = (datetime.now() + timedelta(days=i)).strftime("%Y-%m-%d")
    result = client.get_city_weather("Paris", target_date=date)
    print(f"{date}: {result}")
```

## ❓ 常見問題

### Q1: 最多可以查詢多久以前的天氣？
A: 最多 92 天前（Open-Meteo API 限制）。

### Q2: 最多可以預測多久以後的天氣？
A: 最多 16 天後（Open-Meteo API 限制）。

### Q3: 不提供 target_date 會怎樣？
A: 系統自動使用今天日期，查詢今天的天氣。

### Q4: target_date 格式錯誤會怎樣？
A: 系統會使用預設值（today），查詢今天的天氣。

### Q5: Agent 支援哪些時間表達？
A: 昨天、前天、N天前、今天、明天、後天等中文表達，Agent 會自動計算日期。

## 📚 相關文件

- [MULTI_DAY_FORECAST.md](MULTI_DAY_FORECAST.md) - 多日預報功能說明
- [LOGGING.md](LOGGING.md) - 日誌系統說明
- [SERVER_STARTUP.md](SERVER_STARTUP.md) - 伺服器啟動機制
- [README.md](../README.md) - 專案主要文件

---

**更新日期**: 2025-10-02
**狀態**: ✅ 歷史天氣查詢功能已實作並測試