BioHarbor

BioHarbor

通过 AI Agent 运行真正的生物信息学分析。可靠、可复现，并在你自己的 GPU 上运行。

🧪 Alpha（v0.1）。 序列工具、同源搜索（MMseqs2）和结构预测 （ESMFold，已在 RTX 5090 上验证）均可使用。欢迎反馈——请参阅路线图。

BioHarbor 是一个 MCP 服务，让 Claude、Cursor 和 Codex 等 AI Agent 能够执行生物信息学工具，而不只是查询信息。Agent 提出分析需求后，BioHarbor 会验证输入、将任务安排到有空余资源的 GPU 上、准确记录运行方式，并返回简洁且易于 Agent 读取的摘要。

为什么还要开发另一个生物信息学 MCP 服务？

大多数生物信息学 MCP 服务封装的是数据库（UniProt、PDB、PubMed……）。你可以继续使用它们——BioHarbor 与它们互为补充，负责运行计算任务：

	数据库 MCP 服务	BioHarbor
运行实际分析（搜索、折叠、聚类）	❌	✅
在耗费 GPU 时间之前验证输入	❌	✅
感知 GPU 状态的队列，在共享 GPU 上合理调度	❌	✅
长时间运行的任务返回 job_id，而非超时	❌	✅
简洁摘要 + 磁盘上的文件（节省令牌）	❌	✅
记录每次运行的来源信息，并导出到工作流	❌	✅（计划支持导出）

快速开始

pip install bioharbor
bioharbor doctor             # checks Python, GPUs, workspace, tools
bioharbor setup-db swissprot # reference database for search_homologs (needs MMseqs2)
bioharbor install            # shows how to connect Claude, Cursor or Codex

如需在 GPU 上进行结构预测：pip install "bioharbor[esmfold]"——请参阅 docs/gpu-setup.md（RTX 50xx 需要 CUDA 12.8+ 版 PyTorch）。

连接你的 Agent

BioHarbor 是标准的 MCP 服务，因此可与任何 MCP 客户端配合使用。只需一条命令即可完成常见客户端的配置（命令会写入绝对路径，因此即使在虚拟环境之外，GUI 应用也能找到它）：

客户端	配置
Claude Code	claude mcp add bioharbor -- bioharbor serve
Claude Desktop	bioharbor install claude-desktop --write，然后重启应用
Cursor	bioharbor install cursor --write，或
Codex（命令行、IDE 扩展、应用）	codex mcp add bioharbor -- bioharbor serve，或 bioharbor install codex --write
Biomni（斯坦福大学的生物医学 Agent）	agent.add_mcp(...)；请参阅 docs/use-with-biomni.md
其他客户端	运行 bioharbor serve（stdio）或 bioharbor serve --http（Streamable HTTP）

长时间运行的工具会在约 20 秒内返回 job_id，而不会一直阻塞，因此不会超出任何客户端的工具调用超时时限。

分步配置指南（本地或 GPU 服务端，含故障排查）：docs/connect-clients.md。

然后可以向 Agent 提出类似这样的请求：

找出此重叠群中最长的 ORF，将其翻译，在 Swiss-Prot 中搜索同源序列并预测其结构。哪些区域的置信度较低？

不使用 Agent 也能使用

每个工具也都有对应的 CLI 命令，行为完全一致：

bioharbor tools list
bioharbor run find_orfs [email protected] min_aa=100 --brief   # human-readable
bioharbor run seq_stats sequence=MKTAYIAKQRQISFVKSHFSRQ
bioharbor jobs

共享 GPU 服务端

GPU 位于实验室服务端，而 Agent 运行在你的笔记本上？在服务端运行 BioHarbor，并通过 SSH 隧道连接；无需在服务端额外开放端口：

# on the GPU server
bioharbor serve --http --host 127.0.0.1 --port 8765
# on your laptop, then point Cursor / Codex / Claude Code at http://127.0.0.1:8765/mcp
ssh -N -L 8765:127.0.0.1:8765 you@gpu-server

⚠️ HTTP 模式目前尚无身份验证功能（已列入路线图），因此请将其限制在 127.0.0.1 上，并使用隧道。详情：docs/connect-clients.md。

工具

工具	功能	运行方式
seq_stats	验证序列；类型、长度、GC%、分子量	内联
translate_sequence	DNA/RNA → 蛋白质，六种阅读框中的一种或全部	内联
find_orfs	两条链上的最长 ORF，含坐标	作业
search_homologs	使用 MMseqs2 搜索本地数据库（蛋白质或翻译后的 DNA）	作业
predict_structure	ESMFold 结构、pLDDT 区间、低置信度区域、pTM	作业（GPU）
scrna_pipeline	scanpy 质控 → 聚类 → 标记物	计划中

运行时工具：get_job、list_jobs、cancel_job、describe_tool、list_databases、 gpu_status、read_file。

工作原理

Agent ──MCP──▶ validate input ─▶ inline? ──yes──▶ run ─┐
                                   │ no                  ├─▶ provenance + summary ─▶ Agent
                                   ▼                     │
                     job queue (SQLite) ─▶ GPU placement ┘
                     (waits politely for a GPU with free memory)

• 每次调用都是一个作业，会记录在 SQLite 中，其中包含参数、版本、耗时和所用 GPU， 输出文件旁还会附带一个 provenance.json。
• GPU 分配会读取实时可用显存和利用率（NVML 或 nvidia-smi），预留余量，并为已启动的作业预留显存，确保两个作业不会占用同一块 空间。其他用户的进程也会得到尊重。
• 快速失败：在作业排队前检查输入、二进制文件和数据库，因此错误请求不会排在繁忙的 GPU 后面等待。
• 结果适配 Agent：包含 summary、message、files、suggestions。错误会附带 hint 和 retryable 标记。

详情：docs/design.md。

编写工具

from pydantic import BaseModel, Field
from bioharbor.registry import Resources, RunContext, tool
from bioharbor.results import ToolResult


class FoldParams(BaseModel):
    sequence: str = Field(..., description="Protein sequence")


@tool(
    version="1",
    slow=True,
    resources=Resources(gpu=True, gpu_mem_gb=lambda p: 4 + len(p.sequence) / 100),
)
def predict_structure(params: FoldParams, ctx: RunContext) -> ToolResult:
    """Predict a protein structure with ESMFold."""
    ...
    return ToolResult(summary={"mean_plddt": 87.1}, files=["model.pdb"])

插件可以通过 bioharbor.tools entry-point group，在自己的软件包中提供工具。 请参阅 CONTRIBUTING.md。

许可证

Apache-2.0