phylokit-mcp

phylokit-mcp

phylokit-mcp 是一个 MCP 服务，可让 AI Agent 使用 IQ-TREE 3 构建最大似然树，并使用 MAFFT 比对序列。

没有支持度的拓扑就不是结果。 infer_tree 总会运行自举分析并返回每个分支的支持度。没有可跳过该步骤的标志。

为什么要这样规定

无论数据是否支持它，最大似然树看起来都一样。使用从一棵_已知_的 7 个分类单元树模拟得到的比对数据进行测量（JC，100 次重复，seed 1）：

位点数	信息位点数	是否还原真实树？	最低分支支持度
300	51	是，完全还原	1.00
60	11	否，RF 2	0.57

在 60 个位点的情况下，这棵树包含一个并不存在的分支（C,D,G），却遗漏了一个实际存在的分支（E,F,G）。两次运行都返回形状相同、完全解析的 Newick 字符串。只有支持度值能区分它们，而错误分支恰好是树中_支持度最低_的分支。

它能报告而 Newick 字符串无法表达的内容

• 冲突分支：数据支持度 ≥0.70、但_未出现在_报告树中的分组。带支持度注释的 Newick 字符串无处记录这些分组。
• fraction_resolved：支持度达到 0.70 的分支所占比例。在将任何单个分组重复陈述为事实之前，先查看这个关键数字。
• 带 ΔAIC 的备选模型，而不只是获胜模型。在上文的 300 位点比对中，模拟所用模型为 JC，但 AIC 获胜模型不是 JC（TPM2u 和 TPM2 并列），且多个模型（包括 ΔAIC 为 0.7 的 JC）都处于传统的 ±2 范围内（seed=1，piqtree 0.8.3）。
• 长度与证据：同时提供 n_parsimony_informative 和 n_sites。包含 10,000 个位点、但序列几乎完全相同的比对无法提供任何支持。

工具

工具	功能
infer_tree	ML 树加上自举支持度（非参数法或 UFBoot2），按分支提供。
select_substitution_model	按 ΔAIC/AICc/BIC 对 100 多种模型排序，并指出不同准则结论不一致的情况。
compare_trees	Robinson–Foulds 距离以及不同的分支。比较分裂，而不是字符串。
simulate_alignment	沿指定的树生成序列：阳性对照。
align_sequences	使用 MAFFT 比对未比对的 FASTA，结果直接内联返回或写入新文件（out_path）。
map_positions	将残基映射到其比对列，再将该列映射到其他每条序列。
capabilities	piqtree 和 IQ-TREE 版本、215 种替换模型、MAFFT 版本及限制。

接受 FASTA 或 Newick 的工具也接受文件路径（fasta_path；两个树时使用 trees_path），由服务读取；相对路径以服务的工作目录为基准解析。

测试会运行真实的 IQ-TREE 和 MAFFT（不使用模拟引擎），并包含 23 项突变检查和真实进程的 JSON-RPC 握手测试。

安装

pip install phylokit-mcp

需要 Python 3.12+。IQ-TREE 3 通过 piqtree 0.8 提供，该版本会将它构建到 wheel 中。align_sequences 也需要 PATH 中有 MAFFT 二进制文件；对于未对齐的输入，map_positions 也需要它；其他工具则无需此依赖。详情请见：docs/INSTALL.md。

配置 MCP 客户端

{
  "mcpServers": {
    "phylokit": {
      "command": "uvx",
      "args": ["phylokit-mcp"]
    }
  }
}

如果 uvx 选择的 Python 版本低于 3.12，请使用 "args": ["--python", "3.12", "phylokit-mcp"]。

基准测试结果

我们将使用该服务的 Claude，与在我们配置了 piqtree、cogent3 和 MAFFT 的环境中编写 Python 的 Claude 进行了对比；测试涵盖 38 道系统发育学问题，每道题运行 3 次。平局意味着无需自行搭建环境，该服务也能达到相同结果。每次运行都答对的问题数，服务对比 Python：Claude Haiku 5.5 为 34 对 37，Sonnet 5.5 为 37 对 35，Opus 5.5 为 36 对 35（使用接收文件路径的提交版本）。差异均不显著（预注册；Haiku 和 Sonnet 的 Holm 校正 McNemar 检验 p = 0.75）。服务在 Haiku 上的费用与 Python 大致相同，在 Sonnet 上更高（1.23×），在 Opus 上也更高（1.26×）。

图表展示的是首次 Opus 5.5 运行结果，使用的发布版本将数据作为文本接收。按答案数计算，服务答对了 114 个中的 110 个，Python 答对了 113 个；按题目数计算，每次运行都答对的题目分别为 38 道中的 36 道和 37 道（符号检验 p = 1）。按每道题计算，服务耗时是 Python 的 6.0 倍（95% CI 为 4.4 至 8.3），费用是 14.4 倍（9.9 至 20.2）；两者均为每题比值的几何平均数。大部分费用来自模型将数据文件粘贴到工具调用中；改用文件路径后（预注册的复测，2026-10-18），费用降至 1.26 倍（1.04 至 1.55）。

问题由我们编写，基准测试也由我们执行；欢迎外部复测。该基准测试不评估支持值；方法、对照和其他限制见 benchmarks/agent_qa；Haiku 和 Sonnet 的测试结果见：2026-10-20 复测。

可复现性

在任何设置下都无法做到位级精确：IQ-TREE 会在搜索过程中读取墙上时钟，因此，即使请求和种子相同，分支长度和对数似然值的末尾数字也可能不同，支持值也可能因某次重复结果翻转而发生变化。该服务会报告 deterministic_across_processes: false。请使用 compare_trees 比较树，并以容差比较数值，切勿使用字符串相等比较。测量详情：docs/REPRODUCIBILITY.md。

局限性

• 核苷酸和蛋白质，不支持密码子模型。 传入 sequence_type="protein" 和蛋白质模型（LG、WAG 等）。分子类型是显式声明的，不会自动检测：仅包含 A/C/G/T 的比对也可以是有效的蛋白质序列（丙氨酸/半胱氨酸/甘氨酸/苏氨酸），错误猜测会导致树、似然值和支持度出错，且不会发出警告。
• 支持两种自举，不支持 aLRT 或近似贝叶斯法。 默认采用非参数自举（Felsenstein 1985），在此处计算，支持度为 0.70；这是唯一能报告 ML 树中缺失的强支持分支的方法。support_method="ufboot" 使用 IQ-TREE 的 UFBoot2（Hoang et al. 2018），支持度为 0.95。
• 非参数自举的成本随重复次数线性增长，每次重复都是一次完整的 ML 搜索：对于 89 个分类单元 × 435 个位点，一次重复耗时 25–93 秒，1000 次 UFBoot2 重复耗时 83 秒。上限为 200 个分类单元、1000 次非参数自举和 10000 次 UFBoot2 重复。每个工具每 15 秒发送一次进度通知，因此客户端空闲超时不会中止耗时较长的调用。
• 比对仅使用 MAFFT --auto，且为单线程运行：不提供策略选择、谱系比对或修剪；最多支持 200 条序列，每条 100,000 个残基，耗时上限为 600 秒。不接受带缺口的输入，不会去除缺口。树工具会拒绝长度不齐的输入，而不会进行比对。
• 无根树。 不提供定根、年代推断或祖先重建。

许可证

GPL-2.0-only，因为 piqtree 使用 GPL-2.0-only，该许可证与 GPL-3.0 不兼容。cogent3 使用 BSD 许可证。

如果发布此服务生成的结果，请引用 IQ-TREE 3、piqtree，以及在用于生成比对时引用 MAFFT，而非此封装程序。参考文献见 CITATION.cff， 许可证和隶属信息见 NOTICE。