nucleotide transformer MCP

核苷酸转换器MCP

通过模型上下文协议（MCP）使用核苷酸转换器深度学习模型进行DNA序列分析

目录

• 概述
• 安装
• 本地使用（脚本）
• MCP服务器安装
• 使用Claude代码
• 与Gemini CLI一起使用
• 可用工具
• 例子
• 故障排除

概述

此MCP服务器提供对核苷酸转换器的访问，这是一种用于DNA序列分析的最先进的深度学习模型。它为小型数据集提供快速同步操作，为大规模分析提供异步后台处理。

特性

• DNA序列嵌入：从DNA序列中提取512维上下文化嵌入
• 注意力可视化：生成热图，显示不同序列位置的模型注意力模式
• 核苷酸预测：预测每个位置的核苷酸概率以进行序列分析
• 多种型号尺寸：支持50M至2.5B参数的型号
• 批处理：高效处理多个文件和大型数据集
• 异步处理：长时间运行的任务的后台作业执行

目录结构

./
├── README.md               # This file
├── env/                    # Conda environment
├── src/
│   └── server.py           # MCP server
├── scripts/
│   ├── dna_embedding.py           # DNA sequence embedding extraction
│   ├── dna_embedding_v2.py        # Enhanced embedding extraction with shared lib
│   ├── attention_visualization.py # Attention pattern visualization
│   ├── nucleotide_prediction.py   # Nucleotide probability prediction
│   └── lib/                       # Shared utilities
│       ├── io.py                  # File I/O utilities
│       ├── models.py              # Model loading utilities
│       └── visualization.py       # Visualization utilities
├── examples/
│   └── data/
│       └── sample_sequences.txt   # Demo DNA sequences
├── configs/                       # Configuration files
│   ├── dna_embedding_config.json
│   ├── attention_visualization_config.json
│   ├── nucleotide_prediction_config.json
│   └── default_config.json
└── repo/                          # Original nucleotide-transformer repository

______________________________________________________________________

安装

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• Python 3.10+
• 至少4GB RAM（建议大型型号使用16GB+）
• 可选：支持CUDA的GPU，用于加速推理

创建环境

请遵循中概述的程序 reports/step3_environment.md 有关详细的设置说明。快速设置工作流程如下所示：

# Navigate to the MCP directory
cd /home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/nucleotide_transformer_mcp

# Determine package manager (prefer mamba over conda)
if command -v mamba &> /dev/null; then
    PKG_MGR="mamba"
else
    PKG_MGR="conda"
fi
echo "Using package manager: $PKG_MGR"

# Create conda environment
$PKG_MGR create -p ./env python=3.10 pip -y

# Activate environment
$PKG_MGR activate ./env

安装依赖项

# Core MCP dependencies
pip install fastmcp loguru click pandas numpy tqdm

# ML dependencies for nucleotide transformer
pip install "jax>=0.3.25" "jaxlib>=0.3.25" "dm-haiku>=0.0.9" \
    "transformers>=4.52.4" "torch>=2.7.1" "einops>=0.8.1" \
    "matplotlib>=3.5.0" "seaborn>=0.11.0" "pyfaidx>=0.7.0"

# Install nucleotide transformer package
cd repo/nucleotide-transformer
pip install -e .
cd ../..

______________________________________________________________________

本地使用（脚本）

您可以在没有MCP的情况下直接使用脚本进行本地处理。

可用脚本

脚本示例

DNA包埋提取

# Activate environment
mamba activate ./env

# Extract embeddings from sequences
python scripts/dna_embedding.py \
  --sequences "ATTCCGAAATCGCTGACCGATCGTACGAAA" \
  --model 50M_multi_species_v2 \
  --layer 12 \
  --output results/embeddings.npz

# Extract embeddings from file
python scripts/dna_embedding.py \
  --input examples/data/sample_sequences.txt \
  --output results/embeddings.npz

# Use configuration file
python scripts/dna_embedding.py \
  --config configs/dna_embedding_config.json \
  --output results/embeddings.npz

参数：

• --sequences, -s：DNA序列为字符串（如果没有输入文件，则需要）
• --input, -i：带序列的文件路径（每行一个）（如果没有序列，则需要）
• --output, -o：输出NPZ文件路径（默认：stdout）
• --model, -m：型号名称（默认值：50M_multi_species_v2）
• --layer, -l：从中提取嵌入的层（默认值：12）
• --max-positions：最大序列长度（默认值：32）
• --config, -c：JSON配置文件（可选）

注意力可视化

# Create attention heatmap
python scripts/attention_visualization.py \
  --sequences "ATTCCGAAATCGCTGACCGATCGTACGAAA" \
  --layer 1 \
  --head 4 \
  --output results/attention.png

# Process file with custom settings
python scripts/attention_visualization.py \
  --input examples/data/sample_sequences.txt \
  --layer 2 \
  --head 1 \
  --dpi 300 \
  --output results/attention_heatmap.png

参数：

• --sequences, -s：要可视化的DNA序列
• --input, -i：包含序列的文件路径
• --output, -o：输出PNG文件路径
• --layer, -l：要可视化的注意层（默认值：1）
• --head：注意头号（默认值：4）
• --dpi：图像分辨率（默认值：300）

核苷酸预测

# Predict nucleotide probabilities
python scripts/nucleotide_prediction.py \
  --sequences "ATTCCGAAATCGCTGACCGATCGTACGAAA" \
  --top-k 5 \
  --output results/predictions.csv

# Analyze multiple sequences
python scripts/nucleotide_prediction.py \
  --input examples/data/sample_sequences.txt \
  --top-k 3 \
  --output results/detailed_predictions.csv

参数：

• --sequences, -s：要分析的DNA序列
• --input, -i：包含序列的文件路径
• --output, -o：输出CSV文件路径
• --top-k：每个位置的最高预测数（默认值：5）
• --max-positions：最大序列长度（默认值：32）

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

# Install MCP server for Claude Code
fastmcp install src/server.py --name nucleotide-transformer

选项2:Claude代码的手动安装

# Add MCP server to Claude Code
claude mcp add nucleotide-transformer -- $(pwd)/env/bin/python $(pwd)/src/server.py

# Verify installation
claude mcp list

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

{
  "mcpServers": {
    "nucleotide-transformer": {
      "command": "/home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/nucleotide_transformer_mcp/env/bin/python",
      "args": ["/home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/nucleotide_transformer_mcp/src/server.py"]
    }
  }
}

______________________________________________________________________

使用Claude代码

安装MCP服务器后，您可以直接在Claude Code中使用它。

快速开始

# Start Claude Code
claude

示例提示

工具发现

What tools are available from nucleotide-transformer?

基本序列分析

Use extract_dna_embeddings with sequences ["ATTCCGAAATCGCTGACCGATCGTACGAAA", "ATGAAACGCTACGGTCGCTACGGCAAACGCTAG"] and save to embeddings.npz

基于文件的分析

Extract DNA embeddings from @examples/data/sample_sequences.txt and save results to embeddings.npz

注意力可视化

Create attention visualization for sequence "ATTCCGAAATCGCTGACCGATCGTACGAAA" and save to attention.png

核苷酸预测

Predict nucleotide probabilities for sequences in @examples/data/sample_sequences.txt with top_k 3

长期运行任务（提交API）

Submit DNA embedding extraction for @examples/data/sample_sequences.txt with job_name "sample_analysis"
Then check the job status and get results when completed

批处理

Submit batch DNA analysis for files:
- @examples/data/sample_sequences.txt
with analysis_type "embeddings" and output_dir "batch_results/"

使用@引用

在克劳德代码中，使用 @ 引用文件和目录：

______________________________________________________________________

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

{
  "mcpServers": {
    "nucleotide-transformer": {
      "command": "/home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/nucleotide_transformer_mcp/env/bin/python",
      "args": ["/home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/nucleotide_transformer_mcp/src/server.py"]
    }
  }
}

示例提示

# Start Gemini CLI
gemini

# Example prompts (same syntax as Claude Code)
> What tools are available from nucleotide-transformer?
> Extract embeddings from sequence "ATGAAACGCTACGGTCGC" using model 100M_multi_species_v2
> Create attention visualization for examples/data/sample_sequences.txt

______________________________________________________________________

可用工具

快速操作（同步API）

这些工具会立即返回结果（\10分钟）：

作业管理工具

______________________________________________________________________

例子

示例1：DNA序列嵌入

目标： 从DNA序列中提取512维包埋用于下游分析

使用脚本：

python scripts/dna_embedding.py \
  --input examples/data/sample_sequences.txt \
  --model 50M_multi_species_v2 \
  --layer 12 \
  --output results/sample_embeddings.npz

使用MCP（克劳德代码）：

Extract DNA embeddings from @examples/data/sample_sequences.txt using model 50M_multi_species_v2 and layer 12, save to results/sample_embeddings.npz

预期产量：

• 包含嵌入数组的NPZ文件（N x 512）
• 具有模型配置和处理统计信息的元数据
• 控制台输出显示序列处理成功

示例2：注意力模式可视化

目标： 了解模型如何关注DNA序列的不同部分

使用脚本：

python scripts/attention_visualization.py \
  --input examples/data/sample_sequences.txt \
  --layer 1 \
  --head 4 \
  --output results/attention_patterns.png

使用MCP（克劳德代码）：

Create attention visualization for sequences in @examples/data/sample_sequences.txt using layer 1 and head 4, save to results/attention_patterns.png

预期产量：

• PNG文件，带有显示位置间注意力权重的注意力热图
• 注意力模式的统计分析
• 颜色编码可视化突出显示重要序列区域

示例3：核苷酸概率预测

目标： 预测每个位置最可能的核苷酸进行序列分析

使用脚本：

python scripts/nucleotide_prediction.py \
  --input examples/data/sample_sequences.txt \
  --top-k 5 \
  --output results/nucleotide_predictions.csv

使用MCP（克劳德代码）：

Predict nucleotide probabilities for @examples/data/sample_sequences.txt with top_k 5 and save to results/nucleotide_predictions.csv

预期产量：

• CSV文件，包含位置预测和概率
• 每个位置的Top-k最有可能的核苷酸
• 准确性指标和困惑度得分

示例4：批处理

目标： 高效地同时处理多个文件

使用脚本：

# Create multiple input files
for analysis in promoters genes intergenic; do
  echo "Processing $analysis sequences..."
  python scripts/dna_embedding.py \
    --input "data/${analysis}_sequences.txt" \
    --output "results/${analysis}_embeddings.npz"
done

使用MCP（克劳德代码）：

Submit batch DNA analysis for files ["data/promoters_sequences.txt", "data/genes_sequences.txt", "data/intergenic_sequences.txt"] with analysis_type "embeddings" and output_dir "batch_results/"

示例5：长时间运行的作业工作流

目标： 使用异步作业系统处理大型数据集

使用MCP（克劳德代码）：

1. Submit DNA embeddings job:
   Submit DNA embeddings for @large_dataset.txt with job_name "genome_analysis_2025" and model 250M_multi_species_v2

2. Monitor progress:
   Check status of job "abc123de"

3. View logs:
   Get job log for job "abc123de" with tail 50

4. Retrieve results when completed:
   Get result for job "abc123de"

______________________________________________________________________

演示数据

这 examples/data/ 目录包含用于测试的示例数据：

样本数据内容：

• 短启动子样序列: ATTCCGAAATCGCTGACCGATCGTACGAAA
• 重复元件: ATTTCTCTCTCTCTCTGAGATCGATCGATCGATATCTCTCGAGCTAGC
• 基因样编码序列: ATGAAACGCTACGGTCGCTACGGCAAACGCTACGGTCGCTACGGCAAACGCTAG
• TATA盒的调控序列: CCCGCGGTATATATAAAGCCGCGCTCGCGTCGCGTCGCGAAA
• 随机序列基线: ACGTACGTACGTACGTACGTACGTACGTACGT
• 长复杂序列：混合监管和编码要素

______________________________________________________________________

配置文件

这 configs/ 目录包含配置模板：

配置示例（dna_embedding_configure.json）

{
  "model": {
    "name": "50M_multi_species_v2",
    "alternatives": ["100M_multi_species_v2", "250M_multi_species_v2"]
  },
  "embedding": {
    "layer": 12,
    "max_positions": 32
  },
  "sequences": {
    "default": ["ATTCCGAAATCGCTGACCGATCGTACGAAA"]
  },
  "output": {
    "format": "npz",
    "include_token_embeddings": true,
    "include_mean_embeddings": true
  }
}

______________________________________________________________________

可用模型

故障排除

环境问题

问题： 未找到环境

# Recreate environment
mamba create -p ./env python=3.10 pip -y
mamba activate ./env
pip install fastmcp loguru jax dm-haiku transformers torch matplotlib
cd repo/nucleotide-transformer && pip install -e . && cd ../..

问题： 导入错误

# Verify installation
python -c "from nucleotide_transformer import get_pretrained_model; print('Success')"
python -c "from src.server import mcp; print('MCP server OK')"

问题： CUDA/GPU问题

# Check JAX device
python -c "import jax; print(f'JAX devices: {jax.devices()}')"

# Force CPU mode if GPU unavailable
export JAX_PLATFORM_NAME=cpu

MCP问题

问题： 在Claude代码中找不到服务器

# Check MCP registration
claude mcp list

# Re-add if needed
claude mcp remove nucleotide-transformer
claude mcp add nucleotide-transformer -- $(pwd)/env/bin/python $(pwd)/src/server.py

# Verify connection
claude mcp health

问题： 工具不工作

# Test server directly
python -c "
from src.server import mcp
print('Available tools:')
for name in mcp.list_tools():
    print(f'  - {name}')
"

# Test a specific tool
python -c "
from src.server import mcp
result = mcp.get_tool('extract_dna_embeddings')
print(f'Tool found: {result is not None}')
"

模型和内存问题

问题： 模型下载失败

# Check internet connection and clear cache
rm -rf ~/.cache/huggingface/
python -c "from huggingface_hub import snapshot_download; snapshot_download('InstaDeepAI/nucleotide-transformer-2.5b-multi-species')"

问题： 内存不足

# Use smaller model
# In your prompts, specify: model 50M_multi_species_v2

# Reduce sequence length
# Add parameter: max_positions 16

# Check system memory
free -h

问题： 性能缓慢

# Enable GPU if available
pip install --upgrade "jax[cuda]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html

# Use CPU optimization
export JAX_ENABLE_X64=False
export JAX_PLATFORMS=cpu

工作问题（提交API）

问题： 作业挂起

# Check job directory
ls -la jobs/

# View job details
python -c "
from src.jobs.manager import job_manager
print(job_manager.list_jobs())
"

问题： 作业失败

Use get_job_log with job_id "" and tail 100 to see error details in Claude Code

问题： 作业完成检测（已知问题）\*\*

# Check if job actually completed by examining output files
ls -la jobs//
cat jobs//result.json

# Manual verification that job finished successfully
cat jobs//job.log | tail -20

性能优化

内存管理：

• 使用较小的型号(50M_multi_species_v2)对于大型数据集
• 减少 max_positions 内存约束参数
• 小批量处理文件
• 将submit API用于内存密集型任务

速度优化：

• 启用GPU加速（如果可用）
• 首次下载后缓存模型（首次运行时延迟约30秒）
• 根据您的精度要求使用适当的模型尺寸
• 考虑对多个文件进行批处理

______________________________________________________________________

发展

运行测试

# Activate environment
mamba activate ./env

# Test scripts directly
python scripts/dna_embedding.py --sequences "ATCGATCG" --output test_output.npz

# Test MCP server
python src/server.py &
# In another terminal:
curl -X POST http://localhost:8000/tools -d '{"name": "list_tools"}'

正在启动开发服务器

# Run MCP server in development mode
fastmcp dev src/server.py

# Monitor logs
tail -f logs/server.log

______________________________________________________________________

业绩说明

模型下载行为

• 首次运行：自动下载型号（~100MB-10GB，具体取决于型号）
• 下载时间：30秒到几分钟，具体取决于型号大小和连接
• 后续运行：使用缓存模型快速启动
• 存储：模型缓存在 ~/.cache/huggingface/hub/

执行时间（CPU）

• 50M型号：每个序列约15-30秒
• 250M型号：每个序列约30-60秒
• 2B5型号：每个序列约1-3分钟
• 备注：GPU加速可以提供5-10x的加速

内存需求

• 50M型号：~1-2GB内存
• 250M型号：~4-6GB RAM
• 2B5型号：~16-20GB内存
• 建议：确保2x型号内存可用于稳定运行

______________________________________________________________________

许可证

基于InstaDeep AI的核苷酸转换器项目。

学分

基于 核苷酸转换器 InstaDeep AI