MCP

🚀 天氣MCP服務器 🌤️

一個基於Model Context Protocol (MCP)的天氣查詢服務器，可依據用戶輸入的地址或自動獲取當前位置，查詢天氣信息與預報，為用戶提供便捷的天氣服務。

🚀 快速開始

本項目使用完全免費的Open - Meteo API，無需註冊或配置任何密鑰，以下是安裝與運行步驟。

✨ 主要特性

• 🌍 多種位置查詢方式：支持通過地址、座標以及當前位置進行查詢。
• 🌤️ 即時天氣信息：能夠獲取當前詳細的天氣數據。
• 📅 天氣預報：提供1 - 10天的未來天氣預報。
• 📍 地理編碼：可實現地址與座標之間的轉換。
• 💡 智能建議：根據天氣條件給出生活建議。
• 🌐 多語言支持：採用中文界面，支持全球地址查詢。
• 🔧 易於集成：遵循標準MCP協議，兼容多種AI客戶端。

📦 安裝指南

1. 克隆項目

git clone <repository - url>
cd weather - mcp - server

2. 安裝依賴

npm install

3. 編譯和運行

# 編譯TypeScript
npm run build

# 啟動服務器
npm start

# 或者開發模式（自動重編譯）
npm run dev

💻 使用示例

在Claude Desktop中使用

1. 打開Claude Desktop配置文件：
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json
2. 添加MCP服務器配置：

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/weather - mcp - server/dist/index.js"]
    }
  }
}

3. 重啟Claude Desktop

在其他MCP客戶端中使用

參考各客戶端的文檔，使用stdio傳輸協議連接到服務器：

node /path/to/weather - mcp - server/dist/index.js

可用工具調用示例

1. get - weather - by - address

根據地址獲取當前天氣信息。 參數:

• address (string): 地址，例如："北京市"、"上海市浦東新區"、"New York" 示例:

獲取北京市的天氣

2. get - forecast - by - address

根據地址獲取天氣預報。 參數:

• address (string): 地址
• days (number, 可選): 預報天數，1 - 10天，默認5天 示例:

獲取上海市未來7天的天氣預報

3. get - current - location - weather

獲取當前位置的天氣信息（基於IP地址）。 參數: 無 示例:

獲取我當前位置的天氣

4. get - current - location - forecast

獲取當前位置的天氣預報。 參數:

• days (number, 可選): 預報天數，1 - 10天，默認5天 示例:

獲取我當前位置未來3天的天氣預報

5. get - weather - by - coordinates

根據經緯度座標獲取天氣信息。 參數:

• latitude (number): 緯度， - 90到90之間
• longitude (number): 經度， - 180到180之間 示例:

獲取座標(39.9042, 116.4074)的天氣信息

6. geocode - address

將地址轉換為經緯度座標。 參數:

• address (string): 要解析的地址 示例:

解析"天安門廣場"的座標

可用資源調用示例

weather://status

顯示天氣服務的配置狀態和可用性。

可用提示調用示例

weather - assistant

天氣查詢智能助手。 參數:

• location (string, 可選): 位置信息
• query_type (enum, 可選): 查詢類型，"current"或"forecast"

示例輸出

天氣信息示例

📍 位置: Beijing, Beijing, China
🌡️ 溫度: 22°C (體感溫度: 24°C)
🌤️ 天氣: 晴
💧 溼度: 45%
💨 風速: 12 km/h (SW)
🌡️ 氣壓: 1013 mb
👁️ 能見度: 10 km
☀️ 紫外線指數: 6
🕐 更新時間: 2024 - 01 - 15 14:30

💡 建議:
☀️ 天氣較熱，穿輕便衣物
🧴 紫外線較強，建議塗抹防曬霜

天氣預報示例

📍 Beijing, Beijing, China 天氣預報

🌟 當前天氣:
溫度: 22°C (體感: 24°C)
天氣: 晴
溼度: 45% | 風速: 12 km/h

📅 未來幾天預報:
今天 (2024 - 01 - 15):
  🌡️ 18°C ~ 25°C | 晴
  💧 溼度: 45% | 🌧️ 降雨概率: 10%

明天 (2024 - 01 - 16):
  🌡️ 16°C ~ 23°C | 多雲
  💧 溼度: 55% | 🌧️ 降雨概率: 20%

🔧 技術細節

核心組件

• WeatherService：負責天氣API調用和數據格式化。
• LocationService：提供地理位置服務和地址解析功能。
• MCP Server：基於標準MCP協議的服務器實現。

依賴項

• @modelcontextprotocol/sdk：MCP協議實現。
• axios：HTTP請求庫。
• zod：數據驗證。
• dotenv：環境變量管理。

API服務商

• Open - Meteo：免費天氣數據提供商。
• Open - Meteo Geocoding：免費地理編碼服務。
• IP - API：免費IP地址定位服務。

📚 詳細文檔

項目結構

weather - mcp - server/
├── src/
│   ├── index.ts              # 主服務器文件
│   ├── weather - service.ts    # 天氣服務
│   ├── location - service.ts   # 位置服務
│   └── types.ts             # 類型定義
├── dist/                    # 編譯輸出
├── package.json
├── tsconfig.json
├── env.example
└── README.md

開發命令

# 安裝依賴
npm install

# 開發模式（自動重編譯）
npm run dev

# 編譯
npm run build

# 運行
npm start

添加新功能

1. 在相應的服務類中添加新方法。
2. 在 src/index.ts 中註冊新的工具、資源或提示。
3. 若需要，更新類型定義。
4. 重新編譯和測試。

故障排除

常見問題

1. 網絡連接問題
   • 檢查網絡連接。
   • 確認防火牆設置允許外部API訪問。
2. 地址解析失敗
   • 嘗試使用更具體的地址。
   • 檢查地址拼寫是否正確。
3. 編譯錯誤
   • 確保Node.js版本 >= 18.0.0。
   • 刪除 node_modules 和 dist 目錄後重新安裝。
4. 服務暫時不可用
   • Open - Meteo服務偶爾可能維護，請稍後重試。

調試模式

啟用詳細日誌：

DEBUG = weather - mcp - server npm start

貢獻

歡迎貢獻代碼！請遵循以下步驟：

1. Fork項目。
2. 創建功能分支 (git checkout -b feature/AmazingFeature)。
3. 提交更改 (git commit -m 'Add some AmazingFeature')。
4. 推送到分支 (git push origin feature/AmazingFeature)。
5. 創建Pull Request。

支持

如果您遇到問題或有建議，請：

1. 查看常見問題。
2. 搜索現有的Issues。
3. 創建新的Issue並詳細描述問題。

更新日誌

v1.0.0

• 初始版本發佈。
• 使用Open - Meteo免費API，無需密鑰。
• 支持基本天氣查詢功能。
• 支持地址和座標查詢。
• 支持當前位置自動檢測。
• 支持天氣預報（最多16天）。
• 提供智能天氣建議。
• 完全免費使用。

📄 許可證

本項目採用 MIT 許可證。詳見 LICENSE 文件。

享受使用天氣MCP服務器！ 🌤️✨