CyclicChamp MCP工具
使用CyclicChamp骨干采样算法进行环肽计算分析的MCP工具
目录
概述
CyclicChamp MCP Tools提供了一套全面的环肽计算分析套件，专为7至24个残基的环肽的骨架取样和稳定性评估而设计。这些工具实现了CyclicChamp方法，用于基于模拟退火的肽设计，并具有混合的L/D手性支持。
特性
- P_near稳定性分析：结合RMSD和能量评估分析稳定性指标（P_near>0.9=稳定设计）
- 序列组成分析：具有物理化学性质的综合氨基酸和手性模式分析
- 骨干参数生成：针对不同肽大小优化CyclicChamp模拟退火参数
- 批处理：用于虚拟筛选和参数优化研究的高通量分析
- 混合手性支持：环肽设计中L/D氨基酸组合的天然支持
目录结构
./
├── README.md # This file
├── env/ # Conda environment
├── src/
│ └── server.py # MCP server with 16 tools
├── scripts/
│ ├── pnear_analysis.py # P_near stability analysis
│ ├── sequence_analysis.py # Sequence composition and properties
│ ├── backbone_sampling_params.py # CyclicChamp parameter generation
│ └── lib/ # Shared utilities (io, validation, utils)
├── examples/
│ └── data/ # Demo data
│ ├── results/ # P_near analysis results (15, 20, 24 residue samples)
│ ├── sequences/ # Amino acid type definitions (L/D residues)
│ └── structures/ # Sample cluster center PDB structures
├── configs/ # Configuration files
│ ├── pnear_analysis_config.json # P_near analysis settings
│ ├── sequence_analysis_config.json # Sequence analysis parameters
│ ├── backbone_sampling_config.json # Parameter generation formulas
│ └── default_config.json # Global defaults
└── repo/ # Original CyclicChamp repository______________________________________________________________________
安装
快速设置
运行自动安装脚本：
./quick_setup.sh这将创建环境并自动安装所有依赖项。
手动设置（高级）
对于手动安装或自定义，请执行以下步骤。
先决条件
- Conda或Mamba（建议使用曼巴以加快安装速度）
- Python 3.10+
- 科学Python堆栈（numpy、matplotlib、pandas、scipy）
- MCP框架（fastmcp、loguru）
创建环境
请遵循以下信息 reports/step3_environment.md 了解完整的设置过程。典型的工作流程：
# Navigate to the MCP directory
cd /home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/cyclicchamp_mcp
# Create conda environment (use mamba if available)
mamba create -p ./env python=3.12 pip -y
# or: conda create -p ./env python=3.12 pip -y
# Activate environment
mamba activate ./env
# or: conda activate ./env
# Install core dependencies
mamba run -p ./env pip install matplotlib numpy scipy loguru click pandas tqdm
# Install MCP dependencies
mamba run -p ./env pip install --force-reinstall --no-cache-dir fastmcp
# Test installation
mamba run -p ./env python -c "import numpy; import matplotlib; import scipy; import fastmcp; print('Core imports successful')"______________________________________________________________________
本地使用（脚本）
您可以在没有MCP的情况下直接使用脚本进行本地处理。
可用脚本
| 脚本 | 描述 | 示例 |
|---|---|---|
scripts/pnear_analysis.py | 分析CyclicChamp结果中环肽的P_near稳定性值 | 见下文 |
scripts/sequence_analysis.py | 分析序列组成、手性模式和物理化学性质 | 见下文 |
scripts/backbone_sampling_params.py | 为CyclicChamp模拟退火生成骨干采样参数 | 见下文 |
脚本示例
P_near稳定性分析
# Activate environment
mamba activate ./env
# Analyze P_near stability for 15-residue peptides
python scripts/pnear_analysis.py \
--input examples/data/results/Pnear_values_15res.txt \
--output-dir results/pnear_analysis \
--min-pnear 0.9
# Analyze with custom configuration
python scripts/pnear_analysis.py \
--input examples/data/20res_Pnear_list.txt \
--config configs/pnear_analysis_config.json \
--output-dir results/20res_analysis参数：
--input, -i：Pnear_values\_\*.txt文件的路径（必需）--output-dir, -o：绘图和报告的输出目录（可选）--min-pnear：稳定设计的最小P_near阈值（默认值：0.9）--config：JSON配置文件的路径（可选）
序列组成分析
# Analyze all designs in dataset
python scripts/sequence_analysis.py \
--input examples/data/results/Pnear_values_20res.txt \
--output-dir results/sequence_analysis
# Analyze only stable designs (P_near > 0.9)
python scripts/sequence_analysis.py \
--input examples/data/24res_Pnear_list.txt \
--stable-only \
--min-pnear 0.95 \
--output-dir results/stable_sequences参数：
--input, -i：Pnear_values\_\*.txt文件的路径（必需）--output-dir, -o：输出目录（可选）--stable-only：仅分析阈值以上的稳定设计（标志）--min-pnear：稳定设计的P_near阈值（默认值：0.9）--config：JSON配置文件的路径（可选）
骨干参数生成
# Generate parameters for 15-residue peptides
python scripts/backbone_sampling_params.py \
--size 15 \
--output-dir results/parameters_15res
# Generate optimization parameter combinations
python scripts/backbone_sampling_params.py \
--size 24 \
--optimize \
--output-dir results/optimization_24res参数：
--size, -s：肽大小-必须为7、15、20或24个残基（必填）--output-dir, -o：输出目录（可选）--optimize：生成参数组合以进行优化（标志）--config：JSON配置文件的路径（可选）
______________________________________________________________________
MCP服务器安装
选项1：使用fastmcp（推荐）
# Install MCP server for Claude Code
fastmcp install src/server.py --name cyclicchamp-tools选项2:Claude代码的手动安装
# Add MCP server to Claude Code
claude mcp add cyclicchamp-tools -- $(pwd)/env/bin/python $(pwd)/src/server.py
# Verify installation
claude mcp list选项3：在settings.json中配置
增添 ~/.claude/settings.json:
{
"mcpServers": {
"cyclicchamp-tools": {
"command": "/home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/cyclicchamp_mcp/env/bin/python",
"args": ["/home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/cyclicchamp_mcp/src/server.py"]
}
}
}______________________________________________________________________
使用Claude代码
安装MCP服务器后，您可以直接在Claude Code中使用它。
快速开始
# Start Claude Code
claude示例提示
工具发现
What tools are available from cyclicchamp-tools MCP server? Use get_tool_info to show me all available tools and their categories.P_near分析（快速-~1-2秒）
Use analyze_pnear_stability to analyze @examples/data/20res_Pnear_list.txt with min_pnear=0.9 and show me the stable designs.序列分析（快速-~1-3秒）
Analyze peptide sequences from @examples/data/results/Pnear_values_15res.txt using analyze_peptide_sequences. Focus only on stable designs and show me amino acid composition patterns.参数生成（快速-\ What tools are available from cyclicchamp-tools?
Analyze P_near stability for large peptide dataset Generate backbone parameters for multiple peptide sizes
______________________________________________________________________
### 快速操作（同步API-以秒为单位的结果）
这些工具会立即返回结果（\ 0.9 (both Rosetta and GA)
- Energy 0.9=稳定）
______________________________________________________________________
## 配置文件
这 `configs/` 目录包含配置模板：
|配置|描述|关键参数|
|--------|-------------|-----------------|
| `pnear_analysis_config.json` |P_near分析设置| `min_pnear: 0.9`，绘制颜色、图形大小|
| `sequence_analysis_config.json` |序列分析设置| AA特性、疏水阈值、极性残基|
| `backbone_sampling_config.json` |参数公式|数学公式、冷却速率、优化|
| `default_config.json` |全局默认值|输出格式、DPI、稳定性阈值|
### 配置示例
{ "analysis": { "min_pnear": 0.9, "stable_only": false }, "output": { "format": "png", "plot_dpi": 300 }, "plotting": { "figure_size": [10, 8], "alpha": 0.6 }, "colors": { "rosetta": "blue", "ga": "orange" } }
______________________________________________________________________
## 故障排除
### 环境问题
**问题：** 未找到环境
Recreate environment
mamba create -p ./env python=3.12 pip -y mamba activate ./env mamba run -p ./env pip install matplotlib numpy scipy loguru click pandas tqdm mamba run -p ./env pip install --force-reinstall --no-cache-dir fastmcp
**问题：** 导入错误
Verify installation
mamba run -p ./env python -c "import numpy; import matplotlib; import scipy; import fastmcp; print('All imports successful')"
Test script functions
mamba run -p ./env python -c "from scripts.pnear_analysis import run_pnear_analysis; print('Scripts ready')"
**问题：** 包冲突
Clean installation
mamba clean --all mamba create -p ./env python=3.12 pip -y --force
Reinstall packages as above
### MCP问题
**问题：** 在Claude代码中找不到服务器
Check MCP registration
claude mcp list
Re-add if needed
claude mcp remove cyclicchamp-tools claude mcp add cyclicchamp-tools -- $(pwd)/env/bin/python $(pwd)/src/server.py
**问题：** 工具在Claude代码中不起作用
Test server directly
mamba run -p ./env python -c " import sys sys.path.insert(0, 'src') from server import mcp print('Server imports OK') "
Start dev server to check for errors
mamba run -p ./env fastmcp dev src/server.py
**问题：** 文件路径错误
Use absolute paths or @ references in Claude Code:
- @examples/data/20res_Pnear_list.txt ✓
- examples/data/20res_Pnear_list.txt ✗
### 数据问题
**问题：** P_near文件格式无效
Ensure your P_near file has these exact columns (tab-separated): Name Energy P_near_Rosetta P_near_GA Sequence
Check file with: head -1 your_file.txt
**问题：** 缺少演示数据
Check if demo files exist
ls -la examples/data/ ls -la examples/data/results/
Files should include:
- 20res_Pnear_list.txt
- 24res_Pnear_list.txt
- Pnear_list.txt
### 工作问题
**问题：** 作业处于待处理状态
Check job directory
ls -la jobs/
View job log
tail -20 jobs//job.log
**问题：** 任务失败
Use get_job_log with job_id to see error details: get_job_log(job_id="", tail=100)
**问题：** 找不到作业
Use list_jobs() to see all available job IDs: list_jobs()
______________________________________________________________________
## 发展
### 运行测试
Activate environment
mamba activate ./env
Run server tests
python test_server.py
Test individual scripts
python scripts/pnear_analysis.py --input examples/data/results/Pnear_values_15res.txt python scripts/sequence_analysis.py --input examples/data/results/Pnear_values_15res.txt python scripts/backbone_sampling_params.py --size 15
### 正在启动开发服务器
Run MCP server in dev mode
mamba run -p ./env fastmcp dev src/server.py
Check server logs
Dev server will show inspector URL for testing tools
______________________________________________________________________
## 演出
### 预期性能
|工具|数据集大小|运行时|内存|输出文件|
|------|--------------|---------|--------|--------------|
| `analyze_pnear_stability` |100个设计|~1秒|10 MB |3个文件|
| `analyze_pnear_stability` |1000个设计|~2秒|50 MB |3个文件|
| `analyze_peptide_sequences` |100个序列|~1秒|15 MB |3个文件|
| `analyze_peptide_sequences` |1000个序列|~3秒|75 MB |3个文件|
| `generate_backbone_parameters` |任意大小|\1000个设计）
- **磁盘空间**：每个分析输出约10 MB
______________________________________________________________________
## 许可证
基于最初的CyclicChamp方法。有关原始实现的详细信息，请参阅repo/目录。
## 积分
基于 [CyclicChamp](https://github.com/ichen-lab-ucsb/CyclicChamp) -基于启发式能量的环肽设计
加州大学圣巴巴拉分校陈实验室的原始存储库结构和算法
Claude Sonnet 4的MCP实现和工具提取
______________________________________________________________________
**可用MCP工具总数：16**
- 5作业管理工具
- 3个同步分析工具
- 5提交/批处理工具
- 3实用工具
**已准备好集成Claude Code和Gemini CLI**