us-drought-monitor-mcp-server

---

概述

来自 U.S. Drought Monitor（USDM）数据服务的每周干旱统计信息。查看某个区域当前或指定日期的干旱严重程度、追踪每周历史记录、对州和县进行排名，并统计全国、州、县、HUC 流域、部落、气候分区和 River Forecast Center 地理区域中各县处于干旱状态的周数。大型结果会整理为表格，以供只读 SQL 查询。无需 API 密钥。

调用方指南介绍了数据解读和完整分析数据的获取方式；服务器也会将其作为技能资源提供。

工具

工具	描述
drought_list_reference	浏览干旱类别、DSCI 公式、覆盖范围和精确的地理标识符
drought_get_current_severity	当前或指定日期的快照，包含面积、平方英里、人口、DSCI 以及 4/52 周 DSCI 变化
drought_get_timeseries	指定区域的每周指标和 DSCI，包含缺失数据区间和峰值摘要
drought_compare_areas	按 DSCI 或 D2+/D3+ 覆盖率对州或县进行排名，或按相对于基准周的变化进行排名
drought_get_weeks_in_drought	统计县在某个干旱类别或更严重类别下的连续周数或非连续周数
drought_dataframe_describe	检查暂存画布：表、列、过期时间和完整的生成方元数据
drought_dataframe_query	对暂存的干旱数据表执行分页只读 SQL 查询
drought_dataframe_drop	移除一个可弃用的暂存表；需通过 DROUGHT_DATAFRAME_DROP_ENABLED=true 显式启用

功能参考

drought_list_reference _工具

• topic：categories、dsci、area_types、coverage、states、counties、tribal、climate_divisions、river_forecast_centers 或 huc；nameContains 为令牌筛选器；state 用于县或气候分区；huc 需要 hucLevel（2、4、6 或 8）。可选的 parentHuc 用于选择现有较短 HUC（级别为 2、4 或 6）的后代
• 每页默认返回 25 条记录，最多限制为 200 条；使用 nextCursor 继续分页，筛选条件必须保持不变。显式指定页数时会返回实际记录数，仅在无更多记录时少于指定数量；totalCount 统计所有匹配项
• 记录会保留带前导零的标识符、气候州邮政编码和数据源版本；bundleVersion 和依主题而定的 sourceMetadata（数据源 URL 和 SHA-256 哈希）标示离线数据包的日期。provenance.sourceUrls 使用相同的数据源选择

---

drought_get_current_severity _工具

• 单个 area（areaType + aoi；HUC 还需提供 hucLevel；aoi 接受精确标识符、精确州名或 "County Name, ST" 格式的名称）；名称唯一且不带后缀的县（如 "King, WA"）在精确名称匹配后也可接受。可选的 date 默认为最新发布的地图；us 会同时选择 CONUS 和 Total
• 每个快照包含累计和分类面积百分比、累计平方英里、累计人口（美国/州/县以外的区域，其 populationStatus 为 unsupported）、dsci，以及相对于整整 28 天和 364 天前的 dsciChange4Weeks / dsciChange52Weeks；每项都带有 available / missing / before_coverage 状态
• 日期超出已发布覆盖范围时，会返回 found: false 和 guidance
• 河流预报中心使用 areaType: "river_forecast_center"，并接受官方代码（例如 CBRFC）或精确名称（Colorado Basin）；支持面积百分比、平方英里和 DSCI。无法在本地参考数据中解析的 RFC 会导致失败

---

drought_get_timeseries _工具

• 1–100 个共享同一 areaType 和 HUC 级别的 areas；包含起止日期的 startDate / endDate；metric 可选 area_percent（默认值）、area_sq_miles、population_percent 或 population_count（仅限美国/州/县）；statisticsType 可选 cumulative（默认值）或 categorical
• 行包含指标分桶和 dsci；missingAreas、missingObservations（按指标和 DSCI 组件列出的日期区间）以及每个区域的 summary（所有并列峰值）覆盖完整时间序列
• 超出内联预算的行会暂存，并通过预览显示，表位于 staging 中；可选的 canvas_id 可将数据暂存到现有画布中。只要元数据能容纳，便会完整地以内联方式返回。发生溢出时，系统会自动保留完整行和元数据，包括零观测结果；metadata_pages 会提供每个数组的总数、已返回数量和下一偏移量

---

drought_compare_areas _工具

• scope 为 states 或 counties（可选 state，否则为全国范围）；metric 为 dsci（默认）、d2_d4 或 d3_d4；可选 date（默认最新）和用于对变化进行排名的 baselineDate；direction 为 desc（默认）或 asc
• 竞赛排名中并列项共享名次；excludedAreas 列出缺少目标值或基准值的区域；changeUnit 为 index 或 percentage_points
• limit（默认 20，上限为 200）设置内联预览大小；完整排名会分阶段返回，并可选择复用 canvas_id

---

drought_get_weeks_in_drought _工具

• 必填参数：startDate、endDate、minCategory（D0–D4）和 minWeeks；mode 为 consecutive（默认）或 non_consecutive；可指定 states 或一个 county，不能同时指定，也可以两者都不指定以查询全国各县
• 每行提供 fips、county、state，以及 startDate / endDate / consecutiveWeeks 或 nonConsecutiveWeeks；县内任意区域达到指定类别或更严重类别即符合条件，连续时间段以请求的时间窗口为界
• 连续模式下，startMayExtendEarlier 和 endMayContinue 用于标记与有效时间窗口相接的边界，表示连续情况存在不确定性。周一结束日期会与最后一张地图的星期二加 6 天进行比较。非连续模式的行不包含这些标记
• 每页默认 25 行，上限为 200；筛选条件不变时，nextCursor 有效期为 5 分钟。显式分页会返回有效数量，只有在没有更多结果时才会少于该数量。计数是持续时间统计，不代表项目资格

---

drought_dataframe_describe _工具

• 使用暂存响应中的 canvas_id；表格包含 SQL 列类型、行数和到期时间
• 指定 table_name 时，返回该表完整的生产者元数据：请求和有效范围、单位、分桶列映射、缺失数据、摘要和来源信息
• 元数据过大时，会返回首页前缀，并提供 metadata_pages。要读取完整的保留集合，请提供 table_name、metadata_field（areas、summary、missingAreas、missingObservations）、metadata_offset 和 metadata_limit（默认 20，上限为 100）；持续读取 metadata_page.next_offset，直到其值为 null。显式分页会返回有效数量，只有在没有更多结果时才会少于该数量；数据来自同一快照，不会再次从上游获取

---

drought_dataframe_query _工具

• 提供 canvas_id 和一个 DuckDB 读取表达式，可选以分号结尾；拒绝写入、多个语句、外部读取和系统目录访问
• 名为 current_schema 的列必须使用表限定（t.current_schema）；拒绝未限定的引用，因为 DuckDB 可能会将其绑定为引擎设置函数
• limit（默认 25，上限为 500）和最大为 250,000 的 offset；使用完全相同的 SQL 继续传入 next_offset，直到其值为 null。显式分页会返回有效数量，只有在没有更多结果时才会少于该数量，不受单元格宽度影响。SELECT * FROM <table_name> ORDER BY row_id 会按原始顺序返回原始行
• 只有当从偏移量 0 开始的一页包含所有行时，countIsExact 才为 true；如需获取总数，请使用 SELECT COUNT(*)

---

drought_dataframe_drop _工具

• 提供 canvas_id 和 table_name；仅移除分析副本。如果表已不存在，则返回 dropped: false；画布已过期时，会报错 canvas_not_found
• 选择启用：除非 DROUGHT_DATAFRAME_DROP_ENABLED=true，否则不会出现在 tools/list 中

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及带可选 OpenTelemetry 跟踪的结构化日志记录。

USDM 专属：

• 面向 USDM 数据服务（usdmdataservices.unl.edu）的固定源客户端：无需密钥；每次调用最多发起 64 个上游请求，传输 64 MiB；最多同时发起 3 个上游请求；重试 1 次并遵循 Retry-After
• 日期会对齐到所在的周二至周一地图周；数据覆盖始于 2000-01-04；最新地图（通常于周四发布）从上游发现
• 累计分桶（d1_d4 = D1 或更严重）会重叠；分类分桶（d1_only）互斥。DSCI 是上游提供的实验性 0–500 指数，不会重新计算
• 离线地理数据包：52 个州和辖区、3,230 个县（包括康涅狄格州规划区）、323 个部落地区、357 个气候分区、13 个河流预报中心和 2,916 个 HUC；由 scripts/update-reference-data.ts 刷新
• 暂存表存储在 DuckDB 中，滑动生命周期为 30 分钟，并会在查询时续期；画布令牌是按租户划分、可共享的能力，因此应将其视为凭据
• 达到每个进程 4 个画布的上限时，未提供令牌的暂存操作会复用该租户最近使用且仍有空位的服务自有画布（每个画布最多 8 张表）。显式提供的画布仍归调用方所有；在线表永远不会被驱逐。staging_capacity_exhausted 建议复用令牌或等待令牌过期，staging_busy 建议等待当前工作完成。两个工作流的准入上限适用于获取数据之前的所有操作，包括内联读取
• 康涅狄格州的 8 个旧版县 FIPS 仍可查询，但不会纳入比较群体。其观测查询结果为空，说明 USDM 按规划区提供康涅狄格州数据；调用 drought_list_reference 并设置 topic: counties、state: CT。县绝不会映射到不同的规划区边界；仅 currentUsdm: false 并不意味着该地区不在历史覆盖范围内
• Node 使用私有且可复用的 Undici HTTP/1.1 调度器，并在服务器关闭时释放；Bun 保留原生 fetch

面向 Agent 的输出：

• 参考记录、查询行和 describe 列使用带 JSON 单元格的紧凑表格；空单元格用于区分缺失的可选字段与 null 值。元数据、嵌套值和可点击 URL 在两种响应形式中均保持完整
• 正整数分页/预览上限超过 200（参考数据、比较、时长）、500（SQL）或 100（元数据）时会被截断；effectiveLimit 和 limitNotice 会说明结果。将 DROUGHT_CLAMP_LIMITS=false 设为关闭截断，改为公布并强制执行这些上限。截断会生成请求日志并增加 drought.limit_clamps 计数器。续传会保留所有记录。非正数和小数上限会被拒绝；数量上限无法限制响应字节数
• 日期输入公布格式 YYYY-MM-DD，并验证日期是否为实际日历日期；空白的可选快照日期和比较日期会保留默认值。若时长阈值超出其时间窗口，会建议降低 minWeeks 或扩大日期范围
• 每个响应都包含来源信息：sourceUrls、retrievedAt、USDM 的 credit 行和实验性 DSCI 引用
• 支持的人口快照和人口序列会添加 provenance.populationInterpretation，并在 dataframe describe/query 中保留：USDM 人口数据是基于人口普查的粗略估算，假设县内人口均匀分布；其精度看似很高，但并非当下的精确人口数。源值保持不变；不会推断人口普查年份
• 缺失数据会明确表示：使用 dsciStatus / populationStatus 表示 null，使用 missingAreas 表示缺失区域，使用 missingObservations 表示缺失观测日期区间，并使用 excludedAreas 表示排除区域；绝不会用 0 填充
• 回显范围和标识信息：requestedRange / effectiveRange、latestMapDate、resolvedAreas，以及指向 drought_dataframe_describe 和 drought_dataframe_query 的暂存句柄

快速开始

连接到托管实例：

claude mcp add --transport http us-drought-monitor-mcp-server https://us-drought-monitor.caseyjhand.com/mcp

或在本地运行：

claude mcp add us-drought-monitor-mcp-server -- npx -y @cyanheads/us-drought-monitor-mcp-server

对于其他客户端，将以下内容添加到 MCP 配置文件中：

{
  "mcpServers": {
    "us-drought-monitor-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/us-drought-monitor-mcp-server"]
    }
  }
}

无需 API 密钥或账户。设置 DROUGHT_DATAFRAME_DROP_ENABLED=true 以开放表删除功能。有关 Docker 或从源代码构建的信息，请参阅运行服务。

配置

变量	说明	默认值
DROUGHT_DATAFRAME_DROP_ENABLED	开放 drought_dataframe_drop，用于删除临时暂存表。	false
DROUGHT_CLAMP_LIMITS	限制过大的正数上限；false 会公布并强制执行最大值。	true
CANVAS_PROVIDER_TYPE	分析引擎：duckdb，或使用 none 禁用暂存和 SQL。	duckdb
CANVAS_DEFAULT_MEMORY_LIMIT_MB	每个画布引擎的内存限制。	128
CANVAS_MAX_CANVASES_PER_TENANT	提供程序画布上限；服务还会单独限制每个进程最多有四个运行中的画布。	4
CANVAS_DEFAULT_ROW_LIMIT	提供程序查询的行数上限；启用画布时至少为 501。	10000
CANVAS_TTL_MS	画布滑动有效期，单位为 ms；暂存表在 30 分钟未使用后过期。	86400000
CANVAS_ABSOLUTE_CAP_MS	画布的绝对有效期，单位为 ms。	604800000
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_HOST	HTTP 绑定地址。	127.0.0.1
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径。	/mcp
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
OTEL_ENABLED	启用 OpenTelemetry。	false

请参阅 .env.example，了解所有服务设置和常见框架覆盖项。

运行服务

本地开发

需要 Bun v1.4.0 或更高版本（或 Node.js v24+）。

git clone https://github.com/cyanheads/us-drought-monitor-mcp-server.git
cd us-drought-monitor-mcp-server
bun install
cp .env.example .env
# optional: set DROUGHT_DATAFRAME_DROP_ENABLED or canvas limits

暂存和 SQL 需要原生 DuckDB，npm 和 Docker 安装包中已包含。便携式 Claude Desktop .mcpb 套件将 CANVAS_PROVIDER_TYPE=none 固定为默认值：数据生成工具会在获取限制范围内返回完整的内联结果。显式画布令牌和 dataframe 操作仍需要分析提供程序；无效、过期或不属于当前用户的令牌绝不会回退为内联成功。

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Docker

docker run --rm -p 127.0.0.1:3010:3010 ghcr.io/cyanheads/us-drought-monitor-mcp-server:latest

此镜像在 Bun 上运行，并包含原生 DuckDB；默认使用 3010 端口上的 HTTP 和无状态会话模式，日志写入 /var/log/us-drought-monitor-mcp-server。默认会安装 OpenTelemetry 同级依赖；如需省略这些依赖，请使用 --build-arg OTEL_ENABLED=false 构建。

要在本地构建，请运行 docker build -t us-drought-monitor-mcp-server .。对于 stdio 客户端，请使用 "command": "docker"，并将 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/us-drought-monitor-mcp-server:latest"] 作为参数。

项目结构

目录	用途
src/mcp-server/tools	工具定义（*.tool.ts）。包含 8 个干旱和 dataframe 工具。
src/services/drought	USDM 客户端、地理位置解析、地图周日期、工作流、暂存和渲染。
src/services/canvas-accessor.ts	访问启动时配置的框架 DataCanvas。
src/config	环境加载、画布默认值、计数模式和限制遥测。
src/data	生成的地理位置参考数据包（reference.json）。
scripts/update-reference-data.ts	维护者从官方来源更新参考数据包。
tests/	单元、契约和集成测试，结构与 src/ 对应。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 服务错误携带每个工具内联 errors[] 契约中声明的 reason
• 在 src/index.ts 的 createApp() 数组中注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。

美国干旱监测由内布拉斯加大学林肯分校的国家干旱减灾中心、美国农业部、国家海洋和大气管理局以及美国国家航空航天局联合制作。地图由 NDMC 提供。

DSCI：Akyuz，F. A. 2017. 干旱严重程度与覆盖范围指数。美国干旱监测。