# 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：

```text
afdb_uniprot50_minimal
```

对应 FoldSeek 官方数据库名：

```text
Alphafold/UniProt50-minimal
```

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

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

## 推荐部署方式

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

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

示例目录：

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

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

```text
/data/foldseek/databases/afdb_uniprot50_minimal/
```

然后设置：

```bash
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 应为：

```text
<DATABASE_ROOT>/afdb_uniprot50_minimal/afdb_uniprot50_minimal
```

## 下载官方数据库

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

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

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

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

## 安装

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

或：

```bash
bash quick_setup.sh
```

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

## 运行

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

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

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

```bash
FOLDSEEK_MCP_REMOTE_FALLBACK=false
```

## Artifacts

每次搜索会创建：

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