内容
# DFT AutoPilot
**English** | [简体中文](README.zh-CN.md)
> 在自己的高性能计算（HPC）环境中运行第一性原理DFT计算（Quantum ESPRESSO · VASP · Gaussian），通过聊天客户端进行操作 —— **您自己的** HPC。一个MCP服务器 + 一个Claude技能，将 *"计算NiO的DOS，包含Hubbard U"* 转化为完整的 **模型 → 计算 → 分析 → 报告** 工作流程。
[](https://www.npmjs.com/package/dft-autopilot-mcp)
[](https://www.npmjs.com/package/dft-autopilot-mcp)
[](LICENSE)
[](https://modelcontextprotocol.io)
DFT AutoPilot 是 **BYO‑HPC** （自带高性能计算）：它提供 **编排** 功能，包括输入生成、作业提交、结果提取、文献/材料查找、绘图和报告生成 —— 并在 **您配置的** 计算后端上运行所有操作：国家超级计算网络（SCNet）、**任何Slurm集群（通过SSH）** 或您的 **本地** 机器。它不附带任何计算账户。
---
## ⚠️ 免责声明与责任（请阅读）
DFT AutoPilot仅使用 **您提供的凭证和计算分配** 来编排计算。您使用它时，意味着您理解并同意：
- **您在自己的账户/HPC分配上运行作业，费用和风险自负。** 您对所有计算费用、资源使用、作业行为和生成的数据负责。
- **您负责遵守计算提供商的服务条款** （例如超级计算中心、SCNet或机构集群），以及您使用的DFT引擎的许可证（Quantum ESPRESSO是GPL；**VASP和Gaussian是专有软件，需要您自己的有效许可证**）。
- 本软件按 **"原样"** 提供，不提供任何形式的保证，遵循Apache-2.0许可证。作者 **不承担** 因使用该软件而产生的计算费用、资源浪费、数据丢失、计算失败或错误等任何损害的责任（参见LICENSE第7-8节）。
- 维护者 **不提供托管服务** ，也不访问您的任何账户或数据。该项目 **不隶属于或得到** SCNet、Quantum ESPRESSO项目、VASP或Gaussian的认可或支持。
科学结果必须由合格的研究人员验证。自动代理可能会犯物理错误 —— 请始终审查计划和数值。
---
## 功能
- **3种引擎**：Quantum ESPRESSO、VASP、Gaussian 16 —— 针对每种引擎的输入生成、提交和结果解析。
- **BYO‑HPC后端**：`local` · `slurm`（任何Slurm集群，通过SSH）· `scnet`（国家超级计算网络，使用您自己的账户）。
- **19种MCP工具**，涵盖整个流程（见下文）。
- **`dft-compute`技能**：一种自主的"计算化学家"工作流程，具有强制性的计划审查和每个参数的 `_reasons` 审计。
- **内置知识**：SSSP截止建议、DFT+U指导、QE/VASP参数参考、故障排除说明。
### 工具
| 分组 | 工具 |
|------|------|
| QE | `create_qe_input`, `extract_dft_results`, `lookup_pseudopotential`, `lookup_hubbard_u`, `import_structure` |
| VASP | `create_vasp_input`, `extract_vasp_results` |
| Gaussian | `create_gaussian_input`, `extract_gaussian_results` |
| 作业（后端无关） | `submit_compute_job`, `check_job_status`, `download_job_results`, `preview_remote_file`, `cancel_job` |
| 助手 | `run_pymatgen`, `plot_chart`, `write_report`, `search_literature`, `search_materials` |
---
## 先决条件
- **Node.js ≥ 18** （MCP服务器是Node/TypeScript）。
- 对于`run_pymatgen`、`import_structure`和结构处理：**Python 3**，并安装`pymatgen`和`ase`，且在`PATH`上。
- **DFT引擎**本身在您选择的后端（QE / VASP / Gaussian — 由您获取和许可）。
- 对于`slurm`：**无密码SSH**到集群的登录节点。对于`scnet`：您自己的**SCNet账户**（AccessKey/SecretKey）。
> MCP安装 **不** 安装Python、引擎或赝势 —— 这些由您提供。
---
## 安装
### A. Claude Code插件（推荐 — 技能 + 服务器合一）
```bash
/plugin marketplace add The66user/dft-autopilot-mcp
/plugin install dft-autopilot@dft-autopilot-marketplace
```
您将在安装时被提示进行配置（计算后端、API密钥）；密钥存储在您的操作系统密钥链中。
### B. 通过npm的任何MCP客户端（例如Claude Code CLI）
```bash
claude mcp add --env COMPUTE_PROVIDER=local --env MP_API_KEY=YOUR_KEY \
dft-autopilot -- npx -y dft-autopilot-mcp
```
### C. Claude Desktop（`claude_desktop_config.json`）
```jsonc
{
"mcpServers": {
"dft-autopilot": {
"command": "npx",
"args": ["-y", "dft-autopilot-mcp"],
"env": {
"COMPUTE_PROVIDER": "local",
"MP_API_KEY": "您的材料项目密钥"
}
}
}
}
```
一个一键式 **`.mcpb`** 包也附在GitHub Releases中（Claude Desktop → 设置 → 扩展）。注意：`.mcpb` 包仅包含Node服务器 — Python/pymatgen和DFT引擎必须已安装在您的机器上。
---
## 配置计算后端
设置`COMPUTE_PROVIDER`和匹配的变量（完整列表见[`server/.env.example`](server/.env.example)）。
### `local`
在本地机器上运行。需要本地安装引擎。
```
COMPUTE_PROVIDER=local
```
### `slurm` — 任意Slurm集群（通过SSH）
```
COMPUTE_PROVIDER=slurm
SLURM_HOST=您@login.cluster.edu # 或 ~/.ssh/config 别名；需要无密码SSH
SLURM_REMOTE_BASE_DIR=/scratch/您/dft-autopilot
SLURM_PARTITION=cpu
SLURM_MODULES=module load quantum-espresso/7.4
SLURM_PSEUDO_DIR=/scratch/您/pseudo # 可选：重写QE pseudo_dir
```
### `scnet` — 国家超级计算网络（您自己的账户）
```
COMPUTE_PROVIDER=scnet
SCNET_USER=...
SCNET_ACCESS_KEY=...
SCNET_SECRET_KEY=...
SCNET_CLUSTER_ID=...
SCNET_HPC_URL=...
SCNET_EFILE_URL=...
# ... 见.env.example获取完整列表
```
> **不附带凭证。** 您选择的后端运行在 **您的** 账户下。
---
## 连接您的DFT引擎
DFT AutoPilot **调用** 您已安装的引擎 — 它从不捆绑或安装它们。本节仅介绍 **编排器如何在每个后端查找和运行它们**。（编译QE或安装许可的VASP/Gaussian构建超出了范围 — 请参见每个引擎的文档。）
### `local`
作业通过 `bash -lc` （您的**登录shell**）运行，因此可执行文件（`pw.x`、`vasp_std`、`g16`等）只需在登录shell的`PATH`中。最简单的方法是在您的`~/.bashrc`中激活环境：
```bash
# ~/.bashrc
conda activate qe # 或：module load quantum-espresso/7.4
```
- **QE赝势：** 生成的`.in`中的`pseudo_dir`应指向您的本地UPF文件夹（`QE_PSEUDO_DIR`，或在生成输入时设置）。
- **VASP：** 确保`POTCAR`存在于作业目录中。
### `slurm`
引擎在生成的`sbatch`脚本中从`SLURM_MODULES`（和可选的`SLURM_QE_BIN_DIR`，添加到`PATH`）加载：
```
SLURM_MODULES=module load quantum-espresso/7.4; module load vasp/6.4
SLURM_QE_BIN_DIR=/opt/qe/bin # 可选，如果二进制文件不在模块中
```
- **QE赝势：** 设置`SLURM_PSEUDO_DIR` — `.in`中的`pseudo_dir`将在提交时 **自动重写为此路径**。
- **VASP：** 将`POTCAR`放在作业目录中（它与输入一起上传）；Slurm后端不从库中组装POTCAR。
### `scnet`
每个引擎从您指向的环境脚本中加载；对于VASP，`POTCAR`由元素自动组装：
```
SCNET_QE_ENV_SCRIPT=/path/to/qe-env.sh SCNET_QE_PATH=/path/to/pw.x
SCNET_PSEUDO_DIR=/path/to/pseudo
SCNET_VASP_ENV_SCRIPT=/path/to/vasp-env.sh SCNET_POTCAR_DIR=/path/to/potcar-library
SCNET_GAUSSIAN_ENV_SCRIPT=/path/to/g16-env.sh
```
> 完整的变量列表和注释：[`server/.env.example`](server/.env.example)。
---
## 用法
用普通语言与您的客户端对话 — `dft-compute`技能驱动整个流程。默认情况下，它 **研究参数，显示计划，并等待您的批准**，然后生成输入，提交到您的后端，监控，下载，解析结果，并编写报告。每个它选择的 参数都带有引用的原因。
### 典型会话
> **您：** 使用Quantum ESPRESSO放松Si的体积，然后计算其能带结构，在我的Slurm集群上。
>
> **代理：** *(查找SSSP截止值，扫描文献)* 计划如下：
> 1. `vc-relax` — ecutwfc 50 / ecutrho 400 Ry（SSSP效率），8×8×8 k-grid
> 2. `scf` 在放松的结构上
> 3. `bands` 沿Γ–X–W–K–Γ–L
> 16个核心，≈20分钟。 **批准？**
>
> **您：** 执行
>
> **代理：** *(生成输入 → 提交 → 监控 → 下载 → 解析)* 完成。间接间隙 **≈0.6 eV** （Γ→X），放松a = 5.47 Å。报告位于 `Si_bulk/report.md`，能带图位于 `Si_bulk/04_bands/`。
### 更多您可以要求的内容
- *"使用Gaussian优化水分子，B3LYP/6-311+G(d,p)，然后进行频率检查。*
- *"计算NiO的DOS，包含Hubbard U — 先查找U值。*
- *"使用VASP查找这两个结构之间的Li-diffusion NEB障碍。*
> 想要跳过审查并立即运行？直接说（例如“跳过计划，直接执行”）。
---
## 许可证
Apache-2.0 — 见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。第三方数据/引擎归属（SSSP，QE/VASP/Gaussian）在NOTICE中。
个人和学术使用免费。如果您需要商业支持、托管/端到端DFT服务或合作，请联系存储库配置文件中的联系人。
## 贡献与安全
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [SECURITY.md](SECURITY.md)。安装任何插件都会运行与您的HPC凭证对话的代码 — 请审查源代码并仅配置您信任的后端。
