viennarna MCP

维也纳RNA MCP

集成模型上下文协议（MCP）的RNA二级结构预测和分析工具包

目录

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

概述

该MCP使用ViennaRNA Package 2.7.1提供全面的RNA二级结构预测和分析。它既提供用于交互式使用的快速同步操作，也提供用于大规模分析的后台异步处理。

特性

• MFE结构预测：最小自由能二次结构计算
• 分区函数分析：热力学系综性质和碱基配对概率
• 次优结构：生成指定能量范围内的所有结构
• 共识结构预测：从多个序列比对中预测共识结构
• 结构比较：使用多种距离度量比较RNA结构
• 玻尔兹曼抽样：热力学系综的示例结构
• 批处理：高效处理多个序列
• 作业管理：对长时间运行的任务进行完整的生命周期管理

目录结构

./
├── README.md               # This file
├── env/                    # Conda environment
├── src/
│   └── server.py           # MCP server
├── scripts/
│   ├── mfe_prediction.py              # MFE structure prediction
│   ├── partition_function.py          # Partition function calculation
│   ├── suboptimal_structures.py       # Suboptimal structure generation
│   ├── consensus_structure.py         # Consensus structure prediction
│   ├── structure_comparison.py        # RNA structure comparison
│   ├── boltzmann_sampling.py          # Boltzmann ensemble sampling
│   └── lib/                           # Shared utilities
├── examples/
│   └── data/               # Demo data
├── configs/                # Configuration files
└── repo/                   # Original ViennaRNA repository

______________________________________________________________________

安装

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• Python 3.10+
• 维也纳RNA包2.7.1

创建环境

根据环境设置报告，执行以下步骤：

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

# Create conda environment (use mamba if available)
mamba create -p ./env python=3.12 -y
# or: conda create -p ./env python=3.12 -y

# Activate environment
mamba activate ./env
# or: conda activate ./env

# Install ViennaRNA from bioconda
mamba install -c bioconda viennarna -y

# Install Python dependencies
mamba run -p ./env pip install loguru click pandas numpy tqdm

# Install MCP dependencies
mamba run -p ./env pip install --force-reinstall --no-cache-dir fastmcp

验证

# Test ViennaRNA import
mamba run -p ./env python -c "import RNA; print('ViennaRNA successfully imported!')"

# Test basic folding
mamba run -p ./env python -c "import RNA; print('MFE test:', RNA.fold('GAGUAGUG')[1])"

______________________________________________________________________

本地使用（脚本）

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

可用脚本

脚本示例

MFE结构预测

# Activate environment
mamba activate ./env

# Run with sequence
python scripts/mfe_prediction.py \
  --sequence "GAGUAGUGGAACCAGGCUAUGUUUGUGACUCGCAGACUAACA"

# Run with input file
python scripts/mfe_prediction.py \
  --input examples/data/simple_rna.seq \
  --output results/mfe_output.txt

参数：

• --sequence, -s：RNA序列字符串（如果没有输入文件，则需要）
• --input, -i：序列文件的路径（序列的替代）
• --output, -o：输出文件路径（默认：stdout）
• --temperature, -t：温度单位为摄氏度（默认值：37.0）

配分函数计算

python scripts/partition_function.py \
  --input examples/data/simple_rna.seq \
  --save-probabilities \
  --output results/partition/

参数：

• --input, -i：输入序列文件（必填）
• --sequence, -s：直接序列字符串（替代输入）
• --output, -o：输出目录（默认：results/）
• --save-probabilities：保存碱基对概率
• --temperature, -t：温度单位为摄氏度（默认值：37.0）

共识结构预测

python scripts/consensus_structure.py \
  --alignment examples/data/demo_alignment.fa \
  --show-individual \
  --output results/consensus/

参数：

• --alignment, -a：多序列比对文件（必填）
• --output, -o：输出目录（默认：results/）
• --show-individual：显示单个结构预测
• --temperature, -t：温度单位为摄氏度（默认值：37.0）

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

# Install MCP server for Claude Code
cd /home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/viennarna_mcp
fastmcp install src/server.py --name ViennaRNA

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

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

# Verify installation
claude mcp list

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

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

______________________________________________________________________

使用Claude代码

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

快速开始

# Start Claude Code
claude

示例提示

工具发现

What tools are available from ViennaRNA?

MFE基本预测

Use predict_mfe_structure with sequence "GGGAAACCC"

基于文件的分析

Use predict_mfe_structure with input_file @examples/data/simple_rna.seq

分区函数分析

Use calculate_partition_function with sequence "GGGAAACCC" and save_probabilities True

一致性共识结构

Use predict_consensus_structure with alignment_file @examples/data/demo_alignment.fa

结构比较

Use compare_rna_structures with structure1 "((.....))" and structure2 "((....))"

长期运行任务（提交API）

Submit suboptimal structure generation for sequence "GGGGAAAACCCC" with energy_range 10.0
Then check job status

批处理

Submit batch MFE prediction for sequences ["GGGAAACCC", "AAAUUUGGG", "CCCCUUUUGGGG"]

使用@引用

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

______________________________________________________________________

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

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

示例提示

# Start Gemini CLI
gemini

# Example prompts (same as Claude Code)
> What tools are available?
> Use predict_mfe_structure with sequence "GGGAAACCC"

______________________________________________________________________

可用工具

快速操作（同步API）

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

作业管理工具

______________________________________________________________________

例子

示例1：单序列结构预测

目标： 预测单个RNA序列的二级结构

使用脚本：

python scripts/mfe_prediction.py \
  --sequence "GAGUAGUGGAACCAGGCUAUGUUUGUGACUCGCAGACUAACA" \
  --output results/single_sequence/

使用MCP（克劳德代码）：

Use predict_mfe_structure to process sequence "GAGUAGUGGAACCAGGCUAUGUUUGUGACUCGCAGACUAACA"

预期产量：

• 用点括号表示的二级结构
• 最小自由能（kcal/mol）
• 序列长度和组成

示例2：来自对齐的共识结构

目标： 从多个序列预测共识二级结构

使用脚本：

python scripts/consensus_structure.py \
  --alignment examples/data/demo_alignment.fa \
  --show-individual \
  --output results/consensus/

使用MCP（克劳德代码）：

Use predict_consensus_structure with alignment_file @examples/data/demo_alignment.fa and show_individual True

预期产量：

• 共识顺序和结构
• 单个序列预测
• 共识能源和统计

示例3：结构对比分析

目标： 比较两种RNA二级结构

使用脚本：

python scripts/structure_comparison.py \
  --file1 examples/data/structure1.db \
  --file2 examples/data/structure2.db \
  --show-details

使用MCP（克劳德代码）：

Use compare_rna_structures with file1 @examples/data/structure1.db and file2 @examples/data/structure2.db

预期产量：

• 基对距离
• 树编辑距离
• Jaccard相似性
• F1得分和详细指标

示例4：批量处理多个序列

目标： 高效处理多个序列

使用脚本：

for seq in "GGGAAACCC" "AAAUUUGGG" "CCCCUUUUGGGG"; do
  python scripts/mfe_prediction.py --sequence "$seq" --output results/batch/
done

使用MCP（克劳德代码）：

Submit batch MFE prediction for sequences ["GGGAAACCC", "AAAUUUGGG", "CCCCUUUUGGGG"]

预期产量：

• 用于跟踪的批处理作业ID
• 每个序列的单独结果
• 所有序列的汇总统计数据

示例5：大规模次优分析

目标： 生成大量次优结构

使用MCP（克劳德代码）：

Submit suboptimal structure generation for sequence "GGGGAAAACCCC" with energy_range 15.0 and max_structures 5000

监控进度：

Check job status for the submitted job
Get job log to see detailed progress
Get job result when completed

______________________________________________________________________

演示数据

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

______________________________________________________________________

配置文件

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

配置示例

{
  "temperature": 37.0,
  "energy_range": 5.0,
  "max_structures": 100,
  "output_format": "detailed"
}

______________________________________________________________________

故障排除

环境问题

问题： 未找到环境

# Recreate environment
mamba create -p ./env python=3.12 -y
mamba activate ./env
mamba install -c bioconda viennarna -y
pip install fastmcp loguru

问题： 导入错误

# Verify ViennaRNA installation
python -c "import RNA; print('ViennaRNA version:', RNA.version())"

# Verify MCP installation
python -c "from fastmcp import FastMCP; print('FastMCP imported successfully')"

MCP问题

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

# Check MCP registration
claude mcp list

# Re-add if needed
claude mcp remove ViennaRNA
fastmcp install src/server.py --name ViennaRNA

问题： 工具不工作

# Test server directly
cd /home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/viennarna_mcp
mamba run -p ./env python src/server.py

问题： Python路径问题

# Set Python path for shared libraries
export PYTHONPATH=./scripts:$PYTHONPATH
mamba run -p ./env python src/server.py

工作问题

问题： 作业挂起

# Check job directory
ls -la jobs/

# View job log
cat jobs//job.log

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

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

问题： 作业文件权限被拒绝

# Fix permissions
chmod -R 755 jobs/

脚本问题

问题： 未找到脚本

# Verify scripts directory
ls -la scripts/

# Check script permissions
chmod +x scripts/*.py

问题： ViennaRNA算法错误

# Test basic RNA folding
mamba run -p ./env python -c "import RNA; print(RNA.fold('GGGAAACCC'))"

______________________________________________________________________

发展

运行测试

# Activate environment
mamba activate ./env

# Set Python path
export PYTHONPATH=./scripts:$PYTHONPATH

# Run comprehensive tests
python test_mcp_fixed.py

正在启动开发服务器

# Run MCP server in dev mode
cd src
mamba run -p ../env python server.py

# Or use fastmcp dev mode
fastmcp dev src/server.py

添加新工具

1. 在中创建新脚本 scripts/
2. 将配置添加到 configs/
3. 在中添加MCP工具包装 src/server.py
4. 更新此README文档

______________________________________________________________________

性能指南

何时使用同步与提交API

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

• 单序列（\10个序列）
• 能量范围大（>10千卡/摩尔）
• 广泛采样（>100个样本）
• 大型比对（>20个序列）
• 工作流集成

内存使用

______________________________________________________________________

许可证

该项目基于维也纳RNA包2.7.1。

学分

基于 维也纳RNA包装 由维也纳RNA项目。

• 维也纳RNA包装：全面的RNA二级结构分析
• FastMCP：模型上下文协议框架
• MCP集成：定制实现无缝LLM集成

______________________________________________________________________

摘要

✅ 17个MCP工具 -完整的RNA分析覆盖率 ✅ 双API设计 -同步速度，提交比例 ✅ 作业管理系统 -具有持久性的完整生命周期 ✅ 6个独立脚本 -无需MCP即可直接使用 ✅ 综合测试 -所有核心功能均已验证 ✅ 生产就绪 -具有日志记录和监控功能的强大服务器 🚀 准备部署 -与Claude Code和Gemini CLI兼容

工具总数：17（5个作业管理+6个同步+5个提交+1个批次） 框架：FastMCP 2.14.1+维也纳RNA 2.7.1 环境：使用曼巴/康达的Python 3.12 安装时间：与曼巴共度约2-3分钟