drfold2 MCP

DRfold2 MCP

使用具有端到端学习和几何优化的RNA复合语言模型（RCLM）进行从头计算RNA 3D结构预测。该MCP工具提供了对DRfold2高级深度学习模型的访问，用于RNA结构预测、系综生成和分子动力学改进。

目录

• 快速开始
• Claude代码集成
• 手动测试和开发
• 故障排除
• 可用工具
• 工作流示例
• Claude桌面集成
• Gemini CLI集成
• 用例脚本
• 演示数据
• 目录结构
• 特性
• 性能基准

快速开始

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• Python 3.11（经过测试和验证）
• CUDA（可选，用于GPU加速）

安装

对以下命令进行了测试并验证其有效性：

# Navigate to the MCP directory
cd drfold2_mcp

# Step 1: Create the conda environment
mamba create -p ./env python=3.11 pip -y

# Step 2: Activate the environment
eval "$(mamba shell hook --shell bash)" && mamba activate ./env

# Step 3: Install core dependencies
pip install torch numpy scipy biopython loguru click pandas tqdm

# Step 4: Install FastMCP with force reinstall
pip install --force-reinstall --no-cache-dir fastmcp

# Step 5: Download DRfold2 models and compile Arena
cd repo/DRfold2
bash install.sh
cd Arena
make Arena
cd ../../

可选：OpenMM安装用于结构优化

# Install OpenMM for molecular dynamics refinement
mamba activate ./env
mamba install -c conda-forge openmm -y

Claude代码集成（推荐）

Claude Code的安装

1. 完成环境设置 （以上步骤）

1. 使用Claude Code注册MCP服务器:

   # Navigate to your MCP directory (use full absolute path)
   cd /path/to/drfold2_mcp

   # Register server with Claude Code
   claude mcp add DRfold2 -- $(pwd)/env/bin/python3.11 $(pwd)/src/server.py

   # Verify registration
   claude mcp list
   # Should show: DRfold2: ... - ✓ Connected

1. 测试集成:

   # Open Claude Code
   claude
   # Now you can use all DRfold2 tools through natural language commands

Claude代码的快速测试命令

安装后，在Claude Code中尝试以下提示：

# Tool discovery
"What tools are available from DRfold2? Give me a brief description of each."

# Basic structure prediction (mock mode for testing)
"Use predict_rna_structure on examples/data/test_sequence.fasta with use_mock=true"

# Job workflow test
"Submit an ensemble prediction job for examples/data/test_sequence.fasta with use_mock=true, then check its status"

# Complete RNA analysis workflow
"I have an RNA sequence in examples/data/test_sequence.fasta. Walk me through a complete analysis:
1. First validate the sequence
2. Then predict its structure
3. Finally refine the structure
Use mock mode for all steps."

手动测试和开发

手动运行MCP服务器

# Activate environment (prefer mamba over conda)
mamba activate ./env  # or: conda activate ./env

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

# Or test tools directly
python -c "
from src.server import mcp
import asyncio
tools = asyncio.run(mcp.get_tools())
print(f'Found {len(tools)} tools: {list(tools)}')
"

集成测试

运行自动化测试以验证功能：

# Run simple integration tests
python tests/simple_integration_test.py

# Expected output: 6/6 tests passed (100% pass rate)

故障排除

常见问题及解决方案

1.服务器无法启动

# Check Python environment
which python
python --version

# Verify imports
python -c "from src.server import mcp; print('MCP server OK')"

# Check for missing dependencies
pip list | grep -E "fastmcp|loguru"

2.在Claude代码中找不到工具

# Verify server registration
claude mcp list | grep DRfold2

# Check server connection
claude mcp list
# Should show ✓ Connected next to DRfold2

3.模型下载问题

如果在模型下载过程中遇到SSL证书错误：

# Use mock mode for testing without models
# All tools support use_mock=true parameter

4.作业管理问题

# Check job directory
ls -la jobs/

# View recent job logs
tail -50 jobs/*/job.log

# Clear old jobs if needed
rm -rf jobs/old_job_id/

环境验证

# Complete system check
python -c "
import sys
print(f'Python: {sys.version}')

try:
    import torch
    print(f'PyTorch: {torch.__version__}')
except ImportError:
    print('PyTorch: Not installed')

try:
    import numpy
    print(f'NumPy: {numpy.__version__}')
except ImportError:
    print('NumPy: Not installed')

try:
    import fastmcp
    print(f'FastMCP: {fastmcp.__version__}')
except ImportError:
    print('FastMCP: Not installed')

from pathlib import Path
mcp_root = Path.cwd()
if (mcp_root / 'src' / 'server.py').exists():
    print('✅ MCP server file found')
else:
    print('❌ MCP server file missing')

if (mcp_root / 'examples' / 'data' / 'test_sequence.fasta').exists():
    print('✅ Test data found')
else:
    print('❌ Test data missing')
"

制作笔记

模拟模式与真实模式

• 模拟模式 (use_mock=true):

- 用于测试的快速合成预测 - 无需模型重量 - 现实的结构输出 - 建议开发

• 真实模式 (use_mock=false):

- 需要DRfold2型号重量（~1.3GB） - 完全预测精度 - 执行时间更长 - 推荐用于生产

绩效预期

Use predict_rna_structure with file examples/data/test_sequence.fasta Submit ensemble prediction for the test sequence with 4 models Check the status of job abc123

## 用例脚本

已创建并测试了以下脚本。 **备注**：完全执行需要模型权重（请参阅故障排除部分）。

|脚本|状态|描述|命令示例|
|--------|---------|-------------|-----------------|
| `examples/use_case_1_basic_prediction.py` | ⚠️ 需求模型|使用单一模型进行基本RNA结构预测| `mamba run -p ./env python examples/use_case_1_basic_prediction.py --input examples/data/test_sequence.fasta --output results/basic` |
| `examples/use_case_2_ensemble_prediction.py` | ⚠️ 需求模型|带聚类的多模型集成预测| `mamba run -p ./env python examples/use_case_2_ensemble_prediction.py --input examples/data/test_sequence.fasta --output results/ensemble --max-models 5` |
| `examples/use_case_3_structure_refinement.py` | ⚠️ 格式问题|OpenMM分子动力学改进| `mamba run -p ./env python examples/use_case_3_structure_refinement.py --input structure.pdb --output refined.pdb --steps 1000` |
| `examples/use_case_4_model_inference.py` | ⚠️ 需求模型|单个模型测试和分析| `mamba run -p ./env python examples/use_case_4_model_inference.py --input examples/data/test_sequence.fasta --model cfg_95 --analyze` |

### 执行状态

- **环境设置**: ✅ 完整-Python 3.11，已安装所有依赖项
- **竞技场汇编**: ✅ 完成-成功构建C++可执行文件
- **型号下载**: ❌ 失败-SSL证书问题阻止模型权重下载
- **脚本语法**: ✅ 完整-所有脚本在语法上都是正确的，并且能够正确处理错误

看 `reports/step4_execution.md` 查看详细的执行结果和故障排除信息。

## 演示数据

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

|文件|描述|大小|与一起使用|
|------|-------------|------|----------|
| `test_sequence.fasta` |测试RNA序列（30个核苷酸）： `UUGGGUUCCCUCACCCCAAUCAUAAAAAGG` |36字节|所有预测工具|
| `cfg_for_folding.json` |DRfold2的几何优化参数|518字节|结构细化|
| `cfg_for_selection.json` |模型选择配置参数|519字节|集合预测|

### 演示数据使用示例

**快速结构预测：**

Using MCP tool (in Claude Code)

Use predict_rna_structure with input from @examples/data/test_sequence.fasta

Using script directly

mamba run -p ./env python scripts/basic_prediction.py \ --input examples/data/test_sequence.fasta \ --output results/demo_structure.pdb \ --use-mock

**集成分析：**

Using MCP tool (in Claude Code)

Submit ensemble prediction for @examples/data/test_sequence.fasta with max_models 3

Using script directly

mamba run -p ./env python scripts/ensemble_prediction.py \ --input examples/data/test_sequence.fasta \ --output results/demo_ensemble \ --max-models 3 \ --use-mock

### 演示数据来源

- `test_sequence.fasta`：原始DRfold2测试序列来自 `repo/DRfold2/test/seq.fasta`
- `cfg_*.json`：从DRfold2优化脚本中提取的配置模板
- 所有文件均已验证RNA序列的有效性和正确的格式

## 已安装的软件包

安装在中的密钥包 `./env`:

- 火炬=2.9.1+cu128
- numpy=2.4.0
- SciPy=1.16.3
- 生物色素=1.86
- fastmcp=2.14.1
- loguru=0.7.3
- 单击=8.3.1
- 熊猫=2.3.3
- tqdm=4.67.1

用于结构优化的可选软件包：

- openmm（与conda/mamba单独安装）

## 目录结构

./ ├── README.md # This file ├── env/ # Main conda environment (Python 3.11) ├── src/ # MCP server source code (to be implemented) ├── examples/ # Use case scripts and demo data │ ├── use_case_1_basic_prediction.py │ ├── use_case_2_ensemble_prediction.py │ ├── use_case_3_structure_refinement.py │ ├── use_case_4_model_inference.py │ ├── data/ # Demo input data │ │ ├── test_sequence.fasta # Test RNA sequence │ │ ├── cfg_for_folding.json # Optimization parameters │ │ └── cfg_for_selection.json # Selection parameters │ └── README.md # Examples documentation ├── reports/ # Setup reports │ ├── step3_environment.md │ └── step3_use_cases.md └── repo/ # Original DRfold2 repository └── DRfold2/ ├── DRfold_infer.py ├── cfg_95/ # Model configuration 1 ├── cfg_96/ # Model configuration 2 ├── cfg_97/ # Model configuration 3 ├── cfg_99/ # Model configuration 4 ├── model_hub/ # Downloaded model weights (~1.3GB) ├── Arena/ # Structure relaxation tool ├── PotentialFold/ # Optimization suite └── script/ # Utility scripts

## 特性

### 核心能力

- **RNA复合语言模型（RCLM）**：增强协同进化信号捕获
- **多模式集合**：4种不同的型号配置（cfg95、cfg96、cfg97、cfg99）
- **端到端预测**：直接序列到3D结构预测
- **几何优化**：受距离限制的FAPE损失
- **结构聚类**：多种构象生成
- **竞技场放松**：基于物理的结构细化

### 用例分类

1. **基本预测** （高优先级，简单）

   - 单模型推理
   - 快速处理（约2-5分钟）
   - 适用于初步结构评估

1. **集合预报** （高优先级，中等）

   - 多模型共识
   - 聚类分析
   - 不同的构象（约10-20分钟）

1. **结构精修** （中等优先级，简单）

   - OpenMM分子动力学
   - 琥珀色力场
   - 能量最小化（~5-15分钟）

1. **模型分析** （低优先级，简单）

   - 单个模型测试
   - 原始预测访问
   - 研发

### GPU加速

所有用例都支持CUDA加速：

python examples/use_case_1_basic_prediction.py --device cuda

## 性能基准

根据提供的30个核苷酸序列进行测试：

|用例|CPU时间|GPU时间（如果可用）|输出|
|----------|----------|------------------------|--------|
|基本预测|~3-5分钟|~1-2分钟|单体三维结构|
|合奏（5个模型）|~15-25分钟|~5-10分钟|5个不同的结构|
|结构细化|~5-10分钟|~2-5分钟|结构细化|
|模型推断|~2-3分钟|~30秒|原始预测|

## 故障排除

### 模型文件丢失（主要问题）

如果遇到“找不到模型目录”错误：

**问题**：SSL证书问题阻止下载模型权重：

cd repo/DRfold2 bash install.sh # Fails with SSL error

**错误信息**:

OpenSSL: error:0A000438:SSL routines::tlsv1 alert internal error Unable to establish SSL connection.

**可能的解决方案**:

1. **替代下载方法**:

# Try with different SSL settings wget --no-check-certificate https://zhanggroup.org.com/DRfold2/res/model_hub.tar.gz # Or use curl with SSL bypass curl -k -L -o model_hub.tar.gz https://zhanggroup.org.com/DRfold2/res/model_hub.tar.gz

1. **手册下载**：直接在web浏览器中访问URL并手动下载

1. **联系人存储库**：向DRfold2维护人员提出问题

**所需文件**：下载内容应包含以下型号的重量（~1.3GB）：

- `model_hub/cfg_95/` -模型配置文件
- `model_hub/cfg_96/` -模型配置文件
- `model_hub/cfg_97/` -模型配置文件
- `model_hub/cfg_99/` -模型配置文件
- `model_hub/RCLM/epoch_67000` -RCLM主要型号重量

### 竞技场编译失败

如果结构松弛失败：

cd repo/DRfold2/Arena make clean make Arena

### OpenMM问题

对于结构细化问题：

**问题**：OpenMM期望具有末端基团的正确格式化的生物分子结构

ValueError: No template found for residue 61 (G). The atoms and bonds in the residue match G, but the set of externally bonded atoms is missing 1 O atom. Is the chain missing a terminal capping group?

**解决方案**:

1. **检查OpenMM安装**:

mamba run -p ./env python -c "import openmm; print('OpenMM working')"

1. **必要时重新安装**:

mamba install -p ./env -c conda-forge openmm --force-reinstall

1. **使用兼容结构**：OpenMM精制需要具有5'和3'末端的适当封端的RNA结构

### CUDA问题

如果GPU加速失败：

Check PyTorch CUDA support

python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"

### 内存问题

对于大序列或多个模型：

- 使用CPU模式： `--device cpu`
- 减小集合大小： `--max-models 2`
- 单独处理顺序

## 已知问题

### 安装依赖关系

- **竞技场编译**：需要C++编译器和make
- **OpenMM**：仅用于细化的可选依赖项
- **模型重量**：首次使用时需要大量下载（~1.3GB）

### 运行时间限制

- **序列长度**：最适合小于200个核苷酸的序列
- **内存使用**：GPU内存随序列长度而缩放
- **处理时间**：对于长序列，集合预测可能很耗时

## 备注

### 型号配置

- **cfg95、cfg96、cfg97、cfg99**：针对不同RNA类型优化的不同训练配置
- **集成方法**：结合预测以获得更好的准确性和置信度估计
- **RCLM架构**：使用基于转换器的语言模型来增强序列理解

### 输出格式

- **.pdb文件**：标准3D结构格式
- **.ret文件**：DRfold2内部格式，包含几何和能量数据
- **聚类结果**：具有构象分组的文本文件

### 环境变量

无需。所有路径都是相对于MCP目录的。

## 当前状态摘要

### ✅ 工作部件

- **环境**：具有所有核心依赖项的Python 3.11环境
- **竞技场工具**：C++可执行文件已编译并准备好进行结构松弛
- **OpenMM**：已成功安装用于分子动力学优化
- **用例脚本**：所有4个脚本语法正确，错误处理得当
- **示例数据**：测试序列和配置文件可用

### ❌ 已知问题

1. **模型权重**：由于SSL证书错误，无法下载（需要~1.3GB）
1. **OpenMM兼容性**：RNA结构需要适当的末端封端才能精制
1. **依赖链**：用例1、2和4需要模型权重才能执行

### 🔧 后续步骤

1. 解决模型重量下载问题（联系维护人员或使用其他方法）
1. 模型可用后，端到端测试用例
1. 为已验证的用例实现MCP服务器包装器
1. 为OpenMM兼容性添加结构准备管道

有关详细的执行日志和调试信息，请参阅 `reports/step4_execution.md`.

### 引用

如果您在研究中使用DRfold2，请引用：

@article{li2025drfold2, title={Ab initio RNA structure prediction with composite language model and denoised end-to-end learning}, author={Yang Li, Chenjie Feng, Xi Zhang, Yang Zhang.}, journal={}, year={2025} }