README - plumed2-mcp-server by phelanshao

PLUMED2 MCP Server / PLUMED2 MCP 服务器

English

Overview

The PLUMED2 MCP Server is a Model Context Protocol (MCP) server that provides AI assistants with powerful tools for generating, validating, and optimizing PLUMED input files for molecular dynamics simulations. This server enables seamless integration of PLUMED expertise into AI workflows.

Features

🔧 Input File Generation: Generate complete PLUMED input files with collective variables, bias methods, and output configurations
📋 Template System: Access pre-defined templates for common simulation scenarios (protein folding, drug binding, phase transitions, nucleation)
⚡ Performance Optimization: Get intelligent suggestions to optimize PLUMED performance for large systems
✅ Syntax Validation: Validate PLUMED syntax with detailed error reporting and reference checking
🌐 International: Fully English codebase with professional documentation

Installation

Prerequisites

Python 3.11 or higher
pip package manager

Install Dependencies

cd plumed_mcp_server
pip install -r requirements.txt

MCP Client Configuration

Add the following configuration to your MCP client settings (e.g., Claude Desktop, Cline, etc.):

{
  "mcpServers": {
    "plumed2": {
      "command": "python",
      "args": [
        "-m", "plumed_mcp_server.main"
      ],
      "cwd": "/path/to/plumed_mcp_server",
      "alwaysAllow": [
        "generate_plumed_input",
        "validate_plumed_syntax", 
        "optimize_plumed_performance",
        "get_plumed_template"
      ]
    }
  }
}

Note: Replace /path/to/plumed_mcp_server with the actual path to your installation directory.

Available Tools

1. `generate_plumed_input`

Generate complete PLUMED input files based on simulation requirements.

Parameters:

collective_variables (required): List of collective variables to compute
bias_methods (optional): List of bias methods to apply
output_config (optional): Output configuration settings
system_info (optional): System information for optimization
molinfo_config (optional): Molecular information settings
group_definitions (optional): Custom group definitions

2. `validate_plumed_syntax`

Validate PLUMED input syntax and check for common errors.

Parameters:

plumed_input (required): PLUMED input content to validate
number_of_replicas (optional): Number of replicas for @replicas syntax validation

3. `optimize_plumed_performance`

Get performance optimization suggestions for PLUMED simulations.

Parameters:

plumed_input (required): PLUMED input content to analyze
system_info (optional): System information (number of atoms, simulation length, etc.)

4. `get_plumed_template`

Retrieve pre-defined or custom PLUMED templates.

Parameters:

template_name (required): Name of the template to retrieve
system_type (optional): Type of system for template customization

Usage Examples

Example 1: Generate a Simple Distance CV with Metadynamics

Prompt to AI:

Generate a PLUMED input file for metadynamics simulation of a protein. I want to use the distance between atoms 1 and 2 as a collective variable, with metadynamics bias. Include output every 100 steps.

Expected AI Response: The AI will use the generate_plumed_input tool with parameters like:

{
  "collective_variables": [
    {
      "type": "DISTANCE",
      "label": "d1",
      "atoms": [1, 2]
    }
  ],
  "bias_methods": [
    {
      "type": "METAD",
      "arg": "d1",
      "sigma": 0.1,
      "height": 1.0,
      "pace": 500
    }
  ],
  "output_config": {
    "stride": 100,
    "file": "colvar.dat"
  }
}

Generated Output:

# PLUMED input file generated by PLUMED2 MCP Server
# Collective Variables
d1: DISTANCE ATOMS=1,2

# Bias Methods  
METAD ARG=d1 SIGMA=0.1 HEIGHT=1.0 PACE=500

# Output
PRINT ARG=d1 STRIDE=100 FILE=colvar.dat

Example 2: Validate PLUMED Syntax

Prompt to AI:

Please validate this PLUMED input:
d: DISTANCE ATOMS=1,2
METAD ARG=d SIGMA=0.1 HEIGHT=1.0 PACE=500
PRINT ARG=d STRIDE=100 FILE=colvar.dat

Expected AI Response: The AI will use the validate_plumed_syntax tool and report validation results, including any syntax errors, warnings, or suggestions.

Example 3: Get Performance Optimization

Prompt to AI:

Optimize this PLUMED input for a large system with 100,000 atoms:
[PLUMED input content]

Expected AI Response: The AI will use the optimize_plumed_performance tool and provide specific suggestions like using neighbor lists, adjusting stride values, or optimizing collective variable calculations.

Example 4: Use Templates

Prompt to AI:

Give me a PLUMED template for protein folding studies.

Expected AI Response: The AI will use the get_plumed_template tool with template_name: "protein_folding" and return a complete template with common collective variables and bias methods for protein folding simulations.

Testing

Run the test suite to verify installation:

cd plumed_mcp_server
python -m pytest tests/ -v

All 33 tests should pass (100% success rate).

Development

The server is built using the FastMCP framework and follows modular design principles:

tools/: MCP tool implementations
logic/: Core business logic modules
resources/: MCP resource providers
tests/: Comprehensive test suite

Contributing

Contributions are welcome! Please ensure all tests pass and follow the existing code style.

License

This project is open source. Please check the license file for details.

中文

概述

PLUMED2 MCP 服务器是一个模型上下文协议（MCP）服务器，为AI助手提供强大的工具来生成、验证和优化分子动力学模拟的PLUMED输入文件。该服务器能够将PLUMED专业知识无缝集成到AI工作流程中。

功能特性

🔧 输入文件生成: 生成包含集体变量、偏置方法和输出配置的完整PLUMED输入文件
📋 模板系统: 访问常见模拟场景的预定义模板（蛋白质折叠、药物结合、相变、成核）
⚡ 性能优化: 获得针对大型系统的PLUMED性能优化智能建议
✅ 语法验证: 验证PLUMED语法，提供详细的错误报告和引用检查
🌐 国际化: 完全英文化的代码库和专业文档

安装

前置要求

Python 3.11 或更高版本
pip 包管理器

安装依赖

cd plumed_mcp_server
pip install -r requirements.txt

MCP 客户端配置

将以下配置添加到您的MCP客户端设置中（如Claude Desktop、Cline等）：

{
  "mcpServers": {
    "plumed2": {
      "command": "python",
      "args": [
        "-m", "plumed_mcp_server.main"
      ],
      "cwd": "/path/to/plumed_mcp_server",
      "alwaysAllow": [
        "generate_plumed_input",
        "validate_plumed_syntax", 
        "optimize_plumed_performance",
        "get_plumed_template"
      ]
    }
  }
}

注意: 请将 /path/to/plumed_mcp_server 替换为您的实际安装目录路径。

可用工具

1. `generate_plumed_input`

根据模拟需求生成完整的PLUMED输入文件。

参数:

collective_variables (必需): 要计算的集体变量列表
bias_methods (可选): 要应用的偏置方法列表
output_config (可选): 输出配置设置
system_info (可选): 用于优化的系统信息
molinfo_config (可选): 分子信息设置
group_definitions (可选): 自定义组定义

2. `validate_plumed_syntax`

验证PLUMED输入语法并检查常见错误。

参数:

plumed_input (必需): 要验证的PLUMED输入内容
number_of_replicas (可选): 用于@replicas语法验证的副本数量

3. `optimize_plumed_performance`

获取PLUMED模拟的性能优化建议。

参数:

plumed_input (必需): 要分析的PLUMED输入内容
system_info (可选): 系统信息（原子数、模拟长度等）

4. `get_plumed_template`

检索预定义或自定义的PLUMED模板。

参数:

template_name (必需): 要检索的模板名称
system_type (可选): 用于模板定制的系统类型

使用示例

示例1: 生成简单的距离CV与元动力学

AI提示词:

为蛋白质的元动力学模拟生成一个PLUMED输入文件。我想使用原子1和2之间的距离作为集体变量，应用元动力学偏置。每100步输出一次。

预期AI响应: AI将使用 generate_plumed_input 工具，参数如下：

{
  "collective_variables": [
    {
      "type": "DISTANCE",
      "label": "d1",
      "atoms": [1, 2]
    }
  ],
  "bias_methods": [
    {
      "type": "METAD",
      "arg": "d1",
      "sigma": 0.1,
      "height": 1.0,
      "pace": 500
    }
  ],
  "output_config": {
    "stride": 100,
    "file": "colvar.dat"
  }
}

生成的输出:

# PLUMED input file generated by PLUMED2 MCP Server
# Collective Variables
d1: DISTANCE ATOMS=1,2

# Bias Methods  
METAD ARG=d1 SIGMA=0.1 HEIGHT=1.0 PACE=500

# Output
PRINT ARG=d1 STRIDE=100 FILE=colvar.dat

示例2: 验证PLUMED语法

AI提示词:

请验证这个PLUMED输入：
d: DISTANCE ATOMS=1,2
METAD ARG=d SIGMA=0.1 HEIGHT=1.0 PACE=500
PRINT ARG=d STRIDE=100 FILE=colvar.dat

预期AI响应: AI将使用 validate_plumed_syntax 工具并报告验证结果，包括任何语法错误、警告或建议。

示例3: 获取性能优化

AI提示词:

为包含100,000个原子的大型系统优化这个PLUMED输入：
[PLUMED输入内容]

预期AI响应: AI将使用 optimize_plumed_performance 工具并提供具体建议，如使用邻居列表、调整步长值或优化集体变量计算。

示例4: 使用模板

AI提示词:

给我一个用于蛋白质折叠研究的PLUMED模板。

预期AI响应: AI将使用 get_plumed_template 工具，参数为 template_name: "protein_folding"，并返回包含蛋白质折叠模拟常用集体变量和偏置方法的完整模板。

测试

运行测试套件以验证安装：

cd plumed_mcp_server
python -m pytest tests/ -v

所有33个测试都应该通过（100%成功率）。

开发

该服务器使用FastMCP框架构建，遵循模块化设计原则：

tools/: MCP工具实现
logic/: 核心业务逻辑模块
resources/: MCP资源提供者
tests/: 综合测试套件

贡献

欢迎贡献！请确保所有测试通过并遵循现有的代码风格。

许可证

本项目为开源项目。请查看许可证文件了解详情。

plumed2-mcp-server

PLUMED2 MCP Server / PLUMED2 MCP 服务器

English

Overview

Features

Installation

Prerequisites

Install Dependencies

MCP Client Configuration

Available Tools

1. generate_plumed_input

2. validate_plumed_syntax

3. optimize_plumed_performance

4. get_plumed_template

Usage Examples

Example 1: Generate a Simple Distance CV with Metadynamics

Example 2: Validate PLUMED Syntax

Example 3: Get Performance Optimization

Example 4: Use Templates

Testing

Development

Contributing

License

中文

概述

功能特性

安装

前置要求

安装依赖

MCP 客户端配置

可用工具

1. generate_plumed_input

2. validate_plumed_syntax

3. optimize_plumed_performance

4. get_plumed_template

使用示例

示例1: 生成简单的距离CV与元动力学

示例2: 验证PLUMED语法

示例3: 获取性能优化

示例4: 使用模板

测试

开发

贡献

许可证

1. `generate_plumed_input`

2. `validate_plumed_syntax`

3. `optimize_plumed_performance`

4. `get_plumed_template`

1. `generate_plumed_input`

2. `validate_plumed_syntax`

3. `optimize_plumed_performance`

4. `get_plumed_template`