# 快速開始指南
## 🚀 5 分鐘上手 Weather MCP
本指南將幫助您快速開始使用 Weather MCP 查詢天氣資訊。
## 前置需求
- Python 3.8 或以上版本
- pip 套件管理工具
- (可選) Google API Key - 用於 LangChain Agent 功能
## 安裝步驟
### 1. 複製專案
```bash
cd /home/alex/projects/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. (可選) 設定環境變數
```bash
cp .env.example .env
# 編輯 .env 檔案，設定您的 GOOGLE_API_KEY
export GOOGLE_API_KEY="your_api_key_here"
```
## 使用方式
### 方法 1: 互動式命令列
最簡單的使用方式：
```bash
python main.py --mode interactive
```
然後輸入您的天氣查詢：
```
🌤️ Weather query: Tokyo weather
🌤️ Weather query: 台北未來6小時天氣
🌤️ Weather query: viz London # 顯示視覺化圖表
```
### 方法 2: Python 程式
建立一個 `my_weather.py` 檔案：
```python
from weather_mcp import WeatherMCPClient
# 建立客戶端
client = WeatherMCPClient()
# 查詢城市天氣
result = client.get_city_weather("Tokyo", hours=12)
if "weather" in result:
weather = result["weather"]["hourly"]
temps = weather["temperature_2m"]
print(f"Tokyo 溫度範圍: {min(temps):.1f}°C - {max(temps):.1f}°C")
```
執行：
```bash
python my_weather.py
```
### 方法 3: 使用 LangChain Agent（需要 API Key）
```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("日本東京未來6小時會下雨嗎？")
print(answer)
```
### 方法 4: 資料視覺化
```python
from weather_mcp import WeatherMCPClient, create_visualizer
client = WeatherMCPClient()
result = client.get_city_weather("Tokyo", hours=12)
if "weather" in result:
visualizer = create_visualizer()
# 建立圖表
fig = visualizer.plot_weather_overview(
result["weather"],
"Tokyo Weather Forecast"
)
# 儲存圖表
fig.savefig("tokyo_weather.png", dpi=150, bbox_inches='tight')
print("圖表已儲存為 tokyo_weather.png")
```
## 執行範例程式
專案包含完整的使用範例：
```bash
python examples/simple_usage.py
```
這會執行：
- ✅ 基本客戶端查詢
- ✅ LangChain Agent 示範（需要 API Key）
- ✅ 資料視覺化
- ✅ 進階錯誤處理
## 主程式模式
`main.py` 支援多種模式：
### 客戶端測試模式
```bash
python main.py --mode client
```
### Agent 測試模式
```bash
python main.py --mode agent --api-key YOUR_KEY
```
### 視覺化測試模式
```bash
python main.py --mode viz
```
### MCP 伺服器模式
```bash
python main.py --mode server
```
## 常用功能
### 1. 查詢城市經緯度
```python
client = WeatherMCPClient()
geo = client.geocode_city("Tokyo")
print(geo)
# {'city': 'Tokyo', 'display_name': 'Tokyo, Japan', 'coord': {'lat': 35.6895, 'lon': 139.6917}}
```
### 2. 查詢指定座標天氣
```python
weather = client.get_weather(35.6895, 139.6917, hours=6)
print(weather["hourly"]["temperature_2m"])
```
### 3. 一次性查詢城市天氣
```python
result = client.get_city_weather("London", hours=12)
print(result["display_name"]) # London, United Kingdom
print(result["weather"]["hourly"]["temperature_2m"])
```
### 4. 產生天氣統計摘要
```python
from weather_mcp import create_visualizer
visualizer = create_visualizer()
summary = visualizer.get_weather_summary(weather_data)
print(f"溫度範圍: {summary['temperature']['min']:.1f}°C - {summary['temperature']['max']:.1f}°C")
```
## 支援的城市
內建中英文地名對照：
| 中文 | 英文 |
|------|------|
| 日本/東京 | Tokyo |
| 台灣/台北 | Taipei |
| 中國/北京 | Beijing |
| 韓國/首爾 | Seoul |
| 美國/華盛頓 | Washington |
| 英國/倫敦 | London |
| 法國/巴黎 | Paris |
| 德國/柏林 | Berlin |
也可以直接使用任何城市名稱，會自動透過 Open-Meteo API 查詢。
## 常見問題
### Q: 如何取得 Google API Key？
A: 前往 [Google AI Studio](https://makersuite.google.com/app/apikey) 申請免費 API Key。
### Q: 不設定 API Key 可以使用嗎？
A: 可以！基本的天氣查詢功能不需要 API Key，只有 LangChain Agent 功能需要。
### Q: 支援哪些天氣資料？
A:
- 溫度（Temperature）
- 相對濕度（Relative Humidity）
- 降水機率（Precipitation Probability）
- 風速（Wind Speed）
### Q: 可以查詢幾天的天氣？
A: 目前支援 1-24 小時的逐時預報。
### Q: 圖表無法顯示怎麼辦？
A: 確認已安裝 matplotlib，並在 Jupyter 環境中使用 `%matplotlib inline`。
## 下一步
- 📚 閱讀完整 [README.md](../README.md)
- 🧪 查看 [測試文件](TESTING.md)
- 🔧 探索原始碼：`src/weather_mcp/`
- 💡 運行範例：`examples/simple_usage.py`
## 需要協助？
- 提交問題：[GitHub Issues](https://github.com/weather-mcp/weather-mcp/issues)
- 查看範例：`examples/` 目錄
- 閱讀測試：`tests/` 目錄
---
享受使用 Weather MCP！🌤️
