protein-mcp-server

---

概述

通过一个统一入口查询实验蛋白质结构（PDB）和预测蛋白质结构（AlphaFold）。可跨 RCSB、AlphaFold DB、3D-Beacons、UniProt、InterPro 和 Foldseek 搜索、获取、比对和注释结构及其配体。无需 API 密钥。

工具

工具	描述
protein_search_structures	按文本、序列或生物体／方法／分辨率搜索实验和预测结构，并可选用筛选条件
protein_get_structure	获取实验结构、预测结构或最佳可用结构的元数据和坐标 URL
protein_find_similar	查找序列同源物（RCSB mmseqs2）或折叠同源物（Foldseek）
protein_track_ligands	解析配体的组分 ID、查找包含该配体的结构，或映射其结合位点
protein_compare_structures	使用 TM-align 或 jFATCAT 对齐结构，可与参考结构比对或比较所有结构对
protein_analyze_collection	以计数、直方图、时间线和交叉表的形式分析 PDB
protein_get_annotations	获取 UniProt 特征和变体，以及带有 GO 术语的 InterPro 结构域

资源

资源	描述
pdb://{entry_id}	PDB 条目的实验结构摘要
af://{uniprot}	UniProt 登录号对应的 AlphaFold DB 预测结构摘要

对于不展示资源的客户端，这两种资源也可通过 protein_get_structure 访问。

功能参考

protein_search_structures _工具

• 至少提供 query、sequence（mmseqs2 搜索；min_identity / max_evalue 仅与其搭配时生效）、organism、method 或 max_resolution 中的一项；content_type 可设为 experimental、predicted 或 all（默认值）；每页最多返回 100 条结果（默认 25 条），通过 limit / start 控制
• sequence 至少需要 10 个残基；空白字符会被移除，大小写会统一；无效序列会报错 invalid_sequence。每条结果都会标明其 source 和条目 id，后者可传递给其他工具
• 可选的 facets（method、organism、polymer_type、resolution、release_year、molecular_weight）会增加分类统计，每个维度最多包含 PROTEIN_FACET_BUCKET_CAP 个分组

---

protein_get_structure _工具

• source: experimental（默认值）接受 PDB 条目 ID，以及搜索返回的 AF_* / MA_* 计算模型 ID（这些结果的 source 为 predicted）；predicted 接受 UniProt 登录号，用于获取带有 pLDDT/PAE 的 AlphaFold 模型；best_available 接受 UniProt 登录号，并返回分辨率最高的实验结构，若无则返回最佳预测结构。每次调用最多处理 PROTEIN_MAX_BATCH_IDS 个 ID（默认 25 个）
• 无法解析的 ID 会列入 failed[]；超过上限而未处理的 ID 会显示在 requested / processed 中。如果没有任何 ID 可解析，调用会报错 all_failed；如果 ID 类型与 source 不匹配，则会报错 mixed_id_types。记录会包含现有文件的 coordinateUrls
• include_coords 会在大小限制内内嵌坐标文本；若批次超出限制，则返回 overflow 概要，可使用 sections: [ids] 再次调用

---

protein_find_similar _工具

• by: sequence 会根据 sequence、pdb_id 或 uniprot 运行同步的 RCSB mmseqs2 搜索，并按 max_evalue / min_identity 筛选；by: structure 会根据 pdb_id 或 uniprot 运行异步 Foldseek 搜索，除非 databases 另有指定，否则会搜索 pdb100 + afdb50。如果某字段仅被另一种模式读取，则会报错 mode_mismatched_field；每页最多返回 100 条结果（默认 25 条）
• 序列遵循与 protein_search_structures 相同的规则；如果提供了直接的 sequence，则优先于标识符。结果会标明其 source（结构搜索结果还会标明 database），并按 score 排序；响应会报告 totalCount 和 nextStart
• 如果结构任务在轮询预算用尽时仍在运行，则会返回 status: computing 和 ticketId；使用 ticket_id 再次调用即可继续查询。多链结构会通过 query 一次搜索一条链（从 0 开始，默认值为 0），总链数见 queryCount

---

protein_track_ligands _工具

• mode 可设为 find_ligand（query：名称或分子式）、structures_with_ligand（comp_id）或 binding_site（pdb_id，可选 comp_id）；缺少模式所需输入时会报错 missing_param。limit 范围为 1–100（默认 25）；后两种模式可通过 start 分页
• find_ligand 会返回组分 ID，以及分子式、分子量、SMILES 和 InChIKey，并按 depositionCount 排序；totalCount 和 candidatesConsidered 可显示候选池是否被截断；structures_with_ligand 会按分辨率从高到低列出条目
• binding_site 会返回带有接触距离的口袋残基，并同时使用标签命名空间（asymId、seqId）和作者命名空间（authAsymId、authSeqId）编号；仅适用于实验结构

protein_compare_structures _工具

• 2 个结构，最多为 PROTEIN_MAX_COMPARE_STRUCTURES（默认值为 10，最大值为 25），每个结构包含一个 pdb_id 和可选的标签命名空间 chain；method 可设为 tm-align（默认值）、fatcat-rigid 或 fatcat-flexible；reference 可设为 first（默认值）或 all_pairs；timeout_s（5–120）用于设置每对结构的轮询时限
• 每对结构的结果行包含 status（complete、computing、failed）、tmScore、rmsd、alignedResidues、modeledResidues 和 coverage；TM-score 根据 a 的长度进行归一化，因此调换一对结构的顺序会改变分数。如果上游提供了 similarityScore 和 sequenceSimilarity，结果中也会包含它们
• 正在计算的结构对会返回其任务 uuid；在 resume[] 中使用 { a, b, uuid } 再次调用，即可轮询该任务，而无需重新提交。如果 method 或结构对不匹配，则会分别以 resume_method_mismatch 或 resume_job_mismatch 失败

---

protein_analyze_collection _工具

• group_by 可设为 method、organism、polymer_type、resolution、release_year、molecular_weight 中的一个，也可选择其中两个不同维度进行交叉制表；可通过 query、organism、method、max_resolution 和 content_type 限定范围（默认值为 experimental）。interval 用于设置 resolution / molecular_weight 的数值分箱宽度，或设为 "year" 用于 release_year
• 返回 total 和 bucketsReturned；每个分桶包含 label 和 count（数值分箱还会添加 rangeFrom / rangeTo），每个维度都会报告 missingValueCount
• bucket_limit（1–500，默认值为 PROTEIN_FACET_BUCKET_CAP）分别限制每个维度的分桶数量；truncated 和 notice 会说明结果被截断的位置

---

protein_get_annotations _工具

• 可传入 uniprot 登录号，或通过 UniProt 交叉引用解析的 pdb_id（作者 chain 可用于选择一个登录号）；include 可设为 features、domains、variants 或 all（默认值）；limit 分别为每种类别分页（1–200，默认值为 50），并可通过独立的零起始索引 features_offset、variants_offset 和 domains_offset 设置偏移量（默认值均为 0）
• 返回 UniProt 特征和天然变异，以及包含 GO 术语的 InterPro 结构域；如果一个 PDB 条目映射到多个登录号，则使用编号最低的作者链，并在 ambiguity 中列出其余登录号
• 每个请求的类别都包含 featuresTotal、variantsTotal 或 domainsTotal；如果当前页之后还有记录，则会设置 truncated，并在 notice 中指出下一页的偏移量
• 错误类型包括 missing_identifier、invalid_accession、no_uniprot_mapping 或 chain_not_found

---

pdb://{entry_id} _资源

• entry_id 是 PDB 条目 ID（例如 4HHB）；返回 application/json，包含标题、方法、分辨率、生物体、配体，以及同时携带 authAsymIds 和 labelAsymIds 的 polymerEntities
• 数据与 source: experimental 的 protein_get_structure 相同

---

af://{uniprot} _资源

• uniprot 是 UniProt 登录号或 AlphaFold DB 条目 ID（例如 AF-P69905-F1）；返回 application/json，包含 meanPlddt、confidenceBuckets、cifUrl / pdbUrl / bcifUrl 和 modelVersion
• 数据与 source: predicted 的 protein_get_structure 相同

功能

基于 @cyanheads/mcp-ts-core：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

PDB / AlphaFold 专属功能：

• 搜索、获取和比较时，对实验结构（PDB）和预测结构（AlphaFold DB、ModelArchive、3D-Beacons 提供方）采用相同的处理方式
• RCSB、AlphaFold DB、3D-Beacons、UniProt、InterPro 和 Foldseek 均无需密钥
• 集合分析通过 RCSB 的 facet 引擎运行，并返回分桶计数，而非匹配条目
• Foldseek 和比对任务最多轮询 PROTEIN_ASYNC_POLL_TIMEOUT_MS（默认 30 s），随后返回恢复句柄（ticketId、每对一个 uuid），而不再阻塞
• 链命名空间保持分离：authAsymIds 用于 protein_get_annotations 的 chain，labelAsymIds 用于 protein_compare_structures 的 chain

适合 Agent 的输出：

• 来源信息：每条命中都会注明其 source（experimental / predicted）以及背后的引擎或数据库；protein_get_structure 和 protein_get_annotations 还会包含 attribution 块（参见上游数据许可）
• 优雅处理部分失败：failed[] 行和每对各自的 status 可避免单个错误 ID 或配对导致请求失败
• 分页与提示：分页工具会返回 totalCount 和 nextStart；超出末尾的 start 会在 notice 中单独标记，以区别于零匹配；所有提示都会合并到这一个 notice 中

快速开始

公共托管实例

可使用公共实例 https://protein.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "streamable-http",
      "url": "https://protein.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。无需 API 密钥。

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/protein-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/protein-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/protein-mcp-server:latest"]
    }
  }
}

要使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需账号或 API 密钥：所有上游服务均公开。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/protein-mcp-server.git

2. 进入目录：

cd protein-mcp-server

3. 安装依赖项：

bun install

4. 配置环境（可选）：

cp .env.example .env
# every variable has a working default

配置

所有变量均为可选项。

变量	描述	默认值
PROTEIN_ASYNC_POLL_TIMEOUT_MS	异步比对或 Foldseek 作业返回 computing 前的轮询时长预算（最小值为 1000）。	30000
PROTEIN_MAX_BATCH_IDS	每次 protein_get_structure 调用的最大 ID 数（1–100）。	25
PROTEIN_MAX_COMPARE_STRUCTURES	每次 protein_compare_structures 调用的最大结构数（2–25）。	10
PROTEIN_FACET_BUCKET_CAP	protein_search_structures 分面中每个维度的分桶数，以及 protein_analyze_collection 的默认值（1–500）。	50
PROTEIN_FANOUT_CONCURRENCY	按 ID 和按配对扇出时的最大上游并发请求数（1–16）。	5
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。覆盖服务端在代码中声明的 stateless 模式。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
OTEL_ENABLED	启用 OpenTelemetry。	false

每个上游服务的基础 URL 也可以指向镜像：RCSB_SEARCH_BASE_URL、RCSB_DATA_BASE_URL、RCSB_FILES_BASE_URL、RCSB_MODELS_BASE_URL、RCSB_ALIGNMENT_BASE_URL、BEACONS_BASE_URL、ALPHAFOLD_BASE_URL、MODELARCHIVE_BASE_URL、FOLDSEEK_BASE_URL、UNIPROT_BASE_URL、INTERPRO_BASE_URL。有关默认值和完整的可选覆盖项列表，请参见 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t protein-mcp-server .
docker run --rm -p 3010:3010 protein-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/protein-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口：注册工具和资源，并初始化提供方服务。
src/config	解析和验证服务专用环境变量，使用 Zod。
src/mcp-server/tools	工具定义（*.tool.ts）和共享架构（_schemas.ts）。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/services	上游客户端：rcsb/（搜索、数据、分面）、alphafold/、beacons/（3D-Beacons）、uniprot/（UniProt、InterPro、GO）、alignment/（RCSB 结构比对）、foldseek/，以及 shared/ 中的 HTTP、并发、标识符和来源标注辅助工具。
tests/	与 src/ 目录结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参见 CLAUDE.md/AGENTS.md。简要说明如下：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 在 src/mcp-server/*/definitions/index.ts 的汇总导出文件中导出新的定义，并在 src/index.ts 的 createApp() 数组中注册
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不编造缺失字段

上游数据许可

结构和注释数据来自各自采用不同许可证的公共数据库。protein_get_structure 和 protein_get_annotations 会返回一个 attribution 区块，其中列出为该响应提供数据的每个来源的许可证、引用信息和主页。CC BY 和 CC BY-SA 来源在再分发时需要署名；CC0 来源仅要求引用。

来源	提供的数据	许可证
RCSB PDB	protein_get_structure — 实验记录	CC0 1.0 Universal
AlphaFold DB	protein_get_structure — 预测模型	CC BY 4.0
ModelArchive	protein_get_structure — MA_* 计算模型	CC BY 4.0
SWISS-MODEL	protein_get_structure — best_available 模型	CC BY-SA 4.0
BFVD	protein_get_structure — best_available 模型	CC BY 4.0
UniProt	protein_get_annotations	CC BY 4.0
InterPro	protein_get_annotations — 结构域/家族数据	CC0 1.0 Universal
GO	protein_get_annotations — GO 术语	CC BY 4.0

best_available 模型通过 3D-Beacons 提供，因此区块会注明实际提供模型的服务商；没有人工整理条目的服务商会使用 See provider terms 作为备用说明，而不是猜测许可证。只有在提供数据时，InterPro 和 GO 才会分别列出署名信息。本表涵盖上游数据；服务本身的代码采用单独的许可证（参见许可证）。

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详见 LICENSE。