MCP Weather Sample

一個完整的 Model Context Protocol (MCP) 示範專案，展示如何整合天氣服務與多種 AI 模型。

專案簡介

MCP Weather Sample 是一個基於 MCP (Model Context Protocol) 的示範應用程式，展示如何建立一個完整的客戶端-伺服器架構，整合天氣 API 服務與多種 AI 模型 (Claude、GPT、Gemini)。專案支援兩種傳輸模式：STDIO 和 SSE (Server-Sent Events)，提供靈活的部署選項。

核心功能

• 🌤️ 天氣查詢服務: 整合 NOAA Weather API，提供即時天氣預報和警報
• 🤖 多 AI 模型支援: 支援 Anthropic Claude、OpenAI GPT 和 Google Gemini 模型
• 🔄 雙傳輸模式: 支援 STDIO（本地）和 SSE（遠端）兩種連接方式
• 🔐 安全認證: 內建 API 金鑰驗證機制
• ⚡ 異步架構: 全面使用 Python asyncio 提供高效能處理
• 🛠️ 工具導向: 基於 MCP 工具呼叫模式的 AI 互動

技術亮點

• 現代 Python: 使用 Python 3.12+ 的最新特性
• FastAPI 整合: 使用 FastAPI 和 FastMCP 建構 SSE 伺服器
• 模組化設計: 清晰的客戶端和伺服器分離架構
• 配置驅動: 透過 JSON 配置文件管理多伺服器設定

技術堆疊

核心框架

• Python 3.12+: 主要開發語言
• MCP >=1.12.2: Model Context Protocol 核心框架
• FastAPI >=0.116.1: 現代 Web 框架（SSE 模式）
• FastMCP: 基於 FastAPI 的 MCP 伺服器實現

AI 模型整合

• Anthropic >=0.59.0: Claude AI 模型
• OpenAI >=1.97.1: GPT 模型
• Google GenAI >=1.27.0: Gemini 模型

網路與資料處理

• httpx >=0.28.1: 異步 HTTP 客戶端
• jsonschema >=4.25.0: JSON Schema 驗證
• python-dotenv >=1.1.1: 環境變數管理

快速開始

環境需求

• Python 3.12 或更高版本
• UV 套件管理器（建議）或 pip
• 有效的 API 金鑰：
  • NOAA Weather API（免費）
  • AI 模型 API 金鑰（Anthropic、OpenAI 或 Google）

安裝步驟

1. 複製專案

   git clone <repository-url>
   cd mcp-sample
   

2. 安裝依賴

   # 使用 UV（建議）
   uv sync
   

3. 配置環境變數

   # 建立 .env 檔案
   cp .env.example .env
   
   # 編輯 .env 檔案，添加您的 API 金鑰
   ANTHROPIC_API_KEY=your_anthropic_key
   OPENAI_API_KEY=your_openai_key
   GOOGLE_API_KEY=your_google_key
   

4. 設定伺服器配置

   檢查並修改 servers-config.json 檔案中的設定：

   {
     "mcpServers": {
       "sse_weather": {
         "type": "sse",
         "url": "http://localhost:8080/sse",
         "accessToken": "your_access_token"
       },
       "stdio_weather": {
         "type": "stdio",
         "command": "uv",
         "args": ["run", "python", "weather.py"],
         "cwd": "src/servers/weather/stdio"
       }
     }
   }
   

   註意： your_access_token 設定在 src/servers/weather/sse/user_db.py 中。

    users = {
        "felix": {
            "api_key": "password123",
            "full_name": "Felix Kewa",
            "role": "admin"
        },
        "alice": {
            "api_key": "alicepass456",
            "full_name": "Alice Johnson",
            "role": "developer"
        },
        "bob": {
            "api_key": "bobsecret789",
            "full_name": "Bob Smith",
            "role": "viewer"
        }
    }   
   

基本使用範例

1. 啟動 SSE 天氣伺服器

uv run src/servers/weather/sse/mcp-weather.py

2. 啟動 MCP 客戶端

# 在另一個終端機中
uv run src/client/client.py

3. 基本天氣查詢

MCP Client Started!
Type your queries or 'quit' to exit.

Query: 阿拉巴馬州是否有天氣警報？
Calling tool get_alerts with args {'state': 'AL'}]
是的，阿拉巴馬州有多個天氣警報生效中：

**高溫警告
**
*   **北阿拉巴馬州與田納西州中南部部分地區**：預計酷
熱指數將高達華氏106度。
*   **阿拉巴馬州西南部、佛
羅里達州西北部與密西西比州東南部部分地區**：預計酷熱指數將高達
華氏109度。
*   **阿拉巴馬州中部**：包括 Autauga、Bibb
、Blount、Bullock、Calhoun、Chilton、Coosa、Dallas、Elmore、Etowah、F
ayette、Greene、Hale、Jefferson、Lamar、Lowndes、Macon、Marengo、Marion、Montgomery、Perry
、Pickens、Pike、Shelby、St. Clair、Sumter、Talladega、Tallapoosa、Tus
caloosa、Walker 與 Winston 等郡，預計酷熱指數將高達華氏106度。

高溫與高濕度可能導致與高溫相關的疾病。建議多喝水、待在有空調
的室內、避免日曬，並關心親友鄰居。在戶外時需格外小心，穿
著輕便寬鬆的衣物，並盡量將劇烈活動安排在清晨或傍晚。

**
離岸流聲明**
*   **阿拉巴馬州沿海地區（Mobile Coastal, Baldwin Coastal）
與佛羅里達州沿海地區**：有危險的離岸流。離岸流即使對
泳技最好的人也可能造成危險，將他們從岸邊捲入深水區。建議在有救生員
看管的區域游泳。若被捲入離岸流，請保持冷靜並漂浮，不要逆
流游泳。

架構概覽

graph TB
    subgraph "客戶端層"
        Client[MCP Client]
        Host[MCP Host]
        AI[AI Models]
    end
    
    subgraph "傳輸層"
        STDIO[STDIO Transport]
        SSE[SSE Transport]
    end
    
    subgraph "伺服器層"
        StdioServer[STDIO Weather Server]
        SSEServer[SSE Weather Server]
    end
    
    subgraph "外部服務"
        Weather[NOAA Weather API]
    end
    
    Client --> Host
    Host --> AI
    AI --> Host
    Host --> STDIO
    Host --> SSE
    STDIO --> StdioServer
    SSE --> SSEServer
    StdioServer --> Weather
    SSEServer --> Weather

主要元件

MCP 客戶端 (src/client/client.py)

• MCPClient: 單一 MCP 伺服器連接管理
• MCPHost: 多伺服器管理和 AI 模型整合
• ModelVendor: AI 模型供應商枚舉

天氣伺服器

• STDIO 模式 (src/servers/weather/stdio/weather.py): 本地標準輸入輸出連接
• SSE 模式 (src/servers/weather/sse/mcp-weather.py): HTTP SSE 遠端連接

提供的工具

• get_alerts: 獲取美國州份的天氣警報
• get_forecast: 獲取指定座標的詳細天氣預報

進階功能

工具權限控制

透過 servers-config.json 精確控制每個伺服器可使用的工具：

{
  "allowedTools": ["get_alerts", "get_forecast"],
  "notAllowedTools": ["get_forecast"]
}

API 金鑰管理

SSE 模式支援多種認證方式：

• HTTP Header: x-api-key
• Bearer Token: Authorization: Bearer <token>
• Query Parameter: ?api_key=<key>

文件導覽

• 快速開始指南: 詳細的安裝和設定教學
• 使用者指南: 完整的使用說明和範例
• 開發者指南: 開發環境設定和貢獻指南
• 架構文件: 系統架構深度解析

授權條款

本專案採用 MIT 授權條款。

貢獻指南

歡迎參與專案貢獻！請參閱 貢獻指南 了解如何：

• 回報問題
• 提交功能請求
• 提供程式碼貢獻
• 改進文件

支援與回饋

如有問題或建議，請：

1. 查閱 常見問題
2. 搜尋現有的 Issues
3. 建立新的 Issue 或 Discussion

---

開始您的 MCP 之旅！ 🚀 探索如何用 Model Context Protocol 建構智慧應用程式。