Evo2-7B Bioinformatics MCP Server

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
  ↓
Agent

POST https://health.api.nvidia.com/v1/biology/arc/evo2-7b/forward
Authorization: Bearer $NVIDIA_API_KEY

1. プロジェクト紹介

5 つの MCP Tools を提供します：

本プロジェクトは 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: Evo2 MCP Server

2. Evo2 API 概要

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 に指定してください。

確認済みの公式事実（実装根拠、2026-08-24）

実測とドキュメントの差異（2026-08-24 ライブ検証、タスク要件により実際のインターフェースを記録）

本物の key でホスト型 health.api.nvidia.com エンドポイントを調査したところ、ドキュメント記載の layer 名はホスト型エンドポイントでは使用できないことが判明しました：

対応策（実装済み・ライブ検証済み）：

• 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 統計と明確な説明を返します。アライメントを推測することは絶対にありません。

3. NVIDIA API Key の取得方法

1. https://build.nvidia.com/ を開き、右上の Get API Key をクリックします（NVIDIA アカウントへのログインが必要）。

2. key を作成します（nvapi-xxxxxxxx... の形式）。

3. 環境変数に設定します。コード / 設定 / Git には書き込まないでください：

export NVIDIA_API_KEY="nvapi-xxxxxxxx"

または .env.example をコピーして .env にし、値を入力します（.env は .gitignore で無視されます）。

4. インストール

# 推荐：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 が必要です。

5. 環境変数

6. CLI 起動

# 三种方式等价
python -m evo2_mcp
evo2-mcp
uv run evo2-mcp      # 用 uv 管理的项目环境
# pixi 环境：
pixi run evo2-mcp

サーバーは stdio 経由で MCP クライアントと通信します。正常に起動すると出力はありません（MCP ハンドシェイク待ち）。

7. MCP 設定

Claude Code（.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（~/.cursor/mcp.json またはプロジェクトの .cursor/mcp.json）

{
  "mcpServers": {
    "evo2": {
      "command": "uv",
      "args": ["run", "evo2-mcp"],
      "env": { "NVIDIA_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Codex（~/.codex/config.toml）

[mcp_servers.evo2]
command = "uv"
args = ["run", "evo2-mcp"]
env = { "NVIDIA_API_KEY" = "YOUR_API_KEY" }

自社ホスト NIM

{
  "mcpServers": {
    "evo2": {
      "command": "uv",
      "args": ["run", "evo2-mcp"],
      "env": {
        "EVO2_MCP_BASE_URL": "http://localhost:8000/biology/arc/evo2"
      }
    }
  }
}

8. Tool 一覧

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 を返します。単一レコードのエラーは他に影響しません。

9. 使用例

{
  "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": [...]
}

10. FASTA の例

{
  "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）を出力します。

11. Variant scoring の例

{
  "sequence": "ACGTACGTACGTACGTACGT",
  "position": 10,
  "ref": "A",
  "alt": "G"
}

12. Batch scoring の例

{
  "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 → 解释结果

13. エラー処理

すべてのエラーは MCP 経由で構造化 JSON として返されます：{"error": "Evo2APIError", "message": "..."}。evo2_batch_score では単一アイテムの失敗は {"error": ..., "status": ...} を返し、バッチ全体は中断しません。

14. Rate limit

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 は重複排除してリクエスト数を削減。

15. セキュリティに関する注意事項

• 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 リクエストのみをトリガーできる。

16. 生物学的解釈の制限

• 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.

17. 実装根拠と検証ソース（2026-08-24）

• 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 でいつでも切り替えられます。

18. バッチスコアリングと Embedding 抽出（scripts/score_fasta.py）

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

主要パラメータ：

効率設計：各配列につきリクエストは 1 回だけ送信（output_layers=["unembed","norm"] で logits と embedding を同時取得）；logits の layer 名は実行全体で一度だけ検出；同時実行数はセマフォで制限。

19. Embedding の関連付けと下流分析（scripts/analyze_run.py）

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 3

analysis_<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 -s

live テストは実際に 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 忽略）