Evo2-7B 생물정보학 MCP 서버

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 live 검증, 작업 요구사항: 실제 인터페이스 기록)

실제 key로 호스팅 health.api.nvidia.com 엔드포인트를 탐색한 결과 문서의 layer 이름은 호스팅 엔드포인트에서 적용되지 않습니다:

대응 조치(구현 완료, live 통과):

• EVO2_MCP_LOGITS_LAYER 설정 추가(기본 auto): 스코어링 도구가 먼저 문서 이름 output_layer를 시도하고, 422 has no attribute(호스팅 엔드포인트)를 받으면 자동으로 unembed로 전환하여 캐시하고 이후 재탐색하지 않음; 자체 호스팅 NIM 2.x 컨테이너는 한 번에 성공, 추가 요청 0회.

• NPZ 파서는 bare 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"(기본값): 각 레이어에 대해 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는 한 번만 계산하고 모든 variant에 재사용;

• 동일한 (position, alt)의 mutant는 한 번만 forward(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(1s, 2s, 4s, 8s, 16s…, 상한 30s + 지터; Retry-After가 있으면 우선 따르되 상한 60s);

• 재시도 상한 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 시퀀스 표현(시퀀스당 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 忽略）