dnabert2 MCP

DNABERT-2mcp

使用DNABERT-2进行全面的DNA序列分析，并支持模型上下文协议

目录

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

概述

此MCP服务器使用DNABERT-2模型为DNA序列分析提供了全面的工具。它通过同步（即时）和异步（后台）API支持嵌入提取、序列分类、相似性分析和预测任务。

特性

• DNA序列包埋提取：使用DNABERT-2提取768个维度嵌入
• 序列分类：二元/多类DNA序列分类的微调模型
• 相似性分析：通过聚类和可视化计算序列相似性
• 序列预测：使用经过训练的DNABERT-2模型进行预测
• 批处理：通过后台作业管理处理大规模数据集
• 模拟实现：用于测试和开发的后备系统

目录结构

./
├── README.md               # This file
├── env/                    # Main MCP environment (Python 3.10)
├── env_py3.8/              # Legacy DNABERT-2 environment (Python 3.8)
├── src/
│   ├── server.py           # MCP server with 26 tools
│   └── jobs/               # Job management system
├── scripts/
│   ├── extract_dna_embeddings.py      # DNA embeddings extraction
│   ├── extract_dna_embeddings_mock.py # Mock fallback implementation
│   ├── analyze_sequence_similarity.py # Sequence similarity analysis
│   ├── predict_dna_sequences.py       # DNA sequence prediction
│   ├── classify_dna_sequences.py      # Model fine-tuning
│   └── lib/                # Shared utilities
├── examples/
│   ├── data/               # Demo CSV files (train, dev, test)
│   └── models/             # Example model directory
├── configs/                # Configuration files
├── tests/                  # Integration tests
└── repo/                   # Original DNABERT-2 repository

______________________________________________________________________

安装

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• Python 3.10+（用于MCP服务器）
• Python 3.8（适用于DNABERT-2模型）
• 约2GB磁盘空间，适用于型号和环境

创造环境

该项目使用双环境设置来处理兼容性要求：

# Navigate to the MCP directory
cd /home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/dnabert2_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"

# Main environment for MCP server (Python 3.10)
$PKG_MGR create -p ./env python=3.10 pip -y

# Activate main environment
eval "$($PKG_MGR shell hook --shell bash)"
$PKG_MGR activate ./env

# Install MCP dependencies
pip install fastmcp loguru pandas numpy tqdm PyYAML

# Legacy environment for DNABERT-2 (Python 3.8)
$PKG_MGR create -p ./env_py3.8 python=3.8 -y
$PKG_MGR activate ./env_py3.8

# Install DNABERT-2 dependencies
pip install torch==1.13.1+cu117 transformers==4.29.2 -f https://download.pytorch.org/whl/cu117
pip install peft omegaconf evaluate accelerate scikit-learn einops
pip install numpy==1.24.4 pandas==2.0.3 matplotlib seaborn

______________________________________________________________________

本地使用（脚本）

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

可用脚本

脚本示例

DNA包埋提取

# Activate DNABERT-2 environment
mamba activate ./env_py3.8

# Extract embeddings from single sequence
python scripts/extract_dna_embeddings.py \
  --sequence "ACGTTAGCATCGGATCTATCTATCGACACTTGGTTATCGATCTACGAGCATCTCGTTAGC" \
  --pooling mean \
  --device auto

# Extract embeddings from CSV file
python scripts/extract_dna_embeddings.py \
  --input examples/data/dev.csv \
  --output results/embeddings.npy \
  --config configs/extract_dna_embeddings_config.json

参数：

• --input, -i：带“序列”列的CSV文件路径（批处理所需）
• --sequence, -s：单个DNA序列串（单个需要）
• --output, -o：嵌入的输出文件路径（默认：打印到stdout）
• --config, -c：配置文件（可选）
• --pooling：池化策略-“cl”、“mean”、“max”（默认值：“cls”）
• --device：要使用的设备-“自动”、“cuda”、“cpu”（默认值：“自动”）

序列相似性分析

# Analyze similarity in CSV file
python scripts/analyze_sequence_similarity.py \
  --input examples/data/dev.csv \
  --metric cosine \
  --clusters 2 \
  --visualize \
  --output results/similarity/

# Pairwise comparison of two sequences
python scripts/analyze_sequence_similarity.py \
  --seq1 "ACGTTAGCATCGGATCTATCTATCGACACTTGGTTATC" \
  --seq2 "ACGTTCGCATCGGATCTATCTATCGACACTTGGTTATC" \
  --metric cosine

参数：

• --input, -i：带“序列”列的CSV文件（可选）
• --seq1, --seq2：两个序列用于成对比较（可选）
• --metric：相似性度量-“余弦”、“欧几里德”（默认值：“余弦”）
• --clusters：K表示簇的数量（默认值：2）
• --visualize：创建PCA可视化图（标志）

DNA序列预测

# Predict single sequence
python scripts/predict_dna_sequences.py \
  --sequence "ACGTTAGCATCGGATCTATCTATCGACACTTGGTTATC" \
  --model_path results/trained_model \
  --device auto

# Batch prediction
python scripts/predict_dna_sequences.py \
  --input examples/data/test.csv \
  --model_path results/trained_model \
  --output results/predictions.csv

DNA序列分类（模型训练）

# Train classification model with LoRA
python scripts/classify_dna_sequences.py \
  --input examples/data \
  --output results/classification \
  --epochs 3 \
  --use_lora \
  --learning_rate 2e-5

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

# Activate main environment
mamba activate ./env

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

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

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

# Verify installation
claude mcp list

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

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

______________________________________________________________________

使用Claude代码

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

快速开始

# Start Claude Code
claude

示例提示

工具发现

What tools are available from DNABERT_2?

基础DNA包埋提取

Use extract_dna_embeddings with input file @examples/data/dev.csv

可视化序列相似性分析

Use analyze_sequence_similarity on @examples/data/dev.csv with metric "cosine", clusters 3, and visualize set to true

长跑训练任务

Submit DNA classification training for dataset in @examples/data using submit_dna_classification with epochs 5 and use_lora true
Then check the job status

批量处理多个文件

Submit batch embeddings extraction for files:
- @examples/data/train.csv
- @examples/data/dev.csv
- @examples/data/test.csv

使用@引用

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

______________________________________________________________________

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

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

示例提示

# Start Gemini CLI
gemini

# Example prompts (same patterns as Claude Code)
> What tools are available from DNABERT_2?
> Use extract_dna_embeddings with file examples/data/dev.csv
> Submit long-running classification training for examples/data

______________________________________________________________________

可用工具

MCP服务器提供 26工具 跨越多个类别：

作业管理工具（5个工具）

同步工具（快速操作\10分钟|重定向|

extract_dna_embedding

使用DNABERT-2从DNA序列中提取768个维度的嵌入。

参数：

• input_file （str，必填）：带“序列”列的TSV文件路径
• output_file （str，可选）：输出目录以保存结果
• batch_size （int，默认值=32）：处理的批大小
• pooling （str，default=“cl”）：池化策略（“cl”，“mean”，“max”）
• kmer （int，默认值=6）：DNABERT的K-mer大小（3、4、5或6）
• max_seq_length （int，默认值=100）：最大序列长度
• device （str，默认值=“自动”）：设备（“自动”、“cuda”、“cpu”）

例子：

Use extract_dna_embeddings with input_file "@examples/data/dev.csv" and pooling "mean"

分析序列相似性

使用聚类和可视化选项分析DNA序列之间的相似性。

参数：

• input_file （str，可选）：带有“sequence”列的CSV文件
• seq1, seq2 （str，可选）：两个序列用于成对比较
• metric （str，默认值=“余弦”）：相似性度量（“余弦”，“欧几里德”）
• clusters （int，默认值=2）：K表示簇的数量
• visualize （bool，默认值=False）：创建PCA可视化

例子：

Use analyze_sequence_similarity with input_file "@examples/data/dev.csv", metric "cosine", clusters 3, and visualize true

提交工具（长时间操作>10分钟）

提交dna分类

提交DNA序列分类培训以进行背景处理。

参数：

• input_dir （str，必填）：包含train.csv、dev.csv、test.csv的目录
• output_dir （str，可选）：保存模型和结果的路径
• epochs （int，默认值=3）：训练周期数
• max_length （int，默认值=100）：最大序列长度
• use_lora （bool，default=False）：使用LoRA进行高效微调
• batch_size_train （int，默认值=8）：训练批大小
• learning_rate （浮动，默认值=2e-5）：学习率
• job_name （str，可选）：跟踪的可选名称

例子：

Submit DNA classification training for dataset in "@examples/data" with epochs 5, use_lora true, and job_name "my_training_job"

计划的工具（API就绪，计划实施）

______________________________________________________________________

例子

实施例1：基本DNA包埋提取

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

使用脚本：

mamba activate ./env_py3.8
python scripts/extract_dna_embeddings.py \
  --input examples/data/dev.csv \
  --output results/embeddings/ \
  --pooling mean

使用MCP（克劳德代码）：

Use extract_dna_embeddings to process @examples/data/dev.csv with pooling "mean" and save results to results/embeddings/

预期产量：

• 嵌入形状：（15768）适用于dev.csv中的15个序列
• 保存为带有元数据的.npy文件
• 处理时间：模拟实现约30秒

示例2：序列分类训练

目标： 训练用于二元DNA序列分类的DNABERT-2模型

使用脚本：

mamba activate ./env_py3.8
python scripts/classify_dna_sequences.py \
  --input examples/data \
  --output results/classification \
  --epochs 3 \
  --use_lora \
  --learning_rate 2e-5

使用MCP（克劳德代码）：

Submit DNA classification training for dataset in @examples/data with epochs 3, use_lora true, and output_dir "results/classification"

预期产量：

• 在结果/分类中训练模型文件/
• 培训指标和测试结果
• 通过提交API跟踪工作

示例3：序列相似性分析

目标： 通过聚类分析DNA序列之间的相似性

使用脚本：

mamba activate ./env_py3.8
python scripts/analyze_sequence_similarity.py \
  --input examples/data/dev.csv \
  --metric cosine \
  --clusters 2 \
  --visualize \
  --output results/similarity/

使用MCP（克劳德代码）：

Use analyze_sequence_similarity on @examples/data/dev.csv with metric "cosine", clusters 2, and visualize true

预期产量：

• 成对比较的相似性矩阵（15x15）
• 每个序列的集群分配
• PCA可视化图（如果启用了可视化）

示例4：批处理工作流

目标： 并行处理多个数据集

使用MCP（克劳德代码）：

Submit batch embeddings extraction for files:
- @examples/data/train.csv
- @examples/data/dev.csv
- @examples/data/test.csv

Use job_name "batch_embeddings_experiment"

监控进度：

List all running jobs
Get job status for the batch job
Get job log with tail 20 to see recent progress

______________________________________________________________________

演示数据

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

数据格式

所有CSV文件遵循相同的格式：

sequence,label
AAAAAGCCTGTGAAGCACAGAGAGCAGCCAGCCAGAGCTGATGCTCAATGGCAGAAACTGCTTAGTCACGCTGAAAGGGAGCCAAGGCAATAGCAGAGTGG,1
ACCTGCTAACAATTAAGGCCTCCAGGTCTACCCTGCAGCTGGGCCTGAGGAGGTCCTCTTGAAAGGAGTGGGTAACAGCGCACTATTGAGGGCCTGTGAAG,0

哪里：

• sequence：DNA序列串（每个100个核苷酸）
• label：二进制分类标签（0或1）

______________________________________________________________________

配置文件

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

配置示例

{
  "model": {
    "name": "zhihan1996/DNABERT-2-117M",
    "device": "auto"
  },
  "processing": {
    "max_length": 512,
    "batch_size": 16,
    "pooling": "mean"
  },
  "output": {
    "base_dir": "./results",
    "overwrite": false
  }
}

______________________________________________________________________

故障排除

环境问题

问题： 未找到环境

# Recreate environments
mamba create -p ./env python=3.10 -y
mamba create -p ./env_py3.8 python=3.8 -y
# Reinstall dependencies as shown in Installation section

问题： 导入错误

# Verify installation in correct environment
mamba activate ./env
python -c "import fastmcp; print('MCP environment OK')"

mamba activate ./env_py3.8
python -c "import torch, transformers; print('DNABERT environment OK')"

MCP问题

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

# Check MCP registration
claude mcp list

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

问题： 工具不工作

# Test server directly
mamba activate ./env
python -c "from src.server import mcp; print(list(mcp.list_tools().keys()))"

工作问题

问题： 作业挂起

# Check job directory
ls -la jobs/

# View job metadata
cat jobs//metadata.json

问题： 作业失败

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

问题： 模拟实现已激活

• 当DNABERT-2模型存在兼容性问题时，这是正常行为
• 模拟实现为测试提供了真实的结果
• 要使用真实模型，请设置具有兼容Triton版本的专用Python 3.8环境

模型问题

问题： CUDA内存不足

• 减少 batch_size 工具调用中的参数
• 使用 device 参数设置为“cpu”而不是“auto”
• 以较小的块处理数据

问题： 模型下载问题

• 检查网络连接（模型从Hugging Face下载）
• 验证是否有足够的磁盘空间（基本型号约500MB）
• 如果损坏，请清除变压器缓存： rm -rf ~/.cache/huggingface/

______________________________________________________________________

发展

运行测试

# Activate main environment
mamba activate ./env

# Run integration tests
python tests/run_integration_tests.py

# Run specific server tests
python tests/test_server.py

正在启动开发服务器

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

添加新工具

1. 添加工具功能 src/server.py 随着 @mcp.tool() 装饰器
2. 在中实现相应的脚本 scripts/ 目录
3. 将配置模板添加到 configs/
4. 使用工具文档更新此README
5. 将测试添加到 tests/

______________________________________________________________________

性能指南

何时使用同步与提交API

在以下情况下使用同步API：

• 数据集包含\100个序列
• 预期运行时间>10分钟
• 训练模型（分类）
• 批量处理多个文件
• 大规模分析

内存注意事项

• 小型数据集：\10000个序列→ 使用带有批处理的提交API

设备建议

• 仅CPU：有效但速度较慢，使用较小的批大小（batch_size=8）
• GPU（CUDA）：建议用于更快的处理（batch_size=32）
• 内存有限：首先使用带有estimate_memory=true的extract_dna_embeddings_v2

______________________________________________________________________

许可证

本项目建立在以下基础上：

• DNABERT-2：DNA序列分析模型（Apache 2.0许可证）
• FastMCP：模型上下文协议框架（MIT许可证）
• 变形金刚：拥抱脸部转换器库（Apache 2.0许可证）
• PyTorch深度学习框架（BSD 3条款许可证）

学分

基于 DNABERT-2 MAGICS LAB

DNABERT-2原始论文：“DNABERT-2:多物种基因组的高效基础模型和基准”