weather_mcp/
├── src/weather_mcp/          # 主程式套件
│   ├── __init__.py          # 套件初始化
│   ├── server.py            # MCP 伺服器
│   ├── client.py            # MCP 客戶端
│   ├── tools.py             # LangChain 工具包裝
│   ├── agent.py             # LangChain Agent 整合
│   └── visualization.py     # 視覺化工具
├── examples/                # 使用範例
│   └── simple_usage.py      # 基本使用範例
├── tests/                   # 測試檔案
├── docs/                    # 文件
├── main.py                  # 主執行程式
├── requirements.txt         # 依賴套件
├── pyproject.toml          # 專案配置
└── README.md               # 說明文件

git clone <repository-url>
cd weather_mcp

python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\\Scripts\\activate  # Windows

pip install -r requirements.txt

cp .env.example .env
# 編輯 .env 檔案，設定您的 GOOGLE_API_KEY
nano .env  # 或使用任何文字編輯器

# 執行快速測試腳本（驗證所有功能）
python test_quick.py

from weather_mcp import WeatherMCPClient

# 建立客戶端
client = WeatherMCPClient()

# 查詢城市天氣
result = client.get_city_weather("Tokyo", hours=12)
print(result)

import os
from weather_mcp import WeatherAgent

# 設定 API Key
os.environ["GOOGLE_API_KEY"] = "your_api_key"

# 建立 Agent
agent = WeatherAgent()

# 自然語言查詢（支援時間理解）
answer = agent.ask_weather("昨天東京天氣如何？")  # 歷史天氣
print(answer)

answer = agent.ask_weather("明天台北會下雨嗎？")  # 未來天氣
print(answer)

answer = agent.ask_weather("3天前倫敦的天氣")  # 歷史天氣
print(answer)

from weather_mcp import WeatherMCPClient, create_visualizer
from weather_mcp.visualization import plot_weather_trends_horizontal

client = WeatherMCPClient()
result = client.get_city_weather("Tokyo", hours=12)

# 方法1: 快速繪圖
plot_weather_trends_horizontal(result["weather"], "Tokyo Weather")

# 方法2: 使用視覺化物件
visualizer = create_visualizer()
fig = visualizer.plot_all_metrics(result["weather"], "Tokyo")
fig.savefig("tokyo_weather.png")

python main.py --mode interactive

viz Tokyo                 # 今天東京天氣視覺化
viz Tokyo 2025-10-01      # 昨天東京天氣視覺化
raw London 2025-10-03     # 明天倫敦原始數據

# 客戶端範例
python main.py --mode client

# Agent 範例 (需要 API Key)
python main.py --mode agent --api-key your_key

# 視覺化範例（今天）
python main.py --mode viz

# 視覺化範例（指定日期）
python main.py --mode viz --city Tokyo --date 2025-10-01

# MCP 伺服器
python main.py --mode server

python examples/simple_usage.py
python examples/test_date_feature.py    # 測試日期功能

class WeatherMCPClient:
    def geocode_city(self, city: str) -> Dict[str, Any]
    def get_weather(self, lat: float, lon: float, hours: int = 12) -> Dict[str, Any]
    def get_alerts(self, lat: float, lon: float) -> Dict[str, Any]
    def get_city_weather(self, city: str, hours: int = 12) -> Dict[str, Any]

class WeatherAgent:
    def ask_weather(self, question: str, language: str = "zh-tw") -> str
    def get_weather_data(self, city: str, hours: int = 12) -> Dict[str, Any]
    def translate_city_name(self, city: str) -> str

class WeatherVisualizer:
    def plot_temperature_trend(self, weather_data: Dict[str, Any]) -> plt.Figure
    def plot_weather_overview(self, weather_data: Dict[str, Any]) -> plt.Figure
    def plot_all_metrics(self, weather_data: Dict[str, Any]) -> plt.Figure
    def get_weather_summary(self, weather_data: Dict[str, Any]) -> Dict[str, Any]

# 安裝測試依賴
pip install -e ".[dev]"

# 執行測試
pytest

# 執行測試並顯示覆蓋率
pytest --cov=weather_mcp

# 啟用詳細日誌
export DEBUG=true
python main.py --mode interactive

from datetime import datetime, timedelta
from weather_mcp import WeatherMCPClient

client = WeatherMCPClient()

# 查詢昨天的天氣（自動設定 past_days）
yesterday = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")
result = client.get_city_weather(city="Tokyo", target_date=yesterday)

# 查詢明天的天氣（自動設定 forecast_days）
tomorrow = (datetime.now() + timedelta(days=1)).strftime("%Y-%m-%d")
result = client.get_city_weather(city="Paris", target_date=tomorrow)

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

agent = WeatherAgent()

# 歷史天氣
agent.ask_weather("昨天東京天氣如何？")
agent.ask_weather("3天前台北的天氣")

# 未來天氣
agent.ask_weather("明天倫敦會下雨嗎？")
agent.ask_weather("後天巴黎的天氣")