epa-drinking-water-mcp-server

---

概述

提供来自 SDWIS DMAP 和 UCMR 5 公布数据的 EPA 饮用水记录。解析供水系统，查看历史违规记录与执法行动，并检索铅和铜规则摘要或未受监管污染物的出现测量数据。通过 stdio 或 Streamable HTTP 运行，无需 API 密钥。

工具

工具	说明
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	可选地移除一个暂存表格

Dataframe 工具需要使用设置了 CANVAS_PROVIDER_TYPE=duckdb 的 npm 或 Docker；drop 还需要设置 SDWIS_DATAFRAME_DROP_ENABLED=true。Claude Desktop 安装包提供六个用于读取 EPA 数据的工具。

功能参考

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 _工具

• 至少需要一个筛选条件：pwsid、name_contains、state、county（需要提供州）、population_min / population_max、source、system_type、primacy_agency 或 pwsid_prefix
• activity 默认为 active；如需选择其他范围，请明确指定 inactive 或 all。州指报告的法律实体所在州；县指服务覆盖的县，两者均不能确定完整的实际服务边界

---

sdwis_get_system_profile _工具

• 必需的九位字母数字 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，最大限制为 100，并支持使用 cursor 分页
• 每项对应一个表列条目，包含类型、行数、过期时间、筛选条件、来源、完整性和续页信息。没有全局 canvas 列表

---

sdwis_dataframe_query _工具

• 必需的 canvas_id 和 sql 中的一条只读 SELECT、WITH 或 FROM 语句（最多 20,000 个字符）；请先描述 canvas
• 最多保留 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 监测数据彼此区分；空结果既不能证明当前符合规范，也不能证明自来水安全或不存在污染物
• 来源日期保留其日历含义；非午夜的来源时间戳会保留在 _raw 字段中
• 按需获取 UCMR 数据，并仅在进程内缓存；即使已获取归档数据，全州范围的请求也可能超出 45 秒的成员查询时限。请按 PWSID/县缩小范围，不要将服务器视为完整的全国数据仓库

便于 Agent 使用的输出：

• 来源信息——effective_filters、来源 URL、retrieved_at、可用时的发布/HTTP 验证器，以及解读注意事项
• 完整性——即使此前已在其他页面或分区中返回数据，source_complete:false 仍可能与 has_more:false 同时出现；聚合不会恢复完整性
• 整条记录分页——limit 默认为 10，最大为 100；字节数限制可能导致返回的记录更少。使用未更改的选择器跟进 next_cursor，包括空的 phase:membership 页面；来源游标在 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 bundle 将 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

该镜像默认通过端口 3010 使用无状态会话的 Streamable HTTP。若要暂存 SQL 数据，请添加 -e CANVAS_PROVIDER_TYPE=duckdb。

项目结构

路径	用途
src/index.ts	注册、源初始化和可选画布
src/config	Dataframe-drop 配置
src/domain	选择器、参考数据、架构和双表面格式化
src/mcp-server/tools/definitions	六个 EPA 工具和三个可选 dataframe 工具
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。