AlphaFold Sovereign MCP

AlphaFold Sovereign MCP

回答结构生物学或变异相关问题，通常意味着要手动查询许多公共数据库——AlphaFold DB、Open Targets、ClinVar、gnomAD 等——并协调它们各自的格式。此服务通过一组 MCP 工具调用封装这些数据源，并在你自己的机器上作为本地进程运行；整个过程中不会经过我们的托管服务，没有遥测数据，并使用一个始终保留在本地磁盘上的 SQLite 知识图谱。在默认的在线模式下，工具会直接查询这些公共上游数据源，因此你查询的标识符会发送给它们（其中一个数据源 DisGeNET 需要单独申请免费的 API 密钥）；设置 ALPHAFOLD_OFFLINE=1 可在任何套接字打开之前拒绝出站请求，从而确保标识符不会离开本机（知识图谱工具仍会从本地数据作答；上游数据源工具则会报告其来源不可用）。此处的“Sovereign”意为本地优先——你的计算和存储结果都留在本机——而非服务无需网络即可运行。

一个模型上下文协议服务——AlphaFold MCP 服务——通过一组 MCP 工具调用封装 AlphaFold DB 和另外 8 个公共生物医学数据源，并在显式请求显示特定异构体时，有条件地请求 UniProtKB 进行验证。该服务由一个本地 SQLite 知识图谱提供支持，并包含查询和导出工具（结果可通过其 API 持久化；目前尚未接入自动的逐次调用持久化功能）。

这是一个没有获得资助、独立的开源项目。它不是一项服务，也未通过任何受监管用途的认证；其输出仅供研究参考，在任何临床或监管用途之前，都应由合格人员进行审核。

研究署名： Santiago Maniches（ORCID 0009-0005-6480-1987）独立负责指导和维护此服务，并且是其原创研究成果的唯一科学作者。AI 辅助工具为编码、测试和内部审核提供了支持。它们不是科学共同作者、临床验证者，也不能替代独立评估。公共数据库、预测模型和现有算法仍归功于各自的来源。

本项目与 Google DeepMind 或 EMBL-EBI 没有关联，也未获其认可或赞助。“AlphaFold”是其各自所有者的商标，此处仅用于描述本软件所使用的公共数据（AlphaFold DB API）。

状态： Beta。已通过工程验证（行覆盖率和分支覆盖率均为 100%）。尚未由独立领域专家进行科学验证；尚未部署到生产环境。请参阅 STATUS.md 和 LIMITATIONS.md。

---

项目简介

这是一个 Python MCP 服务，可：

• 将 AlphaFold DB、MONDO、HPO、Open Targets、ClinVar、gnomAD、 DisGeNET、ChEMBL 和 Ensembl 封装为 MCP 工具调用。显式指定编号 亚型时，也可能触发 UniProtKB 序列与身份核验。每次调用都会保留上游记录 及其来源信息。检索并非新的生物学观察；衍生工作流会明确标注为 Topologica 计算，而非来源报告的发现。
• 将多个上游数据源整合为多源工作流：变异交叉引用报告、 疾病–靶点概况摘要、启发式靶点成药性评分、药物再利用候选项 排名，以及跨物种结构距离计算。
• 提供本地 SQLite 知识图谱（storage/knowledge_graph.py）， 其中包含查询、导出和遍历工具。全新安装不会自动插入生物医学记录； 数据通过知识图谱 API 的显式写入操作存储。现有 SQLite 文件 会予以保留，包括早期版本中的示例行；历史数值并非经过独立验证的来源 记录。分析工具不会自动持久化其结果。
• 包含一个探索性的 Cα 派生特征向量模块。使用可选的 [tda] 扩展 （gudhi）时，该模块会报告 H₀/H₁ 终端过滤 Betti 数；不会计算 H₂。 回退方案报告的是 4-Å 接触图连通分量数和几何特征，而非持久同调。 这些特征向量之间的 L2 距离并非经过校准的蛋白质同源性或生物学功能度量。

该项目面向 mcp-spec 2025-06-18，运行于 Python 3.10–3.13。

AlphaFold DB 兼容性： 预测 API 已于 2026 年 6 月公布现代模型和 序列字段名称，并宣布旧字段将于此后停用。截至 2026 年 10 月 9 日， 抽样检查的实时 API 仍提供旧别名。客户端使用当前字段，同时保留对旧版响应的兼容性； 当 API 返回多个亚型时，会选择与请求完全匹配的 UniProt 登录号。有关迁移约定、 尚存的片段限制，以及可选的 2026 年 10 月 PDBe/IUCr 文献注释证据客户端， 请参阅 API 兼容性说明。 这些注释来自上游 PDBe 研究，并非 AlphaFold Sovereign 的独立科学发现。

证据责任

AlphaFold Sovereign MCP 不会开发或验证 AlphaFold 的底层结构预测、 MONDO 本体断言、UniProt 注释或 ClinVar 提交内容。这些内容归属于引用的来源， 并保留其来源报告的置信度和局限性。

Topologica 负责可靠检索、登录号身份核验、 跨来源关联、可复现的本地计算、来源归属，以及如实报告失败和不确定性。 基于预测结构作出的推断仍取决于该预测；不会因为与另一个数据库关联， 就变成实验观察结果。衍生启发式方法是研究辅助工具，并非经来源验证的临床结论。

ClinVar 身份边界： 类似 BRCA1:c.181T>G 的相对基因表达式 可用于发现可能的记录，但不能确定唯一的参考等位基因；此类结果会标记为 未经核实的候选项，其分类不能归于该查询。类似 NM_007294.4:c.181T>G 的匹配版本转录本表达式仅允许进行字面转录本标题匹配。 ClinVar Variation ID 可能代表一组等位基因；无论哪种匹配级别，都无法确立独立的 临床等效性或患者特异性分类。来源故障会与未找到匹配项分开报告。不假定存在 跨转录本等效性。

不是什么

• 它不是托管服务或 SaaS。
• 它未通过任何受监管用途的认证（HIPAA、GxP、21 CFR Part 11、FedRAMP、FIPS、SOC 2）。代码以一种未来可能支持此类认证的方式构建了审计日志，但尚未进行此类审计。
• 它不会训练、微调或发布 AlphaFold 模型——它使用的是 AlphaFold DB 的公共 REST API。
• 变异报告中的证据是供专家审查的暂定计算信号，并非既定的 ACMG/AMP 标准。classify_variant_acmg 工具不会在基因–疾病机制及特定标准的证据未经核实的情况下判定临床分类。
• assess_target_druggability 返回的“可成药性等级”是基于药物先例数量、Open Targets 可成药性标签、pLDDT 和 gnomAD 约束构建的启发式指标，并非经过验证的预测。
• “结构距离”是对衍生的 Cα 特征向量计算的 L2 距离。它不是序列一致性、RMSD、持久图 Wasserstein 距离、经过验证的同源性或功能等价性。由于不同方法的量纲不兼容，因此会分别报告，而不会排序。
• 此处使用的 AlphaFold 结构是带有每个残基 pLDDT 置信度的预测模型，而非实验结构。低 pLDDT 区域并不可靠；某些蛋白质（包括 BRCA1）的大部分区域置信度都较低，对这些区域进行结构推断时应谨慎。

如需了解已知限制的完整逐项列表（包括模块引用、影响和计划的解决方案），请参阅 LIMITATIONS.md。 如需了解整体定位——哪些内容通过了工程验证，哪些尚未通过科学验证——请参阅 STATUS.md。

---

安装

从 PyPI 安装（推荐）

pip install alphafold-sovereign-mcp

也可以使用 uvx 运行，无需安装：

uvx alphafold-sovereign-mcp

PyPI 上的每个版本都通过 OIDC Trusted Publishing 由 release.yml 工作流构建，并附带已签名的 GitHub Release，其中包含 Sigstore（cosign）签名包、CycloneDX SBOM 和 Zenodo DOI 镜像。CI 会通过 slsa-github-generator 生成 SLSA L3 构建来源证明；将证明附加到每个版本是路线图中的一项工作。scripts/replicate.sh 会下载准确发布的 wheel 和 sdist，重新计算它们的 PyPI SHA-256 摘要，根据这些文件内容以及此仓库的发布工作流身份验证 GitHub Release Sigstore 签名包，并独立验证已发布的 CycloneDX SBOM 是否与下载的 wheel 关联。如果未来的版本附带 SLSA 来源证明，且已安装 slsa-verifier，同一脚本也会根据 wheel 验证该证明。

从源代码安装

git clone https://github.com/smaniches/alphafold-sovereign-mcp
cd alphafold-sovereign-mcp
uv pip install -e .
# With persistent-homology TDA (requires gudhi):
# uv pip install -e ".[tda]"

验证安装

$ alphafold-sovereign --version
1.5.7
$ alphafold-sovereign --self-test
SELF-TEST PASS - ACMG helpers behave as expected on the BRCA1 c.5266dupC fixture.

如果你使用 uvx 运行而未安装，请改用 uvx alphafold-sovereign-mcp --self-test（只有通过 pip/uv 安装后，裸命令 alphafold-sovereign 才会出现在 PATH 中）。

--self-test 会完全离线运行：它使用内置的 BRCA1:c.5266dupC 测试样例，检查确定性的 ACMG 证据辅助函数（将 VEP、gnomAD 和 AlphaMissense 映射到 ACMG 标准）。通过时返回退出代码 0，失败时返回非零退出代码。不会发起网络请求，也无需凭据。

配置 Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "alphafold-sovereign": {
      "command": "alphafold-sovereign-mcp",
      "args": []
    }
  }
}

重启 Claude Desktop 后，这些工具便可在对话中使用。可以尝试提问，例如：“对 BRCA1 c.5266dupC 进行分诊”或“评估 EGFR 是否适合作为药物靶点”。请参阅 examples/ 目录，了解三个端到端示例，展示会话的实际效果。

离线模式

ALPHAFOLD_OFFLINE=1 alphafold-sovereign-mcp

在打开套接字之前拒绝出站 HTTP 请求（引发 AirGapError），但可通过 ALPHAFOLD_ALLOW_HOSTS 将明确允许的主机加入白名单。知识图谱查询和导出工具仍会从本地 SQLite 存储中返回结果。上游查询工具没有本地缓存，因此会报告其数据源不可用；请注意，结构工具目前会将此情况显示为“没有 AlphaFold 模型”，而非明确的离线错误。

---

工具清单

该服务通过四个模块提供 29 个 MCP 工具。每个工具的输入架构都是 Pydantic 模型；结果为 JSON。

疾病与本体（tools/disease.py）

工具	功能
lookup_disease	MONDO 记录 + 层级结构 + ICD 交叉引用
search_diseases	对 MONDO 本体进行全文搜索
lookup_phenotype	HPO 术语 + 相关疾病
get_gene_phenotype_profile	某个基因的 HPO 表型 + gnomAD 约束
get_disease_targets	某个 MONDO 疾病的热门药物靶点（Open Targets）
get_target_diseases	某个 UniProt 靶点的热门疾病（Open Targets）
get_common_disease_targets	并行分析精选 MONDO 疾病
triage_variant_3d	HGVS → ClinVar + gnomAD 约束（疾病／结构背景：指针注释）
phenotype_to_structures	HPO → 疾病 → OT 靶点 → UniProt ID
compare_disease_target_overlap	两种疾病靶点集的 Jaccard 相似度
resolve_icd10_to_mondo	ICD-10 代码 → MONDO 疾病记录

精准医学（tools/precision_medicine.py）

工具	功能
generate_variant_clinical_report	HGVS → 多数据库来源报告 + 未经审核的计算信号
assess_target_druggability	UniProt → HOT/WARM/COLD/NOT_DRUGGABLE 等级
synthesize_protein_dossier	UniProt → 多来源简报
map_disease_drug_landscape	MONDO → 已批准药物 + 研发管线 + ChEMBL 阶段计数
classify_variant_acmg	HGVS → 来源证据 + 未评估的候选信号；不自动判定临床类别
find_drug_repurposing_candidates	MONDO → 按 OT 证据 × ChEMBL 阶段排序的候选项

计算得出的候选信号不属于经评估的临床 ACMG/AMP 标准。来源分类（例如 ClinVar）保留其原始归属；临床解读需要独立审核。

结构智能（tools/structure_intelligence.py）

工具	功能
analyze_structural_confidence	平均 pLDDT + 置信度等级 + 从 PAE 推导的结构域边界
compute_topology_fingerprint	64 分量探索性向量；GUDHI 在过滤终点计算 H₀/H₁；H₂ 不可用
compare_proteins_topologically	2–10 种蛋白质的成对 L2 指纹距离矩阵
find_evolutionary_structural_shifts	Ensembl 序列一致性 + 标注方法的结构特征距离；不进行混合尺度风险排序
score_binding_pocket_geometry	几何口袋检测 + 启发式药物可成药性指数
detect_intrinsically_disordered	IDR 图谱（连接区、尾部、长 IDR）
get_protein_structure	获取 AlphaFold 模型：元数据、下载 URL、可选坐标

知识图谱（tools/knowledge_graph_tools.py）

工具	功能
query_variant_database	搜索本地存储的变异优先级分析结果
query_protein_database	搜索本地存储的蛋白质评估结果
get_knowledge_graph_stats	数据库大小、实体计数、最近活动
export_research_dataset	将表格导出为 JSON，供 pandas/ML 工作流使用
find_drug_gene_network	遍历本地药物–基因–疾病图谱

示例用法

请参阅 examples/ 中的研究工作流指南。 此前命名的临床会话转录已弃用，因为 它们描述的是过时的输出约定。当前的合成回归 测试会测试检索和证据归因，但不会断言未经独立验证的临床结论。

临床变异报告

generate_variant_clinical_report(hgvs="BRCA1:c.181T>G")

该服务会搜索 ClinVar、gnomAD、AlphaMissense（通过 AlphaFold DB）、 Open Targets 疾病证据、ChEMBL 和 Ensembl VEP，并返回 一份注明来源的研究报告，其中包含未经审核的计算信号。 上方的基因相对示例属于候选搜索：不能将 ClinVar 记录的分类 借作等位基因身份的证明。若要严格匹配转录本标题，请使用带版本号的 转录本表达式；即便如此，仍需进行额外验证以确认临床等位基因身份。客户端不会自动执行变异特异性的实验 结构或 SIFTS 映射。

可选的 PDBe/IUCr 文献证据

临床报告工具还支持选择启用、注明来源的 残基注释查询，但仅当同时提供规范 UniProt 登录号及其从 1 开始计数的 UniProt 残基位置时才可用：

generate_variant_clinical_report(
    hgvs="RBM39:p.Trp495Ala",
    include_literature_evidence=True,
    literature_uniprot_id="Q8VH51",
    literature_uniprot_residue=495,
)

该示例展示的是请求格式，并不能证明此 HGVS 表达式已映射到转录本或经过临床解读。 返回的 literature_residue_evidence 保留 PDBe/IUCr 注释 来源信息：出版物标识符、文本挖掘所得句子及精确片段、 提取置信度、实验 PDB 链/残基信息， 以及来源报告的 UniProt 对应关系。来源错误以及存在歧义或缺失的 残基映射会明确区分。

这些证据不会更改 ACMG 标准或致病性等级。 请独立核实 HGVS 到 UniProt 的精确坐标；客户端不会独立验证 SIFTS 或实验质量。请参阅 兼容性和映射限制。

药物再利用

find_drug_repurposing_candidates(disease_mondo_id="MONDO:0007739")

返回 Open Targets 证据显示与该疾病相关的药物， 并按复合指标排序：OT 证据分数 × 针对该靶点达到的最高 ChEMBL 临床阶段。

跨物种结构差异

find_evolutionary_structural_shifts(
    gene_symbol="ACE2",
    target_species=["mus_musculus", "rhinolophus_ferrumequinum"]
)

对于每个物种：获取直系同源基因（Ensembl）和 AlphaFold 结构，计算 TDA 指纹，并返回该指纹与人类结构指纹之间的 L2 距离以及序列一致性。

---

数据源

来源	使用内容	许可证
AlphaFold DB v6 (EBI/DeepMind)	结构、pLDDT、PAE、AlphaMissense	CC BY 4.0
UniProtKB REST (EMBL-EBI/SIB/PIR)	有条件地验证显示的同工型身份，而非检索常规注释	CC BY 4.0
MONDO (OLS4)	疾病本体、ICD 交叉引用	CC BY 4.0
HPO (JAX)	表型术语、基因-疾病关联	HPO 许可证（可免费用于所有用途）
Open Targets	疾病-靶点证据	CC0 1.0（数据）
ClinVar (NCBI)	变异致病性	公共领域
gnomAD v4	群体等位基因频率	CC0 1.0
DisGeNET	基因-疾病关联评分	免费学术版 / 商业版 (MedBioinformatics)
ChEMBL v37 (EMBL-EBI)	药物生物活性、MoA、ADMET	CC BY-SA 3.0
Ensembl (EMBL-EBI)	VEP、直系同源基因、基因查找	无限制（数据）；Apache 2.0（代码）

全文使用 UniProt 登录号作为蛋白质标识符。只有当 AlphaFold DB 中未单独标记某个同工型时，才会查询 UniProtKB REST API：在重用模型前，其经整理的 Displayed 标记和完整的规范序列必须与模型一致。这项额外的上游请求有独立的速率限制，并且在离线模式下会被阻止。验证失败时会引发错误，而不是据此证明模型不存在。 本版本未集成结构域 (InterPro)、Gene Ontology、实验结构 (RCSB PDB) 和组织表达 (Human Protein Atlas) 查找。

可选的 PDBe/IUCr 文献客户端不是第十个默认核心数据源：只有在 include_literature_evidence=True 且提供了明确的 UniProt 坐标时才会调用。数据源自 PDBe 的 IUCr 文本挖掘流程，且需要单独注明上游来源。 这并不表示会检索 RCSB PDB 实验结构。

完整的来源声明请参见 NOTICE。

---

架构

clients/_base.py
  ├── Air-gap enforcement (refuses sockets when ALPHAFOLD_OFFLINE=1)
  ├── Token-bucket rate limiting (aiolimiter)
  ├── Exponential backoff with jitter (tenacity)
  ├── Circuit breaker (CLOSED / OPEN / HALF_OPEN)
  └── HTTP/2 transport with connection pooling and keep-alive (httpx)

storage/knowledge_graph.py
  ├── SQLite WAL mode (embedded, ACID)
  ├── 6 entity tables: proteins, variants, diseases, drugs, genes, phenotypes
  ├── 4 relationship tables: protein_disease, protein_drug, variant_disease, gene_phenotype
  ├── tool_invocations audit table (SHA-256 of input + output, timestamps)
  └── Analytical views: variant_summary, drug_landscape

domain/disease.py
  └── Pure Python frozen dataclasses (PathogenicityClass, VariantReport, ...)

domain/druggability.py
  └── Pure, I/O-free target-druggability heuristic (named/cited weights and
      cut-offs, plus confidence / data-completeness / borderline reporting)

完整的模块映射请参见 ARCHITECTURE.md。

---

测试与质量

• 全面的离线单元测试套件（使用 respx 模拟上游服务，包括参数化扩展）；在笔记本电脑上，完整套件可在不到一分钟内以隔离方式运行。
• 对已发布功能范围（src/alphafold_sovereign/clients、domain、storage、server、tools）的覆盖率：行覆盖率 + 分支覆盖率均为 100%，每个已发布模块的覆盖率均为 100%。
• 代码检查：ruff（19 类规则，参见 pyproject.toml 中的 [tool.ruff.lint]）。类型检查：对完整源代码树运行 mypy --strict。
• 安全：bandit 和 CodeQL security-extended。
• 供应链：发布 CI 会构建并证明发行包，基于已安装运行时依赖闭包生成与 wheel 绑定的 CycloneDX SBOM，并使用 Sigstore 对发布制品进行签名。scripts/replicate.sh 会独立下载已发布的 wheel 和 sdist，验证其 PyPI 哈希值和 Sigstore bundle，并检查已发布的 CycloneDX 绑定。CI 会生成 SLSA 来源证明；将其附加到每个 GitHub Release 仍是路线图中的一项工作。

完整 CI 矩阵（Python 3.10、3.11、3.12、3.13 × Ubuntu、macOS）会在每次推送时运行。上方的覆盖率百分比是当前 HEAD 上运行 git clone && uv run nox -s cov 得到的结果；如果发现差异，请提交 issue。

---

贡献

必须通过 DCO 签署（git commit -s）。无需转让版权。 覆盖率门槛：CI 要求已发布功能范围达到 100% 的行覆盖率和分支覆盖率（nox -s cov）。 完整指南：CONTRIBUTING.md。

---

同一作者的相关 MCP 服务

• uniprot-mcp — UniProt Swiss-Prot 和 TrEMBL 的 Model Context Protocol 服务（pip install uniprot-mcp-server）。
• semantic-scholar-mcp — Semantic Scholar MCP 服务，涵盖 2 亿多篇学术论文（pip install s2-mcp-server）。

---

引用

机器可读的元数据：CITATION.cff（GitHub 会在侧边栏中显示“引用此仓库”按钮，并读取此文件）。

@software{maniches_alphafold_sovereign_mcp,
  author    = {Maniches, Santiago},
  title     = {AlphaFold Sovereign MCP},
  year      = {2026},
  version   = {1.5.7},
  url       = {https://github.com/smaniches/alphafold-sovereign-mcp},
  license   = {Apache-2.0},
  orcid     = {0009-0005-6480-1987},
  doi       = {10.5281/zenodo.20134773}
}

引用基于此软件得出的结果时，也请按照各自的引用要求引用上游数据源（AlphaFold DB、UniProtKB（用于验证明确指定的异构体时）、Open Targets、ChEMBL、Ensembl、ClinVar、gnomAD、MONDO、HPO、DisGeNET）。

许可证

版权所有 2024–2026 Santiago Maniches。

根据 Apache License, Version 2.0 授权。请参阅 LICENSE。

专利权保留：请参阅 PATENTS.md。 商标政策：请参阅 TRADEMARKS.md。