内容
center">
<h1>gnomad-genetics-mcp-server</h1>
<p><b>通过MCP查询gnomAD数据库中的变异等位基因频率、基因功能丧失约束、基因变异列表和测序覆盖率，并结合ClinVar显著性。</b>
<div>7 工具（+1 可选）• 2 资源 • 1 提示</div>
</p>
</div>
<div align="center">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/gnomad-genetics-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/gnomad-genetics-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](https://github.com/cyanheads/gnomad-genetics-mcp-server/releases/latest/download/gnomad-genetics-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=gnomad-genetics-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZ25vbWFkLWdlbmV0aWNzLW1jcC1zZXJ2ZXIiXX0=) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22gnomad-genetics-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fgnomad-genetics-mcp-server%22%5D%7D)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
</div>
---
## 工具列表
以下是五个gnomAD工具，以及用于DuckDB支持的画布表的SQL分析的：
| 工具 | 描述 |
|:---|:---|
| `gnomad_get_variant` | 查询一个或多个变体的完整群体记录 — 包括AC/AN/AF总体和每个遗传祖先组、纯合子/半合子计数、质量标志、转录后果、预测因子和ClinVar显著性。批量查询最多25个ID，每个项目部分成功。 |
| `gnomad_get_gene | 基因功能丧失约束 — pLI、LOEUF（`oe_upper`）及其置信区间、观察/预期比率和Z分数。按或Ensembl基因ID查询。 |
| `gnomad_list_gene_variants` | 查询一个基因、转录本或区域中的所有变体及其等位基因频率和预测后果，可按后果类别和最大AF过滤。输出到`gene_variants`画布表。 |
| `gnomad_get_coverage` | 查询一个基因、转录本或区域的测序覆盖率 — 平均/中位数深度和每个样本在不同深度阈值上的覆盖率，按callset轨道汇总。可以区分真正的缺失变体和不可调用的位置。 |
| `gnomad_search_clinvar` | 通过NCBI E-utilities查询基因水平的ClinVar详细信息 — 分类变体、审查状态（星级评分）、条件和提交计数。输出到`clinvar_variants`画布表。 |
| `gnomad_dataframe_query` | 对画布表执行只读SQL `SELECT`查询。 |
| `gnomad_dataframe_describe` | 列出画布上的表及其列，以便在编写SQL之前进行查询。 |
| `gnomad_dataframe_drop` | 删除画布上的命名表以释放内存。默认情况下关闭，可通过`GNOMAD_DATAFRAME_DROP_ENABLED=true`启用。 |
### `gnomad_get_variant`
一个调用可查询变体的普遍程度和致病性。
- 批量查询最多25个ID，每个ID为`chrom-pos-ref-alt`变体ID（例如`1-55051215-G-GA`）或rsID（例如`rs11591147`）
- 每个项目部分成功 — 错误的ID将出现在`failed[]`中而不会影响其他ID
- 返回每个祖先的频率向量，不会折叠为单个全局AF
- 报告哪些callset（`exome` / `genome`）携带变体、质量标志、转录后果、预测因子和ClinVar显著性
- 空的`found[]`表示变体不在所选数据集中 — 可与`gnomad_get_coverage`配对以确认位置可调用
---
### `gnomad_get_gene_constraint`
与等位基因频率正交的轴 — 功能丧失变体在一个基因中比在另一个基因中更有意义。
- 接受HGNC符号（`PCSK9`）或Ensembl基因ID（`ENSG00000169174`）
- 返回pLI（>0.9不耐受）、LOEUF / `oe_lof_upper`（<0.6 v4中不耐受，<0.35 v2中不耐受）及其下限、观察/预期比率和Z分数
- 许多基因具有空约束（稀疏上游）— 空字段被报告为null，而不会被伪造
- `constraint_flags`显示gnomAD团队标记的v4测试警告
---
### `gnomad_list_gene_variants`
列出基因、转录本或区域中的变体，然后查询整个集合的SQL。
- 仅需提供`gene`、`transcript_id`或`region`（`chrom-start-stop`，1基数，包含）
- 可选过滤器：一个`consequence_class`（`lof` / `missense` / `synonymous` / `other`）和/或最大等位基因频率
- 完整结果存储在名为`gene_variants`的DataCanvas表中，并带有内联预览和`canvas_id`和`table_name` — 使用`gnomad_dataframe_query`查询以按AF排名、按后果计数或在完整集合上分组
- 重用`canvas_id`会替换存储的表；不会追加
- 当画布禁用时（`CANVAS_PROVIDER_TYPE` != `duckdb`），工具返回带有`spilled=false`的上限内联预览，SQL路径不可用
---
### `gnomad_get_coverage`
区分真正的缺失变体和不可调用的位置。
- 仅需提供`gene`、`transcript_id`或`region`
- 返回平均和中位数读取深度，以及每个样本在每个阈值（1×至100×）上的覆盖率，汇总每个callset轨道
- `coverage_source`缩小到一个轨道（`exome` / `genome`）；省略以返回所有可用的轨道
- 在覆盖良好的区域中缺失的变体是有信息量的；在覆盖不佳的区域中缺失的变体则不是
---
### `gnomad_search_clinvar`
通过NCBI E-utilities进行基因面板管理深度的变体。
- 返回一个基因的已分类ClinVar变体 — 临床意义、审查状态（星级评分）、相关条件、分子后果和提交计数
- 可选过滤器：`clinical_significance`（例如`pathogenic`）和最低星级评分（`min_review_stars`，0-4）
- 完整集合存储在`clinvar_variants`画布表中，并带有内联预览；重用`canvas_id`会替换该表
密钥，但NCBI_API以提高速率限制 vs 3 req---
### 画布数据框工具
`gnomad_dataframe、`gnomadcribe`和`ad_dataframe_drop列表工具存储的表上运行。
gnomad_dataframe仅运行单语句 — 和文件/HTTP表函数被画布拒绝
- `ad_dataframe_describe`返回每个已阶段表的名称、行计数和 — 在编写SQL
- `gnomad_dataframe_drop`是一种刻意的突变（`readOnlyHint: false`）；如果`GNOMAD_DATAFRAME_DROP_ENABLED=true`，则它不会出现在`tools/list`中
## 资源和提示
| 类型 | | 描述 |
|:---|:---|:---|
| 资源 | `gnomad://variant/{dataset}/{variantId}` | 查询一个变体的群体记录 — 镜像`gnomad_get_variant`。`dataset`段保持URI自描述。 |
| 资源 | `gnomad://gene/{dataset}/{gene}/constraint` | 基因功能丧失约束 — 镜像`gnomad_get_gene_constraint`。 |
| 提示 | `gnomad_variant_triage` | 有指导的罕见病变体分类工作流程：群体频率 → 基因约束 → 可调用性检查，按顺序。 |
所有资源数据也可通过工具访问。列表工具（`gnomad_list_gene_variants`、`gnomad_get_coverage`、`gnomad_search_clinvar`）返回分析行集而不是稳定的单URI文档，因此它们不作为资源暴露 — 而是调用工具。
## 功能
基于[`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)构建：
- 声明式工具、资源和提示定义 — 每个基元一个文件，框架处理注册和验证
- 统一错误处理 — 处理程序抛出，框架捕获、分类和格式化
- 带代理恢复提示的类型化错误合约
- 可插拔身份验证：`none`、`jwt`、`oauth`
- 带有可选OpenTelemetry跟踪的结构化日志记录
- STDIO和Streamable HTTP传输
gnomAD特定：
- 整个核心表面的单一无密钥GraphQL源 — ClinVar显著性在gnomAD自己的响应中加入每个变体
- `dataset`和`reference_genome`是不同的、一致性验证的参数（v4/v3 ⇒ GRCh38，v2.1/ExAC ⇒ GRCh37）；两者都在每个工具的输出中回显，因此错误的构建坐标不匹配是可见的
- 礼貌的客户端 — 保守的并发上限和指数退避对抗社区资助的速率限制API
- 会话SQL分析：`gnomad_list_gene_variants`和`gnomad_search_clinvar`在DuckDB支持的画布表上阶段化其完整结果，可通过`gnomad_dataframe_query`查询
代理友好输出：
- 返回每个祖先的等位基因频率向量，不会折叠为单个全局AF — 跨祖先对比是临床解释所需的信号
- 温和的部分失败 — `gnomad_get_variant`返回每个项目的`failed[]`行和可行的消息，而不是使整个批次失败
- 每个响应的出处 — 有效的`dataset`和`reference_genome`回显；上游的空字段保留为null，不会伪造
- 错误的恢复提示（`incoherent_build`、`invalid_target`、`gene_not_found`、`canvas_disabled`）以便调用者知道下一步
## 快速入门
在MCP客户端配置文件中添加以下内容。gnomAD是一个免费的无密钥API — 无需凭证。
```json
{
"mcpServers": {
"gnomad-genetics-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["@cyanheads/gnomad-genetics-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
或使用npx（无需Bun）：
```json
{
"mcpServers": {
"gnomad-genetics-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@cyanheads/gnomad-genetics-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": " }
}
}
}
```
或使用Docker：
```json
{
"mcpServers": {
"gnomad-genetics-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT_TYPE=stdio",
"ghcr.io/cyanheads/gnomad-genetics-mcp-server:latest"
]
}
}
}
```
对于Streamable HTTP，设置传输并启动服务器：
```sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# 服务器监听在http:3010
```
启用路径，还需设置`CANVAS_PROVIDER_TYPEdb`（@duckdb/node对等依赖；Cloudflare Workers上不可用）。
### 先决条件
- [Bun v1.3.0](https://bun.sh/)或更高版本（或Node.js v）。
- 无API密钥 — gnomAD的GraphQL端点是无密钥的。可选的`NCBI_API提高`gnomad_search_clinvar速率限制。
### 安装
1. **克隆仓库：**
```sh
git clone https://github.com/cyanad-genetics-mcp-server.git
. **进入目录：**
```sh
nomad-genetics-server
```
3. **安装依赖**
```sh
bun install
```
4. **配置环境：**
```sh
cp . .env
#都是可选的 — 服务器开箱即用，无密钥
```
所有变量都是可选的；服务器使用运行：
| 变量 | 描述 | |
|:---------|:------------|:--------|
| `GNOMAD_API_BASE_URL` | gnomAD GraphQL端点用于私有镜像或测试。 | `https://gnomad.broadinstitute.org/api` `GNOMAD_DEFAULT_DATASET` |调用省略`dataset`时使用的数据集（`gnomad_r4` / `ad_r3` / `gnomad_r2_1` / `exac`）。 | `gnomad_r4` |
| `GNOMAD_REQUEST_TIMEOUT_MS` | 对GraphQL端点的每个请求的超时时间，毫秒。 | `30000` |
| `GNOMAD_MAX_CONCURRENCY` | 对社区资助的API的并发上游请求的上限 — 礼貌。 | `2` |
| `GNOMAD_MAX_VARIANT_BATCH` | 每个`gnomad_get_variant`调用接受的最大变体ID。 | `25` |
| `CLINVAR_BASE_URL` | `gnomad_search_clinvar`的NCBI E-utilities基准URL。 | `https://eutils.ncbi.nlm.nih.gov/entrez/eutils` |
| `NCBI_API_KEY` | 可选的NCBI密钥。提高E-utilities的速率限制从3到10 req/s。 | — |
| `CANVAS_PROVIDER_TYPE` | 设置为`duckdb`以启用列表工具后面的溢出/SQL路径。当`none`时，它们返回上限内联预览。 | `none` |
| `GNOMAD_DATAFRAME_DROP_ENABLED` | 启用`gnomad_dataframe_drop`工具的可选门控。默认关闭。 | `false` |
| `MCP_TRANSPORT_TYPE` | 传输：`stdio`或`http`。 | `stdio` |
| `MCP_HTTP_PORT` | HTTP服务器的端口。 | `3010` `MCP_AUTH_MODE` | 身份验证模式：`none`、`或`oauth`。 |` |
| `MCP_LOG | 日志级别（RFC4）。 | `info` |
| `OTEL_ENABLED` | 启用Telemetry仪器](https://github.com/c/mcp-ts-core/tree/main/docs/telemetry)。 | `false` |
详见[`.env.example`](./.env.example)获取完整的可选覆盖列表。
## 运行服务器
### 本
- **构建并运行： ```sh
# 一次
bun run rebuild
已构建的服务器
start:stdio
# 或
bun run start:http
```
- **运行检查和测试：**
```sh
bun run devcheck # 校验、格式化、类型检查、安全检查
bun run test # Vitest 测试套件
bun run lint:mcp # 验证MCP定义是否符合规范
```
### Docker
```sh
docker build -t gnomad-genetics-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 gnomad-genetics-mcp-server
```
Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志记录到 `/var/log/gnomad-genetics-mcp-server`。OpenTelemetry 对等依赖项默认安装 — 使用 `--build-arg OTEL_ENABLED=false` 构建以省略它们。
## 项目结构
| 目录 | 用途 |
|:----------|:--------|
| `src/index.ts` | `createApp()` 入口点 — 注册工具/资源/提示并初始化服务。 |
| `src/config` | 服务器特定的环境变量解析和验证，带有 Zod。 |
| `src/mcp-server/tools` | 工具定义 (`*.tool.ts`) 和共享输入模式。 |
| `src/mcp-server/resources` | 资源定义 (`*.resource.ts`)。 |
| `src/mcp-server/prompts` | 提示定义 (`*.prompt.ts`)。 |
| `src/services/gnomad` | gnomAD GraphQL 客户端、查询文档和域类型。 |
| `src/services/clinvar` | NCBI E-utilities 客户端，用于可选的 ClinVar 工具。 |
| `src/services/canvas-accessor.ts` | 框架的可选 DataCanvas 的模块级访问器。 |
## 开发指南
参阅 [`CLAUDE.md`/`AGENTS.md`](./CLAUDE.md) 获取和架构规则。简而言之：
- 处理程序抛出，框架捕获 — 工具逻辑中无 `try/catch`
- 使用 `ctx.log` 进行请求范围的日志记录，使用 `ctx.state` 进行租户范围的存储
- 在 `src/index.ts` 中将新工具和资源注册到 `createApp()` 数组中
- 包装外部 API 调用：验证原始 → 规范化为域类型 → 返回输出模式；绝不伪造缺失字段
## 贡献
欢迎提交问题和拉取请求。在提交之前运行检查和测试：
```sh
bun run devcheck
bun run test
```
## 许可证
Apache-2.0 — 详见 [LICENSE](LICENSE) 获取详情。
gnomAD 数据由 [Genome Aggregation Database](https://gnomad.broadinstitute.org) （Broad Institute）提供。ClinVar 数据由 [NCBI](https://www.ncbi.nlm.nih.gov/clinvar/) 提供。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器