AI导哈

晶体结构生成服务

一个用于生成精确晶体结构的Model Context Protocol (MCP)服务器，支持DFT、量子化学和凝聚态物理计算。

  • by Indranil2020
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Indranil2020/crystal_mcp_server

使用说明

晶体结构生成器MCP服务器

一个全面的模型上下文协议（MCP）服务器，用于为DFT、量子化学和凝聚态物理计算生成精确的晶体结构。

特性

  • ✨ 全覆盖：支持所有230个空间组
  • 🔬 PyXtal集成：高质量结构生成
  • 📐 结构转换：超级电池、板、表面
  • 🔷 对称性分析：Spglib驱动的对称性检测
  • 📁 多种格式：CIF、POSCAR、XYZ、JSON导出
  • ✅ 全面验证：距离检查、晶格验证
  • ⚡ MLFF优化：尚未实施
  • 🎯 地面状态搜索：尚未实施

有关最准确和完整的功能列表，请参阅 API 参考.

安装

先决条件

  • Node.js 18+和npm
  • Python 3.8+和pip
  • Git

快速安装

# Clone repository
git clone https://github.com/Indranil2020/crystal_mcp_server.git
cd crystal_mcp_server

# Install Node.js dependencies
npm install

# Install Python dependencies
pip install -r requirements.txt

# Build TypeScript
npm run build

# Run tests
npm test

详细安装

1.安装Node.js依赖项

npm install

这将安装：

  • @模型上下文协议/sdk
  • zod（模式验证）
  • python shell（python桥）

2.安装Python依赖项

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install packages
pip install -r requirements.txt

所需的Python包：

  • pyxtal>=1.0.0 -晶体结构生成
  • pymatgen>=2024.1.1 -材料分析
  • spglib>=2.5.0 -对称操作
  • ase>=3.22.0 -原子模拟环境

可选MLFF包（计划中；MLFF尚未实施）：

  • chgnet>=0.3.0 -CHGNet MLFF模型
  • matgl>=1.0.0 -M3GNet MLFF型号
  • mace-torch>=0.3.0 -MACE MLFF模型

3.构建和测试

# Compile TypeScript
npm run build

# Run tests
npm test

# Lint code
npm run lint

用法

启动服务器

# Start with npm
npm start

# Or run directly
node dist/index.js

服务器在用于MCP协议通信的stdio传输上运行。

连接到LLM

要从支持MCP的LLM客户端使用此服务器，请配置客户端以启动服务器 node dist/index.js 并将工作目录设置为此仓库。看 连接到LLM代理 有关分步设置示例。

可用工具

1.发电机_晶体

生成具有指定成分和空间群的晶体结构。

{
  composition: ["Si", "Si"],
  space_group: 227,  // Diamond structure
  seed: 42
}

2.generate_space_group_scan

扫描多个空间组以找到稳定的结构。

{
  composition: ["Na", "Cl"],
  space_groups: [225, 216, 221],
  parallel: true
}

3.制造超级电池

从现有结构创建超级单元。

{
  structure_dict: {...},  // Structure object from generate_crystal
  scaling_matrix: [2, 2, 2]  // 2x2x2 supercell, or [[2,0,0],[0,2,0],[0,0,2]]
}

4.发电机板

生成用于DFT计算的表面板。

{
  structure_dict: {...},  // Structure object from generate_crystal
  miller_indices: [1, 0, 0],
  thickness: 5,  // Number of atomic layers
  vacuum: 15.0   // Vacuum padding in Angstroms
}

5.分析对称性

检测并分析晶体对称性。

{
  structure_dict: {...},  // Structure object
  symprec: 0.001,         // Symmetry precision tolerance
  detect_primitive: true  // Find primitive cell
}

6.验证结构

验证晶体结构质量。

{
  structure_dict: {...},  // Structure object
  checks: ["distances", "lattice", "stoichiometry"],  // Available checks
  min_distance: 1.5  // Minimum interatomic distance in Angstroms
}

7.optimize_structure_mlff（尚未实现）

计划的MLFF优化接口（CHGNet、M3GNet、MACE）。

{
  structure_dict: {...},  // Structure object
  mlff_model: "chgnet",   // Options: "chgnet", "m3gnet", "mace"
  optimizer: "BFGS",      // Options: "BFGS", "FIRE", "LBFGS"
  fmax: 0.01,             // Force convergence criterion (eV/A)
  steps: 500              // Maximum optimization steps
}

8.ground_state_search（尚未实施）

计划在各个太空群中进行地面搜索。

{
  composition: ["Si", "Si"],
  space_groups: [227, 141, 194],
  mlff_model: "chgnet",
  num_structures_per_group: 5
}

9.出口结构

将结构导出为多种格式。

{
  structure_dict: {...},  // Structure object
  formats: ["cif", "poscar", "xyz", "json"],  // Output formats
  output_directory: "./output"  // Optional output path
}

例子

示例1：生成金刚石硅

const result = await mcpClient.callTool("generate_crystal", {
  composition: ["Si", "Si"],
  space_group: 227,
  seed: 42
});

示例2：创建曲面板

// First generate bulk structure
const bulk = await mcpClient.callTool("generate_crystal", {
  composition: ["Ti", "O", "O"],
  space_group: 136  // Rutile TiO2
});

// Then create (110) surface
const slab = await mcpClient.callTool("generate_slab", {
  structure_dict: bulk.structure,
  miller_indices: [1, 1, 0],
  thickness: 5,
  vacuum: 15.0,
  fix_bottom_layers: 2
});

示例3：地面状态搜索（尚未实现）

const search = await mcpClient.callTool("ground_state_search", {
  composition: ["Si", "Si"],
  space_groups: [227, 141, 194],  // Diamond, I41/amd, P63/mmc
  num_structures_per_group: 10,
  mlff_model: "chgnet",
  optimization_settings: {
    optimizer: "BFGS",
    fmax: 0.01,
    steps: 500
  }
});

建筑

crystal-mcp-server/
├── src/
│   ├── types/          # TypeScript type definitions
│   ├── utils/          # Utility functions
│   ├── python/         # Python backend scripts
│   ├── tools/          # MCP tool implementations
│   │   ├── generation/
│   │   ├── transformation/
│   │   ├── analysis/
│   │   ├── optimization/
│   │   └── export/
│   ├── server.ts       # MCP server setup
│   └── index.ts        # Entry point
├── tests/              # Test suites
├── docs/               # Documentation
└── package.json

代码质量标准

该项目遵循严格的防御性编程实践：

  • ✅ 100%类型提示 -所有功能均已完全键入
  • ✅ 防御验证 -处理前检查输入
  • ✅ 综合测试 -单元和集成测试
  • ✅ 清除错误消息 -包括可采取行动的建议
  • ✅ 符合PEP 8标准 -Python代码遵循标准
  • ✅ 符合ESLint标准 -TypeScript代码遵循标准

演出

基准测试

操作 时间 备注
生成晶体 <1s 单结构
空间组扫描（230） ~10分钟 并行模式
MLFF优化（尚未实施） N/A 计划功能
地面状态搜索（尚未实现） N/A 计划功能

内存需求

  • 最低配置：8 GB RAM，4核
  • 推荐：16GB RAM，8核
  • 大规模：32+GB RAM，GPU支持

故障排除

Python导入错误

# Verify Python packages
python -c "import pyxtal; print(pyxtal.__version__)"
python -c "import chgnet; print('CHGNet OK')"
python -c "import spglib; print('Spglib OK')"

MLFF模型加载失败（计划中）

# Download CHGNet model
python -c "from chgnet.model import CHGNet; CHGNet.load()"

# Check GPU availability (optional)
python -c "import torch; print(torch.cuda.is_available())"

权限错误

# Make Python scripts executable
chmod +x src/python/*.py

贡献

欢迎投稿！请确保：

  1. 所有测试均通过： npm test
  2. 代码为： npm run lint
  3. 遵循防御性编程指南
  4. 为新功能添加测试
  5. 更新文档

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

内置：

支持

状态：

版本：

最后更新时间： 2025年12月

相关 MCP