Evo2-7B Bioinformatics MCP Server

Ein Server, der die von NVIDIA gehostete Evo2-7B Forward API als MCP (Model Context Protocol) Tools kapselt, sodass Agents wie Claude Code, Cursor, Codex Evo2 über natürliche Sprache steuern können:

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. Projektübersicht

Stellt 5 MCP-Tools bereit:

Dieses Projekt ist ein Bioinformatics MCP Tool Server, kein einfacher HTTP-API-Wrapper:

• Automatische Validierung/Normalisierung von DNA-Sequenzen (Großschreibung, Entfernen von Leerzeichen, klare Fehlermeldung bei ungültigen Zeichen)

• Berechnung der Likelihood basierend auf der offiziellen Semantik (Byte-Level-Tokenizer + Causal Shift, siehe §17)

• Mehrstufiges Ausgabedesign (summary / raw / save), um eine Explosion des MCP-Kontexts zu verhindern

• Vollständige Fehlerklassifizierung (400/401/403/404/408/413/422/429/5xx/Timeout) + Retry/Backoff

• API-Key wird nur aus Umgebungsvariablen gelesen, niemals hartkodiert, niemals in Logs

• Begleitende Batch-Skripte: scripts/score_fasta.py (Batch-FASTA-Scoring + Embedding-Extraktion, siehe §18) und scripts/analyze_run.py (Cluster-/Klassifikations-/Regressions-Nachanalyse, siehe §19)

Related MCP server: Evo2 MCP Server

2. Einführung in die Evo2-API

Evo2 (Arc Institute / NVIDIA) ist ein DNA-Basismodell (StripedHyena2-Architektur); die 7B-Version hat 32 Layer, ist Apache-2.0-lizenziert und hat einen Trainingskontext von bis zu 1M bp. NVIDIA bietet einen gehosteten NIM-Dienst an:

• Forward-Endpunkt: POST https://health.api.nvidia.com/v1/biology/arc/evo2-7b/forward

• Anfragekörper (offizielles OpenAPI ForwardInputs):

  { "sequence": "ACGTACGT...", "output_layers": ["output_layer"] }

  output_layers unterstützt 1–100 Layernamen (z. B. output_layer, decoder.layers.24.mlp.linear_fc2, decoder.layers.3.self_attention, embedding, decoder.final_norm).

• Antwortkörper (offizielles OpenAPI ForwardOutputs): {"data": "<base64 编码的 NPZ>", "elapsed_ms": <int>}; sehr große Antworten können mit Content-Type: application/zip (rohe NPZ-Bytes) zurückgegeben werden.

• output_layer = finale Logits, Shape [seq_len, batch_size, 512] (512 ist die gepaddete Vocabulary-Größe des Byte-Level-Tokenizers).

⚠️ Deprecation-Hinweis (am 2026-08-24 verifiziert): Der auf build.nvidia.com gehostete arc/evo2-7b-Endpunkt wurde als Deprecated markiert (Seite zeigt „This NIM Endpoint has been deprecated"). Die offizielle NIM-Dokumentation (docs.nvidia.com/nim/bionemo/evo2/latest/) beschreibt eine API, die mit dem gehosteten Endpunkt völlig übereinstimmt; falls der gehostete Endpunkt nicht verfügbar ist, kann stattdessen ein selbst gehosteter NIM-Container verwendet werden, wobei EVO2_MCP_BASE_URL auf http://localhost:8000/biology/arc/evo2 zeigt.

Verifizierte offizielle Fakten (Implementierungsbasis, 2026-08-24)

Unterschiede zwischen Live-Test und Dokumentation (Live-Verifizierung am 2026-08-24; die Aufgabe verlangt die Erfassung der tatsächlichen API)

Beim Testen des gehosteten health.api.nvidia.com-Endpunkts mit einem echten Key wurde festgestellt, dass die in der Dokumentation genannten Layernamen auf dem gehosteten Endpunkt nicht gelten:

Gegenmaßnahmen (implementiert und live bestanden):

• Neue Konfiguration EVO2_MCP_LOGITS_LAYER (Standard auto): Die Scoring-Tools versuchen zuerst den Dokumentationsnamen output_layer; bei 422 has no attribute (gehosteter Endpunkt) wechseln sie automatisch zu unembed und cachen die Wahl, sodass keine weitere Erkundung nötig ist. Bei selbst gehosteten NIM-2.x-Containern gelingt der Aufruf sofort, ohne zusätzliche Anfragen.

• Der NPZ-Parser unterstützt sowohl nackte Keys (output_layer) als auch <name>.output (unembed.output) und greift als Fallback auf die Heuristik „letzte Dimension = 512" zurück.

• 422-Fehlermeldungen weisen jetzt auf die auf dem gehosteten Endpunkt verfügbaren Attributnamen hin.

Wenn das zurückgegebene seq_len nicht mit der Länge der Eingabesequenz übereinstimmt (z. B. weil der Server Padding/BOS hinzugefügt hat), verweigert dieser Server die Berechnung der Likelihood und gibt rohe Statistiken + eine klare Erklärung zurück; eine Ausrichtung wird nie erraten.

3. NVIDIA-API-Key erhalten

1. Öffnen Sie https://build.nvidia.com/, oben rechts Get API Key (Anmeldung mit NVIDIA-Konto erforderlich).

2. Erstellen Sie einen Key (in der Form nvapi-xxxxxxxx...).

3. Setzen Sie ihn als Umgebungsvariable, nicht in Code / Konfiguration / Git:

   export NVIDIA_API_KEY="nvapi-xxxxxxxx"

   Oder kopieren Sie .env.example zu .env und füllen Sie es aus (.env wird von .gitignore ignoriert).

4. Installation

# 推荐：pip / uv
pip install -e ".[dev]"
# 或
uv sync --extra dev

# 推荐（本项目自带）：pixi 项目本地环境
pixi install
pixi run test

Erfordert Python >= 3.10 (empfohlen 3.11+). Kernabhängigkeiten: mcp>=2.0, httpx>=0.27, numpy>=1.26, pydantic>=2.6, python-dotenv>=1.0. Das AnalysesSkript (scripts/analyze_run.py) benötigt zusätzlich Dev-Abhängigkeiten: scikit-learn, pandas, matplotlib.

5. Umgebungsvariablen

6. CLI-Start

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

Der Server kommuniziert über stdio mit MCP-Clients; nach erfolgreichem Start gibt es keine Ausgabe (wartet auf den MCP-Handshake).

7. MCP-Konfiguration

Claude Code (.mcp.json)

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

Hinweis: Ob ${NVIDIA_API_KEY} vom Client expandiert wird, hängt von der Client-Implementierung ab. Die sicherste Methode ist, den echten Key direkt einzutragen:

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

Aber committen Sie niemals eine .mcp.json mit einem echten Key nach Git (fügen Sie die Datei zu .gitignore hinzu oder injizieren Sie den Key über Umgebungsvariablen/Secret-Management-Tools). Alternativ kann env weggelassen werden; der Server-Prozess liest NVIDIA_API_KEY selbst aus der Umgebung oder .env:

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

Cursor (~/.cursor/mcp.json oder Projekt-.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" }

Selbst gehostetes NIM

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

8. Tool-Liste

evo2_forward(sequence, output_layers=["output_layer"], mode="summary", save_path=None)

Führt Evo2-7B-Forward-Inferenz auf einer DNA-Sequenz aus. mode:

• "summary" (Standard): gibt für jeden Layer shape / dtype / min / max / mean / std zurück, kontextsicher;

• "save": speichert den rohen Tensor als .npz (output/evo2_forward_<时间戳>.npz) und gibt den Pfad zurück;

• "raw": gibt den vollständigen Tensor inline zurück (nur wenn die Gesamtzahl der Elemente ≤ EVO2_MCP_RAW_INLINE_MAX, Standard 4096, um eine Kontextexplosion zu verhindern).

Hinweis zu Layernamen: Der gehostete Endpunkt health.api.nvidia.com akzeptiert Modellattributnamen (für Logits unembed, außerdem embedding_layer, norm, blocks.N.mlp); die Dokumentationsnamen output_layer/decoder.layers.N.* gelten nur für selbst gehostete NIM-2.x-Container. evo2_score/evo2_variant_score/evo2_batch_score/evo2_score_fasta erkennen dies automatisch, keine manuelle Angabe nötig; nur beim direkten Aufruf von evo2_forward muss der Name passend zum tatsächlichen Endpunkt gewählt werden.

evo2_score(sequence, include_per_position=False)

Berechnet die Likelihood von Evo2 für die Sequenz:

{
  "sequence_length": 123,
  "total_log_likelihood": -123.45,
  "mean_log_likelihood": -1.2345,
  "scored_positions": 122,
  "per_position_log_likelihood": null,
  "method_notes": "...",
  "disclaimer": "..."
}

Semantik (übereinstimmend mit der offiziellen Arc-Implementierung): logits[i] sagt die Base an Position i+1 voraus; nach Log-Softmax über den vollständigen 512-Vocab wird der Byte-Index der Zielbase genommen; Position 0 geht nicht in die Bewertung ein, daher gilt scored_positions = length - 1, und mean ist der Durchschnitt dieser N-1 Werte. per_position_log_likelihood[k] entspricht der 0-basierten Position k+1 (also der 1-basierten Position k+2). Wenn das von der API zurückgegebene seq_len nicht zur Sequenz ausgerichtet werden kann, werden keine Ergebnisse erfunden; es werden rohe Statistiken und eine klare Erklärung zurückgegeben:

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)"
}

Validierungskette: Positionsbereich → Koordinatenumrechnung → ref muss mit der Base an dieser Position der Sequenz übereinstimmen → ref≠alt → 1-basierte Position 1 (0-basiert 0) kann nicht bewertet werden (ein kausales LM kann dem ersten Token keine Wahrscheinlichkeit zuweisen) → klare Fehlermeldung.

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 }
  ]
}

• Der WT-Forward wird nur einmal berechnet und für alle Varianten wiederverwendet;

• Mutanten mit gleichem (position, alt) werden nur einmal ge-forewarded (Memoization);

• Die Parallelität ist durch EVO2_MCP_MAX_CONCURRENCY begrenzt (Standard 2, respektiert das NVIDIA-Rate-Limit);

• Ein einzelner Variantenfehler beeinträchtigt nicht den gesamten Batch (pro Eintrag wird error zurückgegeben).

evo2_score_fasta(fasta_path=None, fasta_text=None)

>sequence_1
ACGTACGT...
>sequence_2
TTGGCCAA...

• fasta_text: Inline-FASTA (standardmäßig verfügbar, mit Größen-/Datensatz-Obergrenzen);

• fasta_path: Lesen nur erlaubt, wenn die Datei innerhalb von EVO2_MCP_ALLOWED_DIRS liegt; andernfalls klare Ablehnung;

• Gibt pro Eintrag total_log_likelihood / mean_log_likelihood zurück; ein einzelner Fehler wirkt sich nicht auf die übrigen aus.

9. Anwendungsbeispiele

{
  "sequence": "acgtACGT acgt",           // 小写 + 空白自动处理
  "output_layers": ["output_layer"],
  "mode": "summary"
}

Rückgabe:

{
  "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 }
}

Wenn der Agent die vollständigen Logits möchte:

{ "sequence": "ACGT...", "mode": "save" }

{
  "saved": true,
  "path": "/abs/path/output/evo2_forward_20260824_153000.npz",
  "bytes_on_disk": 24576,
  "layer_stats": [...]
}

10. FASTA-Beispiel

{
  "fasta_text": ">geneA\nACGTACGTACGT\n>geneB\nTTGGCCAATTGG"
}

(oder "fasta_path": "/data/genomes/genes.fa"; dafür muss EVO2_MCP_ALLOWED_DIRS=/data/genomes konfiguriert sein)

Für großes FASTA-Scoring (z. B. ganze Verzeichnisse mit Enhancern/Promotern) plus Embedding-Extraktion verwenden Sie scripts/score_fasta.py (siehe §18) – jeder Lauf erzeugt einen eigenen Run-Ordner (scores.csv + embeddings.npz).

11. Beispiel für Varianten-Scoring

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

12. Beispiel für Batch-Scoring

{
  "sequence": "ACGTACGTACGTACGTACGT",
  "variants": [
    { "position": 10, "ref": "A", "alt": "G" },
    { "position": 12, "ref": "T", "alt": "C" },
    { "position": 14, "ref": "A", "alt": "T" }
  ]
}

Typischer Agent-Workflow (entspricht „Analysiere alle SNPs auf der Sequenz und finde die 20 mit der größten Änderung des Evo2-Scores"):

读取输入 → 解析 DNA / VCF → 生成 WT / mutant → evo2_batch_score
→ 按 |delta_log_likelihood| 排序 → 取前 20 → 保存 CSV → 解释结果

13. Fehlerbehandlung

Alle Fehler werden über MCP als strukturiertes JSON zurückgegeben: {"error": "Evo2APIError", "message": "..."}. Ein einzelner Fehlschlag in evo2_batch_score liefert {"error": ..., "status": ...} zurück und unterbricht den gesamten Batch nicht.

14. Rate limit

Das von NVIDIA gehostete NIM hat ein Rate Limit. Design-Gegenmaßnahmen:

• EVO2_MCP_MAX_CONCURRENCY (Standard 2) begrenzt die Parallelität;

• 429 → exponentieller Backoff (1s, 2s, 4s, 8s, 16s…, Deckelung bei 30s + Jitter; falls Retry-After vorhanden, wird dieses bevorzugt befolgt, aber mit Obergrenze 60s);

• Wiederholungsobergrenze EVO2_MCP_MAX_RETRIES (Standard 4), keine unendlichen Wiederholungen;

• Innerhalb eines Batches wird der WT nur einmal berechnet, identische Mutanten werden dedupliziert, um die Anzahl der Anfragen zu reduzieren.

15. Sicherheitshinweise

• API-Key: Wird nur aus der Umgebungsvariable NVIDIA_API_KEY (oder .env) gelesen; es gibt keinen hartkodierten Key im Code; Logs erfassen nur URL, Sequenzlänge und Layer-Namen, keine Sequenzinhalte oder Keys; Fehlermeldungen enthalten nur eine Zusammenfassung der ersten 500 Zeichen der Antwort.

• Sequenz-Privatsphäre: Alle Logs/Fehler enthalten nur preview (z. B. ACGT...GCTA (len=12345)).

• Pfad-Sandbox:

  • FASTA-Lesen ausschließlich innerhalb von EVO2_MCP_ALLOWED_DIRS; wenn nicht konfiguriert, werden alle lokalen Pfade abgelehnt;

  • Der save_path bei mode="save" muss innerhalb von EVO2_MCP_OUTPUT_DIR liegen;

• .gitignore enthält bereits .env, *.env, output/, *.npz.

• N-Basen: Standardmäßig abgelehnt mit eindeutiger Fehlermeldung (das Evo2-Modell wurde nicht auf mehrdeutigen Basen evaluiert; die Dokumentation garantiert nur, dass A/C/G/T aussagekräftig sind). Falls N tatsächlich durchgereicht werden muss, mit EVO2_MCP_ALLOW_AMBIGUOUS=1 starten – das ist eine explizite Entscheidung, kein stilles Verwerfen.

• Don't execute: Dieser Server führt keinerlei Shell-Ausführungen aus; über FASTA-/Sequenzeingaben kann der Agent nur eingeschränkte HTTP-Anfragen auslösen.

16. Grenzen der biologischen Interpretation

• Der Evo2-Score ist eine model-based sequence likelihood change, keine experimentelle Evidenz und schon gar keine klinische Pathogenitätsdiagnose.

• delta_log_likelihood < 0 darf nur als „die Mutantensequenz ist unter dem Modell unwahrscheinlicher" interpretiert werden, nicht als „pathogen".

• Erst mit Downstream-Validierung (Experimente, Populationsfrequenzen, ClinVar-Annotationen, Auswirkungen auf die Proteinstruktur usw.) kann über Pathogenität gesprochen werden.

• Die Beschreibung jedes Tools enthält den folgenden Hinweis (für MCP-Clients sichtbar):

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. Implementierungsgrundlagen und Validierungsquellen (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

• Referenz der von NVIDIA gehosteten API (arc/evo2-7b-forward OpenAPI-Schema): https://docs.api.nvidia.com/nim/reference/arc-evo2-7b-infer

• Praxistest des verwalteten Endpunkts (2026-08-24, echter Key): output_layer liefert 422 StripedHyena has no attribute 'output_layer'; unembed liefert die Logits (NPZ-Key unembed.output, Shape (1, seq, 512), float64) – daher erkennt das Scoring-Tool den Layer standardmäßig automatisch über EVO2_MCP_LOGITS_LAYER=auto.

• Praxistest im Batch (2026-08-25, echter Key, 3800+ K562-Enhancer/Promotoren):

  • Bei Sequenzen > ~100 kb liefert der verwaltete Endpunkt 422 (PyTorch-canUse32BitIndexMath-Limit) – für Batch-Läufe --skip-longer-than 100000 verwenden;

  • Der Race Condition bei der automatischen Erkennung des Layer-Namens unter Parallelität wurde behoben (forward_logits verwendet lokale Variablen, um die Versuchsnamen zu erfassen) und mit einem Regressionstest abgesichert;

  • Embedding-Extraktion: norm/embedding_layer/blocks.N sind alle verfügbar, Shape (1, seq, 4096) float64 (nach Mean-Pooling 4096-dimensional).

• Arc-Institute-Evo2-Repository (scoring.py, models.py): https://github.com/ArcInstitute/evo2

• vortex CharLevelTokenizer (offizielle Evo2-Tokenizer-Implementierung): PyPI-vtx-1.1.0-Quellcode vortex/model/tokenizer.py

• Evo2-Modellkarte: https://huggingface.co/ArcInstitute/evo2_7b

Falls NVIDIA die API anpasst, gilt die offizielle aktuelle Dokumentation; EVO2_MCP_BASE_URL kann jederzeit umgestellt werden.

18. Batch-Scoring und Embedding-Extraktion (scripts/score_fasta.py)

MCP-Tools eignen sich für interaktive Agent-Aufrufe; für Batch-Scoring großer FASTA-Mengen dient das zugehörige Skript scripts/score_fasta.py (mit der echten API anhand von 3800+ K562-Enhancer/Promotoren validiert).

Jeder Lauf erstellt automatisch einen eigenen Ordner mit Zeitstempel:

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

Wichtige Parameter:

Effizienzdesign: Pro Sequenz wird nur eine Anfrage gesendet (output_layers=["unembed","norm"], Logits und Embedding werden zusammen abgerufen); der Logits-Layer-Name wird pro Lauf nur einmal erkannt; die Parallelität wird über ein Semaphor begrenzt.

19. Embedding-Verknüpfung und Downstream-Analyse (scripts/analyze_run.py)

embeddings.npz ist die mean-gepoolte Sequenzrepräsentation (ein 4096-dimensionaler Vektor pro Sequenz) und eignet sich direkt für Clusterung, Klassifikation und Regression. Laden und Verknüpfen:

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]

Gesamte Analyse mit einem Befehl ausführen (KMeans-Clusterung, Enhancer-vs-Promoter-Klassifikation, Embedding→Likelihood-Regression, PCA-Diagramm):

.pixi/envs/dev/bin/python scripts/analyze_run.py output/run_20260825_104403 --k 3

Ausgabe analysis_<run>.npz (zusammengeführtes X + keys) und analysis_<run>.png. Analyse-Hinweise:

• Vor Ähnlichkeits-/Clusterungsberechnungen die 4096-dimensionalen Vektoren zuerst auf Einheitslänge normalisieren (im Skript bereits erledigt);

• Bei kleinen Stichproben werden Klassifikation/Regression automatisch übersprungen (Schutzschwelle ≥6 Einträge); erst nach dem vollständigen Lauf mit allen 3806 Einträgen sind diese Analysen statistisch aussagekräftig;

• Schlüssel cis_enhancers__xxx → Kategorie enhancers, Region cis; trans_* analog (parse_source kann die Label-Dimension für eine cis-vs-trans-Klassifikation ändern).

Entwicklung und Tests

pixi install          # 或 pip install -e ".[dev]"
pixi run test         # 运行 pytest（全部 mock，不调用真实 API）

Offline-Tests 91 passed / 4 skipped (skip = Live-Gating). Abgedeckt: Sequenzvalidierung, Normalisierung von Groß-/Kleinschreibung und Leerzeichen, ungültige Zeichen, fehlender API-Key, Konstruktion der Forward-Anfrage, 401/408/429/5xx/timeout, automatische Erkennung des Layer-Namens (inklusive Regressionstest für Race Conditions), Variantenvalidierung, mathematische Korrektheit des Varianten-/Batch-Scorings (unabhängig gegen die Arc-Semantik nachgerechnet), NPZ-Dekodierung (JSON base64 / zip / alte JSON-Tensoren / <layer>.output-Key), FASTA-Sandbox, MCP-Session-Integration, reine Skriptfunktionen (Pooling/Schlüsselnamen) usw.

Live-API-Smoke-Test (erfordert einen echten Key; standardmäßig übersprungen). Der Key wird automatisch aus .env gelesen (Settings.from_env() bereits geladen):

EVO2_MCP_RUN_LIVE=1 .pixi/envs/dev/bin/python -m pytest tests/test_live_api.py -v -s

Der Live-Test sendet echte Anfragen an den NVIDIA-Endpunkt und verifiziert: automatische Erkennung des Logits-Layers (unembed), echte NPZ-Parsung ((1, seq, 512) float64), Übereinstimmung von evo2_score mit der manuellen Neuberechnung aus den rohen Logits, Varianten-Score.

Projektstruktur

.
├── 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 忽略）