haddock3 MCP

HADDOCK3 MCP工具

HADDOCK3分子对接和环肽计算分析的MCP工具

目录

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

概述

此MCP服务器为专门为环肽设计的基于HADDOCK3的分子对接工作流程提供了全面的工具。HADDOCK3是生物分子对接的领先计算工具，它整合了实验数据来指导结构预测和蛋白质-肽复合物建模。

特性

• 蛋白质肽对接：与HADDOCK3的多阶段协议进行高级分子对接
• 环肽环化：将线性肽转化为具有特殊距离限制的环状形式
• 信息驱动对接：整合实验数据（核磁共振、诱变、交联）以指导对接
• 批处理：肽库的高通量虚拟筛选
• 作业管理：异步处理，具有实时监控和结果检索功能
• 实验数据集成：支持主动/被动残留物和距离限制

目录结构

./
├── README.md                    # This file
├── env/                         # Conda environment with HADDOCK3
├── src/
│   └── server.py               # MCP server
│   └── jobs/                   # Job management system
├── scripts/
│   ├── protein_peptide_docking.py          # Basic docking protocol
│   ├── cyclic_peptide_cyclisation.py       # Peptide cyclisation
│   ├── information_driven_docking.py       # Experimental data-guided docking
│   └── lib/                    # Shared utilities
├── examples/
│   └── data/                   # Demo data for testing
│       ├── structures/         # Sample PDB structures (proteins & peptides)
│       ├── restraints/         # Experimental restraints files
│       └── sequences/          # Sample peptide sequences
├── configs/                    # Configuration templates
└── repo/                       # Original HADDOCK3 repository

______________________________________________________________________

安装

快速设置

运行自动安装脚本：

./quick_setup.sh

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

手动设置（高级）

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

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• Python 3.10+
• HADDOCK3 C/C++扩展的GCC/G++编译器
• 8+GB RAM，用于典型的对接作业
• 每个作业10+GB磁盘空间

创建环境

请遵循以下信息 reports/step3_environment.md 对于完整的程序。工作流程示例如下：

# Navigate to the MCP directory
cd /home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/haddock3_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 Scientific Dependencies
mamba run -p ./env pip install numpy scipy pandas biopython pdb-tools

# Install MCP dependencies
mamba run -p ./env pip install loguru click tqdm fastmcp

# Install HADDOCK3 (editable installation)
cd repo/haddock3
mamba run -p ../../env pip install -e .
cd ../..

# Force clean FastMCP installation (if needed)
mamba run -p ./env pip install --force-reinstall --no-cache-dir fastmcp

验证安装

# Test core functionality
mamba run -p ./env python -c "
import numpy as np
import scipy as sp
import pandas as pd
import Bio
import haddock
import fastmcp
print('All critical imports successful')
"

# Check HADDOCK3 version
mamba run -p ./env haddock3 --version
# Expected output: haddock3 - 2025.11.0

______________________________________________________________________

本地使用（脚本）

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

可用脚本

脚本示例

蛋白质肽对接

# Activate environment
mamba activate ./env

# Basic usage with demo data
python scripts/protein_peptide_docking.py

# Custom run with specific files
python scripts/protein_peptide_docking.py \
  --input-protein examples/data/structures/1NX1_protein.pdb \
  --input-peptide examples/data/structures/DAIDALSSDFT_3conformations.pdb \
  --ncores 8 \
  --output my_docking_results

参数：

• --input-protein：PDB格式的蛋白质结构（必填）
• --input-peptide：肽结构-支持多种构象（必填）
• --restraints：模糊的交互限制（.tbl格式）
• --ncores：要使用的CPU核数（默认值：4）
• --output：输出目录名（默认：自动生成）

环肽环化

# Basic cyclisation with demo data
python scripts/cyclic_peptide_cyclisation.py

# Custom peptide with specified length
python scripts/cyclic_peptide_cyclisation.py \
  --input my_linear_peptide.pdb \
  --length 14 \
  --ncores 4 \
  --output cyclic_peptide_results

参数：

• --input：PDB格式的线性肽结构（必填）
• --length：残留物数量（如果未指定，则自动检测）
• --ncores：CPU核数（默认值：4）
• --output：输出目录名（默认：自动生成）

信息驱动对接

# Advanced usage with experimental restraints
python scripts/information_driven_docking.py \
  --input-protein examples/data/structures/1NX1_protein.pdb \
  --input-peptide examples/data/structures/DAIDALSSDFT_3conformations.pdb \
  --active-protein "36,109,113" \
  --active-peptide "1,5,8" \
  --passive-protein "34,38,110,111" \
  --passive-peptide "2,6,9" \
  --ncores 8

参数：

• --input-protein, --input-peptide：结构文件（必填）
• --active-protein：有强有力实验证据的蛋白质残基
• --active-peptide：具有强有力实验证据的肽残基
• --passive-protein：证据不足或邻近的蛋白质残基
• --passive-peptide：证据较弱或邻近的肽残基

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

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

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

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

# Verify installation
claude mcp list

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

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

______________________________________________________________________

使用Claude代码

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

快速开始

# Start Claude Code
claude

示例提示

工具发现

What HADDOCK3 tools are available from haddock3-tools?

蛋白质肽对接

Submit a protein-peptide docking job using:
- Protein: @examples/data/structures/1NX1_protein.pdb
- Peptide: @examples/data/structures/DAIDALSSDFT_3conformations.pdb
Name the job "hiv_protease_docking"

环肽环化

Cyclise this linear peptide into cyclic form:
@examples/data/structures/1sfi_peptide-ensemble.pdb

检查作业状态

Check the status of job abc12345 and show me the logs if it's running

信息驱动对接

Perform information-driven docking with experimental data:
- Protein: @examples/data/structures/1NX1_protein.pdb
- Peptide: @examples/data/structures/DAIDALSSDFT_3conformations.pdb
- Active protein residues: 36,109,113 (from NMR data)
- Active peptide residues: 1,5,8 (key binding residues)
- Passive residues: neighbors of active sites

批处理

Submit batch docking jobs for these peptides against 1NX1 protein:
- @examples/data/structures/DAIDALSSDFT_alpha.pdb
- @examples/data/structures/DAIDALSSDFT_ext.pdb
- @examples/data/structures/DAIDALSSDFT_polyII.pdb

Monitor progress and show results when completed.

使用@引用

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

______________________________________________________________________

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

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

示例提示

# Start Gemini CLI
gemini

# Example prompts (same as Claude Code)
> What HADDOCK3 tools are available?
> Submit protein-peptide docking for HIV protease with peptide ensemble
> Check job status and retrieve results when complete

______________________________________________________________________

可用工具

快速操作（提交API）

所有HADDOCK3操作都是长时间运行的，并使用带有作业跟踪的submit API：

作业管理工具

实用工具

______________________________________________________________________

例子

实施例1：碱性蛋白肽对接

目标： 使用HADDOCK3将肽与HIV-1蛋白酶对接

使用脚本：

mamba activate ./env
python scripts/protein_peptide_docking.py \
  --input-protein examples/data/structures/1NX1_protein.pdb \
  --input-peptide examples/data/structures/DAIDALSSDFT_3conformations.pdb \
  --output hiv_protease_docking

使用MCP（克劳德代码）：

Submit protein-peptide docking job:
- Protein: @examples/data/structures/1NX1_protein.pdb
- Peptide: @examples/data/structures/DAIDALSSDFT_3conformations.pdb
- Job name: "hiv_protease_analysis"

Monitor the job and show me the results when complete.

预期产量：

• 对接蛋白肽复合物
• HADDOCK绑定得分
• 结构聚类结果
• 接口接触分析

实施例2：环肽环化

目标： 使用距离限制将线性肽转化为环状

使用脚本：

python scripts/cyclic_peptide_cyclisation.py \
  --input examples/data/structures/1sfi_peptide-ensemble.pdb \
  --length 14 \
  --output cyclisation_results

使用MCP（克劳德代码）：

Cyclise this linear peptide ensemble into cyclic form:
@examples/data/structures/1sfi_peptide-ensemble.pdb

Use automatic length detection and name the job "peptide_cyclisation_14mer"

预期产量：

• 环化肽构象
• 构象集成分析
• 自行车骑行质量评估
• 基于RMSD的聚类

示例3：基于实验数据的信息驱动对接

目标： 利用核磁共振和诱变数据指导肽对接

使用MCP（克劳德代码）：

I have experimental data for protein-peptide binding:

Protein: @examples/data/structures/1NX1_protein.pdb
Peptide: @examples/data/structures/DAIDALSSDFT_3conformations.pdb

From NMR chemical shift perturbation:
- Active protein residues: 36,109,113 (large shifts)
- Active peptide residues: 1,5,8 (critical for binding)

From mutagenesis studies:
- Passive protein residues: 34,38,110,111 (moderate effects)
- Passive peptide residues: 2,6,9 (neighboring residues)

Submit information-driven docking with this experimental data.
Monitor progress and analyze the restraint satisfaction in the results.

预期产量：

• 高置信度对接解决方案
• 实验约束满意度分析
• 使用置信度得分进行界面验证
• 按实验一致性排序的集群

示例4：虚拟筛选流程

目标： 筛选多种肽构象用于药物发现

使用MCP（克劳德代码）：

I want to screen different peptide conformations against HIV protease:

Target: @examples/data/structures/1NX1_protein.pdb

Peptide library:
- @examples/data/structures/DAIDALSSDFT_alpha.pdb
- @examples/data/structures/DAIDALSSDFT_ext.pdb
- @examples/data/structures/DAIDALSSDFT_polyII.pdb

Submit batch docking jobs for all peptides.
Monitor progress and identify the best-scoring complexes.
Rank results by HADDOCK score and cluster size.

预期产量：

• 多个对接作业ID用于并行处理
• 肽构象的比较分析
• 通过绑定亲和力预测进行排名
• 最佳肽结构的鉴定

______________________________________________________________________

演示数据

这 examples/data/ 目录包含用于测试的已验证数据集：

结构化数据

约束数据

______________________________________________________________________

配置文件

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

配置示例

{
  "ncores": 8,
  "sampling": {
    "structures_it0": 1000,
    "structures_it1": 200,
    "structures_itw": 200
  },
  "clustering": {
    "clustfcc": true,
    "min_population": 4,
    "threshold": 7.5
  },
  "scoring": {
    "w_elec": 0.2,
    "w_vdw": 1.0,
    "w_desolv": 1.0,
    "w_air": 0.1
  }
}

______________________________________________________________________

故障排除

环境问题

问题： 找不到环境或导入错误

# Recreate environment
mamba create -p ./env python=3.12 pip -y
mamba activate ./env
mamba run -p ./env pip install numpy scipy pandas biopython pdb-tools
mamba run -p ./env pip install loguru click tqdm fastmcp

# Reinstall HADDOCK3
cd repo/haddock3
mamba run -p ../../env pip install -e .
cd ../..

问题： HADDOCK3导入错误

# Verify HADDOCK3 installation
mamba run -p ./env python -c "import haddock; print('HADDOCK3 OK')"
mamba run -p ./env haddock3 --version

# Check for missing dependencies
mamba run -p ./env python -c "import Bio; print('Biopython OK')"

问题： FastMCP冲突

# Force clean reinstall
mamba run -p ./env pip install --force-reinstall --no-cache-dir fastmcp

MCP问题

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

# Check MCP registration
claude mcp list

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

# Test server directly
mamba run -p ./env python src/server.py

问题： 工具不工作

# Test server functionality
mamba run -p ./env python -c "
from src.server import mcp
tools = list(mcp.list_tools().keys())
print(f'Available tools: {len(tools)}')
for tool in tools:
    print(f'  - {tool}')
"

问题： 作业提交失败

# Check job directory permissions
ls -la jobs/
mkdir -p jobs
chmod 755 jobs

# Verify example data exists
ls -la examples/data/structures/

工作问题

问题： 作业挂起

# Check job status
python -c "
from src.jobs.manager import job_manager
jobs = job_manager.list_jobs()
print(jobs)
"

# Check job directory
ls -la jobs//

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

# View detailed logs
python -c "
from src.jobs.manager import job_manager
log = job_manager.get_job_log('')
print('\n'.join(log['log_lines'][-50:]))  # Last 50 lines
"

# Check HADDOCK3 configuration
cat jobs//output/config.cfg

问题： 文件路径错误

# Verify file paths are absolute
python -c "
import os
print('Current directory:', os.getcwd())
print('Example files:')
for f in ['examples/data/structures/1NX1_protein.pdb']:
    abs_path = os.path.abspath(f)
    exists = os.path.exists(abs_path)
    print(f'  {abs_path}: {exists}')
"

资源问题

问题： 对接时内存不足

• 减少 ncores 参数为4或更小
• 监控系统内存使用情况： htop 或 free -h
• 使用较小的肽集合或减少采样参数

问题： 磁盘空间已满

# Check disk usage
df -h .
du -sh jobs/*

# Clean old job directories
find jobs/ -name "*" -type d -mtime +7 -exec rm -rf {} \;

问题： 运行时间长（>6小时）

• 检查作业是否实际正在运行： get_job_log 最近的活动
• 考虑减少配置中的采样
• 验证是否有足够的CPU内核可用

______________________________________________________________________

发展

运行测试

# Activate environment
mamba activate ./env

# Test server startup
python src/server.py

# Test job manager
python -c "
from src.jobs.manager import job_manager
print('Job manager status:', job_manager.list_jobs())
"

# Run integration tests
python tests/test_integration.py

正在启动开发服务器

# Run MCP server in development mode
mamba run -p ./env fastmcp dev src/server.py

# Test with Claude Code
claude

性能优化

# Monitor job performance
watch -n 30 "ps aux | grep python | grep -v grep"

# Check HADDOCK3 resource usage
htop  # Look for haddock3 and related processes

______________________________________________________________________

许可证

基于HADDOCK3软件套件。请引用：

1. 黑线鳕3Giulini，M.等人，“蛋白质相互作用的信息驱动建模和模拟”，《化学杂志》。信息模型。 (2025)
2. 自行车化协议Trellet，M.等人，“蛋白质肽对接的统一构象选择和诱导拟合方法”，《化学杂志》。理论计算。 (2022)
3. 信息驱动对接Reys，V.等人，“用于生物分子复合物综合建模的HADDOCK2.4网络服务器”《自然协议》（2024）

积分

基于 黑线鳕3 -高模糊性驱动的蛋白质-DOCKing版本3