SHEARLINE

SHEARLINE

为你的 Agent 提供不可或缺的强天气分析能力。 SHEARLINE 是一款免费的 MIT 许可 MCP 服务，为 AI Agent 提供专业级的美国强天气分析工具：带有基于影响的预警标签的实时预警多边形、SPC 对流展望、RAP 派生的点位环境数据 及预报趋势（使用 MetPy 计算 CAPE／风切变／SRH／STP）、MRMS 雷达派生的冰雹和旋转产品、GOES 闪电、地面实况风暴报告（实时 及历史数据），以及综合以上信息的复合威胁简报。已有十几款天气 MCP 封装了基础预报 API；SHEARLINE 刻意跳过它们已有的全部功能，只提供需要正确运用雷达气象学才能呈现的内容。

仅供参考，不能替代 NWS 官方预警。 每个工具都会重复这一点，因为这很重要：遇到天气威胁时，请遵循 weather.gov 和当地主管部门发布的官方预警。

工具

工具	返回内容
get_active_warnings(lat, lon, radius_km=40)	当前有效的龙卷风／强雷暴／山洪警报多边形及 IBW 标签（最大冰雹尺寸、最大阵风、龙卷风探测／破坏威胁）、解析后的风暴移动情况、到期时间，以及准确坐标点是否位于多边形内。另行列出监视预警。
get_spc_outlook(lat, lon, day=1)	该坐标点的 SPC 分类风险（TSTM→HIGH），以及第 1–3 天的龙卷风／冰雹／风概率和显著强对流标记；解读与风险类别相匹配。
get_point_environment(lat, lon)	最新的 RAP 13-km 分析廓线，由 MetPy 计算：MLCAPE/MUCAPE/CINs、LCL、0–1/0–6 km 风切变、0–1/0–3 km SRH、Bunkers 移动、有效入流层、有效 SRH／风切变、SCP 和显著龙卷风参数；并像分析员一样解读（脉冲型、冷季高风切变型或典型超级单体参数环境）。
get_environment_trend(lat, lon)	前瞻视图：同一时次的短期 RAP 预报序列（f00/f01/f03/f06），包含 MLCAPE、0–6 km 风切变、0–1 km SRH、SCP 和 STP，并解读其变化趋势（增强／稳定／持平）——用于判断“情况是否在恶化”，而不是“现在是什么情况”。
get_mrms_severe(lat, lon, radius_km=40)	半径范围内的 MRMS 最大值：60 分钟 MESH（冰雹，英寸和毫米）、低层和中层旋转轨迹（方位切变）、VIL、组合反射率；每项均附有效时间，以及最大值的距离／方位。
get_storm_reports(lat, lon, radius_km=80, hours=6)	标准化的 Local Storm Reports：类型、带单位的强度、时间、位置、距离／方位和备注。
get_lightning(lat, lon, radius_km=40, minutes=15)	近期时段内的 GOES-East GLM 总闪电活动：闪电次数和频率、最近一次雷击（距离／方位／时间），以及分级的户外安全解读（头顶上方／处于雷击范围内／附近）。
get_historical_storm_reports(lat, lon, date, radius_km=80)	查询特定过去日期（YYYY-MM-DD，UTC）袭击某坐标点的冰雹／大风／龙卷风——返回带强度、单位和距离／方位的标准化报告，适用于保险／农业／取证场景。数据覆盖约从 2005 年开始；包含初步 LSR，而非最终 NCEI 记录。
get_threat_brief(lat, lon)	核心功能：并发运行以上所有工具，综合给出威胁等级（无／边缘／较高／显著／极端）及明确说明的判定逻辑、按危险程度排序的灾害、环境概要、最近的风暴特征，以及建议的关注时段。
get_radar_snapshot(lat, lon)	最近的 WSR-88D 雷达最新 Level 2 体扫元数据：VCP（扫描策略）、带距离／方位的最大反射率、粗略的回波顶高度估计。

每个工具都会返回结构化 JSON，包含 data（数值字段，注明单位）、interpretation（通俗易懂的分析员解读）、degraded（上游数据源中哪些未能正常工作，如有——返回部分数据，而非错误）、安全 disclaimer，以及 schema_version——字段契约遵循 semver 稳定性规范（参见 ARCHITECTURE），集成方可以依赖该契约。

示例：真实强风暴期间的威胁简报

2026-06-10 的真实输出，坐标点位于密苏里州北部的一处当前有效龙卷风警报范围内：

{
  "threat_level": "extreme",
  "threat_logic": [
    "Tornado Warning in effect at the point, corroborated by confirmed tornado reports nearby — treat as an immediate life-safety situation.",
    "Severe Thunderstorm Warning at the point tagged 'Considerable' (hail to 1.75\", gusts to 60 mph).",
    "Significant-tornado parameter of 4.0 with storms ongoing — environment strongly supports tornadic supercells.",
    "MRMS MESH of 2.3\" hail within radius in the last hour.",
    "Intense rotation track (azimuthal shear 0.013 /s) nearby in the last hour.",
    "6 tornado report(s) near the point in the report window."
  ],
  "hazards_ranked": [
    {"hazard": "tornado", "level": "extreme"},
    {"hazard": "hail", "level": "extreme"},
    {"hazard": "damaging_wind", "level": "extreme"},
    {"hazard": "flash_flood", "level": "moderate"}
  ],
  "nearest_storm_signature": {
    "signature": "composite reflectivity", "value": "58.5 dBZ",
    "distance_km": 18.0, "direction": "ENE", "valid_utc": "2026-06-10T22:14Z"
  },
  "attention_window": {"window": "now", "until_utc": "2026-06-10T21:00:00-05:00"}
}

同一工具在缅因州海岸一处天气平静的坐标点上，也会给出明确的平静判断，而非报错："threat_level": "none"，并附上环境数值，让 Agent 能看出平静的原因。

安装

需要 Python 3.12+ 和 uv。无需 API 密钥——所有数据源均为公开且匿名的。uvx 一步即可下载并运行已发布的软件包；不会永久安装任何内容。

Claude Code：

claude mcp add shearline -- uvx shearline

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "shearline": {
      "command": "uvx",
      "args": ["shearline"]
    }
  }
}

Streamable HTTP（用于远程/Agent 平台）：

uvx shearline --http --port 8741
# serves at http://127.0.0.1:8741/mcp

在 macOS 上，你也可以双击 scripts/launch.command，在 Terminal 窗口中启动 HTTP 服务（遵循 SHEARLINE_PORT 设置）。

HTTP 传输专为托管而设计：每次工具调用都会输出一行结构化 JSON 日志 （工具、粗略的 1° 经纬度区间、延迟、degraded 列表、缓存 命中/未命中），并应用按客户端计算的令牌桶速率限制；超出限制时返回 429 和 Retry-After。这两项功能仅适用于 HTTP——stdio 行为 保持不变。通过环境变量进行配置：

环境变量	默认值	作用
SHEARLINE_RATE_RPM	60	每个客户端持续请求数/分钟（0 表示禁用限制）
SHEARLINE_RATE_BURST	30	令牌桶容量（最大突发请求数）
SHEARLINE_HTTP_LOG	1	设为 0 可关闭每个请求的日志
SHEARLINE_LOG_LEVEL	INFO	shearline.http 日志记录器的日志级别
SHEARLINE_UPSTREAM_CONCURRENCY	8	上游抓取的最大并发数（以礼貌对待 NOAA）

若要运行最新的未发布 main，而不是 PyPI 版本，请将 shearline 替换为 --from git+https://github.com/lostnumber07/shearline shearline。

为什么需要这些工具

预报 API 会告诉你可能会下雨。在恶劣天气日里，所有重要问题——这场风暴是否正在旋转，冰雹有多大，环境是否具备龙卷风生成条件，我是否处于警报多边形内——都无法通过预报端点回答。这些问题需要警报的 IBW 标签、雷达衍生产品和真实探空数据：

• 警报包含 IBW 标签，而不只是警报文本。 基础等级的 Severe Thunderstorm Warning，与带有 DESTRUCTIVE 标签、阵风达 80 mph 的警报，是不同的规划问题。SHEARLINE 会解析机器可读标签（最大冰雹尺寸、最大阵风、龙卷风探测/破坏威胁）和风暴移动矢量，并为你执行点位是否落入多边形内的测试。
• 诚实计算环境条件。 没有切变的 CAPE 意味着脉冲风暴日；没有 CAPE 的切变则意味着风驱降雨。SHEARLINE 会获取当前 RAP 分析廓线，并使用 MetPy 计算具有区分力的参数——包括有效入流层、有效 SRH/切变、SCP 和 STP——因为高 CAPE/低切变、低 CAPE/高切变以及经典超级单体参数空间会产生截然不同的灾害，而解读结果会说明你处于哪种情况。
• MRMS，因为警报会滞后于风暴。 MESH 会告诉你风暴已经产生了多大的冰雹；旋转轨迹会显示过去一小时内中尺度气旋经过的位置——两者均基于全国雷达拼图，以约 2 分钟的频率更新，通常早于下一次警报更新。
• LSR，因为雷达并非地面实况。 观测员报告会确认实际到达地面的情况——无论是实时情况，还是任意过去日期的情况（保险/取证问题：“那天这个地址遭遇了什么”）。
• 闪电，因为它是最常见的户外安全触发因素。 GOES GLM 总闪电数据按距离分级，适用 30-30 / 10 英里规则——这一信号确实会让球赛、工地或无人机飞行停止。
• 现在，也包括接下来。 点位环境代表当前分析；预报趋势（单个模式周期的 f00→f06）则能说明 STP/CAPE 是否会在下午升高——这就是“现在是什么情况”和“情况是否正在恶化”的区别。
• 一份能够综合所有信息进行推理的简报。 威胁等级基于规则，并会引用触发的规则，因此 Agent 可以审查推理过程，而不是盲目相信直觉。

数据源（均为公开数据，无需密钥）

• 警报：api.weather.gov（NWS）
• 展望：Storm Prediction Center 公共 GeoJSON
• 定点环境：NOMADS RAP grib filter，使用 MetPy 派生
• MRMS：NOAA MRMS on AWS Open Data
• 风暴报告（实时和历史）：Iowa Environmental Mesonet LSR 服务
• NEXRAD Level 2：Unidata on AWS Open Data
• 闪电：GOES GLM on AWS Open Data（GOES-East GLM-L2-LCFA）

覆盖范围仅限美国本土——超出范围的坐标会被拒绝，并给出明确错误。上游数据会缓存（警报 60 s、MRMS/闪电 120 s、LSR 300 s、展望/RAP 30 min、历史报告 6 h），并能优雅降级：如果某个数据源不可用，你会收到部分数据和一个 degraded 字段，而不会遇到未处理的异常。每日 canary 工作流会检查每个上游的响应结构；如果发生架构漂移（字段重命名、存储桶迁移），会在影响到你之前报错。

面向非气象人员的操作指南

使用 SHEARLINE 无需了解 STP 是什么。.claude/skills/ 目录中包含三个端到端操作指南，列出了完成领域任务所需的确切工具调用顺序——将它们添加到任何已连接 SHEARLINE 的 Agent 中即可：

• hail-claim-verification — 某个地址在某天是否发生过破坏性冰雹？（保险 / 取证）
• chase-day-briefing — 展望 → 环境 → 趋势 → 警报 → 雷达，最终给出是否出发的决策及目标时段（追风 / EM）
• event-day-lightning-watch — 监测附近闪电，并依据 30-30 / 10-mile 规则发布暂停 / 避难 / 恢复通知（场馆 / 户外运营）

架构

SHEARLINE 是一个轻量、分层的异步服务：各数据源的抓取 / 解析模块将数据传递给气象推导层，再传递给统一的工具层。每个工具都返回相同的 {data, interpretation, degraded, disclaimer} 封装，每次上游调用都会按 TTL 缓存，单个数据源故障时会降级为返回部分数据，而不是抛出异常。请参阅 ARCHITECTURE.md，了解模块图、get_threat_brief 的请求生命周期、并发模型，以及各数据源模块针对上游特性所做的处理。

开发

git clone https://github.com/lostnumber07/shearline && cd shearline
uv sync
uv run pytest          # offline test suite against recorded fixtures
uv run ruff check .
uv run shearline       # stdio
uv run python scripts/smoke.py     # live smoke test, both transports
uv run python scripts/canary.py    # live upstream drift check (shape-only)

请参阅 ARCHITECTURE.md，了解如何添加工具或数据源。

许可证

MIT © Backshear LLC。天气数据由 NOAA/NWS 和其他公共服务提供；本项目与 NOAA 无关，也未获其认可。