mcp-server-weather-cuhksz 0.2.2

CUHK-SZ Weather MCP Server

MCP Weather 服务器 (mcp_server_weather_cuhksz)

该目录包含了基于和风天气 (QWeather) API、为 MCP 提供天气相关工具的 FastMCP 服务器实现。

一个基于和风天气 (QWeather) API、为语言模型提供天气相关工具的 FastMCP 服务器。

📋 目录

• ✨ 项目描述
• 🎯 核心功能
• 🛠️ 可用工具
• ⚙️ 操作模式
• 🚀 安装与部署
• 🏗️ 项目架构
• 🧪 测试说明
• 🔧 故障排除
• 📄 许可证

✨ 项目描述

本项目基于 FastMCP 框架，将多个和风天气 API 端点封装为标准的 MCP 工具，使语言模型能够轻松地查询实时天气、天气预报、灾害预警和生活指数等信息。

🎯 核心功能

• 丰富工具集: 提供从城市搜索到未来15天天气预报、逐小时预报、灾害预警等多种实用工具。
• 双重操作模式: 支持直连和风天气 API 或通过 unified-api 代理服务运行，灵活适应不同部署需求。
• 动态配置: 通过环境变量在运行时动态决定连接目标，无需修改代码即可切换模式。
• 容器化设计: 提供完整的 Docker 和 Docker Compose 配置，实现一键部署和隔离环境。
• 内置缓存: 对 API 请求结果进行缓存，提高响应速度并减少不必要的 API 调用。

🛠️ 可用工具

---

1. get_location_id

调用和风天气城市搜索，返回含 Location ID 的详细地点列表。注意⚠️: 在调用其他需要地理位置的工具前，必须先调用此工具获取 Location ID。

• 参数说明:
  • location (string): 必须。查询关键字，可以是城市名称、经度,纬度、LocationID 或 Adcode（中国行政区划代码）。例如 "北京" 或 "116.41,39.92"。
  • adm (string): 可选。上级行政区过滤，如 "beijing" 或 "江西省"。
  • search_range (string): 可选。搜索范围，ISO 3166 国家/地区代码，如 "cn"。
  • number (int): 可选。返回数量，取值范围 1-20，默认为 1。
  • lang (string): 可选。语言设置，支持 'zh' (默认) 或 'en'。

---

2. get_daily_weather

获取指定地点未来多天的逐日天气预报。

• 参数说明:
  • days (string): 必须。预报天数，可选值为 '3d', '7d', '10d', '15d', '30d'。
  • location (string): 必须。地理位置参数，必须是 get_location_id 返回的 LocationID 或 经度,纬度 格式。例如 "101010100"。
  • lang (string): 可选。语言设置，支持 'zh' (默认) 或 'en'。
  • unit (string): 可选。单位制，支持 'm' (公制，默认) 或 'i' (英制)。

---

3. get_hourly_weather

获取指定地点未来多小时的逐小时天气预报。

• 参数说明:
  • hours (string): 必须。预报小时数，可选值为 '24h', '72h', '168h'。
  • location (string): 必须。地理位置参数，同上。
  • lang (string): 可选。语言设置，支持 'zh' (默认) 或 'en'。
  • unit (string): 可选。单位制，支持 'm' (公制，默认) 或 'i' (英制)。

---

4. get_weather_warning_now

查询指定地点的实时气象灾害预警信息。

• 参数说明:
  • location (string): 必须。地理位置参数，同上。
  • lang (string): 可选。语言设置，支持 'zh' (默认) 或 'en'。

---

5. get_weather_indices

查询指定地点的天气生活指数。

• 参数说明:
  • days (string): 必须。预报天数，可选值为 '1d' 或 '3d'。
  • location (string): 必须。地理位置参数，同上。
  • lang (string): 可选。语言设置，支持 'zh' (默认) 或 'en'。

⚙️ 操作模式

服务器可在以下两种模式之一运行，由 IS_UNIFIED_API 环境变量控制。

1. 统一 API 代理模式 (Unified API Proxy Mode) - 推荐

• 描述: 在此模式下，服务器作为 unified-api 代理服务的客户端。它将所有天气 API 请求转发到该代理，由代理负责账户选择、负载均衡和认证。这是生产环境或多账户部署场景下的推荐模式。
• 配置 (IS_UNIFIED_API=true):
  • IS_UNIFIED_API: 必须设置为 true。
  • UNIFIED_API_HOST: unified-api 服务的 URL (例如 http://unified-api:6380 或 http://host.docker.internal:6380)。

2. 直连 API 模式 (Direct API Mode)

• 描述: 在此模式下，服务器直接连接到和风天气 API，并使用本地配置的凭证生成 JWT 进行认证。此模式适用于本地开发和独立测试。
• 配置 (IS_UNIFIED_API=false):
  • IS_UNIFIED_API: 必须设置为 false。
  • WEATHER_API_HOST: 和风天气 API 的 URL (例如, https://api.qweather.com)。
  • QWEATHER_KEY_ID, QWEATHER_PROJECT_ID, QWEATHER_PRIVATE_KEY: 您的和风天气凭证。

🚀 安装与部署

本项目设计为在 Docker 环境中运行。

1. 集成部署 (统一 API 代理模式) - 推荐

此方法会同时启动 mcp-server、unified-api 和 redis 服务，是完整的生产和测试部署方案。

a. 环境准备

• 安装 Docker 和 Docker Compose。
• 确保项目根目录下的 .env 文件和 unified_api/ 目录下的配置文件已准备就绪。

b. 启动服务

在项目根目录下执行：

# 构建并以守护进程模式启动所有服务
docker-compose up --build -d

# 查看 mcp-server 的实时日志
docker-compose logs -f mcp-server

# 停止所有服务
docker-compose down

服务启动后，将在 http://localhost:3003 上提供 MCP 接口。根 docker-compose.yml 会自动设置 IS_UNIFIED_API=true。

2. 独立部署 (直连 API 模式)

此方法仅用于单独运行和测试 mcp-server。

a. 配置凭证

在 src/mcp_server_weather_cuhksz/ 目录下创建一个 .env 文件，并填入“直连 API 模式”所需的 QWEATHER_* 变量。

b. 启动服务

从 src/mcp_server_weather_cuhksz/ 目录内部执行：

docker-compose up --build -d

🏗️ 项目架构

模块关系

本项目由两个核心服务组成：

• mcp-server-weather (本项目): 作为 MCP 层，将业务逻辑（天气查询）封装为语言模型可调用的工具。
• unified-api: 作为代理和认证层，管理多个和风天气账户，实现负载均衡和统一的 API 访问入口。

关键设计：运行时动态配置

为了确保配置的灵活性和可靠性，本项目采用以下策略：

1. 集中化配置入口: 所有配置逻辑都集中在主入口 __main__.py 中，由它根据环境变量决定最终的操作模式和 API Host。
2. 运行时动态解析: 核心逻辑模块 mcp_weather.py 中的工具函数在被调用时，才通过 os.getenv(...) 动态获取配置。这确保了工具总是使用最新的、由容器编排工具注入的正确配置，避免了因 Python 模块导入时序问题导致的配置固化。

这种设计确保了由 Docker Compose 注入的配置始终拥有最高优先级，使得服务行为在不同部署环境中一致且可靠。

🧪 测试说明

项目提供了一个自动化测试脚本 test/test.py，用于验证所有 MCP 工具的基本功能。

运行测试

1. 启动服务: 确保服务已通过 docker-compose up -d (在项目根目录) 成功启动。
2. 执行脚本: 在您的本地 Python 环境中（需要安装 fastmcp 客户端库），运行测试：

   # 建议在项目的虚拟环境中运行
   python test/test.py
   

脚本会自动连接 http://localhost:3003 的服务，发现并调用所有可用工具，然后打印出结果或错误信息。

🔧 故障排除

常见问题

1. 工具调用时出现 Name or service not known 错误

• 症状: test/test.py 或其他客户端调用工具时，返回类似 [Errno -2] Name or service not known 的网络错误。
• 原因: mcp-server 容器无法通过其配置的 UNIFIED_API_HOST 地址连接到 unified-api 服务。
• 解决方案:
  • 检查根 docker-compose.yml 文件中 mcp-server 服务的 UNIFIED_API_HOST 环境变量。
  • 对于 Docker for Mac/Windows，推荐使用 http://host.docker.internal:6380，它会指向宿主机的网络。
  • 如果在 Linux 上，您可能需要配置 extra_hosts 或确保两个服务在同一个自定义的 bridge network 中，并使用服务名 http://unified-api:6380 进行通信。

2. unified-api 服务健康检查失败

• 症状: docker-compose up 过程中 mcp-server 等待 unified-api 超时。
• 原因: unified-api 容器未能正常启动。可能是 accounts.yaml 配置错误、私钥文件缺失或路径不正确。
• 解决方案: 使用 docker-compose logs unified-api 查看其详细日志，定位并修复问题。

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。