Atomistic Toolkit MCP Server

MCP Atomic Toolkit

说明

本项目正在积极开发中。接口和行为可能会有所变化。

这是一个基于 FastMCP 的服务，使用 ASE、pymatgen 和现代机器学习原子间势，支持原子建模工作流。

它为 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 传输必须保持 stdout 干净，以用于 JSON-RPC。在 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。

请先从 Agent 调用 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 会通过五个各向同性应变拟合 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 动态

Star 历史

---

🤝 贡献

• 保持输出以文件形式提供，并便于作为工件使用。
• 添加工具时，通常需要同时更新：
  • workflows/core.py
  • mcp_server.py
  • http_app.py TOOL_NAMES
• 除非有意更改部署契约，否则请保留 http_app.py 的兼容行为。

---

📄 许可证

MIT — 详见 LICENSE。