虎鲸-mcp服务器

Name: 虎鲸-mcp服务器
Author: PhelanShao

作者：PhelanShao19 星标更新：2025-06-02

安装使用来源：spider==github.com

项目介绍

ORCA MCP Server

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

概述

ORCA MCP Server 是一个全面的工具，旨在帮助量子化学研究人员和计算化学家进行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';

// 初始化组件
const keywordManager = new KeywordManager();
const coordinateProcessor = new CoordinateProcessor();
const templateEngine = new CalculationTemplateEngine();

// 解析坐标
const molecule = coordinateProcessor.parse_xyz_coordinates(
  'C 0.0 0.0 0.0\nH 0.0 0.0 1.0',
  0, 1
);

// 生成模板
const template = templateEngine.generate_dft_template(molecule, 'B3LYP', 'def2-SVP');

// 验证关键字
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优化

// 生成几何优化输入
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);
// 输出：
// ! 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
// *

重元素计算

// 获取重元素的推荐
const basisRecommendation = await recommendationEngine.recommend_basis_set(
  ['Au', 'Cl'],
  'high',
  2
);

console.log(basisRecommendation);
// 输出：
// {
//   orbital_basis: "SARC-DKH-TZVP",
//   auxiliary_basis_jk: "SARC/JK",
//   auxiliary_basis_cosx: "SARC/J",
//   relativistic_method: "DKH",
//   reasoning: "高精度重元素：推荐使用带有DKH相对论处理的SARC-DKH-TZVP。"
// }

SCF收敛故障排除

// 分析收敛失败
const diagnosis = convergenceDiagnostic.analyze_scf_failure(`
  SCF NOT CONVERGED AFTER 125 ITERATIONS
  在DIIS中振荡行为
  能量变化：1.234e-03
`);

console.log(diagnosis);
// 输出：
// {
//   problem_type: "SCF_OSCILLATION",
//   summary: "SCF收敛可能受到振荡行为的影响...",
//   recommendations: [
//     "尝试阻尼：%scf DampFac 0.7 DampErr 0.05 end",
//     "使用级别移位：%scf Shift Shift 0.5 Erroff 0.1 end"
//   ],
//   suggested_keywords_add: ["VerySlowConv"],
//   suggested_block_modifications: {
//     scf: "DampFac 0.7\nDampErr 0.05"
//   }
// }

测试

项目包括全面的测试覆盖：

# 运行所有测试
npm test

# 带覆盖率运行测试
npm run test:coverage

# 监视模式运行测试
npm run test:watch

测试结构

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

开发

项目结构

orca-mcp-server/
├── src/
│   ├── core/                 # 核心功能
│   │   ├── keywordManager.ts
│   │   ├── coordinateProcessor.ts
│   │   ├── parameterBlockManager.ts
│   │   └── calculationTemplateEngine.ts
│   ├── intelligent/          # AI/ML组件
│   │   ├── parameterRecommendationEngine.ts
│   │   └── convergenceDiagnostic.ts
│   ├── validation/           # 验证系统
│   │   └── orcaInputValidator.ts
│   ├── types/               # TypeScript定义
│   │   └── orca.types.ts
│   └── index.ts             # MCP服务器入口点
├── tests/                   # 测试套件
├── build/                   # 编译的JavaScript
└── docs/                    # 文档

构建

# 开发构建
npm run build

# 开发监视模式
npm run watch

代码质量

该项目使用：

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

贡献

分叉仓库
创建特性分支 (git checkout -b feature/amazing-feature)
进行更改
为新功能添加测试
确保所有测试通过 (npm test)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开拉取请求

开发指南

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

许可

本项目根据MIT许可发布 - 查看LICENSE文件了解详情。

致谢

ORCA量子化学包 - 本服务器支持的量子化学软件
模型上下文协议 - 本服务器实现的协议框架
TypeScript社区 - 提供优秀的工具和类型系统

支持

对于问题、问题或贡献：

查看问题页面
使用详细信息创建新问题
加入项目的讨论论坛

发展路线图

即将推出的功能

Context7集成：增强的文档查找和推荐
基组优化：基于分子属性的自动基组选择
作业监控：与ORCA作业状态监控集成
结果分析：计算后的分析和可视化工具
模板库：可扩展的计算模板库
性能分析：计算性能分析和优化

长期目标

机器学习集成：基于机器学习的参数优化
多软件支持：支持其他量子化学软件包
Web界面：MCP服务器的浏览器界面
云集成：支持基于云的计算
协作功能：多用户计算共享和协作

注意：这是一个独立项目，不正式隶属于ORCA量子化学包开发者。