blastp_mcp

blastp_mcp 将 NCBI BLAST+ 的 blastp 包装为 FastMCP 服务，提供可审计的蛋白质同源性搜索，支持本地产物输出、结构化元数据和数据库状态查询。

设计理念

每次搜索都是可追溯的运行记录。blastp_mcp 不会只返回结果然后丢弃中间产物——它会将查询序列、BLAST 命令参数、标准输出/错误日志、原始 outfmt7 结果、CSV 命中和候选 FASTA 全部写入 runs/<run_id>/ 目录，形成可复查、可重放的运行档案。

项目结构

blastp_mcp/
├── src/
│   ├── server.py          # FastMCP 服务入口，注册 7 个工具
│   ├── blast_service.py   # 核心搜索逻辑：序列解析、参数校验、blastp 调用
│   ├── blast_process.py   # outfmt7 解析 → CSV + 候选 FASTA
│   ├── db_manager.py      # BLAST 数据库管理：别名解析、状态检查、文件扫描
│   └── job_manager.py     # 异步任务管理：提交、状态、结果、日志、取消
├── tests/                 # 测试文件
├── examples/              # 示例 FASTA 序列
├── fixtures/              # 测试用 outfmt7 样本
├── quick_setup.sh         # 一键环境安装脚本
└── requirements.txt

MCP 工具

工具	说明
list_databases()	报告 swissprot、refseq、nr 三个数据库的状态，无需下载大型数据库
search_homology_quick(sequence, ...)	在 SwissProt 上运行限时 BLASTP 搜索，适合快速交互式查询
submit_homology_search(sequence, ...)	提交异步 BLASTP 任务，支持 tiered/swissprot/refseq/nr 数据库
get_blast_job_status(job_id)	查询异步任务状态和元数据
get_blast_job_result(job_id)	获取异步任务完整结果
get_blast_job_log(job_id)	获取任务的标准输出和标准错误日志
cancel_blast_job(job_id)	取消正在运行或排队中的任务

工具参数

search_homology_quick：

• sequence（必填）：蛋白质序列，支持 FASTA 格式或纯序列
• evalue：E 值阈值，默认 1e-5
• max_target_seqs：最大返回命中数，默认 20
• include_alignments：是否包含比对详情，默认 false

submit_homology_search：

• sequence（必填）：蛋白质序列
• database：目标数据库，可选 tiered（默认，从 SwissProt 开始分级搜索）、swissprot、refseq、nr
• evalue：E 值阈值，默认 1e-5
• max_target_seqs：最大返回命中数，默认 50
• num_threads：CPU 线程数，默认 4
• include_alignments：是否包含比对详情，默认 false

快速开始

Linux/macOS 或已安装 Git Bash 的 Windows：

bash quick_setup.sh

Windows PowerShell：

.\quick_setup.ps1

安装脚本会自动完成以下步骤：

1. 创建 Python 虚拟环境 ./env/
2. 安装 Python 依赖
3. 检查 blastp、makeblastdb、blastdbcmd、update_blastdb.pl 是否可用；如果缺失，会从 NCBI 官方 BLAST+ LATEST 目录下载当前平台对应的 standalone BLAST+ 包，并安装到本仓库本地 ./tools/
4. 下载并验证 SwissProt 数据库

数据库存储路径由环境变量 BLAST_DB_DIR 指定，未设置时默认使用 ./db/。

BLAST+ 安装路径由 BLAST_TOOLS_DIR 指定，未设置时默认使用 ./tools/。如果运行环境已经安装 BLAST+，可以通过 BLAST_BIN_DIR=/path/to/ncbi-blast/bin 直接指定。若需要关闭自动安装，可设置 BLAST_MCP_AUTO_INSTALL_BLAST=0。高级场景下也可以用 BLAST_PLUS_URL 指定固定版本的 NCBI BLAST+ tar.gz 下载地址。

数据库策略

数据库	大小	默认安装	说明
SwissProt	~数百 MB	自动安装	最小可用的真实蛋白质 BLAST 数据库，适合快速搜索
RefSeq Protein	~数十 GB	不自动下载	需手动准备 refseq_protein
nr	~数百 GB	不自动下载	非冗余蛋白序列数据库，需手动准备

手动安装大型数据库

将 BLAST 数据库文件放入 BLAST_DB_DIR 目录，使用对应的实际数据库名称：

• refseq 别名 → refseq_protein
• nr 别名 → nr

# 在确认存储空间、网络条件和审批后执行
update_blastdb.pl --decompress refseq_protein
update_blastdb.pl --decompress nr

Tiered 分级搜索

当 database 设为 tiered（默认）时，系统先从 SwissProt 开始搜索：

• 如果命中结果 > 0，直接返回，不再搜索更大的数据库
• 如果没有命中，返回 partial 状态并提示 RefSeq/nr 未下载，建议手动准备后重试

运行产物

每次搜索在 runs/<run_id>/ 下生成完整档案：

runs/<run_id>/
├── query.fasta              # 查询序列（含 SHA256 哈希）
├── blast_command.json       # 完整命令行参数和环境元数据
├── blast_stdout.log         # blastp 标准输出
├── blast_stderr.log         # blastp 标准错误
├── blast_results.outfmt7    # BLAST outfmt 7 格式原始结果
├── blast_hits.csv           # 结构化命中表格
├── candidates/              # 逐条候选序列 FASTA
├── candidates.fasta         # 合并候选序列 FASTA
└── result_summary.json      # 最终结果摘要

BLAST 输出使用 outfmt 7 格式，字段包括 qseqid sseqid pident length mismatch gapopen qstart qend sstart send evalue bitscore stitle sseq。blast_process.py 负责解析并生成 CSV 和候选 FASTA。

环境变量

变量	默认值	说明
BLAST_DB_DIR	./db/	数据库存放目录
BLAST_BIN_DIR	无	额外的 BLAST 二进制文件搜索路径
BLAST_TOOLS_DIR	./tools/	自动安装 NCBI BLAST+ 的本地目录
BLAST_PLUS_URL	无	固定版本 NCBI BLAST+ tar.gz 下载地址，未设置时使用官方 LATEST
BLAST_MCP_AUTO_INSTALL_BLAST	1	是否在缺失 BLAST+ 时自动下载安装；设为 0 可禁用
BLAST_MCP_MAX_SEQUENCE_LENGTH	10000	允许的最大序列长度
BLAST_MCP_MAX_TARGET_SEQS	500	允许的最大目标序列数
BLAST_MCP_MAX_THREADS	≤ 8	允许的最大线程数
BLAST_MCP_TIMEOUT_SECONDS	120	快速搜索超时（秒）
BLAST_MCP_LONG_TIMEOUT_SECONDS	3600	异步任务超时（秒）
BLASTDB	无	NCBI BLAST 标准数据库搜索路径，setup 脚本自动追加

注册到 Claude Code

claude mcp add blastp_mcp -- /path/to/env/bin/python /path/to/blastp_mcp/src/server.py

或使用 quick_setup.sh 末尾打印的注册命令。

故障排查

问题	解决方法
找不到 blastp	安装 NCBI BLAST+ 后重新运行 quick_setup.sh
SwissProt 缺失	重新运行 quick_setup.sh，检查 BLAST_DB_DIR 和网络连接
RefSeq/nr 不可用	这是预期行为，除非手动安装了大型数据库
权限错误	确保 MCP 进程对 runs/ 有写权限，对 BLAST_DB_DIR 有读权限
序列无效	检查序列是否仅包含合法氨基酸字符（ACDEFGHIKLMNPQRSTVWY + ZX*-）
搜索超时	调整 BLAST_MCP_TIMEOUT_SECONDS 或减少 max_target_seqs