# 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
bash quick_setup.sh
```

Windows PowerShell：

```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`

```bash
# 在确认存储空间、网络条件和审批后执行
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

```bash
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` |