pharmacogenomics-guidelines-mcp-server

---

概要

公開されている CPIC Database API の臨床薬理ゲノミクスのエビデンスを提供します。評価済みの遺伝子と薬剤の組み合わせ、ガイドライン、アレルの機能と頻度、ディプロタイプから表現型への変換、処方に関する推奨事項に加え、ClinPGx の検査ラベルとガイドラインへのリンクを確認できます。組み合わせを検索したり、患者のディプロタイプを変換したり、推奨事項を閲覧したり、明示的に指定した遺伝子結果と照合したりできます。6 つのツールはすべて読み取り専用で、API キーは不要です。stdio プロセス、ローカルの Streamable HTTP サーバー、または上記の公開ホストエンドポイントとして実行できます。

ツール

ツール	説明
pgx_search_pairs	遺伝子、薬剤、RxNorm/ATC 識別子、CPIC レベル、検査ラベルで評価済みの遺伝子と薬剤の組み合わせを検索します
pgx_get_guideline	ID、遺伝子、薬剤でガイドラインの対象範囲を取得し、関連する薬剤や組み合わせも確認できます
pgx_lookup_diplotype	ディプロタイプまたは HLA アレルの状態を、遺伝子結果、活性スコア、検索キーに変換します
pgx_get_recommendations	処方に関する推奨事項の原文を閲覧または照合し、オプトイン形式の CDS テストアラートの例を確認します
pgx_search_alleles	アレルの機能、エビデンス、定義メタデータ、集団別頻度を確認します
pgx_list_reference	遺伝子、遺伝子ごとの結果、統制語彙、入力形式を一覧表示します

エージェントスキル

skills/pharmacogenomics-guidelines-guide は、これらのツールを呼び出すエージェント向けに公開されたエージェントスキルです。各識別子の由来、ディプロタイプ表記、検査結果から推奨に至るまでのゲートについて説明します。プラグインのインストール時と .mcpb バンドルでは直接読み込まれます。MCP クライアントは skill://pharmacogenomics-guidelines-guide/SKILL.md リソースとして読み込みます。

機能リファレンス

pgx_search_pairs _tool

• オプションのフィルターは AND 条件で組み合わせられます：geneSymbol、drugName（文字列の部分一致）、drugId、rxnormId、atcId（階層展開なしの完全一致コード）、cpicLevel、provisional、pgxTesting、usedForRecommendation。
• RxNorm／ATC のプレフィックスと ATC の文字は、公開されるスキーマと実行時検証のどちらでも、大文字と小文字を区別せずに受け付けます。前後の空白は無視されます。空白のみの識別子は未設定として扱われます。
• limit のデフォルトは 25 です。100 を超える正の安全な整数は、通知とともに 100 に制限されます。page.nextOffset から続けてください。
• 薬剤レコードとガイドラインへのリンクをそれぞれ含む、完全なペアレコードを返します。Retired のペアは includeRetired: true または cpicLevel: "Retired" の場合にのみ表示されます。

---

pgx_get_guideline _tool

• 3 つの検索モードがあり、他のモードのセレクターは拒否されます：
  • by: "id" と guidelineId
  • by: "gene" と geneSymbol
  • by: "drug" と drugName（完全一致、大文字と小文字を区別しない）または drugId のいずれか一方のみ
• デフォルトの view: "summary" では、正確な drugCount と pairCount を含む完全なガイドラインレコードをページ分割して返します。view: "drugs" または "pairs" では by: "id" が必要です。ガイドラインの記述情報は維持され、選択したトップレベルのコレクションがページ分割されます。もう一方のコレクションは省略されます。
• limit のデフォルトは 25 です。100 を超える正の安全な整数は、通知とともに 100 に制限されます。page.nextOffset を使用して続けてください。ページでは、両方のレスポンス形式とエンリッチメントを合わせた 24,000 バイトのソフト上限が適用され、完全な行の間でのみ切り詰められます。分割できないサイズ超過の行がある場合は、通知とともに oversizedRow: true が設定されます。
• 該当データがない場合は found: false が返されます。薬剤名が曖昧な場合は、ページ分割された candidates が返されます。その場合、page、shown、truncated は候補について記述します。そのリストにある drugId を使って再試行してください。

---

pgx_lookup_diplotype _tool

• geneSymbol と、ソースでサポートされている diplotype を指定します。アレルの順序はどちらでもかまいません：
  • スターアレル（*1/*2、*1x2/*4）
  • HLA アレルの状態（*57:01 positive）
  • 非スター表記（c.1905+1G>A (*2A)/Reference）
• found、matchedDiplotype、guidance に加え、遺伝子の結果、活性スコア、EHR 優先度、検索キーを含む、一致したすべてのソースレコードを返します。
• 複数のレコードが一致した場合は曖昧なまま返され、単一の結果に絞り込まれることはありません。結果の計算は行われません。

---

pgx_get_recommendations _ツール

• 処方に関する推奨事項を取得する場合は、view を省略するか、view: "recommendations" を指定します。view: "test_alerts" は、同じ薬剤、遺伝子型、結果、集団、ページ指定セレクターを使用して CPIC の CDS 言語の例を選択します。推奨事項の取得やガイドラインの結合は行いません。
• mode: "drug" では、drugName（大文字と小文字を区別しない完全一致）または drugId のいずれか一方だけを指定します。
  • 単独で指定するか、geneSymbol または population と組み合わせると、参照モード（exploratory）になります。
  • 照合するには、phenotype または activityScore を追加します。薬剤の推奨事項に複数の遺伝子が関係する場合は、これらの指定に geneSymbol が必要です。
  • または、geneResults マップを追加します。1～10 個の遺伝子を指定し、それぞれを { kind: "phenotype" | "activityScore" | "alleleStatus", value } の形式にします。
• mode: "genotype" では、genotype に1～10個の遺伝子→ディプロタイプのエントリを指定します。各エントリは一意に解決される必要があります。任意の薬剤セレクターを指定すると、結果を絞り込めます。
• mode: "results" では、geneResults、または phenotype／activityScore のいずれか1つを指定した geneSymbol に基づき、複数の薬剤を横断して検索します。任意の薬剤セレクターを指定すると、結果を絞り込めます。関連しないパネル遺伝子が推奨事項を除外することはありませんが、その前提条件と矛盾する結果は除外されます。
• ソースの遺伝子 lookupmethod によって、受け付ける結果の種類が決まります。PHENOTYPE では phenotype、ACTIVITY_SCORE では phenotype または activityScore、ALLELE_STATUS では alleleStatus を指定できます。値はソースの結果／スコアフィールドに照らして検証されます。表現型が計算済みスコアに変換されることはありません。照合する前に、pgx_list_reference の genes トピックと phenotypes トピックを確認してください。
• すべてのモードで、完全一致する population、limit（デフォルトは10）、offset を指定できます。正の安全な整数である limit が50を超える場合は、通知とともに50に制限されます。incompleteLimit（デフォルトは25）は独立して適用され、100を超える場合は制限されます。incompleteOffset は incompletePage.nextOffset を通じて、欠落遺伝子の診断結果をページ分割します。
• status は exploratory、matched、no_match、incomplete、unresolved のいずれかです。薬剤の照合と結果の照合では、入力された遺伝子と少なくとも1つ重複する必要があります。重複する前提条件に関する矛盾は拒否されますが、検証済みパネル内の無関係な遺伝子は無視されます。検索キーに含まれるすべての遺伝子に明示的な結果がある場合にのみ、行が一致します。incompleteMatches には、追加の遺伝子が必要な行が missingGenes とともに列挙され、処方に関するテキストは含まれません。
• 結果が空の場合の通知では、薬剤が解決されない場合、推奨事項のテーブルがない場合、集団が一致しない場合、ページが末尾を超えた場合を区別します。ソースに該当する情報がある場合、テーブルがない旨の通知には、参照用のガイドラインへのリンクが含まれます。
• アラートビューでは、順序付きの alerttext、単数形の phenotype、検索キー、アレルの状態、スコア、集団、バージョンを含む、ソースの完全なレコードが alerts に返されます。No CDS、n/a、疎なフィールド、ソースに明示的に存在する No Result の行は、そのまま維持されます。省略された遺伝情報が No Result に変換されることはありません。前提条件の不足は、アラートテキストを含まず、incompleteAlerts に { testAlertId, drugId, missingGenes } としてのみ表示されます。items と incompleteMatches は空のままです。page と incompletePage は、アラートと診断結果のページ情報を示します。デフォルトのレスポンスでは、どちらのアラートフィールドも省略されます。

---

pgx_search_alleles _ツール

• geneSymbol が必要です。name はまず完全一致で照合し、その後、遺伝子名が先頭に付いた星型アレルの接頭辞を除いて再照合します。clinicalFunctionalStatus は大文字と小文字を区別せず、テキストの完全一致で照合します。返されるソースの表記は変更されません。effectiveQuery には使用されたアレル名が示されます。
• limit のデフォルトは 25 です。100 を超える正の安全な整数は、通知とともに 100 に制限されます。0 以下、小数、安全でない整数の指定は、データ取得前にエラーになります。offset は 0 以上の安全な整数です。
• 24,000 バイトのソフト上限では、両方のレスポンス形式とエンリッチメントを含む、シリアライズされたツール結果全体のサイズを測定します。切り詰める場合は、完全なアレル単位の境界でのみ切り詰め、すべての頻度行を保持します。分割できない先頭行が上限を超える場合は、通知とともに oversizedRow: true を設定します。残りの行を再構築するには、page.nextOffset をたどってください。
• 定義メタデータとともに、アレルの機能およびエビデンスと populationFrequencies を返します。頻度はソースの分数のまま保持され、欠損値は欠損のまま保持され、推定頻度には推定値であることを示すフラグが付きます。

---

pgx_list_reference _ツール

• topic には次のいずれかを指定します。
  • genes — geneSymbol によるフィルタリングは任意です
  • phenotypes — geneSymbol が必要です
  • cpic_levels、pgx_testing、classifications、input_formats
• ライブトピック 2 件（genes、phenotypes）は、limit（デフォルト 25）と offset を使ってページングします。100 を超える正の安全な整数の limit は、通知とともに 100 に制限されます。これらは、個別の活性スコア、頻度、相談テキストを含む、遺伝子と遺伝子結果の完全なレコードを返します。
• 静的トピックは CPIC API を呼び出さずに、語彙全体を返します。geneSymbol は受け付けず、verificationDate が付与されます。

機能

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

CPIC 固有の機能：

• 1 つの検索チェーン：参照値 → ペア → ガイドライン → アレルおよびディプロタイプのエビデンス → 推奨
• CPIC 評価レベル、ClinPGx の検査ラベル、推奨分類はそれぞれ区別して保持されます。検査ラベルは FDA ラベルではなく、評価済みのペアは推奨ではありません。
• 照合には、指定された結果のみを使用します。省略された遺伝子が正常、陰性、または Indeterminate であると仮定することはありません。表現型、小数の活性スコア、HLA アレルのステータスは、それぞれ CPIC 独自の値に照らして検証されます。
• 上限付きワークフロー：
  • 45 秒の期限、最大 100 回の HTTP 試行、同時リクエスト 3 件、リクエストごとに 2 回の再試行
  • 関連項目のスキャンは 2,000 行で停止します（薬剤の解決は 500 行）。ガイドライン一覧と詳細ビューはソース側でページングされます。関連項目の件数にはソースの正確な合計を使用し、合計がない場合に限り、上限付きスキャンを行います。スキャン上限を超えると、部分的な結果を返すのではなく、呼び出しは query_too_broad として失敗します。

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

• 来歴： 重複を除いた正確なリクエスト URL、アクセス時刻、返された行のバージョン、ライセンスおよびポリシーへのリンク。各バージョンは結果内の RFC 6901 JSON Pointer を使用し、requestIndex は requestUrls 内の位置を示します。API の v1 はインターフェースを示すもので、データベースのリリースを示すものではありません。
• 明示的な結果： 推奨の status、遺伝子ごとの geneResolutions、incompleteMatches、復旧方法のテキストを含む型付きエラー理由。
• 情報を損なわないテキスト出力： content[] は完全な結果を JSON として保持し、各レンダリングブロックで、重複しない宛先ごとにクリック可能なリンクを 1 つ配置します。これは structuredContent と一致します。effectiveQuery、notices、page（total、nextOffset）が各結果を説明します。

出典の明記と臨床上の限界

データはCPIC DatabaseとClinPGxから取得しています。CPIC のデータライセンスとClinPGx の利用ポリシーは出典データに適用され、このリポジトリの Apache-2.0 ライセンスはコードに適用されます。

データベースのテーブルでは、ガイドラインの詳細が省略されていたり、ガイドラインの更新が反映されていなかったりする場合があるため、臨床で使用する前に、リンク先の各ガイドラインを確認してください。結果は、明記された遺伝子、薬剤、集団、適応症にのみ適用され、治療の決定は引き続き臨床医と患者が行います。サーバーは患者記録を保存しませんが、遺伝子に関するクエリは CPIC API に送信され、クエリを含むリクエスト URL がレスポンスに表示されます。

はじめに

インストール不要で、ホスト済みのインスタンスに接続できます。

claude mcp add --transport http pharmacogenomics-guidelines-mcp-server https://pharmacogenomics-guidelines.caseyjhand.com/mcp

ホスト済みのインスタンスへのクエリは、CPIC API に到達するまでにそのサーバーを経由します。患者データを扱う場合は、ご自身でインスタンスを実行してください。

または、ローカルで実行します。

claude mcp add pharmacogenomics-guidelines-mcp-server -- npx -y @cyanheads/pharmacogenomics-guidelines-mcp-server

その他のクライアントでは、これを MCP 設定ファイルに追加してください。

{
  "mcpServers": {
    "pharmacogenomics-guidelines-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/pharmacogenomics-guidelines-mcp-server"]
    }
  }
}

API キーは不要です。Docker またはソースからのビルドについては、サーバーの実行を参照してください。

設定

サーバー固有の環境変数は必要ありません。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_HOST	HTTP バインドアドレス。	127.0.0.1
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_ENDPOINT_PATH	MCP エンドポイントのパス。	/mcp
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	debug
OTEL_ENABLED	OpenTelemetryを有効にします。	false

共通のフレームワーク設定の上書きについては、.env.exampleを参照してください。

サーバーの実行

ローカル開発

Bun v1.4.0以降（または Node.js v24 以降）と、https://api.cpicpgx.orgへのネットワークアクセスが必要です。

• クローンしてインストールします。

  git clone https://github.com/cyanheads/pharmacogenomics-guidelines-mcp-server.git
  cd pharmacogenomics-guidelines-mcp-server && bun install
  cp .env.example .env   # optional: adjust transport, logging, or telemetry settings
  

• 本番版をビルドして実行します。

  # 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 run --rm -p 3010:3010 ghcr.io/cyanheads/pharmacogenomics-guidelines-mcp-server:latest

イメージのデフォルトは HTTP トランスポート、ステートレスセッションモードで、ログは /var/log/pharmacogenomics-guidelines-mcp-server に出力されます。MCP クライアントから stdio で実行するには、"command": "docker" と "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pharmacogenomics-guidelines-mcp-server:latest"] を使用してください。ローカルでビルドするには、docker build -t pharmacogenomics-guidelines-mcp-server . を実行します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/mcp-server/tools/definitions	6 つのツール定義と allToolDefinitions レジストリ。
src/mcp-server/tools/shared	ページングスキーマとロスレスの Markdown レンダリング。
src/services/cpic	固定ホストへの CPIC リクエスト、出典レコードのスキーマ、探索、エビデンス、推奨事項の照合。
skills	公開済みのエージェントスキル。createApp({ skills }) を介して MCP で提供されます。
tests/unit	サービス、ツールコントラクト、境界条件、フォーマッターのテスト。
tests/integration	公開済みのスキルリソースを確認する stdio サーバーのテスト。
tests/scripts	バンドルクリーナーとパッケージングリンターのセレクターのテスト。
docs	設計コントラクトと生成されたディレクトリツリー。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。概要は以下のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使用しないでください
• ログには ctx.log を、ストレージには ctx.state を使用してください
• 新しいツールは allToolDefinitions（src/mcp-server/tools/definitions/index.ts）に登録してください。src/index.ts がこれを createApp() に渡します
• 外部 API 呼び出しはラップしてください。生データを検証し、ドメイン型に正規化してから、出力スキーマを返します。不足しているフィールドを決して捏造しないでください

コントリビューション

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

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License の下でライセンスされています。詳しくは LICENSE ファイルを参照してください。