BioHarbor

BioHarbor

AI エージェントから本格的なバイオインフォマティクスを実行できます。信頼性と再現性を備え、ご自身の GPU 上で動作します。

🧪 アルファ版（v0.1）。 配列ツール、相同性検索（MMseqs2）、構造予測 （ESMFold、RTX 5090 で検証済み）が動作します。フィードバックをお待ちしています。ロードマップをご覧ください。

BioHarbor は、Claude、Cursor、Codex などの AI エージェントがバイオインフォマティクスツールを単に検索するのではなく、実行できるようにする MCP サーバーです。エージェントが解析を依頼すると、BioHarbor は入力を検証し、空きのある GPU にジョブを割り当て、実行方法を正確に記録して、エージェントが読み取りやすい簡潔な概要を返します。

なぜ、もうひとつバイオ 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 が必要です）。

エージェントを接続する

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（CLI、IDE 拡張機能、アプリ）	codex mcp add bioharbor -- bioharbor serve、または bioharbor install codex --write
Biomni（Stanford の生物医学エージェント）	agent.add_mcp(...)。詳しくはdocs/use-with-biomni.mdをご覧ください
その他	bioharbor serve（stdio）または bioharbor serve --http（Streamable HTTP）を実行

長時間実行されるツールは、処理をブロックせず、約 20 秒以内に job_id を返すため、すべてのクライアントでツール呼び出しのタイムアウトを回避できます。

ローカルまたは GPU サーバーでの手順ごとの設定（トラブルシューティングを含む）：docs/connect-clients.md。

次のようにエージェントに依頼してみてください。

このコンティグで最も長い ORF を見つけて翻訳し、Swiss-Prot で相同配列を検索して、その構造を予測してください。信頼度が低い領域はどこですか？

エージェントを使わずに利用する

すべてのツールは、同じ動作をする 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 があり、ノート PC でエージェントを使っていますか？サーバー上で 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 → タンパク質に翻訳します。1つまたは6つすべての読み枠に対応します	インライン
find_orfs	両方の鎖で最長のORFを、座標とともに検索します	ジョブ
search_homologs	MMseqs2でローカルDBを検索します（タンパク質、または翻訳したDNA）	ジョブ
predict_structure	ESMFoldによる構造、pLDDTの範囲、信頼度の低い領域、pTMを予測します	ジョブ（GPU）
scrna_pipeline	scanpyによるQC → クラスタリング → マーカー検出	計画中

ランタイムツール：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)

• すべての呼び出しはジョブとして実行されます。パラメーター、バージョン、実行時間、使用したGPUとともにSQLiteに記録され、出力の隣にprovenance.jsonが作成されます。
• GPUの割り当てでは、空きメモリーと使用率をリアルタイムで読み取り（NVMLまたはnvidia-smi）、余裕を確保します。また、開始したジョブのメモリーを予約するため、2つのジョブが同じ領域を取得することはありません。他のユーザーのプロセスも考慮されます。
• 迅速に失敗します。ジョブをキューに追加する前に入力、バイナリー、データベースを確認するため、不正なリクエストが使用中のGPUの後ろで待機することはありません。
• 結果はエージェント向けの形式です：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エントリーポイントグループを介して、独自のパッケージにツールを含めることができます。CONTRIBUTING.mdを参照してください。

ライセンス

Apache-2.0