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

🤝 貢獻

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 檔案。

🔍 故障排除

常見問題

1. MCP 伺服器啟動失敗

   • 確認已安裝所有依賴套件
   • 檢查 mcp_server.log 錯誤訊息

2. Agent 功能無法使用

   • 確認已設定 GOOGLE_API_KEY 環境變數
   • 檢查 API Key 是否有效

3. 視覺化圖表無法顯示

   • 確認已安裝 matplotlib
   • 在 Jupyter 環境中使用 %matplotlib inline

4. 網路連線錯誤

   • 檢查網路連線
   • 確認防火牆設定允許存取 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 - 讓天氣查詢變得簡單而強大! 🌈