ORCA MCP Server

ORCA MCP サーバー

ORCA 量子化学ソフトウェア向けの Model Context Protocol（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（string）：計算のタイプ（"single_point"、"optimization"、"frequency" など）
• charge（number）：分子の電荷
• multiplicity（number）：スピン多重度
• coordinates_xyz_or_internal（string、optional）：分子座標
• keywords（array、optional）：追加の ORCA キーワード
• accuracy_level（string、optional）："low"、"medium"、"high" のいずれか
• blocks（object、optional）：カスタムのパラメーターブロック

例：

{
  "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（string）：ORCA 入力ファイルの全内容

戻り値：

• 検証ステータスと詳細なエラー報告

suggest_keywords

計算タイプと現在のキーワードに基づいて、キーワードを提案します。

パラメーター：

• calculation_type（string）：実行する計算のタイプ
• current_keywords（array、optional）：すでに含まれているキーワード

戻り値：

• 推奨キーワードおよび任意のキーワードとその説明

プログラミングインターフェース

サーバーのコンポーネントを、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. リポジトリをフォークします
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. プルリクエストを作成します

開発ガイドライン

• 新機能には包括的なテストを作成してください
• TypeScript のベストプラクティスに従ってください
• 公開 API をドキュメント化してください
• 意味のあるコミットメッセージを使用してください
• 下位互換性を確保してください

ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳細はLICENSEファイルをご覧ください。

謝辞

• ORCA Quantum Chemistry Package：このサーバーがサポートする量子化学ソフトウェア
• Model Context Protocol：このサーバーが実装するプロトコルフレームワーク
• TypeScript Community：優れたツールと型システムへの貢献

サポート

質問、問題、貢献については、次の手順をご確認ください。

1. Issuesページを確認します
2. 詳細な情報を添えて新しい Issue を作成します
3. プロジェクトのディスカッションフォーラムで議論に参加します

ロードマップ

今後の機能

• Context7 Integration：ドキュメント検索と推奨機能を強化します
• Basis Set Optimization：分子の特性に基づいて基底関数系を自動選択します
• Job Monitoring：ORCA のジョブステータス監視と連携します
• Result Analysis：計算後の分析と可視化ツールを提供します
• Template Library：拡張可能な計算テンプレートライブラリを提供します
• Performance Profiling：計算のパフォーマンス分析と最適化を行います

長期目標

• Machine Learning Integration：機械学習に基づくパラメーター最適化
• Multi-software Support：ほかの量子化学パッケージをサポートします
• Web Interface：MCP サーバーのブラウザーベースのインターフェース
• Cloud Integration：クラウドベースの計算をサポートします
• Collaborative Features：複数ユーザーでの計算の共有と共同作業

---

注：これは独立したプロジェクトであり、ORCA 量子化学パッケージの開発者と公式に提携しているものではありません。