nupack MCP

Nupack MCP

全面的核酸分析工具包，通过本地脚本和MCP服务器集成提供热力学分析、结构预测、序列设计、复杂平衡建模和能量评估。

目录

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

概述

NUPACK MCP为核酸计算生物学提供了一套全面的工具，包括热力学分析、二级结构预测、序列设计、复杂平衡建模和能量评估。该工具包既提供本地使用的独立Python脚本，也提供与Claude Code和其他MCP客户端无缝集成的集成MCP服务器。

特性

• 热力学分析：计算配分函数、自由能和温度依赖性
• 结构预测：使用最小自由能方法预测二次结构
• 序列设计：设计折叠成目标二级结构的序列
• 复杂平衡：分析多链核酸系统和竞争性结合
• 能源评价：详细的能源景观分析和参数敏感性研究
• 双API：同步（快速分析）和异步（长时间运行的任务）API
• 批处理：高效处理多个序列或文件
• 作业管理：后台处理的完整作业生命周期管理

目录结构

./
├── README.md               # This file
├── env/                    # Conda environment
├── src/
│   ├── server.py           # MCP server
│   └── jobs/               # Job management system
├── scripts/
│   ├── thermodynamic_analysis.py    # Thermodynamic analysis
│   ├── structure_prediction.py      # Structure prediction
│   ├── sequence_design.py          # Sequence design
│   ├── complex_equilibrium.py      # Complex equilibrium
│   ├── energy_evaluation.py        # Energy evaluation
│   └── lib/                        # Shared utilities
├── examples/
│   └── data/               # Demo data
│       ├── sequences/      # Test DNA/RNA sequences
│       ├── structures/     # Test secondary structures
│       └── parameters/     # Thermodynamic parameters
├── configs/                # Configuration files
└── repo/                   # Original NUPACK repository

______________________________________________________________________

安装

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• Python 3.10+

创建环境

请严格遵守中的信息 reports/step3_environment.md 以获得设置环境的程序。下面显示了一个示例工作流。

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

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

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

# Install core scientific computing packages
mamba install -c conda-forge numpy scipy pandas matplotlib seaborn jinja2 -y

# Install MCP dependencies
pip install fastmcp loguru --ignore-installed

______________________________________________________________________

本地使用（脚本）

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

可用脚本

脚本示例

热力学分析

# Activate environment
mamba activate ./env

# Run script
python scripts/thermodynamic_analysis.py \
  --sequences ATCGATCGATCG GGCCAATTCCGG \
  --material DNA \
  --temperature 37 \
  --output results/thermo.json

参数：

• --sequences：要分析的DNA/RNA序列（必填）
• --input-file：带序列的文件（每行一个）
• --material：核酸类型（DNA/RNA，默认值：DNA）
• --temperature：温度单位为摄氏度（默认值：37.0）
• --temp-scan：执行温度扫描分析
• --output：输出文件路径（默认值：results/）

结构预测

python scripts/structure_prediction.py \
  --sequence GGCCAATTCCGG \
  --material RNA \
  --energy-gap 5.0 \
  --output results/structure.json

参数：

• --sequence：要分析的DNA/RNA序列（必填）
• --input-file：带序列的文件
• --material：核酸类型（默认：RNA）
• --energy-gap：次优结构的能隙（默认值：5.0）
• --max-suboptimal：最大次优结构（默认值：10）

序列设计

python scripts/sequence_design.py \
  --target-structure "((((....))))" \
  --material DNA \
  --num-designs 5 \
  --output results/design.json

参数：

• --target-structure：用点括号表示的目标结构（必填）
• --material：核酸类型（默认值：DNA）
• --num-designs：要生成的设计数（默认值：5）
• --gc-content：目标GC含量（0.0-1.0）

复杂平衡

python scripts/complex_equilibrium.py \
  --strands ATCGATCGATCG CGAUCGAUCGAU \
  --concentrations 1e-6 1e-6 \
  --thermal-scan \
  --output results/equilibrium.json

参数：

• --strands：链序列列表（必填）
• --concentrations：初始浓度（单位：M）
• --material：核酸类型（默认值：DNA）
• --thermal-scan：执行温度扫描

能源评价

python scripts/energy_evaluation.py \
  --sequence GGCCAATTCCGG \
  --structure "((((....))))" \
  --material RNA \
  --landscape \
  --sensitivity \
  --output results/energy.json

参数：

• --sequence：DNA/RNA序列（必填）
• --structure：用点括号表示的二级结构（必填）
• --material：核酸类型（默认：RNA）
• --landscape：形成能源格局
• --sensitivity：执行参数敏感性分析

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

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

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

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

# Verify installation
claude mcp list

选项3：在settings.json中配置

添加到 ~/.claude/settings.json:

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

______________________________________________________________________

使用Claude代码

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

快速开始

# Start Claude Code
claude

示例提示

工具发现

What tools are available from NUPACK?

基本用法

Use analyze_thermodynamics with sequences ["ATCGATCGATCG", "GGCCAATTCCGG"] and material "DNA"

结构分析

Use predict_structure with sequence "GGCCAAUUCCGGAAGGCC" and material "RNA"

序列设计

Use design_sequence with target_structure "((((....))))" and material "DNA" and num_designs 3

长期运行任务（提交API）

Submit a thermodynamics analysis using submit_thermodynamics_analysis with sequences ["ATCGATCGATCG"] and material "DNA"
Then check the job status

批处理

Process these files in batch using submit_batch_nucleic_acid_analysis:
- @examples/data/sequences/test_dna.txt
- @examples/data/sequences/test_rna.txt

使用@引用

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

______________________________________________________________________

与Gemini CLI一起使用

配置

添加到 ~/.gemini/settings.json:

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

示例提示

# Start Gemini CLI
gemini

# Example prompts (same as Claude Code)
> What tools are available?
> Use analyze_thermodynamics with sequences ["ATCGATCGATCG"] and material "DNA"

______________________________________________________________________

可用工具

快速操作（同步API）

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

作业管理工具

______________________________________________________________________

例子

示例1：DNA发夹分析

目标： DNA发夹的热力学性质分析

使用脚本：

python scripts/thermodynamic_analysis.py \
  --input-file examples/data/sequences/test_dna.txt \
  --material DNA \
  --temperature 37 \
  --output results/hairpin_analysis/

使用MCP（克劳德代码）：

Use analyze_thermodynamics to process @examples/data/sequences/test_dna.txt with material "DNA"

预期产量：

• 单个序列热力学性质
• 自由能计算
• 温度依赖性分析

示例2:RNA结构预测

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

使用脚本：

python scripts/structure_prediction.py \
  --input-file examples/data/sequences/test_rna.txt \
  --material RNA \
  --energy-gap 5.0 \
  --output results/rna_structures/

使用MCP（克劳德代码）：

Use predict_structure with input_file "@examples/data/sequences/test_rna.txt" and material "RNA"

预期产量：

• 用点括号表示的MFE结构
• 能隙内的次优结构
• 碱基对概率

示例3：目标结构的序列设计

目标： 设计折叠成特定结构的DNA序列

使用脚本：

python scripts/sequence_design.py \
  --input-file examples/data/structures/test_structure.txt \
  --material DNA \
  --num-designs 5 \
  --output results/designed_sequences/

使用MCP（克劳德代码）：

Use design_sequence with input_file "@examples/data/structures/test_structure.txt" and material "DNA" and num_designs 5

预期产量：

• 多个设计序列
• 设计质量得分
• 结构兼容性度量

示例4：批处理

目标： 一次处理多个文件

使用脚本：

for f in examples/data/sequences/*.txt; do
  python scripts/thermodynamic_analysis.py --input-file "$f" --output results/batch/
done

使用MCP（克劳德代码）：

Submit batch processing using submit_batch_nucleic_acid_analysis with input_files ["@examples/data/sequences/test_dna.txt", "@examples/data/sequences/test_rna.txt"] and analysis_type "thermodynamics"

示例5：能源景观分析

目标： RNA结构的详细能量分析

使用脚本：

python scripts/energy_evaluation.py \
  --sequence GGCCAAUUCCGGAAGGCC \
  --structure "((((....))))" \
  --material RNA \
  --landscape \
  --sensitivity \
  --output results/energy_landscape/

使用MCP（克劳德代码）：

Use evaluate_energy with sequence "GGCCAAUUCCGGAAGGCC" and structure "((((....))))" and material "RNA" and landscape true and sensitivity true

______________________________________________________________________

演示数据

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

______________________________________________________________________

配置文件

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

配置示例

{
  "_description": "Thermodynamic analysis configuration",
  "_source": "thermodynamic_analysis.py",
  "model": {
    "material": "DNA",
    "temperature": 37.0,
    "total_concentration": 1e-6
  },
  "analysis": {
    "temp_scan": false,
    "temp_range": [25, 65, 5]
  },
  "output": {
    "format": "json",
    "precision": 3
  }
}

______________________________________________________________________

故障排除

环境问题

问题： 未找到环境

# Recreate environment
mamba create -p ./env python=3.10 -y
mamba activate ./env
mamba install -c conda-forge numpy scipy pandas matplotlib seaborn jinja2 -y
pip install fastmcp loguru

问题： 导入错误

# Verify installation
python -c "from src.server import mcp"
python -c "import numpy, scipy, pandas; print('Dependencies OK')"

MCP问题

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

# Check MCP registration
claude mcp list

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

问题： 工具不工作

# Test server directly
python -c "
from src.server import mcp
print('Server loaded successfully')
"

工作问题

问题： 作业挂起

# Check job directory
ls -la jobs/

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

问题： 任务失败

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

脚本问题

问题： 脚本执行失败

# Check input file format
head -5 examples/data/sequences/test_dna.txt

# Verify script help
python scripts/thermodynamic_analysis.py --help

问题： 序列格式无效

# Ensure sequences contain only valid nucleotides (A,T,C,G for DNA; A,U,C,G for RNA)
# Check for line breaks, spaces, or invalid characters

______________________________________________________________________

发展

运行测试

# Activate environment
mamba activate ./env

# Test scripts directly
python test_mcp_direct.py

# Test MCP integration
python test_real_world_scenarios.py

正在启动开发服务器

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

添加新工具

要添加新的NUPACK工具，请执行以下操作：

1. 在中创建脚本 scripts/ 遵循现有模式
2. 在中添加同步工具 src/server.py
3. 为长时间操作添加提交工具
4. 在中创建配置文件 configs/
5. 添加文档和示例

______________________________________________________________________

许可证

基于NUPACK核酸分析软件包。有关许可信息，请参阅原始存储库。

学分

基于 NUS包 -用于分析和设计的核酸包。

内置：

• 用于MCP服务器功能的FastMCP框架
• NumPy、SciPy、科学计算熊猫
• 用于演示和开发的模拟实现

______________________________________________________________________

集成状态： ✅ 已准备好与Claude Code和其他MCP客户端一起用于生产

可用工具

快速操作（同步API）

这些工具会立即返回结果：

长期运行任务（提交API）

这些工具返回job_id进行跟踪：

作业管理

工作流示例

快速分析（同步）

Use the analyze_thermodynamics tool with sequences ["ATCGATCGATCG", "GGCCAATTCCGG"] and material "DNA"

长期预测（异步）

1. Submit: Use submit_structure_prediction with sequence "GGCC"*100 and energy_gap 10.0
   → Returns: {"job_id": "abc123", "status": "submitted"}

2. Check: Use get_job_status with job_id "abc123"
   → Returns: {"status": "running", ...}

3. Get result: Use get_job_result with job_id "abc123"
   → Returns: {"status": "success", "result": {...}}

批处理

Use submit_batch_nucleic_acid_analysis with input_files ["file1.txt", "file2.txt", "file3.txt"] and analysis_type "structure"
→ Processes all files in a single job

发展

# Run tests
python test_direct.py
python test_submit.py

# Test server
fastmcp dev src/server.py

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

技术细节

单一环境方法：使用是因为Python 3.10+可用，它支持所有必需的依赖关系。这种方法提供了：

• 简化依赖关系管理
• 一致的软件包版本
• 更易于维护和部署

存储库分析

NUPACK来源分析

存储库包含NUPACK源代码，其中包含以下关键组件：

• 核心库：位于 repo/NUPACK/src/source/python/
• 参数文件：热力学参数 repo/NUPACK/src/source/parameters/
• 依赖项：scipy>=1.0，numpy>=1.17，pandas>=1.1.0，jinja2>=2.0

安装挑战

由于以下原因，直接安装NUPACK是不可行的：

1. C++后端的编译要求
2. setup.py中的占位符版本字符串(@PROJECT_VERSION@)
3. 通过pip/conda无法获得复杂的构建依赖关系

模拟实施策略

创建了全面的模拟实现，展示了：

• 基于源代码分析的真实的NUPACK API模式
• 使用简化模型进行真实的热力学计算
• 每个主要用例的完整工作流示例

验证示例

这些示例已经过测试和验证，可以与当前的环境设置一起使用：

示例1：热力学分析

# Activate environment (use mamba if available, otherwise conda)
mamba activate ./env  # or: conda activate ./env

# Run thermodynamic analysis with temperature scan
mamba run -p ./env python examples/use_case_1_thermodynamics.py \
  --sequences ATCGATCGATCG GGCCAATTCCGG \
  --material DNA \
  --temperature 37 \
  --parameter-file examples/data/parameters/dna04.json \
  --temp-scan \
  --output results/thermodynamics_output.json

# Expected output: results/thermodynamics_output.json with temperature-dependent free energies
# Execution time: ~0.5 seconds

示例2：结构预测

# Activate environment
mamba activate ./env

# Run structure prediction with suboptimal analysis
mamba run -p ./env python examples/use_case_2_structure_prediction.py \
  --sequence GGCCAATTCCGG \
  --material RNA \
  --temperature 37 \
  --energy-gap 2.0 \
  --output results/structure_output.json

# Expected output: MFE structure ((((....))) with base pair probabilities
# Execution time: ~0.5 seconds

示例3：序列设计

# Activate environment
mamba activate ./env

# Run sequence design for target structure
mamba run -p ./env python examples/use_case_3_sequence_design.py \
  --target-structure "((((....))))" \
  --material DNA \
  --temperature 37 \
  --num-designs 3 \
  --output results/design_output.json

# Expected output: 3 designed sequences that fold into target structure
# Execution time: ~0.5 seconds

示例4：复杂平衡

# Activate environment
mamba activate ./env

# Run complex equilibrium analysis
mamba run -p ./env python examples/use_case_4_complex_equilibrium.py \
  --strands ATCGATCGATCG CGAUCGAUCGAU \
  --concentrations 1e-6 1e-6 \
  --material DNA \
  --temperature 37 \
  --thermal-scan \
  --output results/equilibrium_output.json

# Expected output: Complex formation analysis with thermal stability data
# Execution time: ~0.8 seconds

示例5：能源评估

# Activate environment
mamba activate ./env

# Run energy evaluation with landscape analysis
mamba run -p ./env python examples/use_case_5_energy_evaluation.py \
  --sequence GGCCAATTCCGG \
  --structure "((((....))))" \
  --material RNA \
  --temperature 37 \
  --parameter-file examples/data/parameters/rna99.json \
  --landscape \
  --sensitivity \
  --output results/energy_output.json

# Expected output: Detailed energy breakdown and landscape analysis
# Execution time: ~0.5 seconds

用例

1.热力学分析(use_case_1_thermodynamics.py)

目的：计算核酸序列的热力学性质

特性:

• 分区函数计算
• 自由能评价
• 温度扫描（25-65°C）
• 复杂浓度分析
• 物质支持（DNA/RNA）

关键参数:

• --sequences：要分析的DNA/RNA序列
• --material：DNA或RNA
• --temperature：温度（摄氏度）
• --temp-scan：启用温度扫描
• --output：将结果保存到JSON文件

2.结构预测(use_case_2_structure_prediction.py)

目的：预测次级结构并分析结构组合

特性:

• 最小自由能（MFE）结构预测
• 次优结构枚举
• 基对概率矩阵
• 结构可视化
• 集成分析

关键参数:

• --sequence：要分析的单个序列
• --sequences-file：具有多个序列的文件
• --energy-gap：次优结构的能隙（kcal/mol）

3.序列设计(use_case_3_sequence_design.py)

目的：目标二级结构的设计顺序

特性:

• 靶标结构设计
• 多目标优化
• 设计约束检查
• 突变效应分析
• 基础配对优化

关键参数:

• --target-structure：用点括号表示的目标结构
• --target-structures：多目标设计的多个目标
• --sequence：突变分析的起始序列
• --constraints：具有设计约束的JSON文件

4.复杂平衡(use_case_4_complex_equilibrium.py)

目的：分析多链核酸系统中的平衡

特性:

• 多股复杂分析
• 竞争性约束研究
• 热稳定性分析
• 滴定实验模拟
• 复杂分布计算

关键参数:

• --strands：多链序列
• --concentrations：初始浓度（M）
• --thermal-scan：启用热稳定性分析
• --titration：启用滴定分析

5.能源评估(use_case_5_energy_evaluation.py)

目的：评估和分析结构能量

特性:

• 结构能量计算
• 能源景观分析
• 参数敏感性研究
• 能量分解
• 结构比较

关键参数:

• --sequence：要分析的序列
• --structure：用点括号表示的结构
• --structures-file：具有多个结构/序列对的文件
• --landscape：启用能源景观扫描
• --sensitivity：启用参数敏感性分析

演示数据

参数文件

位于 examples/data/parameters/:

• dna04.json：DNA热力学参数（2004年模型）
• rna99.json：RNA热力学参数（1999年模型）
• rna22.json：更新了RNA参数（2022年模型）

这些文件包含用于能量计算的最近邻热力学参数。

文件格式

输入序列：纯文本，每行一个序列 结构：点括号符号（例如。， (((...)))) 参数：JSON格式，含热力学数据 输出：带分析结果的JSON格式

开发笔记

模拟实现细节

模拟实现提供了NUPACK功能的真实演示：

1. 热力学模型：基于最近邻能量参数
2. 结构预测：简化的互补碱基配对规则
3. 序列设计：使用评分函数的迭代优化
4. 能量计算：GC内容和碱基配对贡献
5. 统计分析：正确的集合平均和概率计算

API模式

Mock实现遵循真实的NUPACK API模式：

# NUPACK-style API usage
model = MockModel(material='RNA', temperature=37.0)
sequences = [MockSequence(seq) for seq in sequence_list]
pfunc, free_energy = mock_pfunc(sequences, model)
structures = mock_mfe(sequences, model)

参数用法

演示参数文件是实际的NUPACK热力学参数：

• 从JSON格式加载
• 用于能量计算
• 支持DNA和RNA材料
• 温度相关缩放

依赖项

核心依赖关系

• numpy>=1.17.0：数值计算
• scipy>=1.0.0：科学计算
• pandas>=1.1.0：数据分析和操作
• matplotlib>=3.0.0：绘图和可视化
• seaborn>=0.11.0：统计数据可视化

开发依赖

• fastmcp：MCP服务器框架
• jinja2>=2.0：模板引擎
• argparse：命令行参数解析
• pathlib：路径操作实用程序

错误处理

这些示例包括以下全面的错误处理：

• 序列格式无效
• 缺少参数文件
• 结构符号不正确
• 温度范围验证
• 文件I/O操作

故障排除

常见问题及解决方法

问题：ModuleNotFoundation错误：没有名为“matplotlib”的模块

症状：UC-004（复杂平衡）失败，出现matplotlib导入错误

解决方案:

# Install matplotlib in the environment
mamba install -p ./env matplotlib --yes
# or if using conda
conda install -p ./env matplotlib --yes

为什么会这样：UC-004需要matplotlib进行热分析可视化，这在初始环境设置中没有包含。

问题：环境激活失败

症状: mamba activate ./env 返回“Shell未初始化”错误

解决方案:

# Use mamba run instead of shell activation
mamba run -p ./env python examples/use_case_1_thermodynamics.py [args...]

# OR initialize shell first
eval "$(mamba shell hook --shell bash)"
mamba activate ./env

问题：找不到参数文件

症状：脚本失败，出现“找不到参数文件”错误

解决方案: 确保您从正确的目录运行，并且存在参数文件：

# Check parameter files
ls examples/data/parameters/
# Should show: dna04.json rna99.json etc.

# Run from project root directory
python examples/use_case_1_thermodynamics.py --parameter-file examples/data/parameters/dna04.json

性能提示

• 所有示例在1秒内执行
• 使用 --output 保存结果以供以后分析
• 每次执行时加载一次参数文件
• 模拟实现随序列长度线性缩放

性能注意事项

模拟实现针对以下方面进行了优化：

• 适用于开发/测试的快速计算
• 真实的参数范围
• 内存高效的矩阵运算
• 可扩展到中等规模的问题

将来的扩展

扩展MCP服务器的潜在领域：

1. 与实际NUPACK编译集成
2. 高级可视化功能
3. 基于机器学习的预测
4. 高通量批量处理
5. 基于Web的界面集成

许可证

该实现遵循NUPACK的学术和研究使用模式。对于生产使用，请确保遵守NUPACK许可条款。

参考文献

• NUPACK：用于分析和设计的核酸包
• Nusback网络应用程序：http://www.nupack.org/
• 热力学模型和算法的原始NUPACK出版物

______________________________________________________________________

*注意：这是一个为MCP开发和演示目的而创建的模拟实现。对于实际的NUPACK功能，请按照官方安装说明安装编译后的NUPACK库。*