us-drought-monitor-mcp-server

---

概要

米国干ばつモニター（USDM）のデータサービスから、毎週の干ばつ統計を取得します。地域の現在または指定日の深刻度を確認し、週ごとの履歴を追跡し、州や郡をランキングし、全国、州、郡、HUC 流域、部族、気候区分、河川予報センターの各地理区分における郡の干ばつ週数を集計できます。大規模な結果は、読み取り専用 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	破棄可能なステージング済みテーブルを 1 つ削除します。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 を指定すると、レベル 2、4、6 の既存の短い HUC の下位地域を選択できます
• 1 ページあたりの既定件数は 25 件で、最大 200 件です。フィルターを変更せずに nextCursor で続きを取得します。ページを明示的に指定すると、有効な件数が返され、データが尽きた場合のみ指定件数を下回ります。totalCount は一致するすべての件数を示します
• レコードでは、先頭のゼロを含む識別子、気候関連の州郵便略号、およびデータソースの版が保持されます。bundleVersion とトピックに応じた sourceMetadata（データソース URL と SHA-256 ハッシュ）でオフラインバンドルの日付を確認できます。provenance.sourceUrls には同じデータソースの選択内容が使われます

---

drought_get_current_severity _ツール

• 1 つの 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 が返されます
• River Forecast Centers では、公式コード（例：CBRFC）または正確な名前（Colorado Basin）を指定して areaType: "river_forecast_center" を使用します。面積比率、平方マイル、DSCI に対応しています。不明な RFC はローカルの参照情報との照合に失敗します

---

drought_get_timeseries _ツール

• 同じ areaType と HUC レベルを共有する 1～100 件の areas を指定します。startDate／endDate は両端を含みます。metric は area_percent（既定値）、area_sq_miles、population_percent または population_count（米国／州／郡のみ）です。statisticsType は cumulative（既定値）または categorical です
• 行には指標バケットと dsci が含まれます。missingAreas、missingObservations（指標および DSCI の各構成要素についての日付期間）、地域ごとの summary（同率のピークをすべて含む）で、時系列全体を網羅します
• インライン予算を超える行は、プレビューを介してステージングされ、テーブルは staging に置かれます。省略可能な canvas_id を指定すると、既存のキャンバスにステージングできます。収まる場合、メタデータはすべてインラインに保持されます。あふれた場合も、観測数が 0 件の結果を含め、行とメタデータ全体が自動的に保持されます。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日後の日付と比較されます。非連続の行にはこれらのフラグはありません
• 1ページあたりの行数はデフォルトで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読み取り式を1つ指定します。書き込み、複数のステートメント、外部読み取り、システムカタログへのアクセスは拒否されます
• current_schema という名前の列は、テーブル名を付けて参照する必要があります（t.current_schema）。DuckDBがこれをエンジン設定関数として解釈する可能性があるため、テーブル名のない参照は拒否されます
• limit（デフォルトは25、最大500）と、最大250,000までの offset を指定できます。next_offset が null になるまで、同じ SQL で続きを取得してください。明示的にページを指定した場合は、セル幅にかかわらず有効件数が返され、データが尽きた場合にのみ件数が少なくなります。SELECT * FROM <table_name> ORDER BY row_id は元の行を順番どおりに返します
• countIsExact が true になるのは、offset 0からの1ページにすべての行が含まれる場合のみです。総件数を取得するには 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 件で、Retry-After を尊重する再試行は 1 回です
• 日付は該当する火曜日〜月曜日のマップ週に切り捨てられます。対象期間は 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 キャンバスに達した場合、トークンを省略したステージングでは、空きスロットがあるサービス所有のキャンバスのうち、そのテナントで最後に使用されたものを再利用します（1 キャンバスあたり 8 テーブル）。明示的に指定されたキャンバスは呼び出し元の所有のままで、存続中のテーブルが退避されることはありません。staging_capacity_exhausted はトークンの再利用または有効期限切れを、staging_busy は処理中の作業が終わるまで待機することを推奨します。2 ワークフローの受け入れ上限は、インライン読み取りを含め、フェッチ前に適用されます
• コネチカット州の旧郡 FIPS 8 件は引き続き検出可能ですが、比較対象の母集団からは除外されます。観測値の検索結果が空であるのは、USDM がコネチカット州を計画地域単位で提供しているためです。topic: counties、state: CT を指定して drought_list_reference を呼び出してください。郡が異なる計画地域境界に割り当てられることはありません。currentUsdm: false だけでは過去の対象期間に関する規則にはなりません
• Node での取得には、再利用可能なプライベートの Undici HTTP/1.1 ディスパッチャーを使用し、サーバーの終了時に解放します。Bun ではネイティブの fetch を引き続き使用します

エージェント向けの出力：

• 参照レコード、クエリ行、説明用の列は、JSON セルを含むコンパクトなテーブル形式です。空のセルと null 値により、存在しない任意フィールドと null 値を区別できます。メタデータ、ネストされた値、クリック可能な URL は、どちらのレスポンス形式でも完全な状態で保持されます
• 正の整数のページ／プレビュー上限が、参照情報、比較、期間では 200、SQL では 500、メタデータでは 100 を超える場合、上限値に調整されます。effectiveLimit と limitNotice に調整結果が示されます。代わりに DROUGHT_CLAMP_LIMITS=false を設定すると、これらの最大値が通知され、適用されます。上限調整はリクエストログと drought.limit_clamps カウンターに記録されます。継続処理ではすべてのレコードが保持されます。0 以下または小数の上限値は拒否されます。件数の上限はレスポンスのバイト数を制限しません
• 日付入力では YYYY-MM-DD が指定され、実在する暦日であることが検証されます。空の省略可能なスナップショット日付と比較日付には、既定値が適用されます。期間内のしきい値が対象期間を超える場合は、minWeeks を小さくするか日付の範囲を広げるよう通知されます
• すべてのレスポンスには出典情報が含まれます：sourceUrls、retrievedAt、USDM の credit 行、実験的な DSCI の引用
• 対応する人口スナップショットと人口系列には provenance.populationInterpretation が追加され、データフレームの説明／クエリ処理後も保持されます：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、またはステージングと SQL を無効にする場合は none。	duckdb
CANVAS_DEFAULT_MEMORY_LIMIT_MB	各キャンバスエンジンのメモリ制限。	128
CANVAS_MAX_CANVASES_PER_TENANT	プロバイダーのキャンバス上限。サーバーはこれとは別に、プロセスあたり4つの稼働中キャンバスを受け入れます。	4
CANVAS_DEFAULT_ROW_LIMIT	プロバイダーのクエリ行数上限。キャンバスが有効な場合は 501 以上にします。	10000
CANVAS_TTL_MS	スライド式のキャンバス有効期間（ミリ秒）。ステージング済みテーブルは30分間使用されないと期限切れになります。	86400000
CANVAS_ABSOLUTE_CAP_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 に固定され、データ取得の上限内でデータ生成ツールが結果をすべてインラインで返します。明示的なキャンバストークンとデータフレーム操作には、引き続き分析プロバイダーが必要です。無効、期限切れ、または他者のトークンがインラインでの成功にフォールバックすることはありません。

• 本番版をビルドして実行する：

  # 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

このイメージはネイティブ DuckDB を含む Bun 上で動作し、デフォルトではステートレスセッションモードでポート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つのツール。
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. Drought Severity and Coverage Index. United States Drought Monitor.