ORCA MCP Server

ORCA MCP 服务

一个面向 ORCA 量子化学软件的模型上下文协议（MCP）服务，提供用于生成、验证和优化 ORCA 输入文件的智能工具。

概述

ORCA MCP 服务是一款综合工具，旨在帮助量子化学研究人员和计算化学家进行 ORCA 计算。它提供以下智能辅助功能：

• 输入文件生成：根据分子结构和计算需求自动生成 ORCA 输入文件
• 语法验证：验证 ORCA 输入文件语法并检测常见错误
• 参数优化：推荐合适的基组、SCF 设置和内存配置
• 收敛诊断：分析计算失败原因并提出修复建议
• 关键字管理：推荐合适的关键字并检测冲突

功能

核心功能

• 🔧 输入文件生成：根据分子坐标和计算参数创建完整的 ORCA 输入文件
• ✅ 语法验证：全面验证 ORCA 输入文件语法并详细报告错误
• 💡 关键字建议：根据计算类型和当前设置智能推荐关键字
• 🎯 参数优化：智能推荐基组、SCF 设置和内存分配
• 🔍 收敛诊断：分析 SCF 收敛失败并提供针对性解决方案

支持的计算类型

• 单点能量计算
• 几何优化
• 频率计算
• 优化与频率联合计算
• TD-DFT（含时 DFT）
• MP2 和耦合簇方法
• NMR 和 EPR 计算

坐标格式支持

• XYZ 坐标：标准笛卡尔坐标
• 内坐标：Z 矩阵格式
• 外部文件：引用 .xyz 和 .gzmt 文件

安装

先决条件

• Node.js 18+
• npm 或 yarn
• TypeScript 5.0+

安装依赖项

npm install

构建服务

npm run build

运行测试

npm test

运行并收集覆盖率

npm run test:coverage

用法

作为 MCP 服务

该服务可与任何兼容 MCP 的客户端配合使用。配置客户端，通过 stdio 传输连接到此服务。

Claude Desktop 的配置示例：

{
  "mcpServers": {
    "orca-mcp-server": {
      "command": "node",
      "args": ["path/to/orca-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

可用工具

generate_input_file

根据计算参数生成完整的 ORCA 输入文件。

参数：

• calculation_type（字符串）：计算类型（"single_point"、"optimization"、"frequency" 等）
• charge（数字）：分子电荷
• multiplicity（数字）：自旋多重度
• coordinates_xyz_or_internal（字符串，可选）：分子坐标
• keywords（数组，可选）：其他 ORCA 关键字
• accuracy_level（字符串，可选）："low"、"medium" 或 "high"
• blocks（对象，可选）：自定义参数块

示例：

{
  "calculation_type": "optimization",
  "charge": 0,
  "multiplicity": 1,
  "coordinates_xyz_or_internal": "C 0.0 0.0 0.0\nH 0.0 0.0 1.0\nH 0.0 1.0 0.0\nH 1.0 0.0 0.0",
  "keywords": ["B3LYP", "def2-SVP"],
  "accuracy_level": "medium"
}

validate_input_syntax

验证 ORCA 输入文件的语法并检测常见错误。

参数：

• inputContent（字符串）：完整的 ORCA 输入文件内容

返回值：

• 验证状态和详细错误报告

suggest_keywords

根据计算类型和当前关键字获取关键字建议。

参数：

• calculation_type（字符串）：预期的计算类型
• current_keywords（数组，可选）：已有的关键字

返回值：

• 推荐和可选的关键字及其说明

编程接口

你也可以在 TypeScript/JavaScript 代码中直接使用服务组件：

import { KeywordManager } from './src/core/keywordManager.js';
import { CoordinateProcessor } from './src/core/coordinateProcessor.js';
import { CalculationTemplateEngine } from './src/core/calculationTemplateEngine.js';

// Initialize components
const keywordManager = new KeywordManager();
const coordinateProcessor = new CoordinateProcessor();
const templateEngine = new CalculationTemplateEngine();

// Parse coordinates
const molecule = coordinateProcessor.parse_xyz_coordinates(
  'C 0.0 0.0 0.0\nH 0.0 0.0 1.0',
  0, 1
);

// Generate template
const template = templateEngine.generate_dft_template(molecule, 'B3LYP', 'def2-SVP');

// Validate keywords
const validation = await keywordManager.validate_keyword_combination(['B3LYP', 'def2-SVP', 'Opt']);

架构

核心组件

• KeywordManager：管理 ORCA 关键字、验证关键字组合并建议缺少的关键字
• CoordinateProcessor：处理分子坐标的解析和验证
• ParameterBlockManager：生成 ORCA 参数块（%scf、%basis 等）
• CalculationTemplateEngine：为不同作业类型创建计算模板

智能组件

• ParameterRecommendationEngine：为基组、SCF 设置和内存提供智能建议
• ConvergenceDiagnostic：分析收敛失败并提出解决方案
• ORCAInputValidator：全面验证输入文件

类型系统

该服务使用在 src/types/orca.types.ts 中定义的全面 TypeScript 类型系统，涵盖：

• 分子结构和坐标格式
• ORCA 计算类型和参数
• 验证结果和错误报告
• 建议和诊断结果

示例

基本 DFT 优化

// Generate input for geometry optimization
const result = await generateInputFile({
  calculation_type: "optimization",
  charge: 0,
  multiplicity: 1,
  coordinates_xyz_or_internal: `
    C 0.0 0.0 0.0
    H 0.0 0.0 1.0
    H 0.0 1.0 0.0
    H 1.0 0.0 0.0
    H -1.0 0.0 0.0
  `,
  accuracy_level: "medium"
});

console.log(result.content);
// Output:
// ! B3LYP-D3BJ def2-SVP Opt
// 
// %pal NProcs 2 end
// 
// * xyz 0 1
// C 0.0 0.0 0.0
// H 0.0 0.0 1.0
// H 0.0 1.0 0.0
// H 1.0 0.0 0.0
// H -1.0 0.0 0.0
// *

重元素计算

// Get recommendations for heavy elements
const basisRecommendation = await recommendationEngine.recommend_basis_set(
  ['Au', 'Cl'],
  'high',
  2
);

console.log(basisRecommendation);
// Output:
// {
//   orbital_basis: "SARC-DKH-TZVP",
//   auxiliary_basis_jk: "SARC/JK",
//   auxiliary_basis_cosx: "SARC/J",
//   relativistic_method: "DKH",
//   reasoning: "High accuracy with heavy elements: SARC-DKH-TZVP with DKH relativistic treatment is recommended."
// }

SCF 收敛问题排查

// Analyze convergence failure
const diagnosis = convergenceDiagnostic.analyze_scf_failure(`
  SCF NOT CONVERGED AFTER 125 ITERATIONS
  oscillating behavior in DIIS
  Energy change: 1.234e-03
`);

console.log(diagnosis);
// Output:
// {
//   problem_type: "SCF_OSCILLATION",
//   summary: "SCF convergence is likely hindered by oscillating behavior...",
//   recommendations: [
//     "Try damping: %scf DampFac 0.7 DampErr 0.05 end",
//     "Use a level shifter: %scf Shift Shift 0.5 Erroff 0.1 end"
//   ],
//   suggested_keywords_add: ["VerySlowConv"],
//   suggested_block_modifications: {
//     scf: "DampFac 0.7\nDampErr 0.05"
//   }
// }

测试

该项目包含全面的测试覆盖：

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

测试结构

• 单元测试：测试各个组件
  • tests/core/：核心功能测试
  • tests/intelligent/：AI/ML 组件测试
  • tests/validation/：验证系统测试
• 集成测试：端到端工作流测试
  • tests/integration/：完整工作流测试

开发

项目结构

orca-mcp-server/
├── src/
│   ├── core/                 # Core functionality
│   │   ├── keywordManager.ts
│   │   ├── coordinateProcessor.ts
│   │   ├── parameterBlockManager.ts
│   │   └── calculationTemplateEngine.ts
│   ├── intelligent/          # AI/ML components
│   │   ├── parameterRecommendationEngine.ts
│   │   └── convergenceDiagnostic.ts
│   ├── validation/           # Validation systems
│   │   └── orcaInputValidator.ts
│   ├── types/               # TypeScript definitions
│   │   └── orca.types.ts
│   └── index.ts             # MCP server entry point
├── tests/                   # Test suites
├── build/                   # Compiled JavaScript
└── docs/                    # Documentation

构建

# Development build
npm run build

# Watch mode for development
npm run watch

代码质量

该项目使用：

• TypeScript 确保类型安全
• Jest 进行测试
• ESLint 检查代码
• Prettier 格式化代码

贡献

1. Fork 此代码仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行修改
4. 为新功能添加测试
5. 确保所有测试通过（npm test）
6. 提交修改（git commit -m 'Add amazing feature'）
7. 推送到分支（git push origin feature/amazing-feature）
8. 发起 Pull Request

开发指南

• 为新功能编写全面的测试
• 遵循 TypeScript 最佳实践
• 编写公共 API 文档
• 使用有意义的提交消息
• 确保向后兼容

许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

致谢

• ORCA Quantum Chemistry Package - 本服务支持的量子化学软件
• Model Context Protocol - 本服务实现的协议框架
• TypeScript Community - 感谢其提供出色的工具和类型系统

支持

如有问题、遇到故障或希望贡献：

1. 查看 Issues 页面
2. 创建新问题并提供详细信息
3. 在项目讨论论坛中参与交流

路线图

即将推出的功能

• Context7 Integration：增强文档查找和建议功能
• Basis Set Optimization：根据分子属性自动选择基组
• Job Monitoring：集成 ORCA 作业状态监控
• Result Analysis：计算后的分析和可视化工具
• Template Library：可扩展的计算模板库
• Performance Profiling：计算性能分析和优化

长期目标

• Machine Learning Integration：基于 ML 的参数优化
• Multi-software Support：支持其他量子化学软件包
• Web Interface：基于浏览器的 MCP 服务界面
• Cloud Integration：支持云端计算
• Collaborative Features：支持多用户共享计算和协作

---

注意：这是一个独立项目，与 ORCA 量子化学软件包的开发者没有官方关联。