PLUMED2 MCP Server / PLUMED2 MCP 服务器

PLUMED2 MCP 服务器 / PLUMED2 MCP 服务器

English | 中文

---

English

概述

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：使用元动力学生成简单的距离集体变量

向 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.

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 提示：

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

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

示例 3：获取性能优化建议

向 AI 提示：

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

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

示例 4：使用模板

向 AI 提示：

Give me a PLUMED template for protein folding studies.

AI 的预期响应： AI 将使用 get_plumed_template 工具，并设置 template_name: "protein_folding"，然后返回一个完整模板，其中包含适用于蛋白质折叠模拟的常见集体变量和偏置方法。

测试

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

cd plumed_mcp_server
python -m pytest tests/ -v

全部 33 项测试都应通过（成功率 100%）。

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/: 综合测试套件

贡献

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

许可证

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