Evo2-7B Bioinformatics MCP Server

Сервер, который оборачивает размещённый NVIDIA Evo2-7B Forward API в инструменты MCP (Model Context Protocol), позволяя агентам вроде Claude Code, Cursor, Codex управлять 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-инструментов:

Этот проект — Bioinformatics MCP Tool Server, а не простой HTTP API-обёртка:

• Автоматическая валидация / нормализация DNA-последовательностей (заглавные буквы, удаление пробелов, явная ошибка при недопустимых символах)

• Вычисление likelihood на основе официальной семантики (byte-level tokenizer + causal shift, см. §17)

• Многоуровневый дизайн вывода (summary / raw / save) для предотвращения раздувания MCP-контекста

• Полная классификация ошибок (400/401/403/404/408/413/422/429/5xx/timeout) + retry/backoff

• API-ключ читается только из переменных окружения, никогда не захардкожен и не попадает в логи

• В комплекте пакетные скрипты: scripts/score_fasta.py (пакетная оценка FASTA + извлечение эмбеддингов, см. §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 endpoint: POST https://health.api.nvidia.com/v1/biology/arc/evo2-7b/forward

• Тело запроса (официальная OpenAPI-схема ForwardInputs):

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

  output_layers поддерживает 1–100 имён слоёв (например, 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, форма [seq_len, batch_size, 512] (512 — это padded vocabulary size byte-level токенизатора).

⚠️ Предупреждение об устаревании (проверено 2026-08-24): endpoint arc/evo2-7b, размещённый на build.nvidia.com, помечен как Deprecated (на странице указано "This NIM Endpoint has been deprecated"). API, описанный в официальной документации NIM (docs.nvidia.com/nim/bionemo/evo2/latest/), полностью совпадает с размещённым endpoint'ом; если размещённый endpoint недоступен, можно перейти на самостоятельный контейнер NIM, указав EVO2_MCP_BASE_URL на http://localhost:8000/biology/arc/evo2.

Проверенные официальные факты (основа реализации, 2026-08-24)

Различия между документацией и реальным API (live-проверка 2026-08-24, по заданию зафиксирован фактический интерфейс)

Пробное обращение к размещённому endpoint'у health.api.nvidia.com с реальным ключом показало, что имена слоёв из документации не работают на размещённом endpoint'е:

Принятые меры (реализованы и проверены в live-режиме):

• Добавлена конфигурация EVO2_MCP_LOGITS_LAYER (по умолчанию auto): инструменты оценки сначала пробуют имя из документации output_layer; при получении 422 has no attribute (размещённый endpoint) автоматически переключаются на unembed с кэшированием, после чего повторное зондирование не выполняется; самостоятельный контейнер NIM 2.x срабатывает с первого раза, без лишних запросов.

• Парсер NPZ поддерживает как голые ключи (output_layer), так и формат <имя>.output (unembed.output), с эвристическим запасным вариантом по признаку "последнее измерение = 512".

• Сообщение об ошибке 422 теперь подсказывает доступные имена атрибутов для размещённого endpoint'а.

Если возвращаемый seq_len не совпадает с длиной входной последовательности (например, сервер добавил padding/BOS), этот сервер отказывается вычислять likelihood и возвращает raw-статистику с явным пояснением — никаких догадок о выравнивании.

3. Как получить NVIDIA API Key

1. Откройте https://build.nvidia.com/, в правом верхнем углу Get API Key (требуется вход в аккаунт NVIDIA).

2. Создайте ключ (вида 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

Сервер общается с MCP-клиентом через stdio; после нормального запуска вывода не будет (ожидание 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} клиентом зависит от реализации клиента. Самый надёжный способ — подставить реальный ключ напрямую:

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

Но ни в коем случае не коммитьте .mcp.json с реальным ключом в Git (добавьте этот файл в .gitignore или используйте переменные окружения / менеджер секретов для инъекции). Можно также не передавать env вовсе — процесс сервера сам прочитает NVIDIA_API_KEY из окружения или .env:

{
  "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. Список инструментов

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

Выполняет forward inference Evo2-7B для DNA-последовательности. mode:

• "summary" (по умолчанию): для каждого слоя возвращает shape / dtype / min / max / mean / std, безопасно для контекста;

• "save": сохраняет исходный тензор в .npz (output/evo2_forward_<временная_метка>.npz), возвращает путь;

• "raw": инлайн полного тензора (только если общее число элементов ≤ EVO2_MCP_RAW_INLINE_MAX, по умолчанию 4096, чтобы не раздувать контекст).

Внимание к именам слоёв: размещённый endpoint 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 имя нужно выбирать по фактическому endpoint'у.

evo2_score(sequence, include_per_position=False)

Вычисляет likelihood Evo2 для последовательности:

{
  "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; после log-softmax по полному vocabulary из 512 берётся индекс байта целевого основания; позиция 0 не участвует в оценке, поэтому scored_positions = length - 1, а mean — это среднее по этим N-1 значениям. per_position_log_likelihood[k] соответствует 0-based позиции k+1 последовательности (то есть 1-based позиции k+2). Если seq_len, возвращённый API, невозможно выровнять с последовательностью, результат не подделывается — возвращается 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 в 1-based (0 в 0-based) не подлежит оценке (causal LM не может присвоить вероятность первому токену) → явная ошибка.

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 вычисляется только один раз и переиспользуется для всех вариантов;

• мутант с одинаковыми (position, alt) форвардится только один раз (memoize);

• конкурентность ограничена EVO2_MCP_MAX_CONCURRENCY (по умолчанию 2, с учётом rate limit NVIDIA);

• сбой одного варианта не влияет на весь 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 }
}

Когда агенту нужны полные 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 в целой директории) + извлечения эмбеддингов используйте 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" }
  ]
}

Типичный рабочий процесс агента (соответствует задаче "проанализировать все SNP на последовательности, найти топ-20 по изменению Evo2 score"):

读取输入 → 解析 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

У управляемого NIM от NVIDIA есть rate limit. Предусмотренные меры:

• EVO2_MCP_MAX_CONCURRENCY (по умолчанию 2) ограничивает параллелизм;

• 429 → exponential backoff (1с, 2с, 4с, 8с, 16с…, с потолком 30с + джиттер; при наличии Retry-After он имеет приоритет, но с потолком 60с);

• лимит повторных попыток EVO2_MCP_MAX_RETRIES (по умолчанию 4), бесконечных повторов не будет;

• в батче WT считается только один раз, одинаковые мутанты дедуплицируются — это сокращает число запросов.

15. Замечания по безопасности

• API Key: читается только из переменной окружения NVIDIA_API_KEY (или .env); в коде нет ни одного захардкоженного ключа; в логах фиксируются только URL, длина последовательности и имя слоя, содержимое последовательностей и ключи не логируются; сообщения об ошибках содержат только краткое описание первых 500 символов ответа.

• Конфиденциальность последовательностей: все логи/ошибки содержат только preview (например, ACGT...GCTA (len=12345)).

• Песочница путей:

  • чтение FASTA разрешено только из EVO2_MCP_ALLOWED_DIRS; если не настроено — любые локальные пути отклоняются;

  • save_path в режиме mode="save" должен находиться внутри 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-команд; через FASTA/входные последовательности агент может инициировать только ограниченные HTTP-запросы.

16. Ограничения биологической интерпретации

• Evo2 score — это изменение правдоподобия последовательности на основе модели, а не экспериментальное доказательство и тем более не клинический диагноз патогенности.

• delta_log_likelihood < 0 можно интерпретировать только как «мутантная последовательность менее вероятна по модели», но не как «патогенна».

• Для разговора о патогенности необходима downstream-валидация (эксперименты, частоты в популяции, аннотации ClinVar, влияние на структуру белка и т.д.).

• В описании каждого Tool присутствует следующее заявление (видимое 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

• Справочник управляемого API NVIDIA (OpenAPI-схема arc/evo2-7b-forward): https://docs.api.nvidia.com/nim/reference/arc-evo2-7b-infer

• Практическое тестирование управляемой конечной точки (2026-08-24, реальный ключ): output_layer возвращает 422 StripedHyena has no attribute 'output_layer'; unembed возвращает logits (ключ NPZ unembed.output, shape (1, seq, 512), float64) — поэтому инструмент оценки по умолчанию использует EVO2_MCP_LOGITS_LAYER=auto с автоматическим определением

• Практическое тестирование батчами (2026-08-25, реальный ключ, 3800+ записей K562 enhancer/promoter):

  • при длине последовательности > ~100 kb управляемая сторона возвращает 422 (ограничение PyTorch canUse32BitIndexMath) — для батчей используйте --skip-longer-than 100000;

  • гонка при автоматическом определении имени слоя в условиях параллелизма исправлена (forward_logits использует локальную переменную для запоминания испытанных имён) и добавлен регрессионный тест;

  • извлечение эмбеддингов: 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): исходный код PyPI vtx 1.1.0, vortex/model/tokenizer.py

• Карточка модели Evo2: https://huggingface.co/ArcInstitute/evo2_7b

Если NVIDIA изменит API, ориентируйтесь на актуальную официальную документацию; EVO2_MCP_BASE_URL можно переключить в любой момент.

18. Пакетная оценка и извлечение эмбеддингов (scripts/score_fasta.py)

MCP Tools подходят для интерактивных вызовов агентом; для пакетной оценки больших 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

Ключевые параметры:

Проектирование эффективности: на каждую последовательность отправляется только один запрос (output_layers=["unembed","norm"], logits и эмбеддинги получаются одновременно); имя logits-слоя определяется только один раз за весь запуск; параллелизм ограничивается семафором.

19. Связывание эмбеддингов и последующий анализ (scripts/analyze_run.py)

embeddings.npz — это mean-pooled представления последовательностей (по одному вектору размерности 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, автоматическое определение имени слоя (включая регрессию гонки при параллелизме), валидация вариантов, математическая корректность оценки вариантов/батчей (независимый пересчёт по семантике Arc), декодирование NPZ (JSON base64 / zip / старый JSON tensor / ключ <layer>.output), песочница FASTA, интеграция MCP-сессии, чистые функции скриптов (pooling/имена ключей) и т.д.

Смоук-тест на реальном API (требуется реальный ключ, по умолчанию пропускается). Ключ автоматически читается из .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-слоя (unembed), разбор реального NPZ ((1, seq, 512) float64), совпадение evo2_score с ручным пересчётом из сырых logits, оценку вариантов.

Структура проекта

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