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. 複製專案

git clone <repository-url> cd weather_mcp

2. 建立虛擬環境

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

3. 安裝依賴

pip install -r requirements.txt

4. 設定環境變數 (Agent 功能需要)

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

注意: 程式會自動讀取 .env 檔案（需要 python-dotenv 套件，已包含在 requirements.txt 中）

🏃‍♂️ 快速開始

快速測試

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

基本使用

from weather_mcp import WeatherMCPClient # 建立客戶端 client = WeatherMCPClient() # 查詢城市天氣 result = client.get_city_weather("Tokyo", hours=12) print(result)

LangChain Agent 模式

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 [city] [date] - 天氣視覺化（日期為可選的 YYYY-MM-DD 格式）
raw [city] [date] - 顯示原始天氣數據（日期為可選的 YYYY-MM-DD 格式）
自然語言查詢（需要 API Key）

範例：

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 # 測試日期功能

🔧 API 參考

WeatherMCPClient

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

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

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
天氣預報: Open-Meteo Forecast API
AI 模型: Google Gemini 2.5 Flash (透過 LangChain)

🧪 測試

# 安裝測試依賴 pip install -e ".[dev]" # 執行測試 pytest # 執行測試並顯示覆蓋率 pytest --cov=weather_mcp

🤝 貢獻

Fork 專案
建立功能分支 (git checkout -b feature/amazing-feature)
提交變更 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
開啟 Pull Request

📝 License

本專案採用 MIT License - 詳見 LICENSE 檔案。

🔍 故障排除

常見問題

MCP 伺服器啟動失敗
- 確認已安裝所有依賴套件
- 檢查 mcp_server.log 錯誤訊息
Agent 功能無法使用
- 確認已設定 GOOGLE_API_KEY 環境變數
- 檢查 API Key 是否有效
視覺化圖表無法顯示
- 確認已安裝 matplotlib
- 在 Jupyter 環境中使用 %matplotlib inline
網路連線錯誤
- 檢查網路連線
- 確認防火牆設定允許存取 Open-Meteo API

Debug 模式

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

📚 進階功能

歷史與未來天氣查詢

支援查詢過去 92 天和未來 16 天的天氣，系統自動判斷：

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 自動理解時間表達

agent = WeatherAgent() # 歷史天氣 agent.ask_weather("昨天東京天氣如何？") agent.ask_weather("3天前台北的天氣") # 未來天氣 agent.ask_weather("明天倫敦會下雨嗎？") agent.ask_weather("後天巴黎的天氣")

詳細說明請參考：

docs/DATE_FEATURE.md - viz/raw 日期功能說明
docs/HISTORICAL_WEATHER.md - 歷史天氣查詢
docs/MULTI_DAY_FORECAST.md - 多日預報功能

📞 支援與聯絡

問題回報: GitHub Issues
文件: 專案 Wiki
範例: examples/ 目錄

📖 更多文檔

HISTORICAL_WEATHER.md - 歷史天氣查詢功能
MULTI_DAY_FORECAST.md - 多日預報功能說明
LOGGING.md - 日誌系統說明
SERVER_STARTUP.md - 伺服器啟動機制
DYNAMIC_HOURS.md - 動態時間功能
ENV_SETUP.md - 環境變數設定

Weather MCP - 讓天氣查詢變得簡單而強大! 🌈

Weather MCP