highfold med MCP

HighFold MeD MCP

使用HighFold MeD（针对具有N-甲基化和D-氨基酸的环肽对AlphaFold进行了修改）进行环肽计算分析的MCP工具

目录

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

概述

HighFold MeD MCP通过模型上下文协议（MCP）服务器为环肽计算分析提供了全面的工具。这使得像Claude Code这样的人工智能助手能够执行高级分子建模任务，包括结构预测、能量最小化和对具有修饰氨基酸的环肽进行模型微调。

主要特点

• 三维结构预测：使用HighFold MeD对环肽进行基于模板的AlphaFold推理
• 结构弛豫：使用具有骨干约束的OpenMM实现能量最小化
• 批处理：多环肽的高通量加工
• 模型微调：针对环肽数据集的自定义AlphaFold模型自适应
• 序列验证：解析并验证修饰氨基酸的HighFold表示法
• 作业管理：为长时间运行的计算完成异步工作流

独特的环肽支持

• D-氨基酸：dL、dP、dA符号支持
• N-甲基化：h（甲基化组氨酸），p（甲基化脯氨酸）
• 终端修改: .C端子修改符号
• 自行车操作：/环化点符号
• 模板对齐：用于结构预测的预计算模板库

目录结构

./
├── README.md               # This file
├── env/                    # Conda environment (Python 3.10)
├── env_py38/               # Legacy environment for HighFold-MeD
├── src/
│   └── server.py           # MCP server (14 tools)
├── scripts/
│   ├── predict_structure.py   # Single peptide structure prediction
│   ├── batch_predict.py       # Batch processing multiple peptides
│   ├── relax_structure.py     # OpenMM structure relaxation
│   ├── finetune_model.py      # Model fine-tuning (demo mode)
│   └── lib/                   # Shared utilities (32 functions)
│       ├── cyclic_peptides.py # Peptide-specific utilities
│       └── io_utils.py        # I/O and configuration utilities
├── examples/
│   └── data/               # Demo data for testing
│       ├── sequences/      # targets.tsv with cyclic peptide sequences
│       ├── alignments/     # Template alignment files (50+ templates)
│       └── structures/     # Sample PDB structures for relaxation
├── configs/                # JSON configuration files
│   ├── predict_structure_config.json
│   ├── batch_predict_config.json
│   ├── relax_structure_config.json
│   ├── finetune_model_config.json
│   └── default_config.json # Global default settings
└── repo/                   # Original HighFold-MeD repository

______________________________________________________________________

安装

快速设置

运行自动安装脚本：

./quick_setup.sh

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

手动设置（高级）

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

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• Python 3.10+（用于MCP服务器）
• Python 3.8（用于HighFold MeD遗留依赖项，如果使用完整功能）
• RDKit（从conda forge自动安装）
• CUDA工具包（可选，用于全模式下的GPU加速）

创建环境

备注：此项目使用双环境策略-MCP服务器使用Python 3.10，HighFold MeD遗留依赖使用Python 3.8。

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

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

# Create main MCP environment (Python 3.10)
$PKG_MGR create -p ./env python=3.10 pip -y

# Activate environment
$PKG_MGR activate ./env

# Install core dependencies
$PKG_MGR run -p ./env pip install loguru click pandas numpy tqdm

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

# Install RDKit from conda-forge (essential for molecular operations)
$PKG_MGR run -p ./env $PKG_MGR install -c conda-forge rdkit -y

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

可选：用于完全HighFold功能的传统环境

# Create Python 3.8 environment for HighFold-MeD dependencies
$PKG_MGR create -p ./env_py38 python=3.8 -y

# Note: Full ML dependencies (JAX, PyTorch, TensorFlow, OpenMM)
# would be installed here for production use

______________________________________________________________________

本地使用（脚本）

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

可用脚本

脚本示例

预测三维结构

# Activate environment
mamba activate ./env

# Single peptide prediction
python scripts/predict_structure.py \
  --input examples/data/sequences/targets.tsv \
  --index 0 \
  --output results/prediction.txt \
  --demo_mode

# With specific config file
python scripts/predict_structure.py \
  --input examples/data/sequences/targets.tsv \
  --index 0 \
  --config configs/predict_structure_config.json

参数：

• --input, -i：目标文件路径（带肽序列的TSV格式）
• --index：要处理的行索引（默认值：0）
• --output, -o：输出文件路径（默认：自动生成）
• --demo_mode：使用演示模式进行测试（默认值：True）
• --config：JSON配置文件路径

批处理

# Process multiple peptides
python scripts/batch_predict.py \
  --input examples/data/sequences/targets.tsv \
  --max_peptides 5 \
  --output_dir results/batch_predictions/ \
  --demo_mode

# Continue processing even if some peptides fail
python scripts/batch_predict.py \
  --input examples/data/sequences/targets.tsv \
  --max_peptides 10 \
  --continue_on_error

结构弛豫

# Relax a single PDB structure
python scripts/relax_structure.py \
  --input examples/data/structures/1.pdb \
  --output results/1_relaxed.pdb \
  --demo

# Real OpenMM relaxation (requires OpenMM installation)
python scripts/relax_structure.py \
  --input examples/data/structures/1.pdb \
  --restraint_force 20000.0 \
  --tolerance 2.39

模型微调

# Demo mode training
python scripts/finetune_model.py \
  --demo \
  --epochs 10 \
  --output_dir results/finetuning/

# Real training (requires JAX/Haiku)
python scripts/finetune_model.py \
  --train_file training_set.tsv \
  --validation_file validation_set.tsv \
  --epochs 20 \
  --batch_size 4

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

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

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

# Add MCP server to Claude Code using absolute paths
claude mcp add highfold-med-tools -- \
  $(pwd)/env/bin/python \
  $(pwd)/src/server.py

# Verify installation
claude mcp list

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

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

______________________________________________________________________

使用Claude代码

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

快速开始

# Start Claude Code
claude

示例提示

工具发现

What tools are available from highfold-med-tools?

环境验证

Use check_dependencies to verify the HighFold-MeD environment setup

文件验证

Use validate_targets_file to check @examples/data/sequences/targets.tsv

结构预测（提交API）

Submit a 3D structure prediction job for the first peptide in @examples/data/sequences/targets.tsv with demo_mode=True

作业状态监控

Check the status of job abc12345 and show me the latest logs

批处理

Submit a batch prediction job for the first 3 peptides in @examples/data/sequences/targets.tsv

使用@引用

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

______________________________________________________________________

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

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

示例提示

# Start Gemini CLI
gemini

# Example prompts (same as Claude Code)
> What tools are available from highfold-med-tools?
> Use validate_targets_file to check the demo data
> Submit structure prediction with demo_mode=True

______________________________________________________________________

可用工具

MCP服务器提供14个工具，分为4类：

作业管理工具（5个工具）

这些工具管理长时间运行的计算作业：

提交API工具（4个工具）

返回job_id进行跟踪的长时间运行操作：

同步工具（4个工具）

快速操作在几秒钟到几分钟内完成：

实用工具（1个工具）

______________________________________________________________________

例子

示例1：快速验证和分析

目标： 在处理之前验证和分析环肽数据集

使用脚本：

# Check file format
python scripts/predict_structure.py --input examples/data/sequences/targets.tsv --help

# Validate specific peptide
python scripts/predict_structure.py \
  --input examples/data/sequences/targets.tsv \
  --index 0 \
  --demo_mode

使用MCP（克劳德代码）：

First, use validate_targets_file to check @examples/data/sequences/targets.tsv

Then, use get_peptide_info with index 0 to see details about the first peptide

Finally, use check_dependencies to verify the environment is ready

预期产量：

• 带有序列统计的文件验证结果
• 肽详细信息，包括HighFold计数分析
• 具有依赖项可用性的环境状态

示例2：单结构预测工作流

目标： 用D-氨基酸预测环肽的三维结构

使用脚本：

# Direct script execution
python scripts/predict_structure.py \
  --input examples/data/sequences/targets.tsv \
  --index 0 \
  --output results/PhdLP_d_prediction.txt \
  --demo_mode

使用MCP（克劳德代码）：

Submit a structure prediction job for index 0 in @examples/data/sequences/targets.tsv with demo_mode=True and job_name="PhdLP_d_prediction"

Monitor the job status and show me the logs

When complete, get the results and explain the prediction quality

预期产量：

• 用于跟踪的作业ID： "job_12345"
• 带置信度分数的预测总结
• 模板对齐信息
• 三维结构坐标（如果可用）

示例3：批量虚拟筛选

目标： 加工多种环肽用于药物发现

使用MCP（克劳德代码）：

I want to screen the first 5 cyclic peptides in @examples/data/sequences/targets.tsv for drug-like properties.

First, validate the targets file to see what peptides we have

Then submit a batch prediction job with max_peptides=5 and demo_mode=True

Monitor the progress and show me the results when complete, including:
- Which peptides completed successfully
- Any confidence score patterns
- Overall batch statistics

预期工作流程：

1. 文件验证显示了5种以上具有HighFold标记的有效肽
2. 已提交带有跟踪ID的批处理作业
3. 通过日志进行进度监控
4. 带有单个预测文件的最终结果
5. 汇总统计数据和质量指标

示例4：结构松弛管道

目标： 能量最小化预测结构

使用脚本：

# Relax structure with OpenMM
python scripts/relax_structure.py \
  --input examples/data/structures/1.pdb \
  --output results/1_relaxed.pdb \
  --restraint_force 20000.0 \
  --demo

使用MCP（克劳德代码）：

Submit a structure relaxation job for @examples/data/structures/1.pdb with:
- restraint_force: 20000.0
- tolerance: 2.39
- demo_mode: True
- job_name: "peptide_relaxation"

Show me the energy changes when complete

示例5：自定义数据集的模型微调

目标： 调整HighFold以适应特定的环肽家族

使用MCP（克劳德代码）：

I want to fine-tune a model for my custom cyclic peptide dataset.

First, create a demo targets file with 10 peptides using create_demo_targets_file

Then submit a model fine-tuning job with:
- num_epochs: 5
- batch_size: 2
- learning_rate: 0.0001
- demo_mode: True

Monitor the training progress and show me the final model performance

______________________________________________________________________

演示数据

这 examples/data/ 目录包含全面的示例数据：

序列数据

来自targets.tsv的肽样本：

• PhdLP_d （D7.6）：脯氨酸、组氨酸、D-亮氨酸、亮氨酸、脯氨酸、D-丙氨酸
• VIhFIh. （D7.8）：缬氨酸、异亮氨酸、甲基化组氨酸、苯丙氨酸、异亮氨酸和甲基化组氨酸
• dLhdL.PL （D8.1）：D-亮氨酸、甲基化组氨酸、D-亮氨酸、脯氨酸、亮氨酸

对齐数据

结构数据

______________________________________________________________________

配置文件

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

配置结构

配置示例

{
  "model": {
    "name": "model_2_ptm",
    "use_templates": true,
    "max_template_date": "2022-01-01"
  },
  "processing": {
    "demo_mode": true,
    "validate_sequences": true,
    "use_gpu": false
  },
  "cyclic_peptide": {
    "handle_d_amino_acids": true,
    "handle_n_methylation": true,
    "cyclization_method": "auto"
  },
  "output": {
    "save_confidence_scores": true,
    "save_template_info": true,
    "output_format": "pdb"
  }
}

______________________________________________________________________

环肽符号

HighFold MeD使用专门的符号表示修饰氨基酸：

符号元素

真实数据集示例

自 examples/data/sequences/targets.tsv:

______________________________________________________________________

故障排除

环境问题

问题： 未找到环境

# Check environment exists
ls -la env/

# Recreate if needed
mamba create -p ./env python=3.10 -y
mamba activate ./env
pip install loguru click pandas numpy tqdm fastmcp
mamba install -c conda-forge rdkit -y

问题： RDKit导入错误

# Ensure RDKit from conda-forge
mamba activate ./env
mamba install -c conda-forge rdkit -y

# Test import
python -c "from rdkit import Chem; print('RDKit working:', Chem.__version__)"

问题： FastMCP安装问题

# Force reinstall FastMCP
pip install --force-reinstall --no-cache-dir fastmcp

# Verify installation
python -c "import fastmcp; print('FastMCP version:', fastmcp.__version__)"

MCP服务器问题

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

# Check MCP registration
claude mcp list

# Remove and re-add if needed
claude mcp remove highfold-med-tools
claude mcp add highfold-med-tools -- $(pwd)/env/bin/python $(pwd)/src/server.py

# Verify connection
claude mcp list
# Should show: ✓ Connected

问题： 工具不工作

# Test server directly
python -c "
import sys; sys.path.append('src')
from server import mcp
tools = [name for name in dir(mcp) if not name.startswith('_')]
print('Available tools:', len([t for t in tools if hasattr(getattr(mcp, t), '__call__')]))
"

问题： 服务器中的导入错误

# Check all imports work
python -c "
import sys; sys.path.append('src')
from jobs.manager import job_manager
import pandas, numpy, loguru
print('All imports successful')
"

文件格式问题

问题： targets.tsv格式无效

Use validate_targets_file to check your file format. Required columns:
- target_chainseq: Peptide sequence in HighFold notation (required)
- targetid: Unique identifier (optional, auto-generated if missing)

问题： HighFold序列符号无效

Ensure sequences use proper notation:
✓ Correct: "PhdLP_d", "VIhFIh.", "dLhdL.PL"
✗ Incorrect: "PHDLP_D", "vihfih.", "DLHDL.PL"

- Use lowercase 'd' prefix for D-amino acids
- Use lowercase 'h' for methylated histidine
- Standard amino acids in uppercase

问题： 缺少对齐文件

# Check alignment directory
ls examples/data/alignments/

# Alignments are referenced in targets.tsv but paths may be absolute
# The MCP tools automatically resolve relative paths from examples/data/alignments/

作业管理问题

问题： 作业挂起/正在运行

Use get_job_log with job_id "" and tail=0 to see all logs
Check for error messages in the log output
Use cancel_job if needed to terminate stuck jobs

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

Use get_job_log to see error details:
get_job_log("", tail=100)

Common issues:
- File not found: Check input file paths
- Sequence validation: Use validate_targets_file first
- Dependency missing: Use check_dependencies

问题： 演示模式与实际计算

All tools default to demo_mode=True for testing
Set demo_mode=False for real computation (requires full dependencies)

Demo mode provides:
- Fast execution (~seconds)
- Realistic output format
- No heavy dependencies required
- Educational value for learning the workflow

性能问题

问题： 作业队列过长

Jobs run sequentially to prevent resource conflicts
Split large batches into smaller jobs:
- Single peptides: ~10 minutes each
- Small batch: 5-10 peptides maximum
- Large datasets: submit multiple smaller batches

问题： 内存错误

# Check available memory
free -h

# Reduce batch size or enable demo mode
# Large peptides or batches may require 8-16GB RAM

问题： 处理速度慢

Ensure you're using the intended mode:
- demo_mode=True: Fast simulation for testing
- demo_mode=False: Real computation (requires dependencies)

Check system resources:
- CPU: Multi-core beneficial for batch processing
- Memory: 4-8GB for single predictions, 16GB+ for large batches
- GPU: Recommended for model fine-tuning

______________________________________________________________________

开发和测试

运行测试

# Activate environment
mamba activate ./env

# Run individual script tests
python scripts/predict_structure.py --input examples/data/sequences/targets.tsv --index 0 --demo_mode
python scripts/batch_predict.py --input examples/data/sequences/targets.tsv --max_peptides 2 --demo_mode
python scripts/relax_structure.py --input examples/data/structures/1.pdb --demo
python scripts/finetune_model.py --demo --epochs 3

# Test MCP server
fastmcp dev src/server.py

启动开发服务器

# Run MCP server in development mode
fastmcp dev src/server.py
# Access MCP Inspector at: http://localhost:6274

手动验证提示

通过Claude Code接口进行最终验证：

# Quick verification (5 tests, ~5 minutes)
1. "What MCP tools are available from highfold-med-tools?"
2. "Use check_dependencies to verify environment setup"
3. "Use list_example_data to show available files"
4. "Use validate_targets_file to check examples/data/sequences/targets.tsv"
5. "Use list_jobs to show current job queue"

# Comprehensive testing (additional 5 tests)
6. "Create a demo targets file with create_demo_targets_file"
7. "Submit structure prediction with demo_mode=True"
8. "Check the status of the submitted job"
9. "Get logs for the job"
10. "Test error handling with invalid file path"

______________________________________________________________________

许可证

该项目扩展了原始 HighFold MeD 存储库与MCP集成，实现AI助手兼容性。

积分

• HighFold MeD：环肽的原始AlphaFold修饰
• FastMCP：模型上下文协议框架
• RDKit：分子操作和验证
• OpenMM：结构弛豫的分子动力学
• JAX/Haiku：用于模型微调的深度学习框架

______________________________________________________________________

快速参考

基本命令

# Environment setup
mamba activate ./env

# Register MCP server
claude mcp add highfold-med-tools -- $(pwd)/env/bin/python $(pwd)/src/server.py

# Test installation
claude mcp list

# Development server
fastmcp dev src/server.py

关键文件路径

• MCP服务器： src/server.py
• 演示数据： examples/data/sequences/targets.tsv
• 配置： configs/predict_structure_config.json
• 脚本： scripts/predict_structure.py

重要URL

• MCP检查员：http://localhost:6274（跑步时 fastmcp dev)
• FastMCP文档：https://fastmcp.com/docs
• HighFold MeD纸张：\[如果可用，请添加纸张链接\]

本自述提供了使用HighFold MeD MCP工具进行环肽计算分析的全面文档。有关其他帮助，请参阅 scripts/ 目录或使用 --help 用任何脚本标记。