Ncbi Variation

@pipeworx/ncbi-variation

来自 NCBI Variation Services 的 dbSNP refSNP 记录及 HGVS ↔ SPDI ↔ rsID 标准化——该服务可将人类遗传变异的各种写法转换为基因组学其他环节使用的规范坐标。

属于 Pipeworx 的一部分——一个将 AI Agent 连接到 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 的差异至关重要。 同一个 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；被合并的 ID 会返回 merged_snapshot_data，且完全不包含 primary_snapshot_data。此工具包会识别这种情况， 并返回 status: "merged" 及需要重新查询的 rsID（rs3735962 → rs328），而不是空记录。

参考等位基因也在等位基因列表中。 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"
    }
  }
}

此端点实际提供的内容

tools/list 在 https://gateway.pipeworx.io/ncbi-variation/mcp 返回上表中的工具，以及 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