dnabert MCP

DNABERT MCP

使用预训练DNABERT模型进行DNA序列分析的模型上下文协议服务器

目录

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

概述

DNABERT MCP通过专门为基因组数据设计的预训练BERT模型提供强大的DNA序列分析功能。该服务器能够使用最先进的转换器架构进行DNA序列嵌入提取、序列分类和基因组变体分析。

特性

• DNA序列嵌入：从DNA序列中提取高维特征表示
• 多种文件格式：支持TSV和FASTA输入文件
• 批处理：通过后台作业处理高效处理大型数据集
• 内存优化：自动内存估计和批量大小优化
• GPU加速：CUDA和ROCm支持，具有自动CPU回退功能
• 作业管理：通过状态监视和结果检索跟踪长时间运行的任务

关键用例

• 启动子预测：DNA启动子序列分类的微调模型
• 序列分类：使用预训练模型预测和分类DNA序列
• 基因组变异分析：分析SNP和其他基因组变异的影响
• 模体识别：使用注意力模式识别重要的DNA序列基序
• 嵌入提取：为下游机器学习生成向量表示

目录结构

./
├── README.md               # This file
├── env/                    # MCP server environment (Python 3.10)
├── env_py36/              # DNABERT environment (Python 3.6)
├── src/
│   ├── server.py           # MCP server with 20 tools
│   └── jobs/               # Job management system
├── scripts/
│   ├── dna_sequence_embedding.py    # Basic embedding extraction
│   ├── dna_embedding_v2.py          # Enhanced version with shared libs
│   └── lib/                         # Shared utilities (I/O, DNA, model)
├── examples/
│   └── data/               # Demo datasets
│       ├── ft/6/           # Fine-tuning data (dev.tsv, train.tsv)
│       └── pre/            # Pre-training data (6_3k.txt)
├── configs/                # Configuration files
├── tests/                  # Test framework and validation
└── repo/                   # Original DNABERT repository

______________________________________________________________________

安装

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• Python 3.10+（用于MCP服务器）
• Python 3.6（用于DNABERT兼容性）
• 约8GB磁盘空间，适用于各种环境和型号

创造环境

该项目需要双环境：一个用于现代MCP服务器，另一个用于传统DNABERT兼容性。

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

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

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

# Create legacy environment for DNABERT (Python 3.6)
$PKG_MGR create -p ./env_py36 python=3.6 -y

# Activate main environment and install MCP dependencies
$PKG_MGR activate ./env
pip install fastmcp==2.14.1 loguru==0.7.3 pandas==2.3.3 numpy==2.2.6 tqdm==4.67.1

# Activate legacy environment and install DNABERT dependencies
$PKG_MGR activate ./env_py36
pip install torch==1.7.1 torchvision==0.8.2 transformers==2.5.0 numpy==1.19.5 pandas==1.1.5
pip install biopython==1.79 scikit-learn==0.24.2 scipy==1.5.4 tensorboard==2.9.0

# Install DNABERT in editable mode
cd repo/DNABERT && pip install --editable .
cd ../..

验证安装

# Test main environment
$PKG_MGR run -p ./env python -c "import fastmcp; print('✅ Main environment working')"

# Test legacy environment
$PKG_MGR run -p ./env_py36 python -c "import torch; print('✅ Legacy environment working')"

______________________________________________________________________

本地使用（脚本）

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

可用脚本

脚本示例

基本嵌入提取

# Activate DNABERT environment
mamba activate ./env_py36

# Basic usage with small dataset
mamba run -p ./env_py36 python scripts/dna_sequence_embedding.py \
  --input examples/data/ft/6/dev.tsv \
  --output results/embeddings \
  --batch-size 4 \
  --pooling cls

# Using configuration file
mamba run -p ./env_py36 python scripts/dna_sequence_embedding.py \
  --input examples/data/ft/6/dev.tsv \
  --output results/config_test \
  --config configs/dna_embedding_config.json \
  --batch-size 8

参数：

• --input, -i：带DNA序列的TSV文件路径（必填）
• --output, -o：结果输出目录（默认：自动生成）
• --batch-size：处理批大小（默认值：32）
• --pooling：池化策略：“cl”、“mean”、“max”（默认值：“cls”）
• --kmer：K-mer大小：3、4、5、6（默认值：6）
• --max-seq-length：最大序列长度（默认值：100）
• --device：计算设备：“auto”、“cuda”、“cpu”（默认值：“自动”）
• --config：JSON配置文件（可选）

增强版本（推荐）

# Memory estimation before processing
mamba run -p ./env_py36 python scripts/dna_embedding_v2.py \
  --input examples/data/ft/6/train.tsv \
  --estimate-memory

# Process with enhanced features
mamba run -p ./env_py36 python scripts/dna_embedding_v2.py \
  --input examples/data/ft/6/dev.tsv \
  --output results/enhanced \
  --batch-size 4 \
  --validate-sequences \
  --device auto

附加参数：

• --estimate-memory：仅估计内存使用情况，不进行处理
• --validate-sequences：在处理之前验证DNA序列（默认值：True）

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

# Install MCP server for Claude Code
mamba activate ./env
fastmcp install src/server.py --name DNABERT

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

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

# Verify installation
claude mcp list | grep DNABERT

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

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

______________________________________________________________________

使用Claude代码

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

快速开始

# Start Claude Code
claude

示例提示

工具发现

What tools are available from DNABERT?

基本用法

Use extract_dna_embeddings_v2 with input_file @examples/data/ft/6/dev.tsv

使用自定义参数

Extract embeddings from @examples/data/ft/6/dev.tsv using batch size 8 and mean pooling

内存估计

Estimate memory usage for @examples/data/ft/6/train.tsv using extract_dna_embeddings_v2

长期运行任务（提交API）

Submit a background job for @examples/data/ft/6/train.tsv using submit_dna_embeddings_v2
Then check the job status and retrieve results when complete

批处理

Process these files in batch:
- @examples/data/ft/6/dev.tsv
- @examples/data/ft/6/train.tsv
Save results to results/batch_output

使用@引用

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

______________________________________________________________________

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

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

示例提示

# Start Gemini CLI
gemini

# Example prompts (same as Claude Code)
> What tools are available from DNABERT?
> Use extract_dna_embeddings_v2 with examples/data/ft/6/dev.tsv
> Submit background job for large dataset processing

______________________________________________________________________

可用工具

快速操作（同步API）

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

其他提交参数：

• output_dir （可选）：保存所有输出的目录
• job_name （可选）：用于跟踪的自定义名称
• input_files （仅限批处理）：输入文件列表

作业管理工具

占位符工具（未来实施）

这些工具返回有用的错误消息，指示未来的实现：

• generate_dna_sequences -根据提示生成DNA序列
• predict_variant_effects -基因组变异致病性预测
• score_sequences -DNA序列质量评分

______________________________________________________________________

例子

示例1：快速嵌入分析

目标： 从小数据集中提取嵌入以进行探索性分析

使用脚本：

mamba run -p ./env_py36 python scripts/dna_embedding_v2.py \
  --input examples/data/ft/6/dev.tsv \
  --output results/quick_analysis \
  --batch-size 4 \
  --pooling cls

使用MCP（克劳德代码）：

Use extract_dna_embeddings_v2 to process @examples/data/ft/6/dev.tsv with batch size 4 and save results to results/quick_analysis

预期产量：

• embeddings.npy：1000×768嵌入矩阵
• sequence_metadata.csv：带索引的序列信息
• extraction_params.json：配置和时序细节

示例2：大数据集处理

目标： 使用后台作业处理完整的训练数据集

使用脚本：

# Memory estimation first
mamba run -p ./env_py36 python scripts/dna_embedding_v2.py \
  --input examples/data/ft/6/train.tsv \
  --estimate-memory

# Process with optimized settings
mamba run -p ./env_py36 python scripts/dna_embedding_v2.py \
  --input examples/data/ft/6/train.tsv \
  --output results/large_dataset \
  --batch-size 8

使用MCP（克劳德代码）：

First estimate memory for @examples/data/ft/6/train.tsv using extract_dna_embeddings_v2 with estimate_memory True

Then submit background job for @examples/data/ft/6/train.tsv using submit_dna_embeddings_v2 with output_dir "results/large_dataset"

Check job status and retrieve results when complete

示例3：批处理

目标： 一次处理多个文件

使用脚本：

for f in examples/data/ft/6/*.tsv; do
  echo "Processing $f"
  mamba run -p ./env_py36 python scripts/dna_embedding_v2.py \
    --input "$f" \
    --output "results/batch/$(basename "$f" .tsv)" \
    --batch-size 6
done

使用MCP（克劳德代码）：

Submit batch processing for files:
- @examples/data/ft/6/dev.tsv
- @examples/data/ft/6/train.tsv
Save all results to results/batch_processing

示例4：内存约束处理

目标： 在内存有限的机器上处理数据

使用脚本：

mamba run -p ./env_py36 python scripts/dna_embedding_v2.py \
  --input examples/data/ft/6/train.tsv \
  --output results/memory_constrained \
  --batch-size 2 \
  --max-seq-length 50 \
  --device cpu

使用MCP（克劳德代码）：

Process @examples/data/ft/6/train.tsv using extract_dna_embeddings_v2 with:
- batch_size 2
- max_seq_length 50
- device cpu
Save results to results/memory_constrained

______________________________________________________________________

演示数据

这 examples/data/ 目录包含经过验证的示例数据集：

数据格式

TSV格式（ft/目录）：

sequence	label
GTGGGG TGGGGA GGGGAG GGGAGG GGAGGG...	0
GTGTGG TGTGGG GTGGGA TGGGAT GGGATC...	0

• 第1栏： sequence -空格分隔的k-mer标记（k=6）
• 第2栏： label -二进制分类标签（0或1）

TXT格式（前置/目录）：

GTGGGG TGGGGA GGGGAG GGGAGG GGAGGG
TGGGGA GGGGAG GGGAGG GGAGGG GAGGGA

• 用于预训练的原始k-mer序列

______________________________________________________________________

配置文件

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

dna_embedding_configure.json

DNA包埋提取的完整配置：

{
  "_description": "Configuration for DNA sequence embedding extraction using DNABERT",

  "model": {
    "kmer": 6,
    "model_path": "examples/models/dnabert-6-real",
    "device": "auto"
  },

  "processing": {
    "max_seq_length": 100,
    "batch_size": 32,
    "pooling": "cls"
  },

  "output": {
    "save_format": "npy",
    "include_attention": true
  },

  "examples": {
    "small_dataset": {
      "input": "examples/data/ft/6/dev.tsv",
      "description": "1000 sequences for testing",
      "batch_size": 2
    },
    "large_dataset": {
      "input": "examples/data/ft/6/train.tsv",
      "description": "32366 sequences for production",
      "batch_size": 8
    }
  },

  "performance": {
    "cpu_batch_size": 4,
    "gpu_batch_size": 32,
    "memory_efficient": {
      "batch_size": 2,
      "max_seq_length": 100
    }
  }
}

关键参数：

• model.kmer：K-mer尺寸（3、4、5、6）-必须与预先训练的模型相匹配
• processing.batch_size：同时处理的序列数
• processing.pooling：嵌入聚合策略
• performance.*：硬件优化设置

______________________________________________________________________

故障排除

环境问题

问题： 未找到环境

# Recreate environments
mamba create -p ./env python=3.10 -y
mamba create -p ./env_py36 python=3.6 -y

# Reinstall dependencies (see Installation section)

问题： DNABERT环境中的导入错误

# Verify DNABERT installation
mamba run -p ./env_py36 python -c "from repo.DNABERT.src.transformers import BertModel; print('✅ DNABERT working')"

# Reinstall DNABERT if needed
mamba activate ./env_py36
cd repo/DNABERT && pip install --editable . && cd ../..

MCP问题

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

# Check MCP registration
claude mcp list | grep DNABERT

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

# Verify with development server
mamba activate ./env
fastmcp dev src/server.py

问题： 工具工作不正常

# Test server directly
mamba run -p ./env python -c "
from src.server import mcp
tools = list(mcp.list_tools().keys())
print(f'Found {len(tools)} tools: {tools[:5]}...')
"

# Validate script functionality
python tests/validate_mcp_functionality.py

工作问题

问题： 作业处于待处理状态

# Check job directory
ls -la jobs/

# View job details
ls jobs/*/
cat jobs/*/job.log

问题： 作业失败，出现错误

Use get_job_log with job_id "" and tail 50 to see detailed error information

问题： 内存不足错误

# Reduce batch size
--batch-size 2

# Use CPU instead of GPU
--device cpu

# Reduce sequence length
--max-seq-length 50

模型问题

问题： 未找到DNABERT模型

# Download pre-trained model
python download_model.py

# Verify model path in config
grep model_path configs/dna_embedding_config.json

问题： CUDA内存不足

# Force CPU usage
--device cpu

# Reduce batch size
--batch-size 1

# Check GPU memory
nvidia-smi  # if NVIDIA GPU available

数据问题

问题： 输入文件格式无效

# Check file format
head -3 your_file.tsv

# Expected format:
# sequence	label
# GTGGGG TGGGGA GGGGAG ...	0

问题： DNA序列验证错误

# Use validation in v2
--validate-sequences

# Check for invalid characters (should only be A, T, C, G, and spaces)
grep -v "^[ATCG ]*\t[01]$" your_file.tsv

______________________________________________________________________

发展

运行测试

# Activate main environment
mamba activate ./env

# Run automated validation
python tests/validate_mcp_functionality.py

# Test specific components
python test_server_functions.py
python test_sync_tool.py

正在启动开发服务器

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

# Server will start on http://localhost:6277 with MCP inspector

性能监控

# Monitor job execution
tail -f jobs/*/job.log

# Check system resources
htop  # CPU and memory usage
nvidia-smi  # GPU usage (if available)

______________________________________________________________________

许可证

此项目基于原始的DNABERT实现。有关许可的详细信息，请参阅原始存储库。

学分

基于 DNABERT：来自Transformers模型的预训练双向编码器表示，用于基因组中的DNA语言

• 原始存储库: 德纳伯特
• 纸张: 核酸研究，2021
• 作者：季艳蓉、周志涵、刘汉、罗摩那五世

支持

对于问题和疑问：

1. 查看此README和故障排除部分
2. 在中运行验证测试 tests/
3. 查看中的详细文档 reports/
4. 在存储库中为错误或功能请求创建问题