who-gho-mcp-server

---

概要

WHO Global Health Observatory の世界保健統計データを提供します。194 の加盟国にわたる 3,102 件の指標を収録しています。指標を検索し、国、地域、所得グループ、性別、年でデータを照会できます。

ツール

ツール	説明
who_search_indicators	指標名に含まれるキーワードで GHO 指標カタログを検索します
who_list_indicators	ページネーションを使用して指標カタログ全体を閲覧します
who_get_indicator_metadata	指標名と次元の種類を取得します。1 回の呼び出しで 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}	次元の種類の値の、指定された 1 ページ
who://dimension/{dimensionCode}/values{?limit,offset,parentCode}	親コードで絞り込んだ、指定された 1 ページ

それぞれのリソースは、who_get_indicator_metadata および who_list_dimension_values からも取得できるデータを提供します。ツールを呼び出さずにリソースをコンテキストとして注入するクライアントに便利です。

エージェントスキル

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 _tool

• 空白で区切られた各単語は、順序を問わず指標名内の部分文字列に一致する必要があります。ステミングやファジー検索による拡張はありません。指標名に一致するものがない場合は、指標コードの完全一致検索が試行されます。
• who_query_indicator_data で使用する指標コードと表示名を返します
• オフセットベースのページネーション（offset、既定値は 0）を使用し、limit の既定値は 20、最大値は 100 です。totalCount、hasMore、pageInfo、nextOffset を報告します
• totalCount 以上のオフセットを指定すると空のページが返されます。no_results エラーは、一致するものがまったくない場合にのみ発生します

---

who_list_indicators _tool

• キーワードは不要です。3,102 件の指標カタログを参照できます
• limit（既定値は 50、最大値は 500）と offset によるオフセットベースのページネーションを使用します
• 反復処理用に totalCount と hasMore を返します

---

who_get_indicator_metadata _tool

• 最大 1,000 件の指標コードを受け付け、最初の 10 件を並列処理します。返された unprocessedCodes は次の呼び出しで送信してください。GHO_CLAMP_LIMITS=false の場合、10 件を超えるバッチは拒否されます。
• 解決された各コードについて、指標名全体とサポートされているディメンションの種類（例：COUNTRY、SEX、REGION、AGEGROUP）を返します
• 上流にディメンション一覧がない指標は、dimensions: [] と、サンプルデータ行のディメンションの種類と値のペアを示す dimensionsNote を返します。メタデータからディメンション位置は特定できません。
• カタログ項目にもディメンション行にも解決されないコードは notFound に含まれます。処理済みのコードが一つも解決されず、未処理コードも残っていない場合、呼び出しは失敗します

---

who_list_dimensions _tool

• 入力は不要です。GHO カタログ内のすべてのディメンションの種類コードと、人が読み取れるタイトルを返します
• よく使われる種類：COUNTRY、REGION、SEX、WORLDBANKINCOMEGROUP、AGEGROUP
• who_list_dimension_values を呼び出す前にコードを調べるために使用します

---

who_list_dimension_values _tool

• ディメンション値のコードとラベル（例：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 _ツール

• 空間フィルターは1回の呼び出しにつき、country_codes（過去の項目を含むWHO国コード）、region_codes（WHOの集計行）、income_group_codes（世界銀行の集計行）のいずれか1つのみ指定できます。複数を指定すると検証エラーになります。
• 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のみを指定すると、そのディメンションの最初の100件の値をapplication/jsonとして返します（dimensionCodeはwho_list_dimensionsから取得）。
• MCP SDKのRFC 6570マッチャーでは、すべてのURIクエリ変数が必須として扱われるため、以下の2つのページネーション対応形式とは別に登録されています。1つのテンプレートでは、クエリのない形式とページネーション形式の両方に対応できません。
• フィルターなしで空の結果が返された場合、そのディメンションコードは存在しません。

---

who://dimension/{dimensionCode}/values{?limit,offset} _リソース

• limit（1～500）とoffsetは、URIに両方とも指定する必要があります。クエリ変数は任意ではなく、必須です。
• URIのみの場合と同じページフィールドを返します：totalCount、hasMore、nextOffset、および任意のnotice。
• totalCount以上のoffsetを指定すると、エラーではなく空のページを返します。

---

who://dimension/{dimensionCode}/values{?limit,offset,parentCode} _リソース

• parentCodeを追加して、1つの親の値に絞り込みます。たとえば、WHO欧州地域の国の場合はparentCode="EUR"を指定します。limit、offset、parentCodeはすべてURIに指定する必要があります。
• 一致する値がない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）
• 複数のコードによる指標検索で、メタデータを並列に取得
• 行／値の順序は決定的かつ全体で一貫しており、ページネーションでページ間の行が重複したり欠落したりすることはありません

エージェントに適した出力：

• ツールの説明にツール間のワークフローを記載しているため、エージェントは説明だけを見て適切な呼び出し順序（検索 → メタデータ → クエリ）を把握できます
• 構造化されたページネーション情報（データクエリツールの hasMore、nextOffset、pageInfo、truncated）により、エージェントはさらにページを取得するかどうかを判断できます
• 判別可能な型付きエラー理由と、すべての失敗時の 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）。指標の検索、ディメンションの照会、データクエリにわたる 6 つのツール。
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 呼び出しはラップしてください。生データを検証し、ドメイン型に正規化してから、出力スキーマに沿って返します。不足しているフィールドを捏造してはいけません

コントリビューション

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。