内容
# fairchem-mcp
**可由代理控制的MCP服务器**，适用于 [FAIRChem](https://github.com/facebookresearch/fairchem)
和 [ASE](https://wiki.fysik.dtu.dk/ase/) 模拟。
目前大多数LLM驱动的模拟都是**批处理**：代理编写脚本，运行脚本，等待并读取输出。`fairchem-mcp` 使模拟**交互化**。模型仅需加载一次并保持驻留；后台运行松弛和分子动力学；代理可以**实时观察模拟并在运行中调整** —— 切换优化器、提高 `fmax`、改变温度、暂停或中止。
## 为什么
- **常驻模型**。仅需加载UMA/eSEN模型一次；在每次调用中重复使用。无需在每次运行中重新加载模型（耗时数秒至数分钟）。
- **实时监控**。`get_status` 返回步骤、能量、最大力和`trend`判决（`decreasing` / `plateaued` / `stuck` / `diverging`），以便代理决定是否干预。
- **运行中调整**。`steer` 可以 `pause` / `resume` / `abort`，`set_fmax`，`switch_optimizer` 或 `set_temperature`，在运行的作业中。切换优化器时会保留原子位置 —— 它只是重建驱动器。
- **混合命名空间**。高级工具 (`start_relaxation`，…) 和 `execute` / `inspect_expr` 出口共用一个 Python 命名空间，以便代理可以直接对相同的实时 `Atoms` 对象进行 Python 操作。
- **代码感知**。`introspect` 读取**已安装**的 API（真实签名和文档字符串）和实时对象，通过 `jedi` —— 而不是可能过时的文档。
## 安装
```bash
pip install -e . # 核心：mcp + ase + jedi + numpy（与EMT兼容）
pip install -e ".[fairchem]" # 添加 FAIRChem（torch + 模型）以用于 UMA/eSEN
pip install -e ".[lammps]" # 添加 LAMMPS 作为经典力引擎
pip install -e ".[saddles]" # 添加 Sella + POUNCE 以进行过渡态搜索
```
ASE、numpy、jedi 和 mcp 是**核心**依赖项（自动安装）—— 服务器可以直接使用内置的 EMT 计算器。
### FAIRChem（可选）
`pip install -e ".[fairchem]"` 引入 `fairchem-core`（PyTorch + 模型）。要实际加载 UMA 模型，还需要：
- 一个 **Hugging Face 账户**，具有访问 `facebook/UMA` 模型仓库的批准权限，并设置 `huggingface-cli login`（或 `HF_TOKEN`）；
- 适用于您平台的 PyTorch（用于 GPU 的 CUDA 构建；CPU 兼容但较慢）。
除了 `load_model` 之外，所有功能都与普通的 ASE 计算器 (`attach_emt`) 兼容，因此您可以在没有 GPU 或模型的情况下进行开发和测试。
### LAMMPS（可选）
`pip install -e ".[lammps]"` 安装 `lammps` Python 包。LAMMPS 用作**力引擎**（经典势能），而 ASE 驱动动力学，因此 `attach_lammps` 适用于每个可控制的作业（MD、松弛、NEB、声子、EOS、最小值搜索）。
**macOS 注意（Homebrew MPICH）：** PyPI `lammps` 轮链接 `@rpath/libmpi.12.dylib` 和 `libpmpi.12.dylib`，默认情况下动态加载器无法找到它们。如果您有 Homebrew 的 `mpich` (`brew install mpich`)，`attach_lammps` 会在首次使用时**自动符号链接**这些库到 `lammps` 包目录中。如果无法应用（只读安装、非 Homebrew MPI），请手动符号链接它们或在启动服务器之前导出：
```bash
export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_FALLBACK_LIBRARY_PATH
```
通过以下命令验证：`python -c "from lammps import lammps; lammps(cmdargs=['-log','none','-screen','none']).close(); print('ok')"`.
### 过渡态搜索（可选）
`pip install -e ".[saddles]"` 添加两个额外的鞍点后端：
[`sella`](https://github.com/zadorlab/sella) （有理函数 ASE 优化器）和 [`pounce-solver`](https://pypi.org/project/pounce-solver/) （多启动特征向量跟随）。**二聚体**方法 (`start_saddle_search`) 是纯 ASE 的，不需要这些。请参阅 [`examples/saddles/`](examples/saddles/) 以了解这三种方法。
## 注册到 Claude Code
将以下内容添加到您的 MCP 配置中（参见 `examples/claude_mcp_config.json`）：
```json
{
"mcpServers": {
"fairchem": { "command": "fairchem-mcp" }
}
}
```
## 工具
| 工具 | 用途 |
|---|---|
| `list_models` | 列出 FAIRChem 预训练模型 |
| `load_model` | 加载 UMA/eSEN 模型作为常驻计算器 |
| `attach_emt` | 附加快速 EMT 计算器（无 GPU/模型） |
| `attach_lammps` | 附加 LAMMPS（经典势能）作为力引擎 |
| `build_structure` / `load_structure` | 创建/注册 ASE 结构 |
| `start_relaxation` / `start_md` | 启动后台松弛 / 分子动力学（返回 `job_id`） |
| `start_neb` | 启动可控制的弹性带（反应能垒） |
| `start_saddle_search` | 通过二聚体方法（无 Hessian）寻找过渡态 |
| `start_sella_search` | 通过 Sella（RFO + 近似 Hessian）寻找过渡态 |
| `start_pounce_saddles` | 通过 POUNCE 特征向量跟随枚举鞍点 |
| `start_phonons` | 启动有限位移声子计算 |
| `start_eos_scan` | 扫描晶胞应变 → 拟合状态方程（V0、E0、体积模量） |
| `start_elastic_scan` | 应力-应变 → 弹性张量（C_ij）、VRH 模量、Born 稳定性 |
| `start_convex_hull` | 形成能 + 凸包（相稳定性、能量高于 hull） |
| `start_minima_search` | 通过抑制/泛洪寻找多个不同弛豫几何 |
| `get_status` / `get_trajectory` | 观察正在运行的作业 |
| `get_results` | 最终结果：NEB 能垒/能量、声子频率和稳定性、不同最小值、EOS 拟合 |
| `steer` | `pause`/`resume`/`abort`/`set_fmax`/`switch_optimizer`/`set_temperature`/`set_climb` |
| `introspect` | 已安装代码或实时对象的签名/文档字符串/成员 |
| `execute` / `inspect_expr` | 在共享会话命名空间中运行/评估 Python |
资源：`sim://models`，`sim://job/{id}/status`，`sim://job/{id}/trajectory`.
## 示例流程
```
attach_emt() -> calc_1
build_structure({"kind":"bulk","name":"Cu","crystalstructure":"fcc",
"a":3.6,"repeat":[2,2,2],"rattle":0.2}) -> struct_1
start_relaxation("struct_1","calc_1",optimizer="FIRE",fmax=0.01) -> job_1
get_status("job_1") -> {status:"running", trend:{label:"stuck", ...}}
steer("job_1","switch_optimizer",optimizer="LBFGS")
get_status("job_1") -> {status:"converged", ...}
introspect("atoms", live=True) -> 实时对象签名/文档字符串
```
## 寻找多个弛豫几何
`start_minima_search` 找到 PES 的多个**不同**局部最小值 —— 有助于表面吸附位点、团簇异构体或构象体。它从起始结构重复弛豫 PES，**偏向已找到的最小值排斥**，然后对每个逃逸点进行真正的 PES 提炼：
- `kernel="flooding"`（默认）添加高斯凸起 (`sigma` Å，`amplitude` eV）；`kernel="deflation"` 添加逆距离极点 (`eta`，`power`). 两种方法都适用于**固定框架**问题（吸附剂在冻结的板上，锚定构象体）。
- `kernel="basinhopping"`（随机踢 + 弛豫 + Metropolis 接受）是适用于**自由团簇 / 纳米颗粒**的正确工具，它们的刚体旋转会破坏空间偏差。与 `comparator="fingerprint"`（见下文）配对使用。
- 新的最小值通过能量 (`energy_tol`) 和结构`comparator` 进行 deduplication：`"rmsd"`（原始坐标，帧依赖 - 适用于固定框架）或`"fingerprint"`（排序的成对距离；旋转/平移/排列不变 - 适用于自由团簇和分子，或旋转副本不会被错误地计为不同）。每个接受的最小值都注册为其自己的结构。
这会重用 POUNCE 的 `find_minima`（抑制/泛洪）的**逃逸机制**，但通过 ASE 的梯度优化器驱动它 —— 这是 PES 的正确内部求解器，因此每个逃逸弛豫都是一个正常的、可控制的作业（观察趋势、`switch_optimizer`、`set_fmax`，暂停/中止）。POUNCE 的内点求解器不会被用作内部松弛器。
## 示例
[`examples/catalysis/`](examples/catalysis/) 有四个端到端的催化工作流程 —— 吸附能、吸附位点搜索、扩散能垒 NEB 和表面稳定性声子 —— 每个都作为一个可运行的脚本**和**一个 MCP 工具调用的演练。它们在 EMT 上运行；为 UMA 设置 `FAIRCHEM_MCP_EXAMPLE_MODEL`。
[`examples/saddles/`](examples/saddles/) 涵盖了三种单端过渡态路由 —— 二聚体、Sella 和 POUNCE 特征向量跟随 —— 在一个共享系统上，您可以比较它们。
[`examples/alloys/`](examples/alloys/) 建立了合金设计：弹性刚度张量 (`start_elastic_scan`)、形成能凸包 (`start_convex_hull`) 和一个根据稳定性筛选候选者并通过机械性能对幸存者进行排序的设计循环。
## 安全
`execute` / `inspect_expr` 在进程中运行任意 Python。这是一个**受信任的本地开发人员工具** —— 请勿将其暴露给不受信任的输入或网络。
## 注意
- 每次只能运行一个作业（序列化模型/GPU 访问）。
- 所有优化器/积分器都使用 `logfile=None`；stdio 传输保留 stdout 以用于 MCP 协议。
