WeatherInfoMCP
一种MCP（模型上下文协议）服务器，通过美国国家气象局（NWS）API为人工智能代理提供对环境气象数据的访问。
特性
- 🌍 位置管理：根据地址或坐标创建位置
- 🌤️ 天气观测：从NWS站获取实时天气数据
- 📊 数据提取：提取特定的天气指标（温度、湿度、风、描述）
- ⚠️ 天气警报：获取位置的活动天气警报
- 🌡️ 热风险指南：访问HeatRisk信息和CDC仪表板链接
用法
直接从GitHub使用（无需安装）⚡
使用WeatherInfoMCP最简单的方法是直接从GitHub使用，而无需在本地克隆或安装任何东西。此方法使用 uvx （从 uv 包管理器）自动从存储库下载、安装和运行MCP服务器。
先决条件：
- 紫外线 必须安装（它提供
uvx命令）
它是如何工作的：
uvx自动创建一个隔离的环境，从GitHub安装包并运行它- 不需要本地存储库克隆
- 无手动依赖关系管理
- 始终使用存储库中的最新版本
使用OpenAI代理SDK
from agents import Agent
from agents.mcp import MCPServerStdio
# Configuration for direct GitHub usage
PARAMS_WEATHER_MCP = {
"name": "weatherinfo-mcp",
"command": "uvx",
"args": ["--from", "git+https://github.com/Babakjfard/weatherinfo_mcp.git", "weatherinfo-mcp"]
}
weather_server = MCPServerStdio(params=PARAMS_WEATHER_MCP)
agent = Agent(
name="weather-agent",
model="gpt-4",
mcp_servers=[weather_server]
)使用Claude桌面版
将其添加到您的Claude Desktop配置文件中（通常 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"weatherinfo-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/Babakjfard/weatherinfo_mcp.git", "weatherinfo-mcp"]
}
}
}这种方法的好处：
- ✅ 零设置-无克隆、无安装、无虚拟环境管理
- ✅ 始终保持最新-使用GitHub上的最新版本
- ✅ 孤立-
uvx管理隔离环境中的依赖关系 - ✅ 便携式-在任何具有以下功能的系统上都可以以相同的方式工作
uv安装
注： 第一轮可能需要一点时间 uvx 下载并设置包。由于缓存，后续运行速度更快。
作为MCP服务器
该软件包可以用作具有任何MCP兼容客户端的MCP服务器：
python -m weatherinfo_mcp.mcp_tools.main或者使用已安装的脚本：
weatherinfo-mcp使用AI代理框架
OpenAI代理SDK
如果软件包以可编辑模式安装(pip install -e . 或 uv sync)，您可以使用：
from agents import Agent
from agents.mcp import MCPServerStdio
params = {
"name": "weatherinfo-mcp",
"command": "python",
"args": ["-m", "weatherinfo_mcp.mcp_tools.main"],
# PYTHONPATH not needed if package is installed
}
weather_server = MCPServerStdio(params=params)
agent = Agent(
name="weather-agent",
model="gpt-4",
mcp_servers=[weather_server]
)如果未安装程序包，请指定源目录：
import os
project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
params = {
"name": "weatherinfo-mcp",
"command": "python",
"args": ["-m", "weatherinfo_mcp.mcp_tools.main"],
"env": {
"PYTHONPATH": os.path.join(project_root, "src")
}
}Claude桌面配置
如果安装了软件包：
{
"mcpServers": {
"weatherinfo-mcp": {
"command": "python",
"args": ["-m", "weatherinfo_mcp.mcp_tools.main"]
}
}
}如果未安装该包，请使用虚拟环境Python的完整路径并设置PYTHONPATH：
{
"mcpServers": {
"weatherinfo-mcp": {
"command": "/full/path/to/project/.venv/bin/python",
"args": ["-m", "weatherinfo_mcp.mcp_tools.main"],
"env": {
"PYTHONPATH": "/full/path/to/weatherinfo_mcp/src"
}
}
}
}备注：使用虚拟环境Python(/full/path/to/project/.venv/bin/python)确保所有依赖项都可用。
可用工具
MCP服务器提供以下工具：
create_location-根据地址或坐标创建位置对象get_current_observation-获取当前天气观测数据get_temperature_from_observation-提取温度值（摄氏度）get_humidity_from_observation-提取相对湿度（%）get_weather_description_from_observation-提取天气描述get_wind_info_from_observation-提取风速和风向get_alerts-获取某个位置的活动天气警报get_HeatRisk-获取HeatRisk指南和CDC仪表板信息
先决条件
- Python>=3.12
- 紫外线 包管理器（推荐）或pip
- 互联网连接（用于NWS API访问）
安装
使用紫外线（推荐）
- 克隆存储库：
git clone weatherinfo_mcp
cd weatherinfo_mcp- 安装依赖项并创建虚拟环境：
uv sync这将：
- 在中创建虚拟环境 .venv/ - 安装所有必需的依赖项 - 以可编辑模式安装软件包
- 激活虚拟环境（可选，但建议）：
source .venv/bin/activate- 安装笔记本依赖项（可选，用于运行示例笔记本）：
uv pip install -r notebooks/requirements.txt- 设置Jupyter内核（用于Jupyter笔记本）：
# Register the kernel with Jupyter
.venv/bin/python -m ipykernel install --user --name=weatherinfo_mcp --display-name="Python (weatherinfo_mcp)"在此之后，您将在Jupyter笔记本内核选择器中看到“Python（weatherinfo_mcp）”。
使用pip
- 克隆并导航到项目：
git clone weatherinfo_mcp
cd weatherinfo_mcp- 创建并激活虚拟环境：
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate- 安装软件包：
pip install -e .运行测试
该项目包括一个全面的测试套件，用于验证MCP协议的合规性和功能性。一旦可用，请使用以下说明：
测试的先决条件
安装测试框架依赖项：
cd tests
make install这将自动使用 uv 如果可用，或回退到 pip.
或者，手动安装：
# Using uv (if available)
uv pip install -r requirements-framework.txt
# Or using pip
pip install -r requirements-framework.txt运行所有测试
cd tests
make test-all这将运行：
- 基本MCP协议一致性测试
- WeatherInfoMCP特定功能测试
- MCP检查器集成测试
运行特定测试套件
# Base MCP protocol tests only
make test-base
# WeatherInfoMCP-specific tests only
make test-weatherinfo_mcp
# Session lifecycle tests
make test-lifecycle
# Error handling tests
make test-errors
# Simple stdio test
make test-stdio
# Verbose output
make test-verbose测试报告
测试报告保存到 tests/ 目录：
comprehensive_conformance_report.txt-完整测试结果base_conformance_report.txt-基础协议测试weatherinfo_mcp_conformance_report.txt-包装特定测试session_lifecycle_report.txt-会话管理测试error_handling_report.txt-错误处理测试
配置
该包使用NWS API，该API是免费的，不需要API密钥。该服务自动处理：
- 使用geopy进行位置地理编码
- 查找最近的NWS气象站
- 获取实时观测结果
发展
项目结构
weatherinfo_mcp/
├── src/
│ └── weatherinfo_mcp/
│ ├── __init__.py
│ ├── core/
│ │ └── nws_location_service.py # Location service
│ └── mcp_tools/
│ ├── main.py # MCP server entry point
│ └── nws_weather_tools.py # MCP tool definitions
├── tests/ # Test suite
│ ├── Makefile # Test runner
│ ├── comprehensive_stdio_tests.py # Comprehensive tests
│ ├── test_nws_location_service.py # Unit tests
│ ├── test_nws_weather_tools.py # Unit tests
│ └── ...
├── notebooks/ # Example notebooks
├── pyproject.toml # Package configuration
├── uv.lock # Dependency lock file
└── README.md # This file设置开发环境
- 按照上述安装步骤进行操作
- 根据需要安装其他开发工具：
# Install common development tools (optional)
uv pip install pytest black flake8 mypy
# Or
pip install pytest black flake8 mypy运行单个单元测试
# Using pytest
pytest tests/test_nws_location_service.py -v
pytest tests/test_nws_weather_tools.py -v
# Or using Python directly
python -m pytest tests/代码质量
# Format code (if black is installed)
black src/
# Lint code (if flake8 is installed)
flake8 src/故障排除
虚拟环境问题
如果测试失败，并显示“python：没有这样的文件或目录”：
- 确保您已激活虚拟环境：
source .venv/bin/activate - 或者Makefile将自动检测venv（如果存在）
模块导入错误
如果您收到导入错误：
# Reinstall the package in editable mode
uv sync
# Or
pip install -e .测试失败
如果测试因NWS API错误而失败：
- 检查您的互联网连接
- NWS API可能偶尔不可用（测试应妥善处理此问题）
- 某些测试失败可能是由于API暂时中断，而不是代码问题
许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
作者
我说的是j.fard。babak.jfard@gmail.com