foldseek-mcp

独立的 FastMCP 服务端，用 MCP 工具封装 FoldSeek easy-search。

本项目面向 ProteinMCP / Claude / Agent Runtime 使用。MCP 负责参数校验、路径安全、Docker/FoldSeek 调用、结果解析、日志、artifact、command.json 和 manifest.json 记录。

MCP Tools

• foldseek_search_structure：用 PDB/mmCIF 结构文件搜索官方 FoldSeek 数据库。
• foldseek_search_sequence：用 FASTA 文本或 FASTA 文件搜索结构数据库。
• foldseek_list_databases：列出已安装数据库、可用官方数据库、模型状态和 Agent 建议。
• foldseek_download_database：显式下载官方 FoldSeek 数据库。
• foldseek_validate_environment：检查 Docker/FoldSeek、数据库目录、模型目录和运行目录。

默认数据库策略

默认官方数据库 alias：

afdb_uniprot50_minimal

对应 FoldSeek 官方数据库名：

Alphafold/UniProt50-minimal

注意：该官方库约 114GB，不会在普通安装时静默下载。需要显式确认后下载，或由外部流程提前下载好并挂载/配置给 MCP。

不再把自建 fixture 数据库作为默认科学搜索数据库。fixture 只能用于链路 smoke test，不能替代官方数据库。

推荐部署方式

大型 FoldSeek 数据库不要打进 MCP Docker 镜像。推荐：

• MCP 镜像只包含运行环境、FoldSeek runtime、MCP 代码。
• 官方数据库放在服务器持久化目录。
• 运行时通过 volume 或环境变量挂载。

示例目录：

/opt/mgi/foldseek-mcp/
/data/foldseek/databases/afdb_uniprot50_minimal/
/data/foldseek/models/
/data/foldseek/runs/

如果你先在 Windows 下载到 E:\download\foldseek，服务器上可以拷贝成：

/data/foldseek/databases/afdb_uniprot50_minimal/

然后设置：

FOLDSEEK_MCP_DATABASE_ROOT=/data/foldseek/databases
FOLDSEEK_MCP_MODEL_ROOT=/data/foldseek/models
FOLDSEEK_MCP_RUN_ROOT=/data/foldseek/runs
FOLDSEEK_MCP_BACKEND=docker
FOLDSEEK_MCP_DOCKER_IMAGE=openeuler/foldseek:10-941cd33-oe2403sp3
FOLDSEEK_MCP_AUTO_DOWNLOAD=false

数据库 prefix 应为：

<DATABASE_ROOT>/afdb_uniprot50_minimal/afdb_uniprot50_minimal

下载官方数据库

通过 MCP 工具下载时，需要显式确认大体积下载：

{
  "database": "afdb_uniprot50_minimal",
  "confirm_large": true
}

也可以直接用 Docker 下载到外部目录：

$ROOT = "E:\download\foldseek"
New-Item -ItemType Directory -Force -Path "$ROOT\databases\afdb_uniprot50_minimal\tmp"

docker pull openeuler/foldseek:10-941cd33-oe2403sp3

docker run --rm `
  -v "${ROOT}:/data" `
  openeuler/foldseek:10-941cd33-oe2403sp3 `
  foldseek databases "Alphafold/UniProt50-minimal" `
  /data/databases/afdb_uniprot50_minimal/afdb_uniprot50_minimal `
  /data/databases/afdb_uniprot50_minimal/tmp `
  --threads 8

安装

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

或：

bash quick_setup.sh

Windows 默认使用 Docker 后端。如果 Docker Desktop 未启动，MCP 会返回结构化错误 docker_unavailable，提示用户启动 Docker。

运行

python -m foldseek_mcp.server

Artifacts

每次搜索会创建：

runs/jobs/<job_id>/
  query.pdb 或 query.fasta
  results.tsv
  results.json
  stdout.log
  stderr.log
  command.json
  manifest.json

manifest.json 记录 query hash、数据库 alias、数据库 path/prefix、FoldSeek 版本、命令参数、时间戳、状态和 artifact 路径。

常见错误

• docker_unavailable：Windows Docker 后端不可用，启动 Docker Desktop 后重试。
• docker_image_missing：本地没有 FoldSeek Docker 镜像，运行 quick_setup.sh 或 docker pull openeuler/foldseek:10-941cd33-oe2403sp3。
• auto_download_limit_exceeded：官方库体积超过自动下载阈值，需要显式 confirm_large=true。
• database_missing：官方数据库未下载或未挂载到 FOLDSEEK_MCP_DATABASE_ROOT。
• foldseek_nonzero_exit：FoldSeek 命令执行失败，查看该 job 的 stderr.log 和 command.json。