cyc builder MCP

CYC_BUILDER_v1.0 MCP

使用CYC_BUILDER框架进行环肽计算分析和设计的综合MCP工具

目录

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

概述

CYC_BUILDER_v1.0 MCP为环肽计算分析和设计提供了一套全面的工具。该MCP服务器集成了CYC_BUILDER框架，该框架结合了种子制备、基于蒙特卡洛树搜索（MCTS）的片段组装和结构分析，以生成、分析和优化靶蛋白的环肽结合物。

特性

• 从受体和基序结构制备用于环肽设计的种子
• 基于蒙特卡罗树搜索（MCTS）的环肽生成
• 综合结构分析和绑定分数计算
• 具有排名、过滤和聚类功能的后处理
• 虚拟筛选活动的批处理
• 同步（快速）和异步（长时间运行）API
• 用于跟踪长时间运行的计算的完整作业管理系统

目录结构

./
├── README.md               # This file
├── env/                    # Conda environment (Python 3.11.14)
├── src/
│   └── server.py           # MCP server with all tools
├── scripts/
│   ├── seed_preparation.py        # Seed preparation for peptide design
│   ├── peptide_generation.py      # MCTS-based peptide generation
│   ├── structure_analysis.py      # Structure analysis and scoring
│   ├── post_processing.py         # Post-processing and ranking
│   └── lib/                       # Shared utilities
├── examples/
│   └── data/               # Demo data for testing
│       ├── sequences/      # Sample peptide sequences
│       ├── structures/     # Sample 3D structures (PDB files)
│       └── configs/        # Configuration files
├── configs/                # Configuration templates
└── reports/               # Documentation from development steps

______________________________________________________________________

安装

快速设置

运行自动安装脚本：

./quick_setup.sh

这将创建环境并自动安装所有依赖项。

手动设置（高级）

对于手动安装或自定义，请执行以下步骤。

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• Python 3.10+
• RDKit（自动安装）
• 至少4 GB的可用磁盘空间
• Linux/macOS（Windows可以工作，但未经过测试）

创建环境

请严格遵守以下程序 reports/step3_environment.md 营造环境。工作流程示例如下：

# Navigate to the MCP directory
cd /home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/cyc_builder_mcp

# Determine package manager (prefer mamba over conda)
if command -v mamba &> /dev/null; then
    PKG_MGR="mamba"
else
    PKG_MGR="conda"
fi
echo "Using package manager: $PKG_MGR"

# Create conda environment with Python 3.11
$PKG_MGR create -p ./env python=3.11 -y

# Activate environment
$PKG_MGR activate ./env

# Install core scientific dependencies
$PKG_MGR run -p ./env pip install loguru click pandas numpy tqdm biopython requests pyyaml omegaconf joblib scikit-learn scipy

# Install FastMCP framework
$PKG_MGR run -p ./env pip install --force-reinstall --no-cache-dir fastmcp

# Install RDKit from conda-forge
$PKG_MGR run -p ./env mamba install -c conda-forge rdkit -y

# Verify installation
$PKG_MGR run -p ./env python -c "import rdkit, fastmcp, Bio, numpy, pandas, yaml; print('Installation successful!')"

______________________________________________________________________

本地使用（脚本）

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

可用脚本

脚本示例

种子准备

# Activate environment
mamba activate ./env

# Prepare seeds from receptor and motif structures
python scripts/seed_preparation.py \
  --receptor examples/data/structures/rec.pdb \
  --motif examples/data/structures/motif.pdb \
  --output seeds \
  --peptide-length 6 \
  --top-k-matches 5

参数：

• --receptor, -r：受体结构PDB文件（必填）
• --motif, -m：装订主题PDB文件（必填）
• --output, -o：输出目录（默认：种子）
• --peptide-length：设计肽的长度（默认值：5）
• --top-k-matches：得分最高的图案数量（默认值：3）

生成肽

python scripts/peptide_generation.py \
  --seed examples/data/structures/seed.pdb \
  --receptor examples/data/structures/rec.pdb \
  --output generated_peptides \
  --mcts-levels 5 \
  --num-simulations 500 \
  --top-k 10

参数：

• --seed, -s：种子肽结构PDB文件（必填）
• --receptor, -r：受体结构PDB文件（必填）
• --output, -o：输出目录（默认：Output）
• --mcts-levels：MCTS级别数（默认值：5）
• --num-simulations：MCTS模拟数（默认值：500）
• --top-k：要生成的顶级肽的数量（默认值：10）

结构分析

python scripts/structure_analysis.py \
  --peptide examples/data/structures/seed.pdb \
  --receptor examples/data/structures/rec.pdb \
  --output analysis_results.json \
  --include-hydrogen-bonds \
  --include-shape-complementarity

参数：

• --peptide, -p：要分析的肽结构PDB文件（必需）
• --receptor, -r：受体结构PDB文件（可选）
• --output, -o：输出分析文件（默认：stdout）
• --batch, -b：批量分析目录
• --include-hydrogen-bonds：包括氢键分析（默认值：true）
• --include-shape-complementarity：包括形状分析（默认值：true）

后处理

python scripts/post_processing.py \
  --input ./generated_peptides \
  --receptor examples/data/structures/rec.pdb \
  --output final_results \
  --top-k 5 \
  --cluster-similar

参数：

• --input, -i：生成肽的目录（必填）
• --receptor, -r：受体结构PDB文件（必填）
• --output, -o：输出目录（默认：final_results）
• --top-k：要选择的顶级肽的数量（默认值：10）
• --cluster-similar：群集相似结构（默认值：true）

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

# Install MCP server for Claude Code
fastmcp install src/server.py --name cyc-builder-tools

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

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

# Verify installation
claude mcp list

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

{
  "mcpServers": {
    "cyc-builder-tools": {
      "command": "/home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/cyc_builder_mcp/env/bin/python",
      "args": ["/home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/cyc_builder_mcp/src/server.py"]
    }
  }
}

______________________________________________________________________

使用Claude代码

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

快速开始

# Start Claude Code
claude

示例提示

工具发现

What tools are available from cyc-builder-tools?

种子准备（快速）

Prepare seed peptides using @examples/data/structures/rec.pdb as receptor and @examples/data/structures/motif.pdb as motif, with peptide length 6

结构分析（快速）

Analyze the structure @examples/data/structures/seed.pdb against receptor @examples/data/structures/rec.pdb including hydrogen bonds and shape complementarity

肽生成（提交API）

Submit a peptide generation job using seed @examples/data/structures/seed.pdb and receptor @examples/data/structures/rec.pdb with 5 MCTS levels and 500 simulations

检查作业状态

Check the status of job abc12345

批处理

Process all peptide structures in @generated_peptides/ directory against @examples/data/structures/rec.pdb and rank the top 10 candidates

完整管道

Run a complete cyclic peptide design pipeline starting from @examples/data/structures/rec.pdb receptor and @examples/data/structures/motif.pdb motif, generating 5 final candidates

使用@引用

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

______________________________________________________________________

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

{
  "mcpServers": {
    "cyc-builder-tools": {
      "command": "/home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/cyc_builder_mcp/env/bin/python",
      "args": ["/home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/cyc_builder_mcp/src/server.py"]
    }
  }
}

示例提示

# Start Gemini CLI
gemini

# Example prompts (same as Claude Code)
> What cyclic peptide tools are available?
> Prepare seeds from rec.pdb and motif.pdb with default settings
> Submit peptide generation for 10 candidates using MCTS

______________________________________________________________________

可用工具

快速操作（同步API）

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

作业管理工具

实用工具

______________________________________________________________________

例子

示例1：快速结构分析

目标： 计算环肽的结合特性

使用脚本：

python scripts/structure_analysis.py \
  --peptide examples/data/structures/seed.pdb \
  --receptor examples/data/structures/rec.pdb \
  --output analysis.json

使用MCP（克劳德代码）：

Analyze the cyclic peptide structure @examples/data/structures/seed.pdb against receptor @examples/data/structures/rec.pdb and save results to analysis.json

预期产量：

• 绑定得分、界面得分、冲突得分
• 氢键分析
• 形成互补性指标
• 结构特性（顺序、长度等）

示例2：种子制备工作流程

目标： 为设计活动生成种子肽

使用脚本：

python scripts/seed_preparation.py \
  --receptor examples/data/structures/rec.pdb \
  --motif examples/data/structures/motif.pdb \
  --output campaign_seeds \
  --peptide-length 7 \
  --top-k-matches 5

使用MCP（克劳德代码）：

Prepare seed peptides using @examples/data/structures/rec.pdb and @examples/data/structures/motif.pdb with peptide length 7, generating top 5 matches

示例3：完整的设计流程

目标： 从受体到最终候选物的端到端环肽设计

使用MCP（克劳德代码）：

Run a complete cyclic peptide design pipeline starting with receptor @examples/data/structures/rec.pdb and motif @examples/data/structures/motif.pdb. Use 5 MCTS levels, 500 simulations, and deliver 5 final candidates. Name this job "target_campaign_1"

后续提示：

Check the status of job "target_campaign_1"

Show me the execution logs for the last 50 lines

Get the results when the job completes

示例4：批量虚拟筛选

目标： 处理多个受体基序对以发现药物

使用MCP（克劳德代码）：

Submit a batch seed preparation job for these receptor-motif pairs:
1. @targets/target1_rec.pdb with @motifs/motif1.pdb
2. @targets/target2_rec.pdb with @motifs/motif2.pdb
3. @targets/target3_rec.pdb with @motifs/motif3.pdb

Generate top 3 seeds for each pair and name this "virtual_screening_batch_1"

______________________________________________________________________

演示数据

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

______________________________________________________________________

配置文件

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

配置示例

{
  "mcts_levels": 5,
  "num_simulations": 500,
  "top_k": 10,
  "scoring": {
    "interface_weight": 1.0,
    "clash_penalty": 2.0,
    "hydrophobic_bonus": 0.5
  },
  "output": {
    "save_intermediates": true,
    "format": "pdb"
  }
}

______________________________________________________________________

故障排除

环境问题

问题： 未找到环境

# Recreate environment
mamba create -p ./env python=3.11 -y
mamba activate ./env
pip install -r requirements.txt
mamba install -c conda-forge rdkit -y

问题： RDKit导入错误

# Install RDKit from conda-forge
mamba run -p ./env mamba install -c conda-forge rdkit -y --force-reinstall

问题： 导入错误

# Verify installation
python -c "from src.server import mcp; import rdkit; print('All imports successful')"

MCP问题

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

# Check MCP registration
claude mcp list

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

问题： 文件路径无效错误

Ensure your file paths are correct. Use absolute paths or verify files exist:
ls -la examples/data/structures/rec.pdb

问题： 工具不工作

# Test server directly
python -c "
from src.server import mcp
import sys
print(f'Server imported successfully')
print(f'FastMCP server created')
"

工作问题

问题： 作业挂起

# Check job directory
ls -la jobs/

# View job log
ls jobs/*/

问题： 任务失败

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

问题： 磁盘空间不足

# Clean up old jobs
find jobs/ -type f -mtime +7 -delete

# Check disk usage
du -sh jobs/ examples/ results/

文件格式问题

问题： “PDB格式无效”错误

• 原因：PDB文件已损坏或格式不正确
• 解决方案：验证PDB文件的完整性

# Check file size and format
head -10 examples/data/structures/rec.pdb
tail -10 examples/data/structures/rec.pdb

问题： “找不到配置文件”

• 原因：配置文件路径不正确
• 解决方案：使用绝对路径或验证文件是否存在

# List available configs
ls -la configs/

______________________________________________________________________

发展

运行测试

# Activate environment
mamba activate ./env

# Run integration tests
python tests/run_integration_tests.py

正在启动开发服务器

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

测试单个脚本

# Test all scripts with example data
python scripts/seed_preparation.py --receptor examples/data/structures/rec.pdb --motif examples/data/structures/motif.pdb
python scripts/structure_analysis.py --peptide examples/data/structures/seed.pdb --receptor examples/data/structures/rec.pdb
python scripts/post_processing.py --input test_peptides --receptor examples/data/structures/rec.pdb

______________________________________________________________________

许可证

基于CYC_BUILDER v1.0框架。此MCP实现为环肽设计和分析提供了计算工具。

积分

基于 cy_BUILDER -基于结构的环肽设计框架