AI导哈

天气数据服务工具

一个基于Model Context Protocol (MCP)的天气数据服务工具，提供实时天气信息和天气预报，支持GitHub Copilot集成。

  • by Abishek-Raj-M
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Abishek-Raj-M/weather-mcp-server

使用说明

气象MCP工具

使用WeatherAPI.com提供实时天气信息的模型上下文协议（MCP）服务器。此工具允许GitHub Copilot通过使用Python、Flask和Fast MCP构建的本地MCP服务器访问天气数据。

特性

  • 实时天气数据：任何地点的当前天气状况
  • 天气预报：1-10天天气预报和警报
  • 位置搜索：按名称或坐标查找位置
  • 天气警报：主动天气预警和警报
  • 缓存：遵守API速率限制的智能缓存
  • MCP集成：GitHub Copilot的完整模型上下文协议支持

快速开始

太长，读不下去了：安装后，运行 python run.py --flask 对于HTTP服务器或 python run.py 对于MCP模式。

1.设置虚拟环境

# Navigate to project directory
cd weather-mcp-tool

# Create virtual environment (REQUIRED)
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Verify activation (should show (venv) in prompt)

2.安装依赖项

# Upgrade pip
python -m pip install --upgrade pip

# Install core dependencies
pip install -r requirements.txt

# Install development dependencies (optional)
pip install -r requirements-dev.txt

3.配置环境

# Copy environment template
copy .env.example .env  # Windows
# cp .env.example .env  # macOS/Linux

# Edit .env with your configuration
# WEATHER_API_KEY=1401cb7b45b742bab23105426252509

4.运行服务器

# Start MCP server (default mode)
python run.py

# Or start Flask HTTP server
python run.py --flask

可用工具

get_current_weather

获取任何位置的当前天气状况。

# Example usage in Copilot
# "What's the current weather in New York?"

参数：

  • location （str）：城市名称、坐标或位置标识符
  • include_air_quality （bool）：包括空气质量数据（默认值：False）

get_weather_forecast

获取1-10天的天气预报。

# Example usage in Copilot  
# "Can you get me a 7-day weather forecast for London?"

参数：

  • location （str）：城市名称、坐标或位置标识符
  • days （int）：预测天数（1-10，默认值：3）
  • include_alerts （bool）：包括天气警报（默认值：False）

search_locations

按名称或坐标搜索位置。

# Example usage in Copilot
# "Find weather stations near coordinates 40.7128,-74.0060"

参数：

  • query （str）：位置搜索查询

get_weather_alerts

获取活跃的天气警报和警告。

# Example usage in Copilot
# "Are there any weather alerts for Miami today?"

参数：

  • location （str）：城市名称、坐标或位置标识符

配置

环境变量（.env文件）

# Weather API Configuration
WEATHER_API_KEY=your_api_key_here
WEATHER_API_BASE_URL=https://api.weatherapi.com/v1

# MCP Server Configuration  
MCP_SERVER_PORT=5000
MCP_SERVER_HOST=localhost

# Logging Configuration
LOG_LEVEL=INFO

# Caching Configuration
CACHE_TTL=900  # 15 minutes

GitHub复制集成

创建 ~/.config/github-copilot/mcp.json:

{
  "servers": {
    "weather": {
      "command": "path/to/weather-mcp-tool/venv/Scripts/python",
      "args": ["path/to/weather-mcp-tool/src/main.py"],
      "cwd": "path/to/weather-mcp-tool",
      "env": {
        "WEATHER_API_KEY": "1401cb7b45b742bab23105426252509"
      }
    }
  }
}

发展

运行测试

# Ensure virtual environment is activated
source venv/bin/activate  # or venv\Scripts\activate

# Run all tests
pytest

# Run with coverage
pytest --cov=src

# Run specific test file
pytest tests/test_weather_service.py -v

代码质量

# Format code
black src/

# Lint code  
flake8 src/

# Type checking
mypy src/

# Sort imports
isort src/

开发服务器

# Run Flask development server
python run.py --flask

# Run MCP server (for GitHub Copilot integration)
python run.py

API端点（烧瓶模式）

在Flask模式下运行时(--flask 或 RUN_MODE=flask):

  • GET / -服务信息
  • GET /health -健康检查
  • GET /tools -列出可用的MCP工具
  • GET /stats -服务统计和缓存信息

项目结构

weather-mcp-tool/
├── venv/                     # Virtual environment
├── src/
│   ├── __init__.py          # Package initialization
│   ├── main.py              # Main MCP server entry point  
│   ├── weather_service.py   # Weather API service
│   ├── tools.py             # MCP tool definitions
│   └── models.py            # Pydantic models
├── tests/
│   ├── test_weather_service.py
│   ├── test_tools.py
│   └── test_integration.py
├── .env                     # Environment variables
├── .env.example             # Environment template
├── requirements.txt         # Core dependencies
├── requirements-dev.txt     # Development dependencies
├── pyproject.toml          # Python project config
└── README.md               # This file

依赖项

核心依赖关系（requirements.txt）

  • mcp>=1.0.0 -模型上下文协议框架
  • flask>=2.3.0 -HTTP端点的Web框架
  • requests>=2.31.0 -API调用的HTTP客户端
  • python-dotenv>=1.0.0 -环境变量管理
  • pydantic>=2.5.0 -数据验证和序列化
  • uvicorn>=0.24.0 -ASGI服务器
  • gunicorn>=21.2.0 -WSGI服务器

开发依赖关系（requirements-dev.txt）

  • pytest>=7.4.0 -测试框架
  • pytest-cov>=4.1.0 -覆盖率报告
  • black>=23.9.0 -代码格式
  • flake8>=6.1.0 -代码linting
  • mypy>=1.6.0 -类型检查

错误处理

该系统包括全面的错误处理：

  • API错误：天气API连接问题
  • 验证错误：参数或数据无效
  • 网络错误：超时和连接问题
  • 配置错误：缺少API键或设置无效

所有错误都被正确记录并返回结构化错误响应。

缓存

天气服务实现了智能缓存：

  • 缓存TTL：15分钟获取天气数据（可配置）
  • 警报缓存：5分钟用于天气警报
  • 位置缓存：使用标准TTL（位置不经常改变）
  • 内存缓存：简单的内存缓存（可以扩展到Redis）

速率限制

尊重WeatherAPI.com的费率限制：

  • 免费套餐：每月100万次通话
  • 缓存减少了实际的API调用
  • 内置请求重复数据删除

安全

  • API密钥保护：存储在.env文件中，从不存储在代码中
  • 输入验证：所有输入都经过验证和消毒
  • 错误处理：错误响应中没有敏感数据
  • 环境隔离：使用虚拟环境

故障排除

常见问题

  1. Flask/MCP导入错误:

    • 确保虚拟环境已激活
    • 跑 pip install -r requirements.txt

  2. API密钥错误:

    • 检查 .env 文件存在并包含 WEATHER_API_KEY
    • 验证API密钥是否有效

  3. 连接错误:

    • 检查互联网连接
    • 验证WeatherAPI.com是否可访问

  4. 端口已在使用中:

    • 改变 MCP_SERVER_PORT 在 .env 文件
    • 或使用端口终止进程

调试模式

启用调试日志记录：

LOG_LEVEL=DEBUG python src/main.py

健康检查

测试服务器运行状况：

# MCP mode - check logs
python src/main.py

# Flask mode - HTTP endpoint
curl http://localhost:5000/health

贡献

  1. 复刻仓库
  2. 创建要素分支
  3. 通过测试进行更改
  4. 运行质量检查： black, flake8, mypy, pytest
  5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

其他文件

支持

对于问题和疑问：

  1. 检查故障排除部分
  2. 查看日志以了解错误详细信息
  3. 查看其他文档指南
  4. 通过以下方式打开问题：
    • 错误消息
    • 环境详细信息
    • 重现步骤

相关 MCP