NVIDIA がホストする Evo2-7B Forward API を MCP (Model Context Protocol) Tools としてラップするサーバーで、Claude Code、Cursor、Codex などの Agent が自然言語で Evo2 を操作できるようにします：
Agent
↓
MCP Tool
↓
Evo2 MCP Server（本项目）
↓
NVIDIA Evo2-7B Forward API
↓
forward outputs → likelihood / variant scores
↓
AgentPOST https://health.api.nvidia.com/v1/biology/arc/evo2-7b/forward
Authorization: Bearer $NVIDIA_API_KEY5 つの MCP Tools を提供します：
Tool | 機能 |
| DNA sequence に対して Evo2-7B forward inference を実行し、指定した layer の出力統計を返します（または生の tensor を保存） |
| Evo2 モデルによる DNA sequence の model-based likelihood（total / mean / per-position）を計算します |
| 単一の nucleotide variant が Evo2 sequence likelihood に与える影響（Δ log-likelihood）を比較します |
| 複数の nucleotide variants を一括比較します（WT forward を 1 回再利用、並行処理は制限付き、自動重複排除） |
| FASTA 内の各 record をスコアリングします（ローカルパスは |
本プロジェクトは Bioinformatics MCP Tool Server であり、単純な HTTP API wrapper ではありません：
DNA sequence の自動検証 / 正規化（大文字化、空白除去、不正文字は明確にエラー報告）
公式セマンティクスに基づく likelihood 計算（byte-level tokenizer + causal shift、§17 参照）
出力の階層化設計（summary / raw / save）による MCP context の爆発防止
完全なエラー分類（400/401/403/404/408/413/422/429/5xx/timeout）+ retry/backoff
API Key は環境変数からのみ読み取り、ハードコードもログへの出力も一切なし
付属バッチスクリプト：scripts/score_fasta.py（FASTA 一括スコアリング + embedding 抽出、§18 参照）と scripts/analyze_run.py（クラスタリング / 分類 / 回帰のダウンストリーム解析、§19 参照）
Related MCP server: bio-mcp-evo2
Evo2（Arc Institute / NVIDIA）は DNA 基盤モデル（StripedHyena2 アーキテクチャ）で、7B 版は 32 層、Apache-2.0、トレーニングコンテキストは 1M bp に達します。NVIDIA はマネージド NIM サービスを提供しています：
Forward エンドポイント：POST https://health.api.nvidia.com/v1/biology/arc/evo2-7b/forward
リクエストボディ（公式 OpenAPI ForwardInputs）：
{ "sequence": "ACGTACGT...", "output_layers": ["output_layer"] }output_layers は 1〜100 個の layer 名をサポートします（例：output_layer、decoder.layers.24.mlp.linear_fc2、decoder.layers.3.self_attention、embedding、decoder.final_norm）。
レスポンスボディ（公式 OpenAPI ForwardOutputs）：{"data": "<base64 编码的 NPZ>", "elapsed_ms": <int>}；超大レスポンスは Content-Type: application/zip（生の NPZ バイト）で返される場合があります。
output_layer = 最終 logits、shape [seq_len, batch_size, 512]（512 は byte-level tokenizer の padded vocabulary size）。
⚠️ Deprecation の注意（2026-08-24 確認済み）：build.nvidia.com でホストされている
arc/evo2-7bエンドポイントは Deprecated とマークされています（ページに "This NIM Endpoint has been deprecated" と表示）。公式 NIM ドキュメント（docs.nvidia.com/nim/bionemo/evo2/latest/）に記載されている API はホスト型エンドポイントと完全に一致します。ホスト型エンドポイントが利用できない場合は、自社ホストの NIM コンテナに切り替え、EVO2_MCP_BASE_URLをhttp://localhost:8000/biology/arc/evo2に指定してください。
項目 | 結論 | 出典 |
レスポンス形式 | JSON | NVIDIA NIM endpoints ドキュメント + ホスト型 OpenAPI schema（ |
|
| 同上（"Final output/logits"） |
vocabulary サイズ | 512（padded）；byte-level tokenizer、1 bp = 1 token | NVIDIA ドキュメント + Arc/vortex |
A/C/G/T → logits index | A=65, C=67, T=84, G=71（ASCII バイト値） | NVIDIA ドキュメント原文 + |
BOS/EOS/offset | デフォルトで BOS なし（Arc | Arc |
likelihood 計算 |
| Arc |
特殊トークン | 出力で意味を持つのは A/C/G/T の 4 トークンのみ（NIM ドキュメント原文） | NVIDIA ドキュメント |
本物の key でホスト型 health.api.nvidia.com エンドポイントを調査したところ、ドキュメント記載の layer 名はホスト型エンドポイントでは使用できないことが判明しました：
リクエストした layer 名 | ホスト型 API の実際の動作 |
| ❌ |
| ❌ 422 |
| ✅ 最終 logits：NPZ key |
| ✅ |
| ✅ |
| ✅ |
対応策（実装済み・ライブ検証済み）：
EVO2_MCP_LOGITS_LAYER 設定を追加（デフォルト auto）：スコアリングツールは最初にドキュメント名の output_layer を試し、422 has no attribute（ホスト型）を受信した場合は自動的に unembed へ切り替えてキャッシュし、以降は再プローブしません。自社ホストの NIM 2.x コンテナでは 1 回で成功し、余分なリクエストはゼロです。
NPZ パーサーは裸の key（output_layer）と <name>.output（unembed.output）の両方の key 形式をサポートし、「最終次元 = 512」のヒューリスティックでフォールバックします。
422 エラー情報は、ホスト型で利用可能な属性名を案内するようになりました。
返された
seq_lenが入力配列の長さと一致しない場合（例：サーバー側で padding/BOS が追加された場合）、本サーバーは likelihood の計算を拒否し、raw 統計と明確な説明を返します。アライメントを推測することは絶対にありません。
https://build.nvidia.com/ を開き、右上の Get API Key をクリックします（NVIDIA アカウントへのログインが必要）。
key を作成します（nvapi-xxxxxxxx... の形式）。
環境変数に設定します。コード / 設定 / Git には書き込まないでください：
export NVIDIA_API_KEY="nvapi-xxxxxxxx"または .env.example をコピーして .env にし、値を入力します（.env は .gitignore で無視されます）。
# 推荐：pip / uv
pip install -e ".[dev]"
# 或
uv sync --extra dev
# 推荐（本项目自带）：pixi 项目本地环境
pixi install
pixi run test要件：Python >= 3.10（推奨 3.11+）。コア依存関係：mcp>=2.0、httpx>=0.27、numpy>=1.26、pydantic>=2.6、python-dotenv>=1.0。解析スクリプト（scripts/analyze_run.py）には追加で dev 依存関係：scikit-learn、pandas、matplotlib が必要です。
変数 | デフォルト | 説明 |
| なし（必須） | API Key。ここからのみ読み取ります |
|
| サービスアドレス（自社ホスト NIM の場合は変更） |
|
| HTTP 読み取りタイムアウト（秒） |
|
| 408/429/5xx の最大リトライ回数 |
|
| batch/FASTA の同時実行上限 |
| 空 | FASTA の読み取りを許可するディレクトリ（ |
|
|
|
|
|
|
|
| 配列長のハード上限 |
|
|
|
|
| per-position リストの返却上限（超過時は先頭と末尾を取得） |
|
| スコアリング用の logits layer 名： |
# 三种方式等价
python -m evo2_mcp
evo2-mcp
uv run evo2-mcp # 用 uv 管理的项目环境
# pixi 环境：
pixi run evo2-mcpサーバーは stdio 経由で MCP クライアントと通信します。正常に起動すると出力はありません（MCP ハンドシェイク待ち）。
.mcp.json）{
"mcpServers": {
"evo2": {
"command": "uv",
"args": ["run", "evo2-mcp"],
"env": {
"NVIDIA_API_KEY": "${NVIDIA_API_KEY}"
}
}
}
}注意：
${NVIDIA_API_KEY}がクライアントによって展開されるかどうかはクライアント実装に依存します。最も確実な方法は、実際の key を直接入力することです：
{
"mcpServers": {
"evo2": {
"command": "uv",
"args": ["run", "evo2-mcp"],
"env": {
"NVIDIA_API_KEY": "YOUR_API_KEY"
}
}
}
}ただし、実際の key を含む .mcp.json を Git にコミットしないでください（そのファイルを .gitignore に追加するか、環境変数 / シークレット管理ツールで注入してください）。また、env を渡さず、サーバープロセス自身に環境または .env から NVIDIA_API_KEY を読み取らせることもできます：
{
"mcpServers": {
"evo2": {
"command": "uv",
"args": ["run", "evo2-mcp"]
}
}
}~/.cursor/mcp.json またはプロジェクトの .cursor/mcp.json）{
"mcpServers": {
"evo2": {
"command": "uv",
"args": ["run", "evo2-mcp"],
"env": { "NVIDIA_API_KEY": "YOUR_API_KEY" }
}
}
}~/.codex/config.toml）[mcp_servers.evo2]
command = "uv"
args = ["run", "evo2-mcp"]
env = { "NVIDIA_API_KEY" = "YOUR_API_KEY" }{
"mcpServers": {
"evo2": {
"command": "uv",
"args": ["run", "evo2-mcp"],
"env": {
"EVO2_MCP_BASE_URL": "http://localhost:8000/biology/arc/evo2"
}
}
}
}evo2_forward(sequence, output_layers=["output_layer"], mode="summary", save_path=None)DNA sequence に対して Evo2-7B forward inference を実行します。mode：
"summary"（デフォルト）：各 layer の shape / dtype / min / max / mean / std を返し、context に安全です；
"save"：生の tensor を .npz（output/evo2_forward_<时间戳>.npz）として保存し、パスを返します；
"raw"：完全な tensor をインラインで返します（要素総数が EVO2_MCP_RAW_INLINE_MAX（デフォルト 4096）以下の場合のみ。context の爆発を防ぎます）。
layer 名の注意：ホスト型
health.api.nvidia.comエンドポイントが受け付けるのはモデル属性名です（logits はunembed、ほかにembedding_layer、norm、blocks.N.mlp）。ドキュメント名のoutput_layer/decoder.layers.N.*は自社ホストの NIM 2.x コンテナでのみ使用できます。evo2_score/evo2_variant_score/evo2_batch_score/evo2_score_fastaは自動プローブするため手動指定は不要です。直接evo2_forwardを呼び出す場合のみ、実際のエンドポイントに合わせて名前を選択する必要があります。
evo2_score(sequence, include_per_position=False)Evo2 による配列の likelihood を計算します：
{
"sequence_length": 123,
"total_log_likelihood": -123.45,
"mean_log_likelihood": -1.2345,
"scored_positions": 122,
"per_position_log_likelihood": null,
"method_notes": "...",
"disclaimer": "..."
}セマンティクス（Arc 公式実装と一致）：logits[i] は位置 i+1 の塩基を予測し、完全な 512 vocab 上で log-softmax を適用した後、対象の塩基のバイトインデックスを取得します。position 0 はスコアリングに含まれないため、scored_positions = length - 1 となり、mean はこの N-1 個の値の平均です。per_position_log_likelihood[k] は配列の 0-based 位置 k+1（つまり 1-based 位置 k+2）に対応します。API が返した seq_len を配列とアライメントできない場合は、結果を偽造せず、raw 統計と明確な説明を返します：
Likelihood calculation is not supported until the API output format is verified.evo2_variant_score(sequence, position, ref, alt, coordinate="1-based", include_per_position=False){
"position": 100,
"ref": "A",
"alt": "G",
"wildtype_log_likelihood": -500.1,
"mutant_log_likelihood": -500.5,
"delta_log_likelihood": -0.4,
"interpretation": "The mutant sequence is less likely than the wildtype under Evo2-7B ... (NOT a clinical pathogenicity call)"
}検証チェーン：position 範囲 → coordinate 換算 → ref は配列の該当位置と一致する必要あり → ref≠alt → 1-based 位置 1（0-based 0）はスコアリング不可（causal LM は最初の token に確率を割り当てられない）→ 明確なエラー報告。
evo2_batch_score(sequence, variants, coordinate="1-based"){
"sequence_length": 300,
"wildtype_log_likelihood": -1200.0,
"variants": [
{ "position": 100, "ref": "A", "alt": "G", "delta_log_likelihood": -0.42 },
{ "position": 200, "ref": "C", "alt": "T", "delta_log_likelihood": 0.13 }
]
}WT forward は 1 回だけ計算され、すべての variant で再利用されます；
同じ (position, alt) の mutant は forward を 1 回だけ実行します（memoize）；
同時実行は EVO2_MCP_MAX_CONCURRENCY で制限されます（デフォルト 2。NVIDIA の rate limit を尊重）；
個々の variant の失敗は batch 全体に影響しません（各エントリに error を返します）。
evo2_score_fasta(fasta_path=None, fasta_text=None)>sequence_1
ACGTACGT...
>sequence_2
TTGGCCAA...fasta_text：インライン FASTA（デフォルトで利用可能。サイズ / レコード数の上限あり）；
fasta_path：ファイルが EVO2_MCP_ALLOWED_DIRS 内にある場合のみ読み取りを許可し、それ以外は明確に拒否します；
各レコードの total_log_likelihood / mean_log_likelihood を返します。単一レコードのエラーは他に影響しません。
{
"sequence": "acgtACGT acgt", // 小写 + 空白自动处理
"output_layers": ["output_layer"],
"mode": "summary"
}戻り値：
{
"sequence_length": 12,
"requested_output_layers": ["output_layer"],
"returned_layers": ["output_layer"],
"layer_stats": [
{ "name": "output_layer", "shape": [12, 1, 512], "dtype": "float32",
"size": 6144, "min": -3.21, "max": 4.02, "mean": 0.01, "std": 0.98 }
],
"api": { "elapsed_ms": 87 }
}Agent が完全な logits を必要とする場合：
{ "sequence": "ACGT...", "mode": "save" }{
"saved": true,
"path": "/abs/path/output/evo2_forward_20260824_153000.npz",
"bytes_on_disk": 24576,
"layer_stats": [...]
}{
"fasta_text": ">geneA\nACGTACGTACGT\n>geneB\nTTGGCCAATTGG"
}（または "fasta_path": "/data/genomes/genes.fa"。EVO2_MCP_ALLOWED_DIRS=/data/genomes の設定が必要）
大量の FASTA（ディレクトリ全体の enhancer / promoter など）のスコアリング + embedding 抽出には、scripts/score_fasta.py（§18 参照）を使用します——実行ごとに独立した run フォルダ（scores.csv + embeddings.npz）を出力します。
{
"sequence": "ACGTACGTACGTACGTACGT",
"position": 10,
"ref": "A",
"alt": "G"
}{
"sequence": "ACGTACGTACGTACGTACGT",
"variants": [
{ "position": 10, "ref": "A", "alt": "G" },
{ "position": 12, "ref": "T", "alt": "C" },
{ "position": 14, "ref": "A", "alt": "T" }
]
}典型的な Agent ワークフロー（「配列上のすべての SNP を分析し、Evo2 score の変化が最も大きい上位 20 個を探す」に対応）：
读取输入 → 解析 DNA / VCF → 生成 WT / mutant → evo2_batch_score
→ 按 |delta_log_likelihood| 排序 → 取前 20 → 保存 CSV → 解释结果HTTP | 意味 | 本サーバーの動作 |
400 | Bad Request（不正な配列などを含む） | 直接エラーを返し、レスポンス要約を添付 |
401 | API Key が無効 | 直接エラーを返し、 |
403 | 権限なし（ホスト型エンドポイントの非推奨化など） | 直接エラーを返し、考えられる原因を提示 |
404 | パスが存在しない | 直接エラーを返し、 |
408 | サーバータイムアウト | 有限回数のリトライ（backoff）後にエラーを返す |
413 | Payload が大きすぎる | 直接エラーを返し、配列または layer 数を減らすよう促す |
422 | パラメータ検証失敗 | 直接エラーを返し、詳細を添付 |
429 | Rate limit | リトライ + exponential backoff（ |
5xx | NVIDIA サーバーエラー | 有限回数のリトライ後にエラーを返す |
timeout | リクエストタイムアウト（ | 明確なエラー： |
すべてのエラーは MCP 経由で構造化 JSON として返されます：{"error": "Evo2APIError", "message": "..."}。evo2_batch_score では単一アイテムの失敗は {"error": ..., "status": ...} を返し、バッチ全体は中断しません。
NVIDIA ホスト型 NIM には rate limit があります。設計上の対策：
EVO2_MCP_MAX_CONCURRENCY（デフォルト 2）で並行性を制限；
429 → exponential backoff（1 秒、2 秒、4 秒、8 秒、16 秒…、上限 30 秒 + ジッター；Retry-After がある場合はそれを優先するが上限 60 秒）；
リトライ上限 EVO2_MCP_MAX_RETRIES（デフォルト 4）、無限にリトライしない；
batch 内の WT は一度だけ計算し、同一 mutant は重複排除してリクエスト数を削減。
API Key：NVIDIA_API_KEY 環境変数（または .env）からのみ読み取る；コード内にハードコードされた key は一切ない；ログには URL、配列長、layer 名のみ記録し、配列内容と key は記録しない；エラーメッセージにはレスポンス先頭 500 文字の要約のみ含める。
配列のプライバシー：すべてのログ/エラーには preview のみ含める（例：ACGT...GCTA (len=12345)）。
パスサンドボックス：
FASTA 読み取りは EVO2_MCP_ALLOWED_DIRS 内のみ；未設定の場合はすべてのローカルパスを拒否；
mode="save" の save_path は EVO2_MCP_OUTPUT_DIR 内にある必要がある；
.gitignore には .env、*.env、output/、*.npz が含まれている。
N 塩基：デフォルトで拒否し、明確なエラーを返す（Evo2 モデルは曖昧な塩基では評価されておらず、ドキュメントでは A/C/G/T のみ意味があると保証されている）。どうしても N を透過させる必要がある場合は、EVO2_MCP_ALLOW_AMBIGUOUS=1 で起動する —— これは明示的な選択であり、黙って破棄するものではない。
Don't execute：本サーバーは一切の shell 実行を行わない；Agent は FASTA/配列入力によって制限付き HTTP リクエストのみをトリガーできる。
Evo2 score は model-based sequence likelihood change であり、実験的証拠でも臨床的な病原性診断でもない。
delta_log_likelihood < 0 は「変異体配列がモデル下でより可能性が低い」としか解釈できず、「病原性」とは解釈できない。
pathogenicity を論じるには downstream での検証（実験、集団頻度、ClinVar アノテーション、タンパク質構造への影響など）が必要。
各 Tool の description には以下の免責事項が含まれる（MCP クライアントから閲覧可能）：
This is a DNA foundation model inference tool. It does not provide clinical
diagnosis. Model scores should not be interpreted as pathogenicity labels
without additional validation.NVIDIA NIM for Evo 2 — Endpoints：https://docs.nvidia.com/nim/bionemo/evo2/latest/endpoints.html
NVIDIA NIM for Evo 2 — Quickstart：https://docs.nvidia.com/nim/bionemo/evo2/latest/quickstart-guide.html
NVIDIA ホスト型 API リファレンス（arc/evo2-7b-forward OpenAPI schema）：https://docs.api.nvidia.com/nim/reference/arc-evo2-7b-infer
ホスト型エンドポイント実測（2026-08-24、実 key）：output_layer は 422 StripedHyena has no attribute 'output_layer' を返す；unembed は logits を返す（NPZ key unembed.output、shape (1, seq, 512)、float64）—— そのためスコアリングツールはデフォルトで EVO2_MCP_LOGITS_LAYER=auto により自動検出する
バッチ実測（2026-08-25、実 key、3800+ 件の K562 enhancer/promoter）：
配列が > ~100 kb の場合、ホスト側が 422 を返す（PyTorch の canUse32BitIndexMath 制限）—— バッチ実行では --skip-longer-than 100000 を使用；
並行時の layer 名自動検出の競合状態を修正済み（forward_logits はローカル変数で試行名を記録）し、回帰テストを追加；
embedding 抽出：norm/embedding_layer/blocks.N はいずれも使用可能、shape (1, seq, 4096) float64（mean-pool 後 4096 次元）。
Arc Institute Evo2 リポジトリ（scoring.py、models.py）：https://github.com/ArcInstitute/evo2
vortex CharLevelTokenizer（Evo2 公式 tokenizer 実装）：PyPI vtx 1.1.0 のソース vortex/model/tokenizer.py
Evo2 モデルカード：https://huggingface.co/ArcInstitute/evo2_7b
NVIDIA が API を変更した場合は、公式の最新ドキュメントを基準にしてください；EVO2_MCP_BASE_URL でいつでも切り替えられます。
MCP Tools は Agent の対話的呼び出しに適しています；大規模 FASTA スコアリングには付属スクリプト scripts/score_fasta.py を使用します（実 API で 3800+ 件の K562 enhancer/promoter により検証済み）。
実行のたびにタイムスタンプ付きの独立したフォルダを自動作成：
output/run_20260825_104403/
├── scores.csv # 每序列一行：id, header, length, total/mean LL, ...
│ # + embedding_key（与 embeddings.npz 的 record_ids 对齐）
└── embeddings.npz # embeddings: (n, 4096) float32 mean-pooled 矩阵
# record_ids: 与矩阵行一一对应的键（来源__序列id）# 小样本（指定 id）
.pixi/envs/dev/bin/python scripts/score_fasta.py \
--fasta /path/cis/enhancers.fa /path/cis/promoters.fa \
--ids K562_TE_629,K562_MPT_6842 --allow-ambiguous
# 全量（跳过 >100kb —— 托管端对该长度返回 422；保留原始 embedding）
.pixi/envs/dev/bin/python scripts/score_fasta.py \
--fasta /path/cis/enhancers.fa /path/cis/promoters.fa \
/path/trans/enhancers.fa /path/trans/promoters.fa \
--skip-longer-than 100000 --allow-ambiguous \
--embedding-layer norm --keep-raw-embeddings主要パラメータ：
パラメータ | 説明 |
| どの layer の embedding を抽出するか（デフォルト |
| 各配列の生の位置別 embedding |
| この長さを超える配列をスキップ（ホスト型 API の制限、§17 参照） |
| N 塩基の透過を許可（N を含む 5 件の配列も通常通り実行し、caveat 警告付き） |
| 並行数（デフォルト 2、rate limit を尊重） |
| デフォルトの run フォルダ構成を上書き |
効率設計：各配列につきリクエストは 1 回だけ送信（output_layers=["unembed","norm"] で logits と embedding を同時取得）；logits の layer 名は実行全体で一度だけ検出；同時実行数はセマフォで制限。
embeddings.npz は mean-pooled された配列表現（各配列につき 1 つの 4096 次元ベクトル）で、クラスタリング、分類、回帰に直接適しています。読み込みと関連付け：
import csv, numpy as np
run = "output/run_20260825_104403"
rows = list(csv.DictReader(open(f"{run}/scores.csv")))
d = np.load(f"{run}/embeddings.npz", allow_pickle=True)
X = d["embeddings"] # (n, 4096) float32
ids = [str(x) for x in d["record_ids"]] # 与 X 行一一对应
key_to_row = {r["embedding_key"]: r for r in rows if r.get("embedding_key")}
scores = [key_to_row[k] for k in ids] # scores[i] ↔ X[i]ワンクリックで完全な分析を実行（KMeans クラスタリング、enhancer-vs-promoter 分類、embedding→likelihood 回帰、PCA プロット）：
.pixi/envs/dev/bin/python scripts/analyze_run.py output/run_20260825_104403 --k 3analysis_<run>.npz（結合された X + keys）と analysis_<run>.png を出力。分析のポイント：
4096 次元ベクトルは類似度/クラスタリングの前に単位化する（スクリプトで実施済み）；
サンプル数が少ない場合は分類/回帰を自動スキップ（保護閾値 ≥6 件）；全 3806 件を実行完了して初めてこれらの分析に統計的意味がある；
キー cis_enhancers__xxx → カテゴリ enhancers、領域 cis；trans_* も同様（parse_source でラベル次元を変更し cis-vs-trans 分類が可能）。
pixi install # 或 pip install -e ".[dev]"
pixi run test # 运行 pytest（全部 mock，不调用真实 API）オフラインテスト 91 passed / 4 skipped（skip = live ゲート）。カバー：配列検証、大文字小文字/空白の正規化、不正文字、API key 欠如、forward リクエスト構築、401/408/429/5xx/timeout、layer 名の自動検出（並行競合の回帰を含む）、variant 検証、variant/batch スコアリングの数学的正しさ（Arc のセマンティクスに対して独立に再計算）、NPZ デコード（JSON base64 / zip / 旧版 JSON tensor / <layer>.output key）、FASTA サンドボックス、MCP session 統合、スクリプトの純関数（pooling/キー名）など。
実 API スモークテスト（実 key が必要、デフォルトでスキップ）。key は .env から自動読み取り（Settings.from_env() がロード済み）：
EVO2_MCP_RUN_LIVE=1 .pixi/envs/dev/bin/python -m pytest tests/test_live_api.py -v -slive テストは実際に NVIDIA エンドポイントへリクエストし、以下を検証：logits layer の自動検出（unembed）、実際の NPZ 解析（(1, seq, 512) float64）、evo2_score が生の logits から手動で再計算した値と一致すること、variant score。
.
├── pyproject.toml
├── README.md
├── .env.example
├── .gitignore
├── src/evo2_mcp/
│ ├── __main__.py # python -m evo2_mcp 入口
│ ├── config.py # 环境变量配置
│ ├── sequence.py # DNA 校验/归一化
│ ├── api_client.py # HTTP 客户端（retry/backoff/错误分类/响应解码 + layer 自动探测）
│ ├── forward_output.py# NPZ 解码 + likelihood 计算 + embedding 提取
│ ├── fasta.py # FASTA 解析 + 读取沙箱
│ ├── tools.py # 5 个 Tool 的实现
│ └── server.py # MCP server（stdio）
├── scripts/
│ ├── score_fasta.py # 批量 FASTA 评分 + embedding 提取（每次运行独立 run 文件夹）
│ └── analyze_run.py # 下游分析：加载/关联 → 聚类/分类/回归 + PCA 图
├── tests/ # pytest（全 mock，91 用例）+ 可选 live test
└── output/ # mode="save" 的 .npz 输出 + run_*/ 运行结果（git 忽略）Score many single-nucleotide variants against one wildtype sequence. The WT forward pass is computed exactly once and reused; identical (position, alt) mutants are forwarded once; mutant requests run with bounded concurrency (EVO2_MCP_MAX_CONCURRENCY, default 2) to respect NVIDIA rate limits, and per-variant API errors are reported per-variant. Use for saturation-mutagenesis-style analyses. This is a DNA foundation model inference tool. It does not provide clinical diagnosis. Model scores should not be interpreted as pathogenicity labels without additional validation.
| Name | Required | Description | Default |
|---|---|---|---|
| sequence | Yes | Wildtype DNA sequence (>= 2 bp). | |
| variants | Yes | List of {position, ref, alt} dicts (1-based positions). | |
| coordinate | No | 1-based |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure, and it excels. It reveals the caching behavior (WT pass computed once, identical mutants forwarded once), concurrency limits (EVO2_MCP_MAX_CONCURRENCY, default 2) to respect NVIDIA rate limits, and per-variant error reporting. It also adds crucial disclaimers (not clinical diagnosis, not pathogenicity labels). This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place. It leads with the core purpose, then efficiently packs performance details, error handling, and disclaimers. It is slightly longer than minimal but avoids fluff. The structure is logical: purpose → efficiency → safety/limitations. This is good, though a bit dense; a 4 feels right.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch scoring tool with no output schema, the description covers the execution semantics, concurrency, error reporting, and clinical disclaimer. However, it omits any description of the return format or how results are structured (even per-variant errors are mentioned but not the shape). Given the complexity and no annotations, the absence of output details leaves a small but notable gap, so it stops short of a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (sequence and variants have descriptions; coordinate has an enum with a default). The description does not add parameter-level meaning beyond what the schema already provides—it merely restates the variants structure and coordinate default implicitly. It does clarify the 'many' scope, but that is more behavioral than parameter-specific. Baseline 3 is appropriate since the schema covers most parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a strong, specific verb-resource pair: 'Score many single-nucleotide variants against one wildtype sequence.' It clearly states the batch scope and distinguishes itself from single-variant tools by emphasizing 'many' and 'batch.' It also specifies the analysis type (saturation-mutagenesis), which orients the agent on the intended use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool provides a clear when-to-use directive: 'Use for saturation-mutagenesis-style analyses.' It also implies batching by explaining the reuse of the WT forward pass and bounded concurrency. However, it does not explicitly name alternative sibling tools for single-variant scoring, so the agent must infer those from the 'many' qualifier. This is solid but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a forward pass of Evo2-7B on a DNA sequence (forward inference) and return summary statistics — or raw tensors — for the requested model layers (final logits, attention, MLP or embedding outputs). Use this when you need layer outputs for analysis, not just a scalar score. Modes: 'summary' (shape/dtype/min/max/mean/std per layer — default, context-safe), 'save' (write the .npz under the server's output dir and return the path), 'raw' (inline small tensors only; large tensors must be saved to a file instead). This is a DNA foundation model inference tool. It does not provide clinical diagnosis. Model scores should not be interpreted as pathogenicity labels without additional validation.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | summary: per-layer shape/dtype/min/max/mean/std only. raw: inline the tensors as nested lists (small only, capped). save: always write an .npz file in the output dir and return its path. | summary |
| sequence | Yes | DNA sequence over {A,C,G,T}. Lowercase and whitespace are normalised. IUPAC ambiguity codes (N, R, Y, ...) are rejected unless the server was started with EVO2_MCP_ALLOW_AMBIGUOUS=1 (N only). | |
| save_path | No | Optional filename for the saved NPZ (implies mode='save'). Must resolve inside the server's output directory (EVO2_MCP_OUTPUT_DIR, default ./output). If omitted, a timestamped file is used. | |
| output_layers | No | Evo2 layer names. The final logits layer is 'output_layer' on self-hosted NIM 2.x containers, but the hosted health.api.nvidia.com endpoint uses model attribute names — use 'unembed' for final logits (also 'embedding_layer', 'norm', 'blocks.N.mlp'). Scoring tools auto-detect this. See https://docs.nvidia.com/nim/bionemo/evo2/latest/endpoints.html |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full responsibility. It discloses mode behavior (summary is context-safe, raw only for small tensors, save writes to server output dir), ambiguity-code handling with an environment flag, endpoint-dependent layer naming, and the clinical limitation. This is exceptionally transparent for a complex inference tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose, then organizes modes and constraints in a logical flow. Every sentence provides distinct information—no filler. Dense but efficient, appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters, no output schema, and no annotations, this description is remarkably complete. It covers return types, mode constraints, output directory rules, ambiguity handling, endpoint differences, and disclaimers—everything an agent needs to invoke it correctly without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover all parameters (100% coverage), but the description adds significant value: it explains the endpoint-specific layer names (output_layer vs unembed), the save_mode implication of save_path, and the ambiguity environment flag. This goes beyond the schema to make parameter usage clearer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Run a forward pass of Evo2-7B') and explicitly contrasts with scoring tools: 'Use this when you need layer outputs for analysis, not just a scalar score.' This clearly distinguishes from sibling scoring tools and conveys the tool's core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool versus alternatives ('not just a scalar score'), and details the three modes with their intended contexts. It also adds a clinical disclaimer ('does not provide clinical diagnosis'), guiding appropriate usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute the model-based log-likelihood of a DNA sequence under Evo2-7B (nucleotide-level log-likelihood via the byte-level tokenizer). Returns total_log_likelihood, mean_log_likelihood, scored_positions and optionally per_position_log_likelihood (position 0 is unscored by the causal shift; value k corresponds to 0-based position k+1). Use for sequence-level probability estimates. This is a DNA foundation model inference tool. It does not provide clinical diagnosis. Model scores should not be interpreted as pathogenicity labels without additional validation.
| Name | Required | Description | Default |
|---|---|---|---|
| sequence | Yes | DNA sequence over {A,C,G,T} (>= 2 bp). | |
| include_per_position | No | Return the per-position log-likelihood list (default False to keep the response small; long lists are truncated to head+tail). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses output structure, the causal shift causing position 0 to be unscored, optional per-position output, and explicitly warns against clinical diagnosis and pathogenicity interpretation. This is thorough and transparent for a model-scoring tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a few sentences but each adds necessary context: purpose, output details, usage, and disclaimers. It is not overly verbose and front-loads the core function. Slightly dense with parentheticals, but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description fully explains the returned fields (total_log_likelihood, mean_log_likelihood, scored_positions, optional per_position_log_likelihood) and the positional convention. It also addresses interpretation caveats. For a single-sequence inference tool, nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are well-documented in the schema. The description adds little beyond the schema; it does explain the per-position output semantics within the overall description, but that is not parameter-specific. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool computes model-based log-likelihood of a DNA sequence under Evo2-7B, with specific output fields. It does not explicitly differentiate from siblings like evo2_batch_score or evo2_variant_score, but the single-sequence focus is implied by the parameter list and usage text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear context: 'Use for sequence-level probability estimates' and notes this is a DNA foundation model inference tool. It does not explicitly state when not to use it or mention alternatives, but the use case is specified clearly enough without being misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score every record in a FASTA source under Evo2-7B. Provide EITHER fasta_text (inline FASTA) OR fasta_path (local file — only allowed when its directory is listed in EVO2_MCP_ALLOWED_DIRS; the server refuses arbitrary paths). Returns per-record total/mean log-likelihood; per-record errors are reported inline. This is a DNA foundation model inference tool. It does not provide clinical diagnosis. Model scores should not be interpreted as pathogenicity labels without additional validation.
| Name | Required | Description | Default |
|---|---|---|---|
| fasta_path | No | Local FASTA path (sandboxed by EVO2_MCP_ALLOWED_DIRS). | |
| fasta_text | No | Inline FASTA text, e.g. '>seq1\nACGT...'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full disclosure burden. It states the output type (per-record total/mean log-likelihood), error reporting behavior, and importantly warns that scores are not clinical diagnostics. It does not explicitly state read-only behavior, but for an inference tool this is implied and not a significant gap given the safety disclaimers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet covers all essential aspects: purpose, input options, constraints, output, and limitations. The main action is front-loaded, and every sentence serves a purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains the return values clearly. It covers input constraints and error reporting, but does not specify the exact response format (e.g., whether it's a JSON object or text). For a tool with only two parameters, this is a minor gap, so a 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter comments, so the baseline is 3. The description adds value by clarifying the meaning of the output (per-record scores) which is not in the schema, and reinforces the sandboxing constraint for fasta_path, going beyond the schema's own description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Score every record'), the specific resource (FASTA source), and the model (Evo2-7B). It also distinguishes itself from siblings by focusing on FASTA input, making it easily separable from evo2_score or evo2_variant_score without needing to infer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use the tool: 'Provide EITHER fasta_text OR fasta_path', with the path restriction clearly stated. It also provides cautionary guidance on interpreting results, which helps agents avoid misuse. The description mentions no alternatives but the either/or and sandboxing rules effectively guide usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare a single-nucleotide variant: the Evo2-7B log-likelihood of the wildtype sequence vs the mutant sequence. Returns delta_log_likelihood (mutant − wildtype); a negative value means the mutant sequence is LESS likely under the model. Positions are 1-based by default (VCF-style). Variants at position 1 are rejected because a causal LM cannot score the first base. This is a DNA foundation model inference tool. It does not provide clinical diagnosis. Model scores should not be interpreted as pathogenicity labels without additional validation.
| Name | Required | Description | Default |
|---|---|---|---|
| alt | Yes | Alternate allele (single A/C/G/T). | |
| ref | Yes | Reference allele (single A/C/G/T). | |
| position | Yes | Variant position, 1-based by default. | |
| sequence | Yes | Wildtype DNA sequence context (>= 2 bp). | |
| coordinate | No | Coordinate system of `position`. | 1-based |
| include_per_position | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it explains the output meaning (negative delta indicates lower likelihood), the reasoning behind rejecting position 1 (causal LM limitation), coordinate system default, and important limitations (not clinical, not pathogenicity). This goes well beyond a basic verb+object statement and gives the agent a clear model of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with no redundancy. It front-loads the core purpose and output interpretation, then adds constraints and domain caveats. Every sentence carries meaningful information, and the structure makes it easy for an agent to quickly grasp the tool's role.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema or annotations, the description covers the essential aspects: what it computes, how to interpret the result, coordinate system, positional restriction, and domain limitations. It does not explicitly describe the effect of include_per_position (though schema notes default false), but that is a minor gap. Overall, an agent has sufficient context to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (83%), so the baseline is 3. The description adds semantic value by explaining the output delta and the coordinate system, but it does not elaborate on parameters that the schema already documents. It reinforces the 'sequence' as wildtype context, which is consistent with schema descriptions, but adds no new parameter-level nuance beyond the position-1 rejection rule.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Compare a single-nucleotide variant') and defines the exact output ('delta_log_likelihood (mutant − wildtype)'). It clearly distinguishes the tool from siblings by focusing on variant comparison rather than generic scoring or batch operations. The inclusion of the model name (Evo2-7B) and the caveat about clinical diagnosis further clarify its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (for single-nucleotide variant scoring) but does not explicitly compare with siblings like evo2_score or evo2_batch_score. It does provide usage constraints (1-based positions, rejection of position 1, not for clinical diagnosis) that help an agent decide applicability, yet it lacks an explicit 'use when' versus 'use instead' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0evo2_batch_scoreevo2_forwardevo2_scoreevo2_score_fastaevo2_variant_scoreScored across 5 tools
Each tool has a clearly distinct purpose: forward pass for layer tensors, sequence log-likelihood scoring, single variant effect, batch variant scoring, and FASTA-based scoring. The descriptions clearly delineate usage scenarios, reducing misselection risk.
All tools follow the evo2_ verb-noun pattern (forward, score, variant_score, batch_score, score_fasta). While the second part varies, the consistent prefix and action-oriented naming make the set predictable and easy to navigate.
Five tools is well-scoped for a focused DNA model inference server. Each tool adds a distinct capability without redundancy, covering single sequence, variant, batch, and file-based scoring.
The surface covers the core workflows for an Evo2 model: sequence scoring, variant effect analysis (single and batch), FASTA batch processing, and forward pass tensor extraction. No obvious dead ends or missing critical operations for the stated purpose.
Protein analysis: ESM-2/ESMC embeddings, mutation scoring, landscape scans, ESMFold structure.
Hosted DNA language models: promoter, splice, enhancer, chromatin, expression, annotation
Bioinformatics MCP for genomic variant interpretation, gene-disease evidence and literature.
AI-powered bioprotocol optimization — generate, search, and manage lab protocols via MCP
