Ncbi Variation

@pipeworx/ncbi-variation

NCBI Variation Services の dbSNP refSNP レコードと HGVS ↔ SPDI ↔ rsID の正規化 — ヒトの遺伝的バリアントのあらゆる表記を、ゲノミクスの他の処理が基準とする正規座標に変換するサービスです。

Pipeworx の一部です。AI エージェントを 1683 以上の稼働中のデータソースに接続する MCP ゲートウェイです。

ツール

• variation_refsnp(rsid, assembly?, max_frequencies?) — 完全な refSNP レコードです。指定したビルド上のゲノム配置、HGVS のゲノム／転写産物／タンパク質表記、SPDI、遺伝子コンテキスト、ClinVar の臨床的意義、集団ごとのアレル頻度（gnomAD、ExAC、1000 Genomes、TOPMED、ALFA）を返します。「rs113488022 とは何か」に回答します。
• variation_hgvs_to_spdi(hgvs) — HGVS 表記をコンテキスト付き SPDI アレルに正規化し、HGVS の形式が正しいかどうかも検証します。
• variation_spdi_to_rsids(spdi) — 逆方向の変換です。VCF やパイプラインから得た座標とアレルを、他のデータベースが基準とする rsID に変換します。

認証

認証キーは不要です。NCBI は未認証のクライアントに対し、毎秒約 3 リクエスト未満に抑えるよう求めています。このパックは識別用の User-Agent を送信します。

データソース

• https://api.ncbi.nlm.nih.gov/variation/v0/refsnp/{rsid} — refSNP レコード。
• https://api.ncbi.nlm.nih.gov/variation/v0/hgvs/{expr}/contextuals — HGVS → SPDI。
• https://api.ncbi.nlm.nih.gov/variation/v0/spdi/{spdi}/rsids — SPDI → rsID。

注意点

GRCh37 と GRCh38 の違いがすべてを左右します。 1 つの refSNP が、異なる座標で両方のビルドに配置されることがあります。rs113488022（BRAF V600E）は、GRCh38 では 7:140753336、GRCh37 では 7:140453136 に位置し、300kb 離れています。一方のビルドの座標を、もう一方のビルドで注釈付けされたデータセットに渡すと、「見つかりません」となり、「このバリアントは存在しない」と解釈されてしまいます。そのため、assembly は明示的な引数です（デフォルトは GRCh38）。すべての応答で assembly_requested と assemblies_available を示し、指定したビルドに配置がない場合は空の配列を返す代わりに assembly_note でその旨を示します。

SPDI は 0 始まり、HGVS は 1 始まりです。 NC_000007.14:140753335:A:T と NC_000007.14:g.140753336A>T は同じバリアントです。この 1 塩基のずれが、variation_spdi_to_rsids が何も返さない最も一般的な原因です。

廃止された rsID はエラーではありません。 dbSNP は rsID を統合します。統合された rsID では primary_snapshot_data はなく、merged_snapshot_data が返されます。このパックはこれを検出し、空のレコードを返すのではなく、再照会に使う rsID（rs3735962 → rs328）と status: "merged" を返します。

リファレンスアレルもアレルリストに含まれます。 dbSNP は、deleted_sequence と inserted_sequence が等しいリファレンスをアレルとして列挙します。これらを除外することで、alternate_alleles と不要なデータを区別できます。

生のレコードは非常に大きくなります。 rs328 には数千件の引用文献と数十件の配置情報が含まれます。このパックは要約して上限を設けます（max_frequencies、引用文献 25 件）。切り詰められたことが分かるよう、件数は常に併記されます。

クイックスタート

MCP クライアント（Claude Desktop、Cursor、Windsurf など）に追加します。

{
  "mcpServers": {
    "ncbi-variation": {
      "url": "https://gateway.pipeworx.io/ncbi-variation/mcp"
    }
  }
}

このエンドポイントが実際に提供するもの

https://gateway.pipeworx.io/ncbi-variation/mcp の tools/list は、上の表にあるツールに加えて、Pipeworx 共通のメタツールである ask_pipeworx、discover_tools、search_within、remember／recall など、ゲートウェイ全体で使えるツールも返します。そのため、表示されるツール数はこの表より多くなります。現在、単一パックのエンドポイントには、そのパック独自のツールに加えて、共通ツールが約 30 個表示されます。接続の initialize レスポンスに正確な範囲が記載されており、その日の情報として最も信頼できます。

これは意図的な設計であり、偶然に多重化されているわけではありません。メタツールを使えば、このパックでは対応できない質問にも、カタログ全体を対象にルーティングする ask_pipeworx を通じて回答できます。別の MCP サーバーを追加する必要はありません。現時点では、メタツールなしでパックのエンドポイントに接続する方法はありません。追加のスキーマによるコンテキスト消費がルーティングの利点を上回る場合は、複数のパックのエンドポイントではなく、フルゲートウェイに一度だけ接続してください。

または、Pipeworx ゲートウェイ全体に接続すると、このパックのツールだけでなく、すべてのパックのツールが直接一覧表示されます。

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

どちらの URL も、同じゲートウェイと同じ 1683 以上のデータソースにつながります。違いは、どのパックのツールが直接一覧表示されるかだけです。どちらからでも、ask_pipeworx を使えばすべてのツールにアクセスできます。

MCP クライアントがなくても、HTTP 経由で呼び出せます

curl -X POST https://gateway.pipeworx.io/v1/tools/variation_refsnp \
  -H 'Content-Type: application/json' \
  -d '{"rsid":"rs113488022","assembly":"GRCh38"}'

最初の呼び出しにアカウントは必要ありません。任意のツールを確認するには、GET https://gateway.pipeworx.io/v1/tools/variation_refsnp を実行します。ツールを探すには、{"query":"..."} を指定して POST https://gateway.pipeworx.io/v1/tools/search_packs を実行します。

スタンドアロン（ゲートウェイアカウント不要）

このパッケージは、ローカルの stdio MCP サーバーとしても実行できます。Pipeworx アカウントも、ゲートウェイへのラウンドトリップも不要です。

{
  "mcpServers": {
    "ncbi-variation": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-ncbi-variation"]
    }
  }
}

または、直接実行して起動することを確認できます。

npx -y @pipeworx/mcp-ncbi-variation

stdin/stdout 経由で MCP を使用し、このパックのツールのみを対象に initialize／tools/list／tools/call に応答します。上記のゲートウェイ接続で追加される共通メタツールは含まれません。同じソース、同じツールですが、ask_pipeworx によるルーティングはありません。

ask_pipeworx の使用

ツールを直接呼び出す代わりに、自然な英語で質問できます。これは上記のパックのエンドポイントでも、フルゲートウェイでも利用できます。

ask_pipeworx({ question: "your question about Ncbi Variation data" })

ゲートウェイが適切なツールを選択し、引数を自動的に設定します。

詳細情報

• ドキュメントとガイド
• pipeworx.io

ライセンス

MIT