Weather MCP

# 更新日誌 (Changelog)

## [v3.0.0] - 2025-10-02

### ✨ 新增功能 - 歷史天氣查詢

#### 核心特性
- 🕒 **歷史天氣查詢**：支援查詢過去 92 天的天氣數據
- 🤖 **智能日期判斷**：自動判斷過去/未來，無需手動設定參數
- 📅 **極簡 API**：只需提供 `target_date`，系統自動處理
- 🗣️ **自然語言增強**：Agent 支援「昨天」「3天前」等時間表達

#### API 簡化

**移除冗餘參數**：
- 移除 `forecast_days` 參數（自動計算）
- 移除 `past_days` 參數（自動計算）
- 只保留 `target_date` 參數

**新函數簽名**：
```python
# Server
def get_weather(lat, lon, hours=12, target_date="")

# Client
def get_weather(lat, lon, hours=12, target_date="", timeout=None)
def get_city_weather(city, hours=12, target_date="", timeout=None)
```

#### 自動計算邏輯

系統根據 `target_date` 自動判斷：
```python
target_date = "2025-10-01"  # 昨天
→ 自動設定 past_days=1, forecast_days=1

target_date = "2025-10-03"  # 明天
→ 自動設定 past_days=0, forecast_days=2

不提供 target_date
→ 自動使用今天日期
```

#### 使用範例

**查詢歷史天氣**：
```python
from datetime import datetime, timedelta
client = WeatherMCPClient()

yesterday = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")
result = client.get_city_weather("Tokyo", target_date=yesterday)
```

**Agent 自然語言**：
```python
agent = WeatherAgent()
agent.ask_weather("昨天東京天氣如何？")
agent.ask_weather("3天前台北的天氣")
```

### 📝 文檔更新

- ✅ 新增 `docs/HISTORICAL_WEATHER.md` - 完整使用說明
- ✅ 更新 `README.md` - 加入歷史天氣功能
- ✅ 新增 `examples/test_historical_weather.py` - 測試範例

### 🧪 測試

- ✅ 新增歷史天氣參數測試
- ✅ 所有 10 個測試通過（100%）
- ✅ 驗證自動計算邏輯
- ✅ 驗證向後兼容性

### 🔍 日誌改進

新增計算結果記錄：
```
🌤️  get_weather(lat=35.6895, lon=139.69171, hours=12, target_date='2025-10-01', calculated: past_days=1, forecast_days=1)
```

### ⚠️ 破壞性變更

**移除參數**（但完全向後兼容）：
- `forecast_days` 參數已移除（現在自動計算）
- `past_days` 參數已移除（現在自動計算）

**向後兼容說明**：
- 所有現有代碼無需修改
- 不提供 `target_date` 時自動使用今天
- 功能行為保持一致

---

## [v2.0.0] - 2025-10-02

### ✨ 新增功能

#### 多日天氣預報
- 🎯 支援 1-16 天天氣預報（Open-Meteo API `forecast_days` 參數）
- 📅 可指定特定日期查詢（`target_date` 參數，格式：YYYY-MM-DD）
- 🤖 Agent 自動理解時間表達（「明天」「後天」「未來3天」等）
- 🔄 向後兼容：所有新參數都有預設值

#### API 更新

**Server (`server.py`)**:
```python
def get_weather(
    lat: float,
    lon: float,
    hours: int = 12,
    forecast_days: int = 1,      # 新增
    target_date: str = ""         # 新增
) -> List[Content]:
```

**Client (`client.py`)**:
```python
def get_weather(
    lat: float,
    lon: float,
    hours: int = 12,
    forecast_days: int = 1,      # 新增
    target_date: str = "",        # 新增
    timeout: Optional[float] = None
) -> Dict[str, Any]:

def get_city_weather(
    city: str,
    hours: int = 12,
    forecast_days: int = 1,      # 新增
    target_date: str = "",        # 新增
    timeout: Optional[float] = None
) -> Dict[str, Any]:
```

**Tools (`tools.py`)**:
- 更新 `WeatherInput` schema 加入 `forecast_days` 和 `target_date`
- 更新 `CityWeatherInput` schema 加入 `forecast_days` 和 `target_date`
- 更新工具描述說明多日預報功能

**Agent (`agent.py`)**:
- 新增時間理解邏輯到 `AGENT_PROMPT`
- 自動計算日期並注入當前時間到查詢中
- 支援中英文時間表達（今天、明天、後天、未來N天等）

### 📝 文檔更新

- ✅ 新增 `docs/MULTI_DAY_FORECAST.md` - 多日預報完整說明
- ✅ 更新 `README.md` - 加入多日預報功能介紹
- ✅ 新增 `examples/multi_day_forecast.py` - 4 個實用範例

### 🧪 測試

- ✅ 新增 2 個參數驗證測試
- ✅ 所有 17 個測試通過（100%）
- ✅ 驗證向後兼容性

### 🔍 日誌改進

- ✅ 記錄所有新參數到 `mcp_server.log`
- ✅ 格式：`🌤️  get_weather(lat=..., lon=..., hours=..., forecast_days=..., target_date='...')`

### 📊 使用範例

#### 範例 1：查詢明天的天氣
```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="Tokyo",
    forecast_days=2,
    target_date=tomorrow
)
```

#### 範例 2：自然語言查詢
```python
from weather_mcp import WeatherAgent

agent = WeatherAgent()
answer = agent.ask_weather("明天東京天氣如何？")
```

#### 範例 3：查詢未來一週
```python
result = client.get_city_weather(
    city="Paris",
    forecast_days=7
)
```

---

## [v1.0.0] - 2025-10-01

### ✨ 初始版本

- ✅ MCP Server 實作（FastMCP + stdio）
- ✅ MCP Client 實作（async/await）
- ✅ LangChain Agent 整合
- ✅ 資料視覺化（matplotlib）
- ✅ 中英文城市名稱對照
- ✅ 完整測試覆蓋
- ✅ 日誌系統（追加模式）
- ✅ 動態時間顯示功能

---

## 升級指南

### 從 v1.0.0 升級到 v2.0.0

v2.0.0 完全向後兼容，無需修改現有代碼。

**可選升級**：使用新功能

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

# 新功能：查詢明天
from datetime import datetime, timedelta
tomorrow = (datetime.now() + timedelta(days=1)).strftime("%Y-%m-%d")
result = client.get_city_weather("Tokyo", forecast_days=2, target_date=tomorrow)

# 新功能：未來 7 天
result = client.get_city_weather("Tokyo", forecast_days=7)
```

---

**維護者**: Weather MCP Team
**更新日期**: 2025-10-02