Atomistic Toolkit MCP Server

MCP Atomic Toolkit

メモ

このプロジェクトは現在活発に開発中です。インターフェースや動作は変更される可能性があります。

ASE、pymatgen、および最新の機械学習原子間ポテンシャルを活用した、原子論的モデリングのワークフロー向け FastMCP サーバーです。

MCP クライアントに、次の実用的なツールキットを提供します。

• 構造の構築とインポート、
• セル（ひずみ、スーパーセル）や欠陥（空孔、置換、格子間原子）の編集、
• 構造最適化と NVE/NVT/NPT 分子動力学の実行、
• 体積弾性率の推定、
• 構造／軌跡の解析、
• 生成された成果物（データとプロット）のダウンロード。

---

✨ このリポジトリの特長

スクリプトを手作業でつなぎ合わせるのではなく、原子論的なワークフローを MCP ツールとして利用したい場合、このプロジェクトは次の機能を提供します。

• 一般的なシミュレーションタスクですぐに呼び出せる MCP ツール、
• 確認や再利用が容易な ファイルベースの出力、
• チャットのコンテキストにバイナリデータを含めずに済む、成果物のダウンロード URL、
• ヘルスチェックとサーバーカードのエンドポイントを備えた デプロイ対応の HTTP アプリ。

---

🚀 機能

• FastMCP ツールを介した MCP ネイティブのワークフロー
• 構造生成：バルク、表面、分子、スーパーセル、アモルファス、液体、双結晶、多結晶
• xyz/cif/POSCAR テキストからの 構造インポート
• 編集と欠陥：回転、平行移動、ひずみ、スーパーセル、ラップ、空孔、置換、格子間原子
• 計算器：auto は kim → orb → nequix → ASE EMT（Al/Cu/Ag/Au/Ni/Pd/Pt）を順に試します
• 解析フィッティング：Lennard-Jones、Morse、Buckingham の二体ポテンシャル（Render に適しています）
• 最適化と単一ポイントのエネルギー／力／応力計算
• 分子動力学：Velocity Verlet、Langevin、NVT Berendsen、NPT Berendsen
• レシピツール relax_and_md_workflow（構造を緩和してから MD を実行）
• 5 点のエネルギー対ひずみフィットによる 等方体積弾性率
• 解析出力：RDF ＋配位数、MSD ＋熱力学的傾向、VACF ＋拡散
• ダウンロード可能な成果物（xyz、extxyz、cif、traj、png、svg、csv、dat、...）
• レジストリ対応のエンドポイント（/healthz、サーバーカード、Streamable HTTP ルート）

---

⚡ クイックスタート

1) 必要条件

• Python 3.11+

2) インストール

基本インストールでは OpenKIM C++ API は不要です。

pip install -r requirements.txt

または：

pip install -e .

OpenKIM（kimpy）はオプションです。システムの KIM API に対してコンパイルされるため、以前は libkim-api がないマシンでデフォルトのインストールが失敗していました。

KIM 計算器を有効にするには：

# Debian/Ubuntu
sudo apt-get install -y libkim-api-dev pkg-config

pip install -e ".[kim]"

macOS（Homebrew）：brew install openkim-models kim-api を実行してから、pip install -e ".[kim]" を実行します。

追加オプションを使わない場合は、calculator_name='auto'、'emt'、'orb'、または 'nequix' を使用してください。KIM がない場合のフォールバックは、実行時コードにすでに実装されています。EMT は Al、Cu、Ag、Au、Ni、Pd、Pt に対応しています。

3) ローカルで実行

uvicorn mcp_atomictoolkit.http_app:app --host 0.0.0.0 --port 10000

別の方法：

python main.py

STDIO モード（デスクトップ MCP クライアント向け）：

python -m mcp_atomictoolkit.mcp_server

重要

STDIO トランスポートでは、JSON-RPC のために stdout をクリーンな状態に保つ必要があります。サーバーを STDIO モードで実行する際は、print() や stdout へのログ出力を避けてください。

4) 動作確認

curl -s http://localhost:10000/healthz

期待される応答：

{"status":"ok"}

---

🧰 ツールの概要

サーバーが公開する主な MCP ツール：

• list_workspace_capabilities_workflow
• build_structure_workflow
• import_structure_workflow
• manipulate_structure_workflow
• analyze_structure_workflow
• write_structure_workflow
• optimize_structure_workflow
• single_point_workflow
• estimate_elastic_workflow
• run_md_workflow
• relax_and_md_workflow
• analyze_trajectory_workflow
• autocorrelation_workflow

従来のエイリアスも登録されています：build_structure、read_structure_file、write_structure_file、optimize_with_mlip。

エージェントから最初に list_workspace_capabilities_workflow を呼び出してください。インポートされた計算器、EMT の元素サポート、積分器、構造タイプ、編集操作が報告されます。

---

🌐 エンドポイント

• POST / — 主要な MCP Streamable HTTP エンドポイント
• GET /healthz — ヘルスチェック
• GET /docs — 簡易ドキュメント（README）
• GET /.well-known/mcp/server-card.json — MCP サーバーカードのメタデータ
• GET /artifacts/{artifact_id}/{filename} — アーティファクトのダウンロードルート
• /sse/ — MCP アプリにマウントされた互換性エイリアスパス

---

📦 デプロイ

Render

render.yaml が含まれており、すぐに使用できます。

デフォルトの起動コマンド：

uvicorn mcp_atomictoolkit.http_app:app --host 0.0.0.0 --port $PORT

Docker

イメージには libkim-api-dev とオプションの [kim] エクストラがインストールされます。

docker build -t mcp-atomictoolkit .
docker run --rm -p 7860:7860 mcp-atomictoolkit

---

🗂️ プロジェクト構成

src/mcp_atomictoolkit/
  mcp_server.py          # FastMCP tool definitions
  http_app.py            # Starlette app + routing/endpoints
  workflows/core.py      # High-level workflow orchestration
  analysis/              # Structure/trajectory/VACF analysis logic
  structure_operations.py
  optimizers.py
  md_runner.py
  artifact_store.py      # Download artifact registration + URLs

---

🧪 ワークフローに関する注意事項（MCP クライアント向け）

構造構築の対応範囲

build_structure_workflow は以下に対応しています：

• バルク（ASE bulk）
• 表面（ASE surface）
• 分子（ASE molecule）
• スーパーセル（基本構造の倍数化）
• アモルファス／液体（ランダムに詰めた構造）
• 二結晶および多結晶（結晶粒の積層／回転）

既存の構造データは import_structure_workflow を使用して貼り付けます（xyz、cif、または poscar 形式のテキスト）。

編集と欠陥

manipulate_structure_workflow の操作：

• rotate、translate、strain、supercell、wrap
• vacancy（operation_kwargs.index）
• substitute（index、symbol）
• interstitial（symbol、オプションの position）

最適化オプション

optimize_structure_workflow で指定できる項目：

• max_steps、fmax（収束）
• maxstep、alpha（BFGS のステップ／減衰制御）
• constraints（fixed_atoms、fixed_bonds、fixed_cell）

単一点計算と弾性

single_point_workflow はエネルギー、力、応力（周期系の場合）を計算します。

estimate_elastic_workflow は 5 つの等方ひずみにおける E(strain) をフィッティングし、bulk_modulus_GPa と calculator_used を返します。

MD の積分器／アンサンブル

run_md_workflow は以下に対応しています：

• velocityverlet／nve（NVE）
• langevin／nvt-langevin（NVT）
• nvt／nvt-berendsen（NVT）
• npt／npt-berendsen（NPT；pressure_GPa、taup）

relax_and_md_workflow は最適化の後に MD を実行します。

すべてのエネルギー／MD の結果には calculator_requested、calculator_used、calculator_fallbacks が含まれるため、EMT による銅の計算を MLIP の結果と取り違えることはありません。

---

📈 GitHub Pulse

スター履歴

---

🤝 コントリビューション

• 出力はファイルベースとし、アーティファクトとして扱いやすい形式にしてください。
• ツールを追加する場合は、通常、以下の両方を更新してください：
  • workflows/core.py
  • mcp_server.py
  • http_app.py の TOOL_NAMES
• デプロイ契約を意図的に変更する場合を除き、http_app.py の互換性動作を維持してください。

---

📄 ライセンス

MIT — LICENSE を参照してください。