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、数据库目录、模型目录和运行目录。

Related MCP server: ESMfold MCP Server

默认数据库策略

默认官方数据库 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

Local-first remote fallback

Search tools use local-first, remote-fallback:

1. If the requested database is installed or mounted locally, MCP runs local foldseek easy-search.

2. If the local database is missing and FOLDSEEK_MCP_REMOTE_FALLBACK=true, MCP calls the official Foldseek Web API.

3. If the remote API also fails, MCP returns a structured error with a local database remediation hint.

Remote fallback configuration:

FOLDSEEK_MCP_REMOTE_FALLBACK=true
FOLDSEEK_MCP_REMOTE_BASE_URL=https://search.foldseek.com
FOLDSEEK_MCP_REMOTE_TIMEOUT_SECONDS=900
FOLDSEEK_MCP_REMOTE_POLL_INTERVAL_SECONDS=2.0

Remote alias mapping:

afdb_uniprot50_minimal -> afdb50
afdb_swissprot -> afdb-swissprot
afdb_proteome -> afdb-proteome
pdb -> pdb100
cath50 -> cath50

search.foldseek.com is suitable as a free fallback path, but it is a public web server API rather than a production SLA service. For reproducibility, compliance, or private structures, mount local databases and set:

FOLDSEEK_MCP_REMOTE_FALLBACK=false

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。