clima (Kode Rex)

气象MCP-国家气象局版

一个全面的模型上下文协议（MCP）服务器，提供 完全免费 使用美国国家气象局API的天气数据。采用FastMCP构建，用于现代AI助手集成。

特性

核心天气特征

• 零成本：美国政府提供的完全免费的天气数据
• 没有API密钥：无需注册或身份验证
• FastMCP集成：使用FastMCP框架的现代MCP服务器
• 美国国家气象局API：可靠的美国政府官方天气数据
• 实时更新：SSE支持实时天气数据流
• 天气警报：免费实时天气警报和警告
• 全面覆盖：当前天气、预报和警报
• FastMCP SSE传输：带有SSE传输的单个统一服务器，用于API集成

发展特征

• 现代Python：使用Python 3.11+和现代工具构建
• 类型安全：带有MyPy验证的完整类型提示
• 代码质量：自动格式化（黑色）和linting（Ruff）
• 综合测试：56个以上测试，支持pytest和异步
• Docker支持：容器已准备好使用docker compose
• CI/CD管道：GitHub自动化测试和质量检查行动
• 开发者体验：带有方便的开发命令的Makefile
• 模块化架构：使用单独的测试文件清理服务层

安装

快速开始

1. 克隆存储库:

   git clone 
   cd clima-mcp

1. 安装依赖项:

   pip install -e ".[dev]"

1. 设置开发环境 （可选）：

   make dev-setup

1. 就是这样！ 无需API密钥-美国国家气象局API完全免费。

替代安装方法

使用Docker：

# Quick start
docker-compose up --build

# Or using Makefile
make docker-run

使用Makefile（建议用于开发）：

make install-dev
make dev-setup

用法

测试API（推荐的第一步）

clima-mcp test
# or
make run-test

您应该看到：

✓ Location search successful: 10001, Manhattan
✓ Current weather: 81.0°F, Clear
✓ 5-day forecast: 5 days retrieved
✓ Weather alerts: 1 active alerts
🎉 All NWS API tests passed!

带SSE传输的FastMCP服务器

运行带有SSE传输的统一FastMCP服务器以进行API集成：

clima-mcp run
# or
make run

服务器启动于 http://localhost:8000 通过FastMCP SSE传输，提供4个可通过HTTP/SSE访问的天气工具，用于与OpenAI和其他AI服务集成。

测试服务器

打开交互式测试客户端：

open examples/sse_client.html

天气工具

FastMCP服务器为API集成提供了4种天气工具：

核心工具

• get_weather(zip_code)：获取邮政编码的当前天气状况
• get_forecast(zip_code, days=5)：获取天气预报（1-7天）
• get_alerts(zip_code)：获取活动天气警报（完全免费！）
• search_locations(query)：按名称或邮政编码搜索位置

API集成

非常适合 OpenAI函数调用 以及其他人工智能服务集成：

# Example OpenAI function call
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a ZIP code",
            "parameters": {
                "type": "object",
                "properties": {
                    "zip_code": {"type": "string", "description": "ZIP code (e.g., '10001')"}
                },
                "required": ["zip_code"]
            }
        }
    }
]

FastMCP SSE集成

服务器使用 带SSE传输的FastMCP 用于实时API集成：

连接

Server: http://localhost:8000
Transport: SSE (Server-Sent Events)
Protocol: FastMCP

工具调用

工具可通过SSE上的FastMCP协议访问。非常适合：

• OpenAI函数调用
• Claude工具使用
• 自定义AI集成
• 实时天气API

交互式测试

启动服务器并导航到测试客户端：

clima-mcp run
# Then open: http://localhost:8000/

Clima Demo Interface

*显示科罗拉多州伊利实时天气数据的交互式测试客户端*

特征：

• 测试所有4个天气工具
• 实时响应
• 模拟数据演示
• API集成示例

示例用法

Python MCP客户端

from weather_mcp import NationalWeatherServiceClient

async with NationalWeatherServiceClient() as client:
    # Search by zip code
    locations = await client.search_locations("10001")
    location_key = locations[0]["Key"]

    # Get current weather
    weather = await client.get_current_weather(location_key)
    print(f"Temperature: {weather.temperature}°{weather.temperature_unit}")

    # Get alerts (completely free!)
    alerts = await client.get_weather_alerts(location_key)
    print(f"Active alerts: {len(alerts)}")

JavaScript SSE客户端

const eventSource = new EventSource('http://localhost:8000/weather/stream/10001');

eventSource.addEventListener('weather_update', function(event) {
    const data = JSON.parse(event.data);
    console.log(`Temperature: ${data.weather.temperature}°F`);
});

eventSource.addEventListener('weather_alert', function(event) {
    const data = JSON.parse(event.data);
    console.log(`Weather Alert: ${data.alerts[0].title}`);
});

覆盖范围

国家气象局提供全面的覆盖范围：

• 🇺🇸 美国 （所有50个州和地区）
• 邮政编码 支持轻松查找位置
• 坐标 用于精确定位
• 波多黎各、美属维尔京群岛、关岛 和其他美国领土

建筑

main.py (Legacy entry point - use CLI instead)
├── weather_mcp/
│   ├── cli.py (Main CLI with FastMCP SSE server)
│   ├── api_tools.py (FastMCP weather tools)
│   ├── nws.py (National Weather Service client)
│   ├── config.py (Configuration management)
│   ├── models.py (Pydantic data models)
│   ├── exceptions.py (Custom exceptions)
│   └── services/ (Service layer architecture)
│       ├── location_service.py
│       ├── weather_service.py
│       ├── forecast_service.py
│       ├── alert_service.py
│       ├── raw_weather_service.py
│       └── testing_service.py
├── tests/ (Comprehensive test suite)
│   ├── test_location_service.py
│   ├── test_weather_service.py
│   ├── test_forecast_service.py
│   ├── test_alert_service.py
│   ├── test_raw_weather_service.py
│   ├── test_testing_service.py
│   ├── test_weather_config.py
│   └── test_weather_server.py
├── examples/
│   └── sse_client.html (FastMCP test client)
├── .github/workflows/ (CI/CD pipelines)
├── Dockerfile & docker-compose.yml
├── pyproject.toml (Modern Python project config)
├── Makefile (Development commands)
└── .pre-commit-config.yaml (Code quality automation)

服务层架构

该应用程序遵循一个干净的面向服务的架构：

• 命令行界面：具有SSE传输的现代FastMCP服务器
• API工具：4个用于外部集成的天气功能
• 服务：天气操作的业务逻辑
• 模型：Pydantic数据验证和序列化
• 配置：基于环境的设置管理
• 异常处理：自定义异常以更好地管理错误

现代Python项目结构

该项目使用现代Python打包和工具：

• pyproject.toml：现代Python项目配置
• 拉夫：快速换行和代码格式化
• MyPy 的：静态类型检查
• 预承诺：自动质量检查
• GitHub操作：带测试和安全扫描的CI/CD
• 码头工人：容器化部署选项

技术细节

数据源

• 当前天气：NWS观测站
• 预测：NWS网格化预测数据
• 警报：NWS天气警报和警告
• 位置数据：OpenStreetMap提名地理编码

演出

• 无费率限制：API政府，无申请限制
• 缓存：内置缓存以实现最佳性能
• 异步：对并发请求的完全异步/等待支持
• 实时：SSE流媒体实时更新

可靠性

• 政府来源：美国国家气象局官方数据
• 高可用性：政府维护的基础设施
• 没有API密钥：没有身份验证失败或密钥过期
• 全面的错误处理：故障时的优雅降级

配置

服务器可以通过环境变量或 .env 文件：

# Server Configuration
HOST=localhost
PORT=8000
DEBUG=false
LOG_LEVEL=INFO

# SSE Configuration
SSE_HEARTBEAT_INTERVAL=30
SSE_MAX_CONNECTIONS=100
SSE_CONNECTION_TIMEOUT=300

# Cache Configuration
CACHE_TTL_SECONDS=300
CACHE_MAX_SIZE=1000

开发与测试

快速开发命令

该项目包括一个全面的 Makefile 为了便于开发：

# Development setup
make dev-setup          # Full development environment setup
make install-dev         # Install with development dependencies

# Code quality
make format             # Format code with Black and Ruff
make lint               # Run linting checks
make type-check         # Run MyPy type checking
make pre-commit         # Run pre-commit hooks

# Testing
make test              # Run all tests
make test-unit         # Run unit tests only
make test-integration  # Run integration tests only
make coverage          # Run tests with coverage report

# Application
make run-test          # Test the NWS API
make run               # Run FastMCP server with SSE transport

# Docker
make docker-build      # Build Docker image
make docker-run        # Run server in Docker container
make run-docker-dev    # Start development mode with hot reload
make docker-logs       # View Docker logs
make docker-stop       # Stop Docker containers

# Cleanup
make clean             # Clean build artifacts

传统测试

运行综合测试套件：

python run_tests.py

有选项：

python run_tests.py --type unit --coverage --verbose
python run_tests.py --type integration --fail-fast
python run_tests.py --parallel 4

测试覆盖率:

• 所有天气服务的单元测试（单个服务测试文件）
• MCP和SSE服务器的集成测试
• 配置验证测试
• 模拟API对CI/CD的响应
• 56项模块化结构综合测试

代码质量工具

该项目使用现代Python开发工具：

• 黑色：代码格式
• 拉夫：快速分拣和进口分拣
• MyPy 的：静态类型检查
• 预提交挂钩：自动质量检查
• Pytest：支持异步的测试框架
• GitHub操作：自动化CI/CD管道

开发工作流程

1. 设置环境:

   make dev-setup

1. 进行更改和测试:

   make format
   make lint
   make test

1. 提交更改 （预提交钩子会自动运行）：

   git add .
   git commit -m "Your changes"

Docker开发

使用Docker运行以获得一致的环境：

# Production mode
docker-compose up

# Development mode with hot reload
docker-compose --profile dev up

贡献

我们欢迎捐款！该项目包括全面的开发工具，使贡献变得容易。

开发设置

1. 分叉并克隆存储库
2. 设置开发环境:

   make dev-setup

1. 进行更改
2. 进行质量检查:

   make format        # Format code
   make lint          # Check linting
   make type-check    # Type checking
   make test          # Run tests

1. 承诺并推动 （预提交挂钩确保质量）
2. 提交拉取请求

代码质量标准

• 键入提示 所有功能都需要
• 文档字符串 对于所有公共方法
• 测试 对于新功能
• 代码格式化 与黑色
• 掉毛 遵守Ruff
• 100%测试覆盖率 对于新功能

持续集成

该项目使用GitHub Actions用于：

• 自动化测试 Python 3.11
• 代码质量检查 （格式化、换行、类型检查）
• 安全扫描 与Bandit合作
• 覆盖率报告 到Codecov
• Docker构建 验证

项目结构

• 遵循现有的服务层架构
• 在相应的测试文件中为每个新服务添加测试
• 更新新功能的文档
• 使用自定义异常类进行错误处理

许可证

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

支持

对于问题和疑问：

• 查看 美国国家气象局API文件
• 检查 模型上下文协议规范
• 在此存储库中打开问题

徽章

致谢

• 国家气象局 提供免费、可靠的天气数据
• 模型上下文协议 对于协议规范
• FastMCP 现代MCP框架
• 开放街道图 用于地理编码服务
• 优秀开发工具的Python社区（Black、Ruff、MyPy、Pytest）