内容
# just-prs-mcp：用于人工智能代理的多基因风险评分
[](https://pypi.org/project/just-prs-mcp/)
[](https://www.python.org/downloads/)
[](#仅限研究使用)
[](#仅限研究使用)
[](#与-claude-cursor-codex-antigravity-或其他代理一起使用)
[](https://gofastmcp.com)
一个 [MCP](https://modelcontextprotocol.io/) 服务器，为 Claude Code、Cursor、Codex、Antigravity 等人工智能代理提供访问 **[just-prs](https://github.com/antonkulaga/just-prs)** 工具箱的功能。该工具箱包含 5,000+ 个已发表的多基因评分模型，来自 [PGS 目录](https://www.pgscatalog.org/)，VCF 标准化，PRS 计算，群体百分位估计，绝对风险估计，跨基因组比较和质量评估。可以用自然语言询问代理，它会调用正确的工具并解释结果。
来源：[github.com/dna-seq/just-prs-mcp](https://github.com/dna-seq/just-prs-mcp)。基于 **uv + [FastMCP](https://gofastmcp.com)** 构建。
> 编码代理：从 [AGENTS.md](./AGENTS.md) 开始。
## 你可以让代理执行什么操作？
```
"下载 Anton 的公共基因组，标准化它，并计算 2 型糖尿病的 PRS。"
"在 PGS 目录中搜索乳腺癌评分，并显示表现最佳的评分。"
"对 Anton 和 Livia 的基因组进行 DVT 和智力评分，然后比较它们。"
"为此本地 VCF 计算 PRS，并解释百分位和绝对风险。"
"列出我已经标准化的所有基因组，并为最新的一个计算寿命的 PRS。"
```
### 什么是 PRS？
许多特征和常见疾病——如 2 型糖尿病、冠状动脉疾病、身高、寿命——都是 **多基因的**：受到数千个小的遗传效应影响，而不是单个基因。 多基因风险评分（PRS）将这些效应加在一起，并将结果置于参考群体中。 它不是诊断，但可以帮助可视化遗传易感性，并在有足够证据的情况下，将百分位转换为绝对风险估计。
### 什么是 MCP？
[模型上下文协议](https://modelcontextprotocol.io/)（MCP）是一个开放标准，允许 AI 助手调用外部工具。 该服务器将 PRS 计算作为 MCP 工具公开，因此任何兼容的代理——Claude Code、Cursor、Codex、Antigravity 或其他——都可以搜索 PGS 目录、标准化基因组、计算评分并解释结果，而无需基因组学专业知识即可开始使用。
## 目录
- [你可以让代理执行什么操作？](#你可以让代理执行什么操作？)
- [快速入门](#快速入门)
- [与 Claude、Cursor、Codex、Antigravity 或其他代理一起使用](#与-claude-cursor-codex-antigravity-或其他代理一起使用)
- [测试基因组（快速播放）](#测试基因组快速播放)
- [工具](#工具)
- [提示和资源](#提示和资源)
- [典型的代理工作流程](#典型的代理工作流程)
- [模式](#模式)
- [配置](#配置)
- [方法论](#方法论)
- [仅限研究使用](#仅限研究使用)
- [部署](#部署)
- [项目布局](#项目布局)
- [许可证](#许可证)
## 快速入门
需要 Python >= 3.13 和 [uv](https://docs.astral.sh/uv/)。
```bash
# 安装
uv sync # 依赖项（包括开发）
uv sync --extra reference # + pgenlib 用于参考/pgen 工具（Linux/WSL）
# 运行
uv run just-prs-mcp stdio # stdio 传输（适用于 MCP 客户端）
uv run just-prs-mcp stdio --mode extended # 暴露完整的工具界面
uv run just-prs-mcp http # HTTP 传输（默认：3011）
uv run fastmcp dev fastmcp.json # MCP 检查器（交互式 UI）
# 测试
uv run pytest # 全部内存测试，无需网络
uv run ruff check . # 校验
uv run pyright # 类型检查
```
服务器 **启动时没有任何环境配置**——没有 API 密钥，没有缓存目录，没有数据库。 每个设置都是可选的。
## 与 Claude、Cursor、Codex、Antigravity 或其他代理一起使用
### 已发布的软件包——无需克隆
服务器位于 [PyPI](https://pypi.org/project/just-prs-mcp/)，因此任何 MCP 客户端都可以使用 [`uvx`](https://docs.astral.sh/uv/) 启动它——无需克隆或安装步骤。
**Claude 代码：**
```bash
claude mcp add just-prs -- uvx just-prs-mcp@latest stdio # 始终是最新的
claude mcp add just-prs -- uvx just-prs-mcp@0.1.2 stdio # 固定（可复制）
claude mcp list # → just-prs ... ✔ 已连接
```
**Cursor**（`.cursor/mcp.json` 在您的项目或用户 MCP 配置中）：
```json
{
"mcpServers": {
"just-prs": {
"command": "uvx",
"args": ["just-prs-mcp@latest", "stdio"],
"env": { "PRS_MCP_MODE": "essentials" }
}
}
}
```
**Codex** (`~/.codex/config.toml`):
```toml
[mcp_servers.just-prs]
command = "uvx"
args = ["just-prs-mcp@latest", "stdio"]
```
**Antigravity** 或另一个支持 MCP 的助手：添加相同的服务器命令到其 MCP 设置中 - `uvx just-prs-mcp@latest stdio`.
> **版本固定。** `uvx` 缓存它为裸名称解析的第一个版本，因此 `uvx just-prs-mcp` 保持运行该缓存版本。 使用 `@latest` 始终获取最新的，或使用 `@<version>` 进行固定。 裸名称是最坏的情况 - 避免它。
使用 `--mode extended`（或 `PRS_MCP_MODE=extended`）来公开包括批量下载、HuggingFace 上传、发病率先验、多方法绝对风险和参考面板评分在内的完整工具界面。
### 从克隆（开发）
存储库的 `.mcp.json` 通过 `uv run just-prs-mcp stdio` 启动工作树。 Codex 等效：
```toml
[mcp_servers.just-prs]
command = "uv"
args = ["run", "just-prs-mcp", "stdio"]
```
## 测试基因组（快速播放）
两个公开的完整基因组测序（WGS）数据集来自 [just-dna-lite](https://github.com/dna-seq/just-dna-lite) 项目，已内置，因此您可以和您的 AI 代理一起尝试 PRS 计算，而无需您自己的基因组数据：
| 样本 | Zenodo | VCF | 大小 | 许可证 | 工具参数 |
|--------|--------|-----|------|---------|----------------|
| Anton Kulaga | [18370498](https://zenodo.org/records/18370498) | `antonkulaga.vcf` | ~482 MB | CC0（公共领域） | `sample="anton"` |
| Livia Zaharia | [19487816](https://zenodo.org/records/19487816) | `SIMHIFQTILQ.hard-filtered.vcf.gz` | ~349 MB | CC-BY-4.0 | `sample="livia"` |
只需询问您的代理：
```
"下载 Anton 的样本基因组，标准化它，并计算 2 型糖尿病的 PRS。"
```
在后台，代理调用 `download_sample_genome` → `normalize_vcf` → `compute_prs_by_trait` → `percentile` → `absolute_risk`.
## 工具
### 基础工具（始终可用）
| 工具 | 描述 |
|------|-------------|
| `search_scores` | 按自由文本搜索 PGS 目录 |
| `score_info` | 一个 PGS ID 的清理元数据 |
| `best_performance` | 最佳评估指标（OR / HR / AUROC / C-index） |
| `search_traits` | 具有同义词重试的 REST 特征搜索 |
| `trait_info` | 按 EFO / MONDO ID + 关联的 PGS ID 的特征 |
| `list_genomes` | 缓存中已下载和标准化的基因组清单 |
| `download_sample_genome` | 从 Zenodo（后台任务）获取公共样本 WGS VCF |
| `normalize_vcf` | VCF → 基因型 Parquet（后台任务） |
| `compute_prs` | 对一个 PGS 模型进行评分 |
| `compute_prs_batch` | 对多个 PGS 模型进行评分（后台任务） |
| `compute_prs_by_trait` | 对一个特征的所有 PGS 模型进行评分，自动保存结果到磁盘（后台任务） |
| `percentile` | 群体百分位（参考面板 / 理论 / AUROC 回退） |
| `absolute_risk` | 基于 PRS z-score 和群体发病率的绝对疾病风险 |
| `assess_quality` | 质量标签和解释（纯逻辑，无 I/O） |
| `compare_genomes` | 从已保存的 `compute_prs_by_trait` 结果进行跨基因组比较 |
### 扩展工具（通过 `--mode extended` 开启）
| 工具 | 描述 |
|------|-------------|
| `normalize_array` | 23andMe / AncestryDNA → Parquet（后台任务） |
| `download_scoring_file` | 从 EBI FTP 下载一个协调的评分文件 |
| `list_pgs_ids` | EBI FTP 上的所有 PGS ID |
| `download_all_metadata` | 所有元数据表为 Parquet（后台任务） |
| `bulk_download_scores` | 许多/所有评分文件（后台任务） |
| `prevalence_info` | 某个分数或特征的群体发病率先验 |
| `absolute_risk_bundle` | 多方法绝对风险估计 |
| `push_catalog_to_hf` | 上传清理后的目录到 HuggingFace（需要令牌） |
| `download_reference_panel` | 获取 1000G / HGDP+1kGP 面板（后台任务） |
| `reference_score` / `reference_score_batch` | 对参考面板进行评分（需要 `pgenlib`） |
| `pgen_read_pvar` / `pgen_read_psam` / `pgen_score` | PLINK2 二进制操作（需要 `pgenlib`） |
> **文件路径：** 计算工具采用服务器文件系统上的本地路径（VCF / 标准化 Parquet / `.pgen` 目录）。 在 stdio 上，这是指您的机器。 **参考 / pgen 工具** 需要可选的本地 `pgenlib`（Linux/WSL — `uv sync --extra reference`）；如果没有，它会返回一个清晰的安装提示。
## 提示和资源
MCP 提示是可重用的提示模板，代理可以调用这些模板来构造他们对结果的解释：
| 提示 | 描述 |
|--------|-------------|
| `compute_prs_for_trait` | 分步工作流：搜索 → 标准化 → 评分 → 解释 |
| `interpret_prs_result` | 解释单个 PRS 结果（结论、关键数字、上下文、操作） |
| `interpret_trait_results` | 解释一个特征的多个模型组合结果 |
资源：`resource://prs/panels` - 列出可用的参考面板、支持的基因组构建和活动缓存目录。
## 典型的代理工作流程
通过 MCP 服务器的完整 PRS 分析遵循此链：
```
1. search_traits("venous thromboembolism") → 查找特征 ID（EFO_0001645）
2. download_sample_genome(sample="anton") → 下载 VCF
3. normalize_vcf(vcf_path) → VCF → Parquet
4. compute_prs_by_trait(trait_id, vcf_path) → 评分所有 PGS 模型，自动保存 JSON
5. percentile(prs_score, pgs_id) → 群体百分位 + z-score
6. absolute_risk(pgs_id, z_score) → 终身概率 + 风险比率
7. assess_quality(match_rate, auroc, percentile) → 质量标签
```
对于 **跨基因组比较**，重复步骤 2-6，然后：
```
8. compare_genomes(result_paths=[...]) → 按特征排名的比较
```
`compute_prs_by_trait` 自动将每个结果保存为 JSON 缓存目录，并返回 `result_path` 中的文件路径。 将这些路径传递给 `compare_genomes` 以获取每个特征的排名，按百分位排序（高 → 低，无方向判断 - 代理解释每个特征是好还是坏）。
## 模式
`PRS_MCP_MODE`（env）或 `--mode`（CLI），默认为 `essentials`：
| 模式 | 已注册的内容 |
|------|-------------------|
| `essentials` | 目录查找 + 核心计算/分析工作流 + 基因组比较。 默认工具列表小 = 代理污染上下文较少。 |
| `extended` | 所有：批量下载、HuggingFace 上传、发病率先验、多方法绝对风险、参考面板 / pgen 评分。 |
## 配置
所有设置都是可选的 - 服务器启动时具有合理的默认值。 请参阅 [`.env.example`](./.env.example) 和 [`settings.py`](src/just_prs_mcp/settings.py) 以获取完整列表。
| 变量 | 描述 |
|----------|-------------|
| `PRS_MCP_MODE` | `essentials`（默认）或 `extended` |
| `PRS_MCP_CACHE_DIR` | 缓存的目录数据、评分文件、参考面板和保存的结果的根目录。 默认值为 just-prs 自身（`PRS_CACHE_DIR` / platformdirs）。 |
| `PRS_MCP_DEFAULT_GENOME_BUILD` | 默认基因组构建（`GRCh38`） |
| `PRS_MCP_DEFAULT_PANEL` | 默认参考面板（`1000g`） |
| `PRS_MCP_DUCKDB_MEMORY_LIMIT` | 批量评分的 DuckDB 内存限制（例如 `8GB`） |
| `PRS_MCP_HF_TOKEN` | `push_catalog_to_hf` 的 HuggingFace 令牌（也支持 `HF_TOKEN`） |
| `PRS_MCP_TRANSPORT` | `stdio` / `http` / `sse` |
| `PRS_MCP_HOST` / `PRS_MCP_PORT` | HTTP/SSE 的绑定地址（默认 `0.0.0.0:3011`） |
| `PRS_MCP_LOG_LEVEL` | 日志级别（默认为 `info`） |
## 方法论
### 百分位估计
百分位数通过对 **1000 Genomes Project phase 3** 参考面板（2504 个个体，5 个超级群体：AFR、AMR、EAS、EUR、SAS） GRCh38 协调的评分文件进行评分。 每个个体的 PRS 计算为 `Σ(effect_weight × dosage)` 匹配变体，然后按超级群体派生百分位。 用户的 VCF 使用相同的引擎进行评分，并放置在此分布中。
### 质量评分
每个 PGS 模型都具有综合质量评分（0-100），基于四个层级：
- **T1a**：报告 AUROC / C-index（最强证据）
- **T1b**：仅 Beta（0.95× 惩罚）
- **T2**：仅 OR / HR（0.90× 惩罚；通过 probit 转换转换）
- **T3**：无性能指标（0.6× 底线）
评分还考虑队列大小（对数缩放）、模型覆盖率和协调评分惩罚，如果坐标被提升。 质量标签：高（≥70），正常（≥50），中等（≥30），低（<30）。
### 绝对风险
对于疾病特征，`absolute_risk` 将 PRS z-score 转换为具体终身概率和风险比率 vs 群体平均值，使用特征发病率和已发表的效应大小数据。 发病率数据不可用时，工具会引发错误 - 1.0 意味着群体平均风险；> 1.0 意味着风险升高；< 1.0 意味着风险降低。 当流行病学数据不可用时，该工具会引发错误 - 代理应明确披露这一点。
### 解释结果
服务器内置的说明指南会指导连接的代理：
- 将 PRS 呈现为遗传易感性，而不是特征本身的测量值。
- 始终在疾病特征上调用 `absolute_risk` 以获取百分位。
- 尊重特征方向性：对于疾病特征，较高的百分位 = 风险增加（坏）；对于积极特征，风险增加 = 更好；对于中性特征，则无关紧要。
- 标记祖先不匹配、低覆盖率和模型不一致。
- 引用 PGS ID 并链接到 [PGS 目录](https://www.pgscatalog.org/)。
有关 PRS 解释、质量方法论、祖先考虑和常见问题的详细讨论，请参阅 [just-prs 文档](https://github.com/antonkulaga/just-prs#仅限研究使用-interpreting-prs-results)。
## 仅限研究使用
本服务器提供的 PRS 结果仅用于 **研究和教育目的**，不构成医疗建议。 关键注意事项：
- PRS 模型是统计学代理，而不是因果读数。 大多数 GWAS 变体是与因果位点处于连锁不平衡状态的标签 SNP，而不是因果变体本身。
- 许多已发布的评分标准验证有限，祖先代表性狭窄或预测能力一般。 被列入 PGS 目录并不意味着评分标准已准备好用于临床。
- 高 PRS 将估计的风险相对于参考群体进行偏移，但环境、生活方式、年龄、性别和临床生物标志物通常比共同变异信号更重要或更不重要。
- 低匹配率（常见于基于微阵列的消费者测试）意味着该评分仅使用模型的片段 - 噪音更大，信息量更少。
- 祖先很重要：一个群体中训练的评分标准通常在另一个群体中由于 LD 模式和等位基因频率的差异而失去准确性。
高 PRS 并不是诊断；低 PRS 也不能保证。
## 部署
- **Docker**：`docker build -t just-prs-mcp . && docker run -p 3011:3011 just-prs-mcp`（默认 HTTP）。
- **Smithery**：`uv sync --extra smithery`；`pyproject.toml` 中的入口点 + `smithery.yaml`。
- **声明式**：`fastmcp.json` 驱动 `fastmcp run` / `fastmcp dev`.
## 项目布局
```
src/just_prs_mcp/
server.py 构建服务器（）、CLI、关闭、Smithery 入口点
settings.py pydantic-settings（PRS_MCP_*）、安全默认值
client.py 共享 PRSCatalog / REST-客户端构造 + 适配器
models.py Pydantic 工具 I/O 模型（+ 重用 just-prs 模型）
logging_setup.py 标准库日志 → stderr
tools/
catalog.py 基础工具 - PGS 目录查找和查询
compute.py 基础工具 - 标准化、计算、分析、比较
extended.py 扩展工具 - 批量下载、HF 上传、发病率、多风险
reference.py 扩展工具 - 参考面板 / pgen 评分（pgenlib）
测试 内存客户端测试（布线 + 逻辑，无网络）
```
## 许可证
MIT - 请参阅 [LICENSE](./LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器