AI Agent 时代的生物计算：AlphaFold 3 MCP Server 搭建与本地部署

本文收录于专栏 AI Agent智能体系列 ------ 专栏系统覆盖 AI Agent 记忆、工具、插件与实战，点击订阅可跟踪后续更新。
自建 af3-mcp，通过Agent调用AlphaFold3。这篇把过程摊开：怎么从一个能启动的 server 走到 4 步链路全打通、能读AlphaFold3结果 ，以及如何给Agent"安装 MCP"。

本机 conda 环境实测 ：4 个工具的 JSON-RPC handshake + 真跑 submit_af3_job（conda 后台 spawn AF3 v3.0.1 wrapper）+ read_af3_confidence 读 GFP 真实结果------pTM = 0.91 、pLDDT = 92.6。

关键字：AlphaFold 3、MCP server、Model Context Protocol、conda spawn、pTM、pLDDT、JSON-RPC、路径自动探测

text 复制代码

AF3 包成 MCP server
├─ 为什么自建：MacromNex 撞墙（a3m 缺脚本 / docker 段错误 / 路径写死）
├─ 4 步链路：build JSON → conda spawn → 轮询状态 → 读置信度
├─ 零硬编码：4 级路径探测（env > 脚本旁 > $HOME > PATH）
├─ 实测：GFP pTM 0.91 / pLDDT 92.6，6 处 bug 修完
└─ 接入：Hermes config.yaml / Claude Code .mcp.json

[§1. 场景痛点：装 MCP 容易，让 MCP 真跑不容易](#§1. 场景痛点：装 MCP 容易，让 MCP 真跑不容易)

[§2. 4 工具链路设计：组 → 跑 → 查 → 读](#§2. 4 工具链路设计：组 → 跑 → 查 → 读)

[§3. 环境准备（实测版本）](#§3. 环境准备（实测版本）)

[§4. 4 级路径自动探测：零硬编码](#§4. 4 级路径自动探测：零硬编码)

[§5. 协议级实测：4 步链路全打通](#§5. 协议级实测：4 步链路全打通)

[§6. 对话演示：用户说人话 → 自动出结构](#§6. 对话演示：用户说人话 → 自动出结构)

[§7. pTM / pLDDT / ipTM 解读](#§7. pTM / pLDDT / ipTM 解读)

[§8. 踩坑清单：6 处实测 bug](#§8. 踩坑清单：6 处实测 bug)

[§9. 接到 Agent：两边各几行](#§9. 接到 Agent：两边各几行)

[§10. 总结与资产包](#§10. 总结与资产包)

资料	链接	与本文关系
AF3 GitHub README	https://github.com/google-deepmind/alphafold3	docker 推理命令与权重许可出处
AF3 input 文档	https://github.com/google-deepmind/alphafold3/blob/main/docs/input.md	JSON dialect/version 官方说明
MCP Python SDK	https://github.com/modelcontextprotocol/python-sdk	2.x API（MCPServer）出处
mcp-development skill	`~/.hermes/skills/autonomous-ai-agents/mcp-development/`	自建 MCP 的模板 + 4 硬规则

§1. 场景痛点：装 MCP 容易，让 MCP 真跑不容易

实验室的真实场景：AF3 装在共享 GPU 服务器上，五个人都要用------每人 SSH 上去配一遍路径、抄一遍命令，路径改了全组重教一遍；任务一跑几小时，谁都记不住自己的任务跑到哪了。这正是 MCP 的主场：server 常驻服务器，持有环境和任务状态；所有人的 Agent 通过 stdio 直连，schema 强校验参数，管理员改一处全组生效。

问题是有 2 个候选 AF3 MCP（cyanheads/protein 是结构查询不是结构生成，不在本文对比范围），实测只有 1 个能跑：

维度	MacromNex/alphafold3_mcp	af3-mcp（本文）
后端	docker alphafold3 镜像（10+ GB）	本机 conda AF3 env（零 docker 依赖）
a3m 模式	❌ 调仓库里不存在的脚本 `prepare_input_from_a3m.py`，首次调用即 ModuleNotFoundError	不支持（走 MSA-first pipeline）
JAX 段错误	❌ 未修（alphafold3.cpp + jax 顺序错）	✅ wrapper 先 `import jax` 强初始化
路径处理	❌ 默认写死 `/root/...`	✅ 4 级探测（§4），零硬编码
README 可信度	❌ README 说 5 工具实际 6 个，detail.md 说 13 个	4 工具，与代码一致
实际跑通	❌ a3m/jax bug 连环	✅ GFP 真推理 pTM 0.91 / pLDDT 92.6
License	Apache 2.0	MIT

结论：MacromNex 开源但质量可疑，实测后已从 config.yaml 删除（连同 boltz_mn / protein_sol 共 3 个 MacromNex MCP）。最终方案是自建 af3-mcp：4 个工具，跑本机 conda AF3 环境，不依赖 docker。

§2. 4 工具链路设计：组 → 跑 → 查 → 读

复制代码

你的笔记本                    本机 conda AF3
Agent（Hermes/DSH/Claude Code）⇄ af3-mcp ⇄ conda spawn → AF3 v3.0.1
        mcp__af3__build_af3_json      组装输入 JSON
        mcp__af3__submit_af3_job      提交任务（conda 后台 spawn，setsid）
        mcp__af3__get_af3_job_status  查状态
        mcp__af3__read_af3_confidence 解读结果（人话）

4 个工具不是凭空设计的，对应 AF3 流程的最小完备集：

步骤	MCP 工具	落盘物	状态机
1. 组装	`build_af3_json`	`~/af_input/<name>.json`	已组 / 未组
2. 提交	`submit_af3_job`	`~/af_output/<name>.submit.log`（实时 log）	running
3. 轮询	`get_af3_job_status`	---	pending / done
4. 读取	`read_af3_confidence`	`~/af_output/<name>/<name>_summary_confidences.json`	done

关键设计 ：状态靠文件存在性，不靠 docker ps / in-memory dict------"done" = <name>_summary_confidences.json 存在。server 不维护任务表，conda spawn 被 kill 后状态依然准确。任何一步出错都返回 isError: true + 可读错误，Agent 能自己处理；schema 强制字段类型（protein_sequence 非空、name 禁非法字符），违规在协议层就拒。

协议时序图：下面这条 JSON-RPC 握手序列

上图：客户端启动 → initialize 握手（protocol 2025-06-18）→ tools/list 发现 → 4 次 tools/call。绿色路径是成功（conda 真跑），红色是错误路径（结果未就绪时 isError 不崩溃）。

§3. 环境准备（实测版本）

bash 复制代码

# 1. 系统 Python 3.10 装 mcp 2.x（server 进程用）
pip install --user 'mcp>=2.0'

# 2. AF3 conda env 装 v3.0.1 + hmmer
conda create -n AF3 python=3.11 -y
conda activate AF3
pip install alphafold3==3.0.1
conda install -c bioconda hmmer -y

# 3. clone AF3 v3.0.1 源码（pip 包不含可执行 run_alphafold.py，
#    不 clone 会报 ModuleNotFoundError: No module named 'shards'）
git clone https://github.com/google-deepmind/alphafold3.git ~/app/alphafold3-v301 -b v3.0.1

# 4. 权重 + 数据库（向 AF3 服务器申请；学术许可）
ls ~/AF/datasets/                                  # 含 af3.bin 1.1 GB
ls ~/AF/datasets/public_databases_AF3_AF3Complex/   # 含 9 个 .fa 文件，共 357 GB

# 5. GPU 驱动 + CUDA 12.x（消费级 GPU 需 --flash_attention_implementation=xla）
nvidia-smi

包	版本	备注
Python（系统）	3.10	server 进程
Python（AF3 conda）	3.11	jax + alphafold3 3.0.1
mcp	≥2.0	1.x 没 `MCPServer` 类（见 §8 坑 1）
alphafold3	3.0.1	pip 包必须与源码 tag 一致
jax	0.4.x	默认用 CUDA 12
GPU	消费级 12 GB	需 `--flash_attention_implementation=xla`（默认 triton 撞墙）

§4. 4 级路径自动探测：零硬编码

这是与其它 AF3 MCP 候选最大的区别 ------AF3 conda env 路径、源码路径、权重路径不进代码，server 内部 4 级 fallback 自动探测；同一份代码零改动换机器（布局不同时只改 Agent 端 env 即可）。

python 复制代码

# 0. env var 显式覆盖 (mcp_servers.env 传, 优先级最高)
os.environ.get("AF3_RUN_ALPHAFOLD")
# 1. Path(__file__).parent 自定位 (server 旁边 helper scripts)
Path(__file__).parent / "scripts" / "run_af3_jaxfirst.py"
# 2. Path.home() 用户级默认 (Linux $HOME 是约定路径, 跨用户通用)
Path.home() / "anaconda3" / "envs" / "AF3"
# 3. FHS 系统级 + shutil.which
Path("/opt/conda/envs/AF3"), shutil.which("run_alphafold.py")

模块级常量声明（server 启动一次，5 个常量自动配置）：

python 复制代码

AF3_INPUT  = _env_or_default("AF3_INPUT",  Path.home() / "af_input",  Path("/var/lib/af3/input"))
AF3_OUTPUT = _env_or_default("AF3_OUTPUT", Path.home() / "af_output", Path("/var/lib/af3/output"))
AF3_MODELS = _env_or_default("AF3_MODELS", Path.home() / "AF" / "datasets",
                             Path("/opt/af3/weights"), Path("/data/af3/weights"))
AF3_DBS    = _env_or_default("AF3_DBS",    Path.home() / "AF" / "datasets" / "public_databases_AF3_AF3Complex",
                             Path("/opt/af3/databases"), Path("/data/af3/databases"))
AF3_CONDA_ENV = _env_or_default("AF3_CONDA_ENV", Path.home() / "anaconda3" / "envs" / "AF3",
                             Path("/opt/conda/envs/AF3"), Path("/usr/local/anaconda3/envs/AF3"))

§5. 协议级实测：4 步链路全打通

不靠 agent，用一个 25 行的 Python 脚本（资产包 test_client.py）走完整 JSON-RPC handshake + 调全部 4 个工具。真实输出，2026-10-04 本机 conda 真跑：

text 复制代码

=== 1. initialize ===
server: {'name': 'af3'} | protocol: 2025-06-18

=== 2. tools/list ===
- build_af3_json: 组装 AF3 输入 JSON...（schema 完整）
- submit_af3_job: conda spawn 后台（setsid + log 路径）
- get_af3_job_status: done / pending
- read_af3_confidence: 读 summary_confidences.json + atom_plddts 算 mean → 大白话

=== 3. build_af3_json（GFP, P42212, 238 aa）===
[OK] ~/af_input/gfp_demo.json: 蛋白链 A (238 aa) + 无配体, seeds=[1]

=== 4. submit_af3_job（conda 真跑分支）===
[SUBMITTED] AF3 conda 后台进程已启动
  PID: 100181
  log: ~/af_output/gfp_demo.submit.log
  cmd: .../envs/AF3/bin/python .../scripts/run_af3_jaxfirst.py --json_path=... --model_dir=... --db_dir=...

=== 5. get_af3_job_status ===
pending                  # MSA 阶段，4 个 jackhmmer 并发打 357 GB 数据库

=== 6. read_af3_confidence("gfp_demo"，跑完后）===
pTM=0.91（很靠谱）；ipTM=0.00（无配体，纯蛋白无 ipTM）；pLDDT=92.6（结构很靠谱）

关键 4 步全部跑通 ：submit 走 conda env python 后台 spawn（真实 AF3 进程，能 pgrep -af run_af3_jaxfirst.py 看到）；status 检测到 summary_confidences.json 存在即 done；read 解析真 GFP 结果。从 dry-run 到真跑之间修了 6 处 bug，清单见 §8。

§6. 对话演示：用户说人话 → 自动出结构

挂上 MCP 后，用户不需要知道任何 AF3 / conda / MSA / hmmer 概念：

用户说："帮我预测 GFP 的结构，UniProt P42212"

Hermes Agent 自动四步：

python 复制代码

# 步骤 1：组装 JSON（Agent 内部拉 UniProt FASTA 取序列）
mcp__af3__build_af3_json(
    name="gfp_demo",
    protein_sequence="MSKGEELFTGVVPILVELDGDVNGHKFSVSGEGEGDATYGKLTLKFICTTGKLPVPWPTLVTTFSYGVQCFSRYPDHMKQHDFFKSAMPEGYVQERTIFFKDDGNYKTRAEVKFEGDTLVNRIELKGIDFKEDGNILGHKLEYNYNSHNVNYVIMADKQKNGIKVNFKIRHNIEDGSVQLADHYQQNTPIGDGPVLLPDNHYLSTQSALSKDPNEKRDHMVLLEFVTAAGITHGMDELYK"
)
# → "[OK] ~/af_input/gfp_demo.json: 蛋白链 A (238 aa) + 无配体, seeds=[1]"

# 步骤 2：提交任务（conda spawn，setsid 独立进程组）
mcp__af3__submit_af3_job(name="gfp_demo")
# → "[SUBMITTED] AF3 conda 后台进程已启动  PID: 100181  log: ~/af_output/gfp_demo.submit.log"

# 步骤 3：轮询状态（Agent 自动每 30s 调一次直到 done）
mcp__af3__get_af3_job_status(name="gfp_demo")
# → "pending" → "pending" → ... → "done"

# 步骤 4：解读结果（人话）
mcp__af3__read_af3_confidence(name="gfp_demo")
# → "pTM=0.91（很靠谱）；ipTM=0.00（无配体）；pLDDT=92.6（结构很靠谱）"

Agent 最终回复：

GFP 预测完成。

整体质量：pTM = 0.91，pLDDT mean = 92.6，结构很靠谱。

产物：~/af_output/gfp_demo/gfp_demo_model.cif（预测 mmCIF）+ gfp_demo_confidences.json（每残基 pLDDT）。

关键点：

用户全程不说"AF3"、不说"MSA"、不说"conda"------Agent 通过 MCP 工具自己处理。
长任务不阻塞 Agent------submit 后 status polling 是异步的。本机单 HDD 实测 GFP 全程约 3h42，瓶颈在 MSA 磁盘 IO 不是 GPU。
结果是人话不是数字------"结构很靠谱"而不是"pTM=0.91, pLDDT=92.56"。

§7. pTM / pLDDT / ipTM 解读

上图：pLDDT（每个残基的自信程度）和 ipTM（蛋白-配体结合姿势可信度）的阈值含义。
注解：GFP 结果里 ipTM=0.00 不是 bug------纯蛋白场景 AF3 不算 pair-wise pTM，显示"无配体，无 ipTM"比硬给 0.00 更清楚。

§8. 踩坑清单：6 处实测 bug

按时间顺序：

mcp 2.x 改名 ：FastMCP → MCPServer，1.x 教程代码直接 ModuleNotFoundError。修法：pip install --user 'mcp>=2.0' 后用 from mcp.server.mcpserver import MCPServer。
缺 from pathlib import Path ：server 顶层没 import Path，新写的 _env_or_default 用 Path() 报 NameError。修法：补 import。
read_af3_confidence 字段名错 ：原版找 plddt/iptm 顶层字段，实际 AF3 v3.0.1 输出是 ptm 顶层 + chain_pair_iptm[0][1] 嵌套 + atom_plddts 在 confidences.json。修法：读 ptm，mean pLDDT 从 atom_plddts 算。
PYTHONPATH 污染 conda env ：mcp_servers 给 server 进程传了系统 py3.10 的 site-packages，但 conda AF3 是 py3.11------subprocess 启动时 import zstandard 撞 py3.10 的 .so 报 ModuleNotFoundError。修法：env.pop("PYTHONPATH", None)。
os.environ.get('HOME') 返回 None ：Hermes 沙箱启动 server 时不传 HOME，AF3 内部 pathlib.Path(None) 报 TypeError。修法：env.setdefault("HOME", str(Path.home())) 显式补。
系统 python 没 jax ：用 /usr/bin/python3（系统 py3.10）跑 wrapper，import jax 报 ModuleNotFoundError。修法：subprocess 用 conda env 自己的 python（_find_af3_conda_env_python() 自动探测）。

已知的非 bug（设计使然，勿再排查）：

jax+alphafold3.cpp 段错误 ：AF3 v3.0.x 先 import alphafold3.cpp 再 import jax 会在 jaxlib.xla_client.initialize_pjrt_plugin SegFault，无 traceback。conda 直跑必须 wrapper 先 import jax; jax.devices() 强初始化 （scripts/run_af3_jaxfirst.py 就是这个 wrapper）。
conda 直跑找不到 jackhmmer ：subprocess 不继承 shell PATH。修法：env["PATH"] = f"{conda_bin}:{env.get('PATH', '')}" 注入。
Mock MSA 跑不通 ：unpairedMsa: "" 跳过 pipeline 会报 ValueError: Protein chain 1 is missing unpaired MSA.。必须跑真 MSA，这是 AF3 的设计选择。
单机单盘跑 MSA 慢：4 个 jackhmmer 并发打同一块 HDD，CPU 4% / IO 100%；BFD 库 42 分钟，uniref90 库 2h47min。多分子建议串行，不要并行抢盘。

§9. 接到 Agent：两边各几行

Hermes Desktop（~/.hermes/config.yaml 加 mcp_servers.af3 块，改完需重启 gateway 生效）：

yaml 复制代码

mcp_servers:
  af3:
    command: /usr/bin/python3
    args:
      - ~/.hermes/af3-mcp/af3_mcp_server.py
    env:
      PYTHONPATH: ~/.local/lib/python3.10/site-packages
      AF3_INPUT: ~/af_input
      AF3_OUTPUT: ~/af_output
      AF3_MODELS: ~/AF/datasets
      AF3_DBS: ~/AF/datasets/public_databases_AF3_AF3Complex
      AF3_CONDA_ENV: ~/anaconda3/envs/AF3
      AF3_RUN_ALPHAFOLD: ~/app/alphafold3-v301/run_alphafold.py
    timeout: 180
    connect_timeout: 60
    enabled: true

Claude Code / DSH（项目级 .mcp.json）：

json 复制代码

{"mcpServers": {"af3": {
  "command": "python3",
  "args": ["~/.hermes/af3-mcp/af3_mcp_server.py"],
  "env": {"AF3_CONDA_ENV": "~/anaconda3/envs/AF3"}}}}

挂上后模型看到 mcp__af3__build_af3_json 等四个原生工具（mcp__<server>__<tool> 命名两家同形），直接说"预测 GFP 的结构"即可。env 块里的路径也可全部省略------§4 的 4 级探测会自动找，同一份 server 代码换机只改 env。

§10. 总结与资产包

2 个 AF3 MCP 候选 → 1 个能跑通。能跑通的关键不是"装 MCP"的能力（npm install 谁都会），而是修 MCP 的能力------读源码、追段错误、4 级路径自动探测、conda spawn 真跑。

完整MCP代码：

附件包 ：amber-mcp-local

参考来源

google-deepmind/alphafold3 README------docker 命令与权重许可出处。
AF3 input 文档------dialect/version 与配体写法。
MCP Python SDK------2.x API（MCPServer）出处。
Abramson J, et al. Nature 2024. DOI: 10.1038/s41586-024-07487-w。
本机实测：4 工具协议级 handshake + conda 真跑 GFP（pTM 0.91, pLDDT 92.6）+ 6 处 bug 修复 diff。
mcp-development skill（~/.hermes/skills/autonomous-ai-agents/mcp-development/）------自建 MCP 的模板。

系列导航 ：专栏全集 AI Agent智能体系列

我的专栏

蛋白 / 抗体 / 多肽 / 核酸	分子模拟 / 动力学 / 对接	药物 / 设计 / 案例	AI / Agent / 大模型
开源蛋白结构预测	分子模拟基础	小分子药物设计案例	AI Agent系列
开源蛋白生成方法实践	分子动力学模拟-Amber	蛋白药物设计案例	化学大模型
开源多肽设计模型	分子动力学模拟-Gromacs	多肽药物设计案例	《AI Agent原理与实战》
开源多肽性质预测	分子动力学模拟-OpenMM	开源小分子生成设计	CADD中的机器学习模型
DNA/RNA药物设计	結合自由能	高效计算配置	《MCP 入门实战》
siRNA药物设计模型	UCSF DOCK系列	我胡师兄说药	《AI入门实战2026》
ASO药物设计模型	rDock系列 LeDock系列 gnina系列		《经典机器学习实战》

AI Agent 时代的生物计算：AlphaFold 3 MCP Server 搭建与本地部署

目录

相关教程与核心文献

§1. 场景痛点：装 MCP 容易，让 MCP 真跑不容易

§2. 4 工具链路设计：组 → 跑 → 查 → 读

§3. 环境准备（实测版本）

§4. 4 级路径自动探测：零硬编码

§5. 协议级实测：4 步链路全打通

§6. 对话演示：用户说人话 → 自动出结构

§7. pTM / pLDDT / ipTM 解读

§8. 踩坑清单：6 处实测 bug

§9. 接到 Agent：两边各几行

§10. 总结与资产包

参考来源

我的专栏