@bashcat/cwa-mcp-weather/README.md

MCP 伺服器整合中央氣象署 (CWA) 開放資料 API - 完整支援所有15個天氣工具

# CWA Weather MCP Server

🌤️ **中央氣象署開放資料 MCP 伺服器** - 完整支援台灣中央氣象署所有開放資料 API 類別，提供精美格式化的天氣資訊查詢。

[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-0.6.0-green.svg)](https://github.com/modelcontextprotocol/typescript-sdk)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## ✨ 主要特色

- 🌍 **完整 API 支援** - 涵蓋預報、觀測、地震海嘯、警特報、天文等所有類別
- 📱 **精美格式化** - 所有回應皆為易讀的文字格式，避免原始 JSON 輸出
- 📚 **互動式指南** - 內建工具使用指南，提供詳細說明、參數解釋和實用範例
- 🤖 **LLM 優化** - 避免循環調用問題，智能建議單地點查詢
- ⚡ **即插即用** - 只需配置 CWA_API_KEY 即可使用
- 🔧 **完善錯誤處理** - 友好的錯誤訊息和連線測試功能

## 📊 測試狀態

✅ **全功能測試通過率：16/16 (100%)**

所有 16 個 CWA 天氣工具已通過完整測試，確保生產環境可用。最新新增工具使用指南功能，提供完整的使用說明和範例。

## 🛠️ 支援的 API 類別

### 📊 預報類 (3 個工具)

- `get_county_weather` - 縣市 36 小時天氣預報
- `get_township_weather` - 鄉鎮詳細天氣預報
- `get_tidal_forecast` - 潮汐預報（需指定地點和日期）

### 🌡️ 觀測類 (4 個工具)

- `get_weather_station_data` - 氣象站即時觀測
- `get_rainfall_data` - 雨量站觀測資料
- `get_current_weather` - 現在天氣觀測
- `get_uv_index` - 紫外線指數

### 🌍 地震海嘯類 (2 個工具)

- `get_earthquake_report` - 地震報告（顯著/小區域有感）
- `get_tsunami_info` - 海嘯資訊

### ⚠️ 警特報類 (2 個工具)

- `get_weather_warning` - 天氣警特報
- `get_typhoon_info` - 颱風路徑和警報 ✅ **已修復**

### 🌙 天文類 (2 個工具)

- `get_sunrise_sunset` - 日出日沒時刻
- `get_moonrise_moonset` - 月出月沒時刻

### 🔧 系統工具 (3 個工具)

- `list_cwa_apis` - 列出所有可用 API
- `test_cwa_connection` - 測試 API 連線狀態
- `get_tool_usage_guide` - 🆕 **工具使用指南** - 提供詳細的使用說明和範例

## 快速開始

### 安裝依賴

```bash
npm install
```

### 設定環境變數

建立 `.env` 檔案並設定您的 CWA API 授權碼：

```env
CWA_API_KEY=您的CWA_API授權碼
```

### 編譯與執行

```bash
npm run build
npm start
```

### 開發模式

```bash
npm run dev
```

## 使用方式

### 1. 查詢縣市天氣預報

使用 `get_county_weather` 工具查詢縣市等級的天氣預報：

```typescript
// 查詢台北市今明36小時天氣預報
{
  "locationName": "臺北市",
  "elementName": ["Wx", "PoP", "MinT", "MaxT"]
}
```

### 2. 查詢鄉鎮天氣預報

使用 `get_township_weather` 工具查詢鄉鎮等級的天氣預報：

```typescript
// 查詢桃園市中壢區未來3天天氣預報
{
  "county": "桃園市",
  "period": "3days",
  "locationName": "中壢區"
}
```

### 3. 查看工具使用指南

使用 `get_tool_usage_guide` 工具查看所有工具的詳細使用說明：

```typescript
// 查看所有工具使用指南
{}

// 查看特定工具的詳細說明
{
  "toolName": "get_county_weather"
}

// 按類別查看工具
{
  "category": "forecast"
}
```

### 4. 列出可用 API

使用 `list_cwa_apis` 工具查看所有可用的 CWA API 端點。

## API 支援

### 縣市預報

- `F-C0032-001`: 一般天氣預報-今明 36 小時天氣預報

### 鄉鎮預報

支援全台 22 個縣市的 3 天和 1 週天氣預報：

- 宜蘭縣、桃園市、新竹縣、苗栗縣、彰化縣、南投縣
- 雲林縣、嘉義縣、屏東縣、臺東縣、花蓮縣、澎湖縣
- 基隆市、新竹市、嘉義市、臺北市、高雄市、新北市
- 臺中市、臺南市、連江縣、金門縣

## 環境變數

| 變數名稱    | 必要 | 說明                         |
| ----------- | ---- | ---------------------------- |
| CWA_API_KEY | ✅   | 中央氣象署開放資料平台授權碼 |

## 授權碼申請

1. 前往 [中央氣象署開放資料平台](https://opendata.cwa.gov.tw/)
2. 註冊會員並登入
3. 在會員中心取得您的授權碼
4. 將授權碼設定到環境變數 `CWA_API_KEY`

## 許可證

MIT License