shapewarp MCP

SHAPEwarp MCP

使用SHAPE化学探测反应性谱搜索结构相似的RNA序列

目录

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

概述

SHAPEwarp MCP通过SHAPE（引物延伸分析的选择性2'-羟基酰化）化学探测数据提供分析RNA二级结构的工具。此MCP服务器将高性能的基于Rust的SHAPEwarp工具与Python脚本封装在一起，便于与AI助手集成。

特性

• 形状轮廓搜索：使用反应模式查找结构相似的RNA序列
• 数据库管理：通过分析在XML和二进制数据库格式之间进行转换
• 反应性分析：化学探测数据的综合统计分析
• API双重设计：快速同步操作和后台批处理
• 模拟模式支持：在不编译Rust依赖项的情况下测试功能

目录结构

./
├── README.md               # This file
├── env/                    # Conda environment
├── src/
│   ├── server.py           # MCP server
│   └── jobs/               # Job management system
├── scripts/
│   ├── shape_search.py     # SHAPE profile similarity search
│   ├── database_conversion.py # Database format conversion and analysis
│   ├── reactivity_analysis.py # SHAPE reactivity statistical analysis
│   └── lib/                # Shared utilities (15 functions)
├── examples/
│   └── data/               # Demo data (11 test files)
├── configs/                # Configuration files (4 configs)
└── repo/                   # Original SHAPEwarp repository

______________________________________________________________________

安装

先决条件

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

创建环境

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

# Navigate to the MCP directory
cd /home/xux/Desktop/NucleicMCP/NucleicMCP/tool-mcps/shapewarp_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 dependencies
pip install fastmcp loguru click pandas numpy tqdm matplotlib seaborn scipy scikit-learn --ignore-installed

______________________________________________________________________

本地使用（脚本）

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

可用脚本

脚本示例

形状轮廓搜索

# Activate environment
mamba activate ./env

# Run SHAPE similarity search
python scripts/shape_search.py \
  --query examples/data/query.txt \
  --database examples/data/test.db \
  --output results/search_results \
  --max-reactivity 1.0

参数：

• --query, -q：包含RNA序列和SHAPE反应性的查询文件（必填）
• --database, -d：带有引用结构的数据库文件（必需）
• --output, -o：搜索结果的输出目录（默认：results/）
• --max-reactivity：最大反应性值阈值（默认值：1.0）
• --max-align-overlap：最大对齐重叠（默认值：0.5）
• --config, -c：配置文件（可选）

数据库格式转换

python scripts/database_conversion.py \
  --input examples/data/test_db.xml \
  --output results/converted.db \
  --output-format binary

参数：

• --input, -i：输入XML数据库文件（必需）
• --output, -o：输出文件路径（默认：自动生成）
• --output-format：输出格式-“二进制”、“csv”、“json”（默认：“二进制”）
• --config, -c：配置文件（可选）

形状反应性分析

python scripts/reactivity_analysis.py \
  --input examples/data/query.txt \
  --output results/analysis \
  --normalize \
  --window-size 15

参数：

• --input, -i：具有SHAPE反应性的RNA序列（必填）
• --output, -o：分析结果的输出目录（默认：results/）
• --normalize：标准化反应性值（标志）
• --window-size：用于分析的滑动窗口大小（默认值：10）
• --reactivity-threshold：核苷酸分类的自定义阈值（可选）

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

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

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

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

# Verify installation
claude mcp list

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

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

______________________________________________________________________

使用Claude代码

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

快速开始

# Start Claude Code
claude

示例提示

工具发现

What tools are available from SHAPEwarp?

基本用法

Use search_shape_profiles with query_file @examples/data/query.txt and database_file @examples/data/test.db

通过配置

Run analyze_reactivity_profiles on @examples/data/query.txt using normalize True and window_size 15

长期运行任务（提交API）

Submit submit_shape_search with query_file @examples/data/query.txt and database_file @examples/data/test.db
Then check the job status

批处理

Process these files in batch using submit_batch_shape_search:
- @examples/data/query.txt
- @examples/data/query_align.txt
- @examples/data/valid_query.txt

使用@引用

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

______________________________________________________________________

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

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

示例提示

# Start Gemini CLI
gemini

# Example prompts (same as Claude Code)
> What tools are available?
> Use search_shape_profiles with query_file examples/data/query.txt and database_file examples/data/test.db

______________________________________________________________________

可用工具

快速操作（同步API）

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

作业管理工具

______________________________________________________________________

例子

示例1：形状相似性搜索

目标： 基于SHAPE反应模式寻找具有相似二级结构的RNA序列

使用脚本：

python scripts/shape_search.py \
  --query examples/data/query.txt \
  --database examples/data/test.db \
  --output results/example1/

使用MCP（克劳德代码）：

Use search_shape_profiles to search @examples/data/query.txt against @examples/data/test.db and save results to results/example1/

预期产量：

• search_results.tsv：带有搜索结果、分数和p值的TSV文件
• 搜索统计：已处理的查询、总点击量、最佳分数

示例2：数据库格式转换

目标： 将XML数据库转换为二进制格式并分析内容

使用脚本：

python scripts/database_conversion.py \
  --input examples/data/test_db.xml \
  --output results/example2/converted.db

使用MCP（克劳德代码）：

Use convert_database_format to convert @examples/data/test_db.xml to results/example2/converted.db

预期产量：

• converted.db：二进制格式数据库
• database_analysis.txt：分析报告
• transcript_details.csv：详细的成绩单信息

示例3：反应性曲线分析

目标： SHAPE反应性数据归一化综合分析

使用脚本：

python scripts/reactivity_analysis.py \
  --input examples/data/query.txt \
  --output results/example3 \
  --normalize \
  --window-size 15

使用MCP（克劳德代码）：

Run analyze_reactivity_profiles on @examples/data/query.txt with normalize True and window_size 15, save to results/example3/

预期产量：

• summary_statistics.csv：按条目汇总统计
• nucleotide_classifications.csv：核苷酸分析和分类
• sliding_window_analysis.csv：滑动窗口统计

示例4：批处理

目标： 一次处理多个查询文件

使用脚本：

for f in examples/data/query*.txt; do
  python scripts/shape_search.py --query "$f" --database examples/data/test.db --output results/batch/
done

使用MCP（克劳德代码）：

Submit submit_batch_shape_search with input_files [@examples/data/query.txt, @examples/data/query_align.txt, @examples/data/valid_query.txt] and database_file @examples/data/test.db

______________________________________________________________________

演示数据

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

形状数据格式

查询文件遵循SHAPEwarp的格式：

sequence_id
RNA_SEQUENCE_STRING
reactivity1,reactivity2,reactivity3,...

哪里：

• sequence_id：RNA序列的唯一标识符
• RNA_SEQUENCE_STRING：RNA核苷酸序列（A、C、G、U）
• reactivity values：逗号分隔的形状反应性测量（浮点数，NaN表示缺失数据）

______________________________________________________________________

配置文件

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

配置示例

{
  "max_reactivity": 1.0,
  "max_align_overlap": 0.5,
  "use_mock": true,
  "output_format": "tsv"
}

______________________________________________________________________

故障排除

环境问题

问题： 未找到环境

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

问题： 导入错误

# Verify installation
python -c "from src.server import mcp; print('Server loaded:', mcp.name)"

MCP问题

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

# Check MCP registration
claude mcp list

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

问题： 工具不工作

# Test server directly
python -c "
from src.server import mcp
print('Available tools:', list(mcp.list_tools().keys()))
"

问题： 路径问题

# Use absolute paths in configuration
echo "Current directory: $(pwd)"
echo "Environment path: $(pwd)/env/bin/python"
echo "Server path: $(pwd)/src/server.py"

脚本问题

问题： 脚本执行失败

# Test script independently
mamba activate ./env
python scripts/shape_search.py --help

问题： 缺少数据文件

# Verify demo data exists
ls -la examples/data/
# Should show: query.txt, test.db, test_db.xml, etc.

工作问题

问题： 作业挂起

# Check job directory
ls -la jobs/
# View job contents if exists

问题： 作业失败

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

性能问题

问题： 工具运行缓慢

• 当前工具使用模拟数据在\<1秒内执行
• 对于真正的Rust二进制文件，安装FFTW并编译SHAPEwarp：

# Install system dependencies (Ubuntu/Debian)
sudo apt install libfftw3-dev
cd repo/SHAPEwarp
cargo build --release

______________________________________________________________________

发展

运行测试

# Activate environment
mamba activate ./env

# Run integration tests
python tests/run_integration_tests.py

# Test individual scripts
python scripts/shape_search.py --query examples/data/query.txt --database examples/data/test.db

正在启动开发服务器

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

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

模拟模式vs真实模式

所有工具都支持模拟模式进行测试：

• 模拟模式 （默认）：使用生成的数据，立即运行
• 真实模式：需要编译的SHAPEwarp二进制文件，提供实际分析

______________________________________________________________________

许可证

此项目封装了SHAPEwarp工具。有关许可信息，请参阅原始存储库。

学分

基于 SHAPEwarp -一种使用SHAPE反应谱寻找具有相似二级结构的RNA序列的工具。

______________________________________________________________________

业绩说明

• Python脚本：快速启动（＜1秒），适用于API端点
• Rust二进制文件：大规模搜索的高性能（需要编译）
• 模拟模式：测试和开发的即时结果
• 内存使用：最小（仅限pandas/numpy）
• 可扩展性：提交可用于大型数据集的API

快速参考

# Essential commands
mamba activate ./env                    # Activate environment
claude mcp list                        # Check MCP status
python scripts/shape_search.py --help  # Script help

有关详细的使用示例和故障排除，请参阅上面的部分。