Content
# Tool List
[English](#english) |
## 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
```bash
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.):
```json
{
"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:
```json
{
"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:
```bash
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.
