AI导哈

天气数据协议服务

一个为美国国家气象局API提供全面天气数据访问的模型上下文协议服务器，特别关注火险天气监测和警报。

  • by tyson-swetnam
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 tyson-swetnam/weather-mcp

使用说明

天气-MCP（或“气象-MCP”，具体翻译取决于MCP在此上下文中的具体含义，但通常MCP可能代表某种特定的气象或天气相关系统/模块）

国家气象局API的模型上下文协议（MCP）服务器，提供全面的天气数据访问，特别关注火灾天气监测和警报。

特点/功能

🔥 火灾天气监测

  • 红旗警告实时火灾天气警报和预警
  • 火灾天气区域特定区域的预测和状况
  • 火灾天气预报按办事处划分的详细FWF产品

🌤️ 天气数据

  • 点预测2.5公里分辨率的7天预报
  • 网格数据包含所有参数的原始预报网格数据
  • 气象站观测站元数据和数据
  • 天气预警按区域或位置查看所有生效中的天气警报

📊 数据格式

  • 支持GeoJSON的JSON-LD
  • 符合CAP标准的警报格式
  • 可用的OpenAPI规范
  • 实时更新，速率限制宽松

安装

# Clone the repository
git clone https://github.com/tyson-swetnam/weather-mcp.git
cd weather-mcp

# Install dependencies
npm install

# Build the project
npm run build

配置

国家气象局（NWS）API目前无需API密钥，但需要设置User-Agent头部。在“中”进行配置 .env：

# Optional: Custom User-Agent (defaults to weather-mcp/1.0.0)
NWS_USER_AGENT="YourApp/1.0.0 (your.email@example.com)"

# Optional: Rate limiting (requests per second)
NWS_RATE_LIMIT=5

# Optional: Cache settings (in seconds)
CACHE_TTL_ALERTS=300      # 5 minutes
CACHE_TTL_FORECAST=3600   # 1 hour
CACHE_TTL_STATIONS=86400  # 24 hours

快速入门

查看 安装指南 以下是详细的安装说明，针对：

  • Claude Desktop（可译为“Claude桌面版”或保持原样，根据上下文判断是否需要具体翻译） - 桌面应用程序
  • 克劳德·科德 - CLI 工具
  • 克莱恩（Cline，根据上下文，此处为人名或特定术语的音译，具体含义需结合语境） - VSCode 扩展

基本设置

# Build the project
npm run build

# Start the MCP server
npm start

使用Claude Desktop进行配置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "weather-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/weather-mcp/dist/index.js"],
      "env": {
        "NWS_USER_AGENT": "weather-mcp/1.0.0 (your.email@example.com)"
      }
    }
  }
}

配置完成后重启Claude桌面版。参见 `docs/SETUP.md` 翻译成中文是：“文档/设置指南.md” 为克劳德·科德（Claude Code）和克莱恩（Cline）的设置。

作为图书馆

const { WeatherMCP } = require('weather-mcp');

const weatherMCP = new WeatherMCP({
  userAgent: 'MyApp/1.0.0',
  cacheEnabled: true
});

// Get Red Flag Warnings for Arizona
const warnings = await weatherMCP.getFireWeatherAlerts({
  area: 'AZ',
  urgency: 'Immediate'
});

// Get forecast for a location
const forecast = await weatherMCP.getPointForecast({
  latitude: 33.4484,
  longitude: -112.0740
});

可用工具

火灾天气工具

get_fire_weather_alerts

获取最新的红旗预警和火险天气警报。

参数：

  • area州代码（例如，“AZ”，“NM”）
  • point纬度/经度坐标
  • zone火灾天气区域ID
  • urgency按紧急程度筛选（立即、预期、未来）

示例：

{
  "tool": "get_fire_weather_alerts",
  "arguments": {
    "area": "AZ",
    "urgency": "Immediate"
  }
}

get_fire_weather_zone

获取详细的火灾天气区域信息。

参数：

  • zoneId火灾天气区域标识符（例如，“AZZ149”）

示例：

{
  "tool": "get_fire_weather_zone",
  "arguments": {
    "zoneId": "AZZ149"
  }
}

get_fire_weather_forecast

获取火灾天气预报（FWF）产品。

参数：

  • officeNWS办公室代码（例如，“PSR”代表凤凰城）
  • zone特定火灾区域（可选）

天气数据工具

get_point_forecast

获取特定地点的7天天气预报。

参数：

  • latitude十进制度数表示的纬度
  • longitude经度（十进制度数）
  • units“us”（默认）或“si”

示例：

{
  "tool": "get_point_forecast",
  "arguments": {
    "latitude": 33.4484,
    "longitude": -112.0740,
    "units": "us"
  }
}

get_gridpoint_forecast

获取原始预报网格数据。

参数：

  • office网格办公室（例如，“PSR”）
  • gridX网格X坐标
  • gridY网格Y坐标

get_weather_stations

获取气象站信息。

参数：

  • state国家代码
  • limit最大车站数量

get_active_alerts

获取所有有效的天气警报。

参数：

  • area国家或海域代码
  • point纬度/经度坐标
  • region地区代码
  • zone预测区域
  • urgency即时的、预期的、未来的、过去的
  • severity极端、严重、中度、轻微
  • certainty观察到，可能，有可能，不太可能

响应格式

所有工具均返回结构化的JSON响应：

{
  "success": true,
  "data": {
    // Tool-specific data
  },
  "metadata": {
    "source": "api.weather.gov",
    "timestamp": "2024-10-14T12:00:00Z",
    "cached": false
  }
}

火灾与天气综合考量

这款MCP服务器针对火灾天气监测进行了优化，并能与火灾管理系统良好集成：

红旗预警监测

// Monitor Red Flag Warnings for Southwest states
const warnings = await weatherMCP.monitorFireWeather({
  states: ['AZ', 'NM', 'TX'],
  alertTypes: ['Red Flag Warning', 'Fire Weather Watch'],
  callback: (alert) => {
    console.log(`New alert: ${alert.event} for ${alert.areaDesc}`);
  }
});

火灾天气区域分析

// Get fire danger for specific zones
const zones = ['AZZ149', 'AZZ150', 'NMZ106'];
const zoneData = await Promise.all(
  zones.map(zone => weatherMCP.getFireWeatherZone({ zoneId: zone }))
);

与Fire API的集成

设计为与其他火灾管理MCP工具协同工作：

  • 结合NIFC火灾周边数据
  • 与NASA FIRMS热点检测进行关联
  • 结合了RAWS气象站数据进行增强
  • 与空气质量监测进行交叉参照

发展

项目结构

weather-mcp/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── server.ts          # Server implementation
│   ├── tools/             # Tool implementations
│   │   ├── fireWeather.ts
│   │   ├── forecast.ts
│   │   ├── alerts.ts
│   │   └── stations.ts
│   ├── api/              # NWS API client
│   │   ├── client.ts
│   │   ├── endpoints.ts
│   │   └── types.ts
│   ├── cache/            # Caching layer
│   └── utils/            # Utilities
├── test/                 # Tests
├── examples/             # Usage examples
└── docs/                 # Documentation

测试

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Test specific endpoint
npm run test:endpoint -- --grep "fire weather"

建筑；大楼

# Development build
npm run build:dev

# Production build
npm run build

# Watch mode
npm run watch

API 速率限制

NWS API的调用频率限制非常宽松：

  • 目前未实施严格的速率限制
  • 建议：持续5个请求/秒
  • 突发：短时间内可达每秒20个请求
  • 当受限时提供的“Retry-After”头部
  • 需要 User-Agent 头信息

缓存策略

针对不同数据类型的优化缓存：

  • 警报5分钟缓存（关键实时数据）
  • 预测1小时缓存（每小时更新）
  • 网格数据30分钟缓存
  • 站点元数据24小时缓存
  • 火灾区域12小时缓存

错误处理

全面的错误处理，支持重试：

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retryAfter": 5,
    "details": {
      "endpoint": "/alerts/active",
      "timestamp": "2024-10-14T12:00:00Z"
    }
  }
}

相关项目

做出贡献

欢迎投稿！请阅读我们的 贡献指南 详情见下文。

许可证

GNU通用公共许可证第3版 - 参见 许可证 详情请查阅文件。

致谢

  • 国家气象局为公众提供API
  • 西南协调中心的火灾天气需求
  • MCP社区关于协议规范

文档

全面的文档可在以下位置获取： 文档/ 目录：

支持

对于问题、疑问或建议：

相关 MCP