Weather MCP

# Weather MCP 🌤️ 一個 **Model Context Protocol (MCP)** 天氣查詢應用專案，提供天氣數據檢索、LangChain Agent 整合和資料視覺化功能。 ## 🚀 功能特色 ### 核心功能 - **MCP 伺服器**: 基於 FastMCP 的 stdio 協定天氣工具伺服器 - **MCP 客戶端**: 支援異步操作和錯誤處理的客戶端工具 - **LangChain 整合**: React Agent 模式，支援自然語言天氣查詢 - **資料視覺化**: 使用 matplotlib 的天氣趨勢圖表 - **多語言支援**: 中英文天氣查詢和回應 ### 天氣工具 - 🌍 **地理編碼**: 城市名稱轉經緯度 (Open-Meteo Geocoding API) - 🌡️ **天氣預報**: 1-24小時逐時天氣預報 (Open-Meteo Forecast API) - 📅 **多日預報**: 支援 1-16 天天氣預報，可指定日期查詢 - 🕒 **歷史天氣**: 支援查詢過去 92 天的天氣數據 - 🤖 **智能日期**: 自動判斷過去/未來，只需提供日期 - 🗣️ **自然語言**: Agent 自動理解「昨天」「明天」「3天前」等時間表達 - ⚠️ **天氣警報**: 天氣警報查詢 (示意功能) - 📊 **資料視覺化**: 溫度、濕度、降水機率和風速圖表 ## 📦 專案結構 ``` 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 # 說明文件 ``` ## 🛠️ 安裝與設定 ### 1. 複製專案 ```bash git clone <repository-url> cd weather_mcp ``` ### 2. 建立虛擬環境 ```bash python -m venv venv source venv/bin/activate # Linux/Mac # 或 venv\\Scripts\\activate # Windows ``` ### 3. 安裝依賴 ```bash pip install -r requirements.txt ``` ### 4. 設定環境變數 (Agent 功能需要) ```bash cp .env.example .env # 編輯 .env 檔案，設定您的 GOOGLE_API_KEY nano .env # 或使用任何文字編輯器 ``` **注意**: 程式會自動讀取 `.env` 檔案（需要 `python-dotenv` 套件，已包含在 requirements.txt 中） ## 🏃‍♂️ 快速開始 ### 快速測試 ```bash # 執行快速測試腳本（驗證所有功能） python test_quick.py ``` ### 基本使用 ```python from weather_mcp import WeatherMCPClient # 建立客戶端 client = WeatherMCPClient() # 查詢城市天氣 result = client.get_city_weather("Tokyo", hours=12) print(result) ``` ### LangChain Agent 模式 ```python 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) ``` ### 資料視覺化 ```python 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") ``` ## 🎯 主程式使用 ### 互動模式 ```bash python main.py --mode interactive ``` 互動模式支援以下命令： - `viz [city] [date]` - 天氣視覺化（日期為可選的 YYYY-MM-DD 格式） - `raw [city] [date]` - 顯示原始天氣數據（日期為可選的 YYYY-MM-DD 格式） - 自然語言查詢（需要 API Key） 範例： ```bash viz Tokyo # 今天東京天氣視覺化 viz Tokyo 2025-10-01 # 昨天東京天氣視覺化 raw London 2025-10-03 # 明天倫敦原始數據 ``` ### 執行範例 ```bash # 客戶端範例 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 ``` ### 使用範例程式 ```bash python examples/simple_usage.py python examples/test_date_feature.py # 測試日期功能 ``` ## 🔧 API 參考 ### WeatherMCPClient ```python 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] ``` ### WeatherAgent ```python 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 ``` ### WeatherVisualizer ```python 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] ``` ## 🌐 支援的城市 內建中英文城市名稱對照： - 日本/東京 → Tokyo - 台灣/台北 → Taipei - 中國/北京 → Beijing - 韓國/首爾 → Seoul - 美國/華盛頓 → Washington - 英國/倫敦 → London - 法國/巴黎 → Paris - 德國/柏林 → Berlin - 印度/新德里 → New Delhi ## 📊 資料來源 - **地理編碼**: [Open-Meteo Geocoding API](https://open-meteo.com/en/docs/geocoding-api) - **天氣預報**: [Open-Meteo Forecast API](https://open-meteo.com/en/docs) - **AI 模型**: Google Gemini 2.5 Flash (透過 LangChain) ## 🧪 測試 ```bash # 安裝測試依賴 pip install -e ".[dev]" # 執行測試 pytest # 執行測試並顯示覆蓋率 pytest --cov=weather_mcp ``` ## 🤝 貢獻 1. Fork 專案 2. 建立功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交變更 (`git commit -m 'Add amazing feature'`) 4. 推送到分支 (`git push origin feature/amazing-feature`) 5. 開啟 Pull Request ## 📝 License 本專案採用 MIT License - 詳見 [LICENSE](LICENSE) 檔案。 ## 🔍 故障排除 ### 常見問題 1. **MCP 伺服器啟動失敗** - 確認已安裝所有依賴套件 - 檢查 `mcp_server.log` 錯誤訊息 2. **Agent 功能無法使用** - 確認已設定 `GOOGLE_API_KEY` 環境變數 - 檢查 API Key 是否有效 3. **視覺化圖表無法顯示** - 確認已安裝 matplotlib - 在 Jupyter 環境中使用 `%matplotlib inline` 4. **網路連線錯誤** - 檢查網路連線 - 確認防火牆設定允許存取 Open-Meteo API ### Debug 模式 ```bash # 啟用詳細日誌 export DEBUG=true python main.py --mode interactive ``` ## 📚 進階功能 ### 歷史與未來天氣查詢 支援查詢過去 92 天和未來 16 天的天氣，系統自動判斷： ```python 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 自動理解時間表達 ```python agent = WeatherAgent() # 歷史天氣 agent.ask_weather("昨天東京天氣如何？") agent.ask_weather("3天前台北的天氣") # 未來天氣 agent.ask_weather("明天倫敦會下雨嗎？") agent.ask_weather("後天巴黎的天氣") ``` 詳細說明請參考： - [docs/DATE_FEATURE.md](docs/DATE_FEATURE.md) - viz/raw 日期功能說明 - [docs/HISTORICAL_WEATHER.md](docs/HISTORICAL_WEATHER.md) - 歷史天氣查詢 - [docs/MULTI_DAY_FORECAST.md](docs/MULTI_DAY_FORECAST.md) - 多日預報功能 ## 📞 支援與聯絡 - 問題回報: [GitHub Issues](https://github.com/weather-mcp/weather-mcp/issues) - 文件: [專案 Wiki](https://github.com/weather-mcp/weather-mcp/wiki) - 範例: `examples/` 目錄 ## 📖 更多文檔 - [HISTORICAL_WEATHER.md](docs/HISTORICAL_WEATHER.md) - 歷史天氣查詢功能 - [MULTI_DAY_FORECAST.md](docs/MULTI_DAY_FORECAST.md) - 多日預報功能說明 - [LOGGING.md](docs/LOGGING.md) - 日誌系統說明 - [SERVER_STARTUP.md](docs/SERVER_STARTUP.md) - 伺服器啟動機制 - [DYNAMIC_HOURS.md](docs/DYNAMIC_HOURS.md) - 動態時間功能 - [ENV_SETUP.md](docs/ENV_SETUP.md) - 環境變數設定 --- **Weather MCP** - 讓天氣查詢變得簡單而強大! 🌈