who-gho-mcp-server

---

概览

WHO 全球健康观察站的全球健康统计数据：涵盖 194 个成员国的 3,102 项指标。搜索指标，并按国家、地区、收入组、性别和年份查询数据。

工具

工具	描述
who_search_indicators	按指标名称中的关键词搜索 GHO 指标目录
who_list_indicators	分页浏览完整指标目录
who_get_indicator_metadata	获取指标名称和维度类型；每次调用处理 10 个代码，批量较大时可继续获取
who_list_dimensions	列出 GHO API 中提供的所有维度类型代码
who_list_dimension_values	列出某个维度类型（COUNTRY、REGION、SEX 等）的有效代码和标签
who_query_indicator_data	查询某项指标的数据行，并应用空间、时间和维度筛选条件

资源

资源	描述
who://indicator/{indicatorCode}/metadata	单个代码对应的指标名称和支持的筛选维度
who://dimension/{dimensionCode}/values	某个维度类型的前 100 个值
who://dimension/{dimensionCode}/values{?limit,offset}	某个维度类型值的一个指定页面
who://dimension/{dimensionCode}/values{?limit,offset,parentCode}	某个维度类型值的一个指定页面，并按父级代码缩小范围

每项资源均对应可通过 who_get_indicator_metadata 和 who_list_dimension_values 获取的数据，适用于会将资源注入上下文但不会调用工具的客户端。

Agent 技能

who-gho-guide 涵盖维度位置发现、完整的国家比较，以及国家与区域汇总数据的区别。它随插件安装包、npm、Docker 和 MCPB 捆绑包一同提供。MCP 客户端可通过 resources/list 或 io.modelcontextprotocol/skills 扩展（skills/list、skills/get 和 resources/directory/read）发现其 SKILL.md；该服务还会公开 skill://{+path} 资源模板。

功能参考

who_search_indicators _工具

• 每个以空格分隔的单词都必须按任意顺序与指标名称中的子字符串匹配；不进行词干提取或模糊扩展。如果名称没有匹配项，则会尝试精确查询指标代码。
• 返回指标代码和显示名称，供 who_query_indicator_data 使用
• 基于偏移量的分页（offset，默认值为 0），limit 默认值为 20，最大值为 100；会报告 totalCount、hasMore、pageInfo、nextOffset
• 偏移量达到或超过 totalCount 时会返回空页；仅在完全没有匹配项时才会引发 no_results 错误

---

who_list_indicators _工具

• 无需关键词 — 浏览包含 3,102 个指标的目录
• 通过 limit（默认值为 50，最大值为 500）和 offset 进行基于偏移量的分页
• 返回 totalCount 和 hasMore，以便遍历结果

---

who_get_indicator_metadata _工具

• 最多接受 1,000 个指标代码，并并行处理前 10 个；请在下一次提交返回的 unprocessedCodes。当 GHO_CLAMP_LIMITS=false 时，超过 10 个的批次会被拒绝。
• 返回每个已解析代码的完整指标名称和支持的维度类型（例如 COUNTRY、SEX、REGION、AGEGROUP）
• 如果上游没有列出维度，指标会返回 dimensions: []，以及指向样本数据行维度类型/值对的 dimensionsNote。元数据不会标识维度位置。
• 无法解析为目录条目或维度行的代码会列入 notFound；如果没有已处理代码解析成功，且没有剩余未处理代码，则调用会失败

---

who_list_dimensions _工具

• 无需输入 — 返回 GHO 目录中的所有维度类型代码和易读标题
• 常见类型：COUNTRY、REGION、SEX、WORLDBANKINCOMEGROUP、AGEGROUP
• 调用 who_list_dimension_values 前，可使用此工具查找代码

---

who_list_dimension_values _工具

• 返回该维度各值的代码和标签（例如，234 个国家条目、43 个 WHO 区域代码），以及可选的父级层次结构字段（parentCode、parentLabel、parentDimension）
• parent_code 可缩小层次维度的范围 — dimension: "COUNTRY" 配合 parent_code: "EUR" 会返回 WHO 欧洲区域的 58 个国家
• 按 Code 确定性排序；基于偏移量（offset）分页，limit 默认值为 100，最大值为 500 — GHO（3,103 个值）和 DHSMICSGEOREGION（4,932 个值）需要分页
• 对于已知维度，不匹配任何值的 parent_code 会返回空页；即使指定了父级筛选条件，未知维度也会报错
• dimension 中出现未配对的 UTF-16 代理项时，会作为带类型的 malformed_identifier 验证错误而失败

---

who_query_indicator_data _工具

• 每次调用只能使用一种空间筛选条件：country_codes（WHO 国家代码，包括历史条目）、region_codes（WHO 汇总行）或 income_group_codes（世界银行汇总行）——同时提供多个会导致验证错误
• 使用 year_from / year_to 设置时间范围；sex（SEX_BTSX、SEX_FMLE、SEX_MLE）仅在指标的第一个跨领域维度为 SEX 时适用。dim1_value、dim2_value 和 dim3_value 用于选择观测到的位置值；应从返回的类型/值对中查找位置，而非从元数据中查找。sex 会覆盖 dim1_value，并附带提示。
• include_uncertainty（默认值为 true）会添加 low/high 界限；sort（默认为 year_desc，也可设为 year_asc）会进行总行排序，确保分页不会重复或遗漏行
• 基于偏移量的分页，limit 默认值为 200，最大值为 1000；会报告 totalRows、hasMore、pageInfo、nextOffset
• 类型化失败原因：indicator_not_found、no_data、ambiguous_spatial_filter、invalid_year_range、invalid_query、malformed_identifier

---

who://indicator/{indicatorCode}/metadata _资源

• 以 application/json 格式返回指标名称和支持的筛选维度
• indicatorCode 来自 who_search_indicators 或 who_list_indicators
• 如果上游维度表中没有列出该代码对应的维度，则空的 dimensions 会附带 dimensionsNote，而不会报告指标缺失
• 仅当该代码既无法解析到目录名称，也没有任何维度行时，才会返回 404 错误

---

who://dimension/{dimensionCode}/values _资源

• 裸 URI 会以 application/json 格式返回该维度的前 100 个值（dimensionCode 来自 who_list_dimensions）
• 与下方两个分页变体分开注册，因为 MCP SDK 的 RFC 6570 匹配器会将 URI 中的每个查询变量都视为必填项——一个模板无法同时适用于裸 URI 和分页形式
• 未筛选时结果为空，表示该维度代码不存在

---

who://dimension/{dimensionCode}/values{?limit,offset} _资源

• URI 中必须同时提供 limit（1–500）和 offset——查询变量是必填项，而非可选项
• 分页字段与裸 URI 相同：totalCount、hasMore、nextOffset，以及可选的 notice
• offset 大于或等于 totalCount 时会返回空页，而非错误

---

who://dimension/{dimensionCode}/values{?limit,offset,parentCode} _资源

• 添加 parentCode，以缩小范围至某个父级值，例如使用 parentCode="EUR" 表示 WHO 欧洲区域内的国家；URI 中必须同时提供 limit、offset 和 parentCode
• parentCode 未匹配到任何值时，已知维度会返回空页；即使提供了父级筛选条件，未知维度仍会报错
• 输出结构与裸 URI 和分页资源相同：dimension、values、totalCount、hasMore、nextOffset、notice

功能

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

WHO GHO 专属功能：

• 完整覆盖 WHO GHO OData API v2——指标、维度、维度值和数据查询
• 可配置基础 URL 和服务操作截止时间（GHO_BASE_URL、GHO_REQUEST_TIMEOUT_MS），支持自定义或镜像部署
• 对多个代码的指标查询并行获取元数据
• 行和数值采用确定性的全序排列——分页不会在不同页面间重复或遗漏行

便于 Agent 使用的输出：

• 工具描述中包含跨工具工作流——Agent 仅凭描述即可了解正确的调用顺序（搜索 → 元数据 → 查询）
• 提供结构化分页信号（数据查询工具上的 hasMore、nextOffset、pageInfo 和 truncated），方便 Agent 判断是否继续分页
• 错误原因经过区分并具有类型，每种失败路径都会提供 recovery 提示
• 区分空页面与未找到语义——翻页超出末尾、筛选条件未匹配，以及确实不存在的代码都会返回不同结果，而不会统统变成泛化的空结果

开始使用

公共托管实例

公共实例位于 https://who-gho.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

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

自托管 / 本地运行

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

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

也可以使用 npx（无需 Bun）：

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

也可以使用 Docker：

{
  "mcpServers": {
    "who-gho-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/who-gho-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 ≥24）。
• 无需 API 密钥——WHO GHO API 是公开的。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/who-gho-mcp-server.git

2. 进入目录：

cd who-gho-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set optional overrides

配置

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_ENDPOINT_PATH	挂载 MCP 服务的 HTTP 端点路径	/mcp
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。没有工具会在处理程序运行期间要求调用方输入，因此服务声明为 stateless；仅在需要覆盖时设置此项。	stateless
MCP_PUBLIC_URL	用于 TLS 终止反向代理部署的公共源覆盖值	无
MCP_AUTH_MODE	身份验证：none、jwt 或 oauth	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）	info
MCP_GC_PRESSURE_INTERVAL_MS	选择启用的、仅限 Bun 的强制 GC 压力循环（毫秒）。如果持续 HTTP 负载下 RSS 增长，可尝试设置为 60000。	0（已禁用）
LOGS_DIR	日志文件目录（仅限 Node.js）	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
GHO_BASE_URL	WHO GHO OData API 基础 URL（用于自定义／镜像部署的覆盖值）	https://ghoapi.azureedge.net/api/
GHO_REQUEST_TIMEOUT_MS	服务操作的截止时间（毫秒），涵盖请求、读取响应正文、重试和退避	30000
GHO_CLAMP_LIMITS	将正整数分页限制值限制为：搜索 100、指标／维度浏览 500、数据查询 1,000，并显示提示。元数据每次处理 10 个条目并返回续传信息。设为 false 可恢复公布的最大值，并拒绝超出限制的请求。	true
OTEL_ENABLED	启用 OpenTelemetry	false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP 基础 URL；跟踪和指标会导出到其下的 /v1/traces 和 /v1/metrics。日志导出需通过 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 选择启用。	无
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果（仅按键名进行脱敏）	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 who-gho-mcp-server .
docker run --rm -p 3010:3010 who-gho-mcp-server

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

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具／资源并初始化 GHO 服务。
src/config	使用 Zod 解析和验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。共六个工具，涵盖指标发现、维度查询和数据查询。
src/mcp-server/resources	资源定义。指标元数据和维度值资源。
src/services/gho	WHO GHO OData API 服务层——HTTP 客户端、查询构建器、类型。
src/utils	wellFormed()——修复调用方提供的字符串中的未配对 UTF-16 代理项，避免其进入输出、补充数据或故障数据。
tests/	单元和集成测试，结构与 src/ 对应。

开发指南

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

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

贡献

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

bun run devcheck
bun run test

许可证

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