rnafm MCP

RNA-FM-MCP

由RNA基金会模型支持的RNA序列分析工具，可通过模型上下文协议（MCP）访问

目录

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

概述

此MCP服务器提供对RNA基础模型（RNA-FM）功能的访问，用于分析RNA序列。它为快速分析提供了同步工具，为长时间运行的任务提供了异步（提交）API，并为测试和开发提供了全面的回退模式。

特性

• RNA序列包埋：使用RNA-FM提取640维上下文表示
• 二级结构预测：使用概率矩阵预测碱基配对模式
• RNA分类：使用嵌入+K-means进行功能聚类和家族分类
• 作业管理：提交具有进度跟踪和日志监控功能的长时间运行的任务
• 批处理：通过综合分析同时处理多个文件
• 模拟模式：快速生成回退，无需GPU即可进行测试

目录结构

./
├── README.md               # This file
├── env/                    # Main MCP environment (Python 3.10)
├── env_py38/              # Legacy environment for RNA-FM (Python 3.8)
├── src/
│   └── server.py           # MCP server with 11 tools
├── scripts/
│   ├── rna_embeddings.py      # Extract RNA sequence embeddings
│   ├── secondary_structure.py # Predict RNA secondary structure
│   ├── rna_classification.py  # Classify and cluster RNA sequences
│   └── lib/                   # Shared utilities
├── examples/
│   └── data/               # Demo FASTA files and configs
├── configs/                # Configuration templates
│   ├── rna_embeddings_config.json
│   ├── secondary_structure_config.json
│   └── rna_classification_config.json
└── repo/                   # Original RNA-FM repository

______________________________________________________________________

安装

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• MCP服务器的Python 3.10+
• RNA-FM模型的Python 3.8.11（可选，有回退）

创建环境

请严格遵守双环境设置程序 reports/step3_environment.md示例工作流程如下。

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

# Create main MCP environment (Python 3.10 for MCP server)
mamba create -p ./env python=3.10 -y
# or: conda create -p ./env python=3.10 -y

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

# Install MCP dependencies
pip install fastmcp loguru pandas numpy tqdm

# Optional: Create legacy environment for real RNA-FM models (Python 3.8)
mamba create -p ./env_py38 python=3.8.11 pytorch=1.9.0 cudatoolkit=11.1.1 -c pytorch -c conda-forge -y
mamba activate ./env_py38
pip install biopython scikit-learn matplotlib

______________________________________________________________________

本地使用（脚本）

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

可用脚本

脚本示例

RNA包埋物提取

# Activate environment (main env is sufficient for mock mode)
mamba activate ./env

# Run with mock embeddings (fast, no GPU required)
python scripts/rna_embeddings.py \
  --input examples/data/example.fasta \
  --output results/embeddings \
  --use-mock

# Run with real RNA-FM model (requires env_py38 + GPU)
mamba activate ./env_py38
python scripts/rna_embeddings.py \
  --input examples/data/example.fasta \
  --output results/embeddings \
  --config configs/rna_embeddings_config.json

参数：

• --input, -i：包含RNA序列的FASTA文件路径（必填）
• --output, -o：保存嵌入的输出目录（默认：results/）
• --use-mock：使用确定性模拟嵌入而不是RNA-FM模型
• --config, -c：配置文件路径（可选）

二级结构预测

# Run with mock predictions (fast)
python scripts/secondary_structure.py \
  --input examples/data/example.fasta \
  --output results/structures \
  --use-mock \
  --threshold 0.5

# Run with real RNA-FM ResNet model
mamba activate ./env_py38
python scripts/secondary_structure.py \
  --input examples/data/RF00005.fasta \
  --output results/structures \
  --threshold 0.6 \
  --formats npy txt ct

参数：

• --input, -i：包含RNA序列的FASTA文件路径（必填）
• --output, -o：输出目录（默认：results/）
• --threshold, -t：基本对概率阈值（默认值：0.5）
• --use-mock：使用模拟结构预测
• --formats：输出格式：npy、txt、ct（默认：全部）

RNA分类和聚类

# Classify tRNA sequences into functional families
python scripts/rna_classification.py \
  --input examples/data/RF00005.fasta \
  --output results/classification \
  --clusters 3 \
  --use-mock \
  --pca-components 50

参数：

• --input, -i：包含RNA序列的FASTA文件路径（必填）
• --output, -o：输出目录（默认：results/）
• --clusters, -c：K-means的簇数（默认值：3）
• --use-mock：使用模拟嵌入进行分类
• --pca-components：用于可视化的PCA维度（默认值：50）

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

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

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

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

# Verify installation
claude mcp list

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

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

______________________________________________________________________

使用Claude代码

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

快速开始

# Start Claude Code
claude

示例提示

工具发现

What RNA analysis tools are available from RNA-FM?

基本RNA包埋

Extract RNA embeddings from @examples/data/example.fasta using mock mode

具有配置的二级结构

Predict secondary structure for @examples/data/RF00001.fasta with threshold 0.6 using @configs/secondary_structure_config.json

RNA分类

Classify RNA sequences in @examples/data/RF00005.fasta into 3 functional clusters using mock embeddings

长期运行任务（提交API）

Submit RNA classification for @examples/data/format_rnacentral_active.100.sample-Max50.fasta with 5 clusters
Then check the job status

批处理

Process these files in batch with all analysis types:
- @examples/data/RF00001.fasta
- @examples/data/RF00005.fasta
- @examples/data/RF00010.fasta

使用@引用

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

______________________________________________________________________

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

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

示例提示

# Start Gemini CLI
gemini

# Example prompts (similar to Claude Code)
> What RNA tools are available?
> Extract embeddings from examples/data/example.fasta
> Classify RNA sequences in examples/data/RF00005.fasta

______________________________________________________________________

可用工具

快速操作（同步API）

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

作业管理工具

______________________________________________________________________

例子

示例1：RNA序列包埋

目标： 从RNA序列中提取上下文嵌入用于下游分析

使用脚本：

mamba activate ./env
python scripts/rna_embeddings.py \
  --input examples/data/example.fasta \
  --output results/example1/ \
  --use-mock

使用MCP（克劳德代码）：

Extract RNA embeddings from @examples/data/example.fasta using mock mode and save to results/example1/

预期产量：

• 3ktw_C_embeddings.npy：640个暗嵌入（96 x 640）
• 2der_D_embeddings.npy：640个暗嵌入（72 x 640）
• 1p6v_B_embeddings.npy：640个暗嵌入（45 x 640）
• embeddings_summary.txt：处理统计数据

示例2：二级结构预测

目标： 预测RNA碱基配对模式和二级结构

使用脚本：

python scripts/secondary_structure.py \
  --input examples/data/RF00001.fasta \
  --output results/example2/ \
  --use-mock \
  --threshold 0.5

使用MCP（克劳德代码）：

Predict secondary structure for @examples/data/RF00001.fasta with threshold 0.5 using mock mode

预期产量：

• *_probability_matrix.npy：基对概率矩阵
• *_structure.txt：具有碱基对的人类可读结构
• *_structure.ct：连接表格格式文件
• structure_summary.txt：处理摘要

示例3:RNA功能分类

目标： 将RNA序列分为功能家族

使用脚本：

python scripts/rna_classification.py \
  --input examples/data/RF00005.fasta \
  --output results/example3/ \
  --clusters 3 \
  --use-mock

使用MCP（克劳德代码）：

Classify tRNA sequences in @examples/data/RF00005.fasta into 3 functional clusters using mock embeddings

预期产量：

• cluster_assignments.json：序列到集群的映射
• embeddings.npy：全嵌入矩阵（954 x 640）
• embeddings_pca.npy：PCA减少嵌入（954 x 50）
• cluster_analysis.json：聚类统计和轮廓分数
• classification_summary.txt：处理摘要

示例4：批处理

目标： 通过综合分析处理多个RNA文件

使用脚本：

for f in examples/data/RF*.fasta; do
  python scripts/rna_embeddings.py --input "$f" --output results/batch/ --use-mock
  python scripts/secondary_structure.py --input "$f" --output results/batch/ --use-mock
  python scripts/rna_classification.py --input "$f" --output results/batch/ --use-mock
done

使用MCP（克劳德代码）：

Submit batch RNA analysis for all files:
- @examples/data/RF00001.fasta
- @examples/data/RF00005.fasta
- @examples/data/RF00010.fasta

Process with all analysis types using mock mode

______________________________________________________________________

演示数据

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

______________________________________________________________________

配置文件

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

配置示例

{
  "model": {
    "type": "rna-fm",
    "embedding_dim": 640,
    "device": "cuda"
  },
  "processing": {
    "batch_size": 8,
    "use_mock": false
  },
  "mock_generation": {
    "nucleotide_bias": {"A": 0.1, "U": 0.2, "G": 0.3, "C": 0.4},
    "positional_encoding_strength": 0.5
  }
}

______________________________________________________________________

故障排除

环境问题

问题： 未找到环境

# Recreate main environment
mamba create -p ./env python=3.10 -y
mamba activate ./env
pip install fastmcp loguru pandas numpy tqdm

问题： 脚本中的导入错误

# Verify environment activation
which python
python -c "import numpy, pathlib, json; print('Core imports OK')"

问题： 真实模型的遗留环境

# Create legacy environment for RNA-FM
mamba create -p ./env_py38 python=3.8.11 pytorch=1.9.0 cudatoolkit=11.1.1 -c pytorch -y
mamba activate ./env_py38
pip install biopython scikit-learn

MCP问题

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

# Check MCP registration
claude mcp list

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

问题： 工具不工作

# Test server directly
mamba activate ./env
python src/server.py --test

问题： 服务器中的路径问题

# Verify paths exist
ls -la src/server.py
ls -la scripts/
ls -la examples/data/

工作问题

问题： 作业挂起

# Check job directory
ls -la jobs/

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

Use get_job_log with job_id "" and tail 100 to see detailed error logs

问题： 内存不足错误

# Use smaller batch sizes or mock mode
python scripts/rna_embeddings.py --input file.fasta --use-mock

脚本问题

问题： FASTA解析错误

# Validate FASTA format
head -10 examples/data/example.fasta
# Check for proper headers (>) and valid RNA nucleotides (A, U, G, C)

问题： 模拟模式不起作用

# Verify NumPy installation
python -c "import numpy; print(numpy.__version__)"

问题： 真实模型加载失败

# Fall back to mock mode
python scripts/rna_embeddings.py --input file.fasta --use-mock
# Or check if repo/RNA-FM/ exists and is properly configured

______________________________________________________________________

发展

运行测试

# Activate environment
mamba activate ./env

# Test individual scripts
python scripts/rna_embeddings.py --input examples/data/example.fasta --use-mock --output /tmp/test1
python scripts/secondary_structure.py --input examples/data/example.fasta --use-mock --output /tmp/test2
python scripts/rna_classification.py --input examples/data/RF00005.fasta --use-mock --output /tmp/test3

正在启动开发服务器

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

# Or run directly
python src/server.py

性能基准

模拟模式性能 （以fasta为例，3个序列）：

• rna_embeddings.py：~0.8秒，输出4个文件（1.09MB）
• secondary_structure.py：~0.5秒，输出7个文件（160KB）
• rna_classification.py 在RF00005.fasta（954个序列）上：约2.1s，输出5个文件（21.2MB）

______________________________________________________________________

许可证

此MCP服务器基于 RNA-FM 基础模型库，并提供MCP接口，便于访问RNA分析功能。

学分

• 原始RNA-FM模型: ml4bio/RNA-FM
• MCP框架: 人类模型上下文协议
• FastMCP: FastMCP框架