epa-drinking-water-mcp-server

---

概要

SDWIS DMAP および UCMR 5 公表資料に含まれる EPA の飲料水記録を扱います。水道システムを特定し、過去の違反や執行措置を調べ、鉛・銅規則の概要、または規制対象外汚染物質の検出測定値を取得できます。API キーなしで stdio または Streamable HTTP 経由で動作します。

ツール

ツール	説明
sdwis_list_reference	識別子、汚染物質の名前空間、対象範囲、基準、EPA 辞書を解読します
sdwis_search_water_systems	連絡先情報を含まない公共水道システムの一覧を検索します
sdwis_get_system_profile	概要、地理情報、給水区域、または処理情報を取得します
sdwis_get_violations	報告された過去の SDWA 違反をページ単位で取得します
sdwis_search_contaminants	違反、LCR 概要、または UCMR 5 の検出情報を選択します
sdwis_get_enforcement_actions	執行措置または違反との関連付けを取得します
sdwis_dataframe_describe	提供されたキャンバス内のテーブルとデータの出所を確認します
sdwis_dataframe_query	ステージング済みパーティションに対して読み取り専用 SQL を実行します
sdwis_dataframe_drop	必要に応じてステージング済みテーブルを 1 つ削除します

データフレームツールを使用するには、npm または Docker に加えて CANVAS_PROVIDER_TYPE=duckdb が必要です。drop には SDWIS_DATAFRAME_DROP_ENABLED=true も必要です。Claude Desktop バンドルには、EPA の情報を読み取る 6 つのツールが含まれています。

機能リファレンス

sdwis_list_reference _ツール

• 必須の topic：identifiers、system_types、sources、contaminants、violation_types、enforcement_types、treatment、service_areas、standards、または coverage。任意の部分文字列 query
• 解釈トピックはまとめて提供され、辞書は最新の内容です。SDWIS コードと UCMR 分析対象物質は別々の名前空間です。基準では MCL、MCLG、措置レベルについて説明しますが、過去の記録を基準超過として分類することはありません

---

sdwis_search_water_systems _ツール

• 少なくとも1つの絞り込み条件が必要です：pwsid、name_contains、state、county（state が必須）、population_min / population_max、source、system_type、primacy_agency、または pwsid_prefix
• activity の既定値は active です。inactive または all を明示的に選択してください。州は報告された法人の所在州を、郡は給水対象の郡を示します。いずれも、物理的な給水区域全体を確定するものではありません

---

sdwis_get_system_profile _ツール

• 9文字の英数字からなる pwsid が必須です。section は summary（既定値）、geography、service_areas、または treatment で、各セクションは個別にページ分割されます
• Summary は system を返し、子セクションは items を返します。found:false はインベントリに情報がないことを示し、コンプライアンス上の判定ではありません。運営者の連絡先と郵送先住所は除外されます

---

sdwis_get_violations _ツール

• pwsid または state が必須です。county、contaminant、category、health_based、compliance_status は任意です
• 開始日と終了日を含む date_from / date_to で、コンプライアンス期間との重複を選択します。不明な日付は一致しません。モニタリング違反や報告違反には、濃度がない場合があります
• stage:true はデータの分割を要求します。stage_max_rows の既定値は5,000で、上限は25,000です。保持中の別の分割を追加するには、canvas_id を指定してください

---

sdwis_search_contaminants _ツール

• dataset（violations、lcr、または ucmr5）と、pwsid または state が必須です。任意の county、contaminant、期間指定により、それぞれコンプライアンス期間、LCR サンプル期間、UCMR 採取日を選択します
• LCR の鉛／銅では、家庭のサンプルではなく PB90/CU90 の概要を選択します。UCMR の PFAS は29種類の分析対象物質を対象とし、リチウムは別扱いです。zip と detected_only は UCMR 専用です。給水区域の ZIP コードはサンプル採取場所を示すものではなく、検出限界未満の値は不明のままです
• stage、canvas_id、stage_max_rows（既定値5,000、上限25,000）に対応しています。UCMR の初回呼び出しには180秒のクライアントタイムアウトが必要になる場合があります。対象範囲の解決がタイムアウトする場合は、広範なリクエストを PWSID または郡で絞り込んでください

---

sdwis_get_enforcement_actions _ツール

• pwsid が必須です。section は actions（既定値）または associations です。任意の violation_id を指定すると、PWSID に紐づく関連付けキーを通じて関連措置を選択します
• action_type、originator、および開始日と終了日を含む執行日のフィルターは、措置にのみ適用されます。関連付けは別個にページ分割されます。ソースの措置テキストだけでは、連邦命令や金銭的罰則を意味しません
• stage、canvas_id、stage_max_rows（既定値5,000、上限25,000）に対応しています

---

sdwis_dataframe_describe _ツール

• 呼び出し側が保持する canvas_id が必須です。完全一致の table_name は任意です。limit の既定値は10で、cursor によるページネーションで上限100に制限されます
• 各項目にテーブル列のエントリーが1つ含まれ、型、行数、有効期限、フィルター、データ来歴、完全性、続きの有無が示されます。キャンバス全体を一覧表示する機能はありません

---

sdwis_dataframe_query _ツール

• canvas_id と、sql 内の読み取り専用 SELECT、WITH、または FROM ステートメント1つ（最大20,000文字）が必須です。先にキャンバスを説明してください
• 保持される行数は最大 CANVAS_DEFAULT_ROW_LIMIT（フレームワークの既定値は10,000）で、上限は25,000です。row_count、truncated、has_more により、保持された行と省略された行を区別できます。続きの取得では、最大15分間、変更されない結果を読み取ります
• ファイル、ネットワーク、書き込み、システムカタログへのアクセスは拒否されます。source_complete には、SQL が参照しないテーブルも含め、すべてのライブソースの分割が保守的に含まれます

sdwis_dataframe_drop _ツール

• 必須項目は canvas_id と完全一致する table_name です。CANVAS_PROVIDER_TYPE=duckdb および SDWIS_DATAFRAME_DROP_ENABLED=true が必要です
• 冪等です。テーブルがない場合やキャンバスの有効期限が切れている場合は dropped:false を返し、その他のステージング済みパーティションは引き続き利用できます

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレースを備えた構造化ログに対応しています。

EPA 固有の機能：

• 連絡先情報を必要とせずにインベントリとサービスの所属情報を取得できます。ラベルがない場合もソースコードを保持します
• 過去の四半期ごとの SDWIS レコード、LCR の概要、参加が限定された UCMR 5 の監視データをそれぞれ区別して保持します。結果が空でも、現在の法令遵守状況、蛇口の水の安全性、または汚染物質が存在しないことは確認できません
• ソースの日付は暦上の日付の意味を保持します。ソースのタイムスタンプが午前 0 時以外の場合は、_raw フィールドを保持します
• UCMR の取得はプロセス内で遅延実行されます。アーカイブ取得後でも、州全体を対象とするリクエストは 45 秒のサービス所属情報の予算を超える場合があります。サーバーを完全な全米データウェアハウスと見なすのではなく、PWSID／郡で対象を絞り込んでください

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

• 来歴 — effective_filters、ソース URL、retrieved_at、利用可能な場合は公開情報／HTTP バリデーター、および解釈上の注意事項
• 完全性 — 以前のページやパーティションで行が配信されている場合、has_more:false でも source_complete:false のままになることがあります。集約しても完全性は回復しません
• レコード全体単位のページング — limit のデフォルトは 10 で、上限は 100 です。バイト数の制限により、返される行数が少なくなる場合があります。空の phase:membership ページも含め、セレクターを変更せずに next_cursor を使用してください。ソースカーソルは 15 分間操作がないと期限切れになります
• サイズ超過のレコード — item_too_large は record_cursor を返します。view:text を使用して JSON チャンクを連結し、その後、レコードの続きに進んでください。両方の MCP コンテンツサーフェスには同じ値が含まれます

はじめに

次のいずれかの設定を MCP クライアントに追加してください。EPA アカウントや API キーは不要です。

{
  "mcpServers": {
    "epa-drinking-water-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/epa-drinking-water-mcp-server@latest"]
    }
  }
}

または npx を使用する場合（Bun は不要です）：

{
  "mcpServers": {
    "epa-drinking-water-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/epa-drinking-water-mcp-server@latest"]
    }
  }
}

または Docker を使用する場合：

{
  "mcpServers": {
    "epa-drinking-water-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/epa-drinking-water-mcp-server:latest"
      ]
    }
  }
}

SQL ステージングを行うには、npm プロセスの環境に CANVAS_PROVIDER_TYPE=duckdb を設定します（Docker の場合：-e CANVAS_PROVIDER_TYPE=duckdb）。stage:true を指定してソースツールを呼び出し、dataset.canvas_id を保持してから、クエリを実行する前に sdwis_dataframe_describe を呼び出してください。ソースパーティションの続きはすべて保持してください。Claude Desktop バンドルでは CANVAS_PROVIDER_TYPE=none に固定されており、そこでステージングを試みると canvas_disabled が返されます。

ローカルのチェックアウトから Streamable HTTP を使用する場合：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# http://localhost:3010/mcp

前提条件

• Bun ≥1.4.0 または Node.js ≥24.0.0
• EPA サービスへのネットワークアクセス。UCMR の初回呼び出しには、クライアントのタイムアウトを 180 秒に設定してください

インストール

git clone https://github.com/cyanheads/epa-drinking-water-mcp-server.git
cd epa-drinking-water-mcp-server
bun install
cp .env.example .env
bun run rebuild

設定

変数	説明	デフォルト
SDWIS_DATAFRAME_DROP_ENABLED	キャンバスが有効な場合に、ステージング済みテーブルを早期に削除できるようにします	false
CANVAS_PROVIDER_TYPE	none または duckdb。npm／Docker は DuckDB に対応し、MCPB は none に固定されています	none
CANVAS_DEFAULT_ROW_LIMIT	SQL の行数上限。サーバーの最大値 25,000 が上限です	10000
CANVAS_DEFAULT_MEMORY_LIMIT_MB	エンジンごとのメモリ上限。最大 512 MiB です	512
MCP_TRANSPORT_TYPE	stdio または http	stdio
MCP_HTTP_HOST	HTTP バインドアドレス。Docker は 0.0.0.0 にバインドします	127.0.0.1
MCP_HTTP_PORT	HTTP ポート	3010
MCP_AUTH_MODE	none、jwt、または oauth	none
MCP_LOG_LEVEL	最低ログレベル	info
OTEL_ENABLED	OpenTelemetry を有効にします	false

すべてのオーバーライドについては、.env.example を参照してください。

サーバーの実行

ローカル開発

bun run rebuild
bun run start:stdio
# or bun run start:http
bun run devcheck
bun run test

Docker

docker build -t epa-drinking-water-mcp-server .
docker run --rm -p 3010:3010 epa-drinking-water-mcp-server

イメージはデフォルトで、ステートレスセッションを使用する Streamable HTTP をポート 3010 で起動します。SQL ステージングを行うには、-e CANVAS_PROVIDER_TYPE=duckdb を追加してください。

プロジェクト構成

パス	目的
src/index.ts	登録、ソースの初期化、オプションのキャンバス
src/config	データフレームのドロップ設定
src/domain	セレクター、参照データ、スキーマ、デュアルサーフェス形式
src/mcp-server/tools/definitions	6つのEPAツールと3つのオプションのデータフレームツール
src/services/sdwis	検証済みDMAP読み取り、メンバーシップ、ページング、結合
src/services/ucmr5	アーカイブの取得、解析、インデックス作成、発生状況
src/services/dataframe	機能スコープ付きのステージング、SQL、有効期限、削除
tests	ドメイン、サービス、ツール、統合テスト
scripts	ビルド、チェック、パッケージ化、リリース用ツール

開発ガイド

CLAUDE.md と AGENTS.md を参照してください。

• ハンドラーは型付きの失敗をスローし、フレームワークがエラーを表示します
• src/index.ts に直接登録し、正規化の前に上流データを検証してください
• 不確実性、来歴、日付、完全性を保持し、コンプライアンス、世帯の曝露、基準超過を決して推測しないでください
• content[] と structuredContent を同等に保ち、ソース結果をユーザーストレージに書き込まないでください

貢献

課題の報告を歓迎します。提出前に bun run devcheck と bun run test を実行してください。

ライセンス

Apache-2.0。