cdc-health-mcp-server

---

概述

CDC 公共卫生数据来自 CDC Open Data 门户和 CDC WONDER。搜索有关疫苗接种、监测和行为风险的 1,000 多个数据集，查看其架构并使用 SoQL 查询，或按年份、年龄、性别和种族获取全国死亡统计数据。

工具

工具	描述
cdc_discover_datasets	按关键词、类别或标签搜索 CDC 数据集目录
cdc_get_dataset_schema	获取数据集的列架构、行数和元数据
cdc_list_catalog_vocabulary	列出目录的类别和标签值及其条目数
cdc_query_dataset	执行 SoQL 查询——筛选、聚合、排序、全文搜索、选择字段
cdc_query_wonder	查询 CDC WONDER，获取五个数据库中的全国死亡率、人口和死亡率数据

资源

资源	描述
cdc://datasets	浏览量最高的前 50 个目录条目，供参考
cdc://datasets/{datasetId}	特定数据集的元数据和前 100 列

这两项资源与通过 cdc_discover_datasets 和 cdc_get_dataset_schema 也可获取的数据相同，适用于支持资源但不支持工具的客户端。

提示词

提示词	描述
analyze_health_trend	引导式工作流，用于跨 CDC 数据调查公共卫生问题

功能参考

cdc_discover_datasets _工具

• 筛选条件：query、category 和 tags。每页最多返回 100 条结果（默认 10 条）；offset + limit 上限为 10,000（超过后会返回 page_out_of_range）。order 可设为 dataset_id（默认值，分页稳定）或 relevance
• 结果包含 assetType、columnCount（值为 0 表示图表、地图或其他非表格资源）、包含 8 个名称的 columnSample，以及截断至 300 个字符的描述；此外还包含 totalCount 和 appliedFilters
• 当 category 或 tags 的值没有匹配项时，notice 会列出最接近的目录值及其条目数，例如：Vaccination → "Vaccinations" (89 datasets)

---

cdc_get_dataset_schema _工具

• 接受四乘四格式的 datasetId（例如 bi63-dtpu）。column_limit（默认 100）和 column_offset 用于分页查看宽表结构，并返回 totalCount、truncated 和 nextOffset
• 数据集的 description 默认上限为 4,000 个字符（截断时会设置 descriptionTruncated 和 descriptionLength）；full_description: true 会返回完整文本
• 列包含 fieldName、dataType 和 description。rowCountSource 说明 rowCount 是实时值（live）还是 Socrata 的缓存值（cached）。非表格资源会返回 not_queryable 错误

---

cdc_list_catalog_vocabulary _工具

• 每个类别都会完整返回；约 1,600 个标签按条目数排序，并通过 tag_limit（默认 50）和 tag_offset 分页。filter（至少 3 个字符）会按词语匹配进行筛选，不进行模糊匹配
• 每个值都包含 datasetCount；响应还会报告 vocabularySize、categoryCount、tagCount、truncated、nextOffset 和 truncationCeiling（页面之后标签数量的上限）

---

cdc_query_dataset _工具

• 查询子句：select、where、group、having、order 和全文搜索 search。每次调用最多返回 5,000 行（默认 100 行），offset 最大为 1,000,000
• 如需稳定地按偏移量分页，请将唯一的决胜字段放在 order 末尾（未分组行使用 :id，分组查询使用分组列）；缺少该字段时，notice 会提示
• effectiveQuery 会原样回显发送的 SoQL 子句；truncated 和 nextOffset 会报告分页信息，不提供 totalCount。图表或地图 ID 会返回 not_queryable 错误

---

cdc_query_wonder _工具

database	CDC 数据库	年份	种族组	mcd_icd10
underlying_1999_2020 (默认)	D76 — 根本死因	1999–2020	4 个衔接组	—
provisional	D176 — 临时死亡统计	2018 年至当前年份	6 个单一种族组	是
underlying_2018_2024	D158 — 根本死因，单一种族	2018–2024	6 个单一种族组	—
multiple_1999_2020	D77 — 多重死因	1999–2020	4 个衔接组	是
multiple_2018_2024	D157 — 多重死因，单一种族	2018–2024	6 个单一种族组	是

• group_by 接受 year、age_group、sex、race 中的 1–4 项（仅限全国数据）。cause_icd10 和 mcd_icd10 接受 ICD-10 代码、范围（X40-X49）或最多包含 50 项的列表。age_groups 接受单独的 NS（未注明年龄），或与全部 11 个已知年龄组一起使用。使用 limit 和 offset（最大 10,000）对表格分页
• 行包含 deaths、population、crude_rate，以及在可进行年龄标准化时提供的 age_adjusted_rate。CDC 返回为 Suppressed、Unreliable 或 Not Applicable 的单元格会显示为 null，并列在 cellNotes 中；messages 会报告 CDC 隐藏的行，totalCount 为准确值
• CDC 要求请求间隔至少 15 秒，因此调用会逐个排队，间隔 16 秒

---

cdc://datasets _资源

• 按受欢迎程度排列的前 50 个目录条目，每项包含 id、name、assetType、category、columnCount 和 updatedAt，另附目录的 totalCount
• columnCount: 0 表示非表格条目；cdc_discover_datasets 可搜索完整目录并进行分页

cdc://datasets/{datasetId} _资源

• 数据集元数据以及前 100 列，格式为 application/json，包含 columnCount 和 truncated；描述最多 4,000 个字符
• 如需查看更多列或完整描述，请使用 cdc_get_dataset_schema，并设置 column_offset 或 full_description: true

---

analyze_health_trend _提示词

• 参数：必填 topic；可选 timeRange 和 geography
• 返回一条用户消息，将问题路由到 cdc_query_wonder（全国死亡率）或 Socrata 工具（其他所有情况），随后依次进行发现 → 检查 → 建立基线 → 比较 → 综合分析

功能

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

CDC 特有功能：

• 通过 CDC Open Data 门户访问 Socrata SODA API v2.1（约 1,080 个数据集）；无需身份验证，可选应用令牌可提高速率限制
• 通过 XML 请求 API 访问 CDC WONDER 死亡率数据，涵盖 1999 年至当前年份的五个数据库
• 三个 Socrata 工具均接受 domain 输入，仅限 data.cdc.gov（默认）和 chronicdata.cdc.gov；两者提供相同的目录
• category 和 tags 必须与目录自身的取值匹配（类别区分大小写，标签不区分大小写）；cdc_list_catalog_vocabulary 可列出这些取值
• Socrata 会将所有值作为字符串返回，而 year 之类的列在某些数据集中是数字，在另一些数据集中则是文本。请根据列的 dataType 匹配 WHERE 字面量：数字不加引号，字符串使用单引号

便于 Agent 使用的输出：

• 明确报告分页信息：totalCount、truncated、nextOffset 和 shown/cap。两个查询工具的每页上限均为 200,000 个字符，因此较宽的页面可能会在达到 limit 前结束
• 每个已声明原因均提供带恢复提示的类型化错误，例如 not_queryable、page_out_of_range 和 invalid_query
• 上游数据缺失会明确显示：cellNotes 中的 WONDER 状态标记、messages 中的隐藏行提示，以及架构行数中的 rowCountSource
• effectiveQuery 会回显 SoQL 子句或 WONDER 查询摘要，以便复现结果

开始使用

公共托管实例

公共实例已部署在 https://cdc.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "cdc-health-mcp-server": {
      "type": "streamable-http",
      "url": "https://cdc.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地部署

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "cdc-health-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/cdc-health-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "cdc-health-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/cdc-health-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 Docker：

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

如需使用 Streamable HTTP，请设置传输方式并启动服务：

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

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 可选：使用 Socrata 应用令牌提高速率限制。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/cdc-health-mcp-server.git

2. 进入目录：

cd cdc-health-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# optionally set CDC_APP_TOKEN

配置

变量	描述	默认值
CDC_APP_TOKEN	Socrata 应用令牌；可提高速率限制。	无
CDC_BASE_URL	未指定 domain 时请求所用的 SODA 主机（cdc://datasets/{datasetId} 资源）。	https://data.cdc.gov
CDC_CATALOG_URL	Socrata Discovery API 基础 URL。	https://api.us.socrata.com/api/catalog/v1
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
OTEL_ENABLED	启用 OpenTelemetry。	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

  # 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 build -t cdc-health-mcp-server .
docker run --rm -p 3010:3010 cdc-health-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/cdc-health-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具/资源/提示词并初始化服务。
src/config	解析并验证服务专用环境变量，使用 Zod。
src/mcp-server/tools	工具定义（*.tool.ts）。包含四个 Socrata 工具和一个 WONDER 工具。
src/mcp-server/resources	资源定义。目录概览和数据集详情。
src/mcp-server/prompts	提示词定义。健康趋势分析工作流。
src/services/socrata	Socrata 服务——目录搜索、词汇表、元数据和 SoQL 查询。
src/services/wonder	CDC WONDER 服务——XML 请求构建器、响应解析器和请求间隔控制。
src/utils	共享辅助工具——HTML 转文本、表格单元格转义、词汇匹配和响应预算。
tests/	单元测试和集成测试，结构与 src/ 对应。

开发指南

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

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 src/index.ts 中的 createApp() 数组里注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。