mxfold2 MCP

MXfold2 MCP

通过模型上下文协议（MCP）进行深度学习和热力学整合的RNA二级结构预测

目录

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

概述

MXfold2 MCP通过直接脚本使用和模型上下文协议（MCP）集成提供RNA二级结构预测功能。该工具将深度学习模型与热力学参数相结合，以准确预测RNA结构，提供传统的特纳模型方法和现代基于神经网络的方法。

特性

• 深度学习集成：具有热力学参数的神经网络（CNN、LSTM、Transformer）
• 多种型号：不同预测方法的Turner、Mix、MixC、Zuker变体
• 热力学基础：Turner 2004经典RNA折叠参数
• 灵活的输入/输出：FASTA输入、点括号/BPSEQ输出、能量评分
• 异步作业管理：对具有作业跟踪功能的大型数据集进行后台处理
• 综合分析：结构预测、模型比较、热力学分析

目录结构

./
├── README.md               # This file
├── env/                    # Main conda environment (Python 3.10)
├── env_py37/               # Legacy environment for MXfold2 (Python 3.7)
├── src/
│   ├── server.py           # MCP server
│   └── jobs/               # Job management system
├── scripts/
│   ├── rna_structure_prediction.py     # RNA structure prediction
│   ├── model_comparison.py             # Compare multiple models
│   ├── thermodynamic_analysis.py       # Thermodynamic analysis
│   ├── model_training_demo.py          # Training demonstration
│   └── lib/                            # Shared utilities
├── examples/
│   ├── data/               # Demo FASTA files
│   └── models/             # Pre-trained model files
├── configs/                # Configuration files
├── repo/                   # Original MXfold2 repository
└── reports/                # Documentation and test reports

______________________________________________________________________

安装

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• Python 3.10+（用于MCP服务器）
• Python 3.7+（用于MXfold2兼容性）
• Git（用于克隆存储库）

创造环境

此项目使用双环境设置来处理版本兼容性：

# Navigate to the MCP directory
cd /home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/mxfold2_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 main MCP environment (Python 3.10)
$PKG_MGR create -p ./env python=3.10 pip -y
$PKG_MGR run -p ./env pip install loguru click pandas numpy tqdm
$PKG_MGR run -p ./env pip install --force-reinstall --no-cache-dir fastmcp

# Create legacy environment for MXfold2 (Python 3.7)
$PKG_MGR create -p ./env_py37 python=3.7 -y
$PKG_MGR run -p ./env_py37 pip install torch==1.9.0 torchvision==0.10.0 numpy==1.21.0 tqdm pybind11

# Install MXfold2 in legacy environment
$PKG_MGR activate ./env_py37
pip install -e repo/mxfold2

验证安装

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

# Test legacy environment
$PKG_MGR run -p ./env_py37 python -c "import torch, mxfold2; print('MXfold2 available')"

______________________________________________________________________

本地使用（脚本）

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

可用脚本

脚本示例

RNA结构预测

# Activate legacy environment
mamba activate ./env_py37

# Basic prediction with Turner model
python scripts/rna_structure_prediction.py \
  --input examples/data/sample_rna.fa \
  --output results/prediction.json \
  --model Turner

# Use neural model with GPU
python scripts/rna_structure_prediction.py \
  --input examples/data/sample_rna.fa \
  --output results/mix_prediction.json \
  --model Mix \
  --gpu 0

参数：

• --input, -i：包含RNA序列的FASTA文件路径（必填）
• --output, -o：预测的输出文件路径（默认：stdout）
• --model, -m：型号类型（“特纳”、“混合”、“MixC”、“Zuker”）（默认：特纳）
• --gpu：GPU设备ID（CPU为-1）（默认值：-1）
• --verbose：启用详细输出

模型比较

# Compare multiple models
python scripts/model_comparison.py \
  --input examples/data/sample_rna.fa \
  --models Turner,Mix,MixC \
  --output results/comparison.csv

参数：

• --input, -i：包含RNA序列的FASTA文件路径（必填）
• --models, -m：逗号分隔的型号名称（默认：Turner、Mix）
• --output, -o：比较结果的输出文件路径
• --verbose：启用详细输出

热力学分析

# Detailed thermodynamic analysis
python scripts/thermodynamic_analysis.py \
  --input examples/data/sample_rna.fa \
  --output results/analysis.json \
  --detailed

参数：

• --input, -i：包含RNA序列的FASTA文件路径（必填）
• --output, -o：分析结果的输出文件路径
• --detailed：包括详细的结构特征
• --verbose：启用详细输出

培训演示

# Run training demonstration
python scripts/model_training_demo.py \
  --output results/training_demo \
  --model Mix \
  --epochs 3

参数：

• --output, -o：培训演示输出目录（必填）
• --model, -m：要模拟的模型类型（默认值：混合）
• --epochs, -e：训练周期数（默认值：3）
• --verbose：启用详细输出

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

# Activate main environment
mamba activate ./env

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

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

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

# Verify installation
claude mcp list

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

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

______________________________________________________________________

使用Claude代码

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

快速开始

# Start Claude Code
claude

示例提示

工具发现

What tools are available from mxfold2?

基本结构预测

Use predict_rna_structure with input_file @examples/data/sample_rna.fa and model "Turner"

模型比较

Use submit_model_comparison to compare Turner, Mix, and MixC models on @examples/data/sample_rna.fa

热力学分析

Use analyze_thermodynamics with input_file @examples/data/sample_rna.fa and detailed_analysis true

作业管理

Submit model comparison for @examples/data/sample_rna.fa comparing Turner and Mix models
Then check the job status

批处理

Process these files in batch:
- @examples/data/sample_rna.fa
- @examples/data/test_short.fa

使用@引用

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

______________________________________________________________________

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

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

示例提示

# Start Gemini CLI
gemini

# Example prompts (same as Claude Code)
> What tools are available?
> Use predict_rna_structure with file examples/data/sample_rna.fa

______________________________________________________________________

可用工具

快速操作（同步API）

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

作业管理工具

______________________________________________________________________

例子

示例1：基本结构预测

目标： 使用Turner模型预测RNA二级结构

使用脚本：

mamba activate ./env_py37
python scripts/rna_structure_prediction.py \
  --input examples/data/sample_rna.fa \
  --output results/example1/prediction.json \
  --model Turner \
  --verbose

使用MCP（克劳德代码）：

Use predict_rna_structure to process @examples/data/sample_rna.fa with Turner model and save results to results/example1/

预期产量：

• 带点括号结构预测的JSON文件
• 每个序列的MFE能量
• 处理元数据和定时信息

示例2：模型比较分析

目标： 比较相同序列上的Turner和Mix模型

使用脚本：

mamba activate ./env_py37
python scripts/model_comparison.py \
  --input examples/data/sample_rna.fa \
  --models Turner,Mix \
  --output results/example2/comparison.csv \
  --verbose

使用MCP（克劳德代码）：

Submit model comparison for @examples/data/sample_rna.fa comparing Turner and Mix models

预期产量：

• 带有并排模型比较的CSV文件
• 每个模型的性能指标
• 结构差异和能量比较

示例3：热力学分析

目标： 具有结构特征的详细热力学分析

使用脚本：

mamba activate ./env_py37
python scripts/thermodynamic_analysis.py \
  --input examples/data/sample_rna.fa \
  --output results/example3/analysis.json \
  --detailed \
  --verbose

使用MCP（克劳德代码）：

Use analyze_thermodynamics on @examples/data/sample_rna.fa with detailed_analysis true

预期产量：

• 详细的结构特征分析（碱基对、茎、环）
• 能量密度计算
• 所有序列的汇总统计数据

示例4：批处理

目标： 同时处理多个文件

使用脚本：

for f in examples/data/*.fa; do
  mamba run -p ./env_py37 python scripts/rna_structure_prediction.py --input "$f" --output results/batch/
done

使用MCP（克劳德代码）：

Submit batch processing for all FASTA files in @examples/data/

预期产量：

• 每个输入文件的单独预测文件
• 合并处理日志和统计数据
• 带有完成状态的作业跟踪

______________________________________________________________________

演示数据

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

示例数据详细信息

• sample_rna.fa：含有多种RNA类型，可进行全面检测
• test_short.fa：包含2个短序列（~30-50个核苷酸），用于快速检测

______________________________________________________________________

配置文件

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

配置示例

{
  "_description": "Configuration for RNA structure prediction",
  "model": "Turner",
  "gpu": -1,
  "output_format": "json",
  "include_metadata": true,
  "examples": {
    "basic": {
      "input": "examples/data/sample_rna.fa",
      "output": "results/prediction.json"
    }
  }
}

______________________________________________________________________

故障排除

环境问题

问题： 未找到环境

# Recreate environments
mamba create -p ./env python=3.10 -y
mamba create -p ./env_py37 python=3.7 -y
# Follow installation steps above

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

# Verify MXfold2 installation
mamba activate ./env_py37
python -c "import torch, mxfold2; print('Success')"

# Reinstall if needed
pip install -e repo/mxfold2

问题： FastMCP导入错误

# Reinstall fastmcp in main environment
mamba activate ./env
pip install --force-reinstall --no-cache-dir fastmcp

MCP问题

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

# Check MCP registration
claude mcp list

# Re-add if needed
claude mcp remove mxfold2
claude mcp add mxfold2 -- $(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()))
"

问题： 使用了错误的环境

# Verify correct Python interpreter
which python  # Should point to ./env/bin/python for MCP server

脚本问题

问题： 未找到MXfold2

# Check MXfold2 installation in legacy environment
mamba activate ./env_py37
python -c "import mxfold2; print(mxfold2.__file__)"

# Install if missing
cd repo/mxfold2
pip install -e .

问题： 找不到模型文件

# Check model files exist
ls -la examples/models/
# Should show TrainSetAB.conf and TrainSetAB.pth

# Copy from repo if missing
cp repo/mxfold2/mxfold2/models/* examples/models/

工作问题

问题： 作业挂起

# 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

问题： 磁盘上累积的作业

# Clean old job directories (optional)
find jobs/ -type d -name "????????" -mtime +7 -exec rm -rf {} \;

______________________________________________________________________

发展

运行测试

# Activate main environment
mamba activate ./env

# Run all tests
python tests/run_integration_tests.py

# Test specific functionality
python tests/test_mcp_server.py
python tests/test_tools_functionality.py

正在启动开发服务器

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

# Test with MCP inspector
npx @anthropic/mcp-inspector src/server.py

性能监控

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

# Check disk usage
du -sh jobs/ results/

______________________________________________________________________

许可证

该项目基于MXfold2软件构建。请参阅原始许可条款。

学分

基于 MXfold2 -使用热力学积分的深度学习进行RNA二级结构预测。

参考文献

• Sato K，Akiyama M，Sakakibara Y.使用热力学积分的深度学习预测RNA二级结构。自然通讯。 2021.
• 特纳DH，马修斯DH。NNDB：用于预测核酸二级结构稳定性的最近邻参数数据库。核酸研究。 2010.