MDEngine

MDEngine

由 ForceField Silicon 打造

面向 Claude 和其他 Agent 的分子动力学工作台，配备 LAMMPS MCP 服务：原生 macOS Metal 轨迹查看器、命令行工具，以及可检查轨迹并以分离式后台任务运行 LAMMPS 模拟的 MCP 服务。托管版会在 GPU 上运行相同任务：Claude 将输入文件发送到 api.forcefieldsilicon.com 上的分子动力学 MCP 服务，并获取结果，无需安装任何内容。

从这里开始

• Claude Code：claude mcp add --transport http mdengine-cloud https://api.forcefieldsilicon.com/mcp
• claude.ai：添加自定义连接器，URL 为 https://api.forcefieldsilicon.com/mcp
• Claude Desktop：从 GitHub 发布页面安装 .mcpb 捆绑包
• 你的密钥附带一个额度包，访问 https://forcefieldsilicon.com/mdengine
• 矿物加工和蛋白质相关的流程指南：https://github.com/forcefieldsilicon/mdengine-plugins

状态：0.7.1 已发布。 已签名并通过公证的 macOS 应用、命令行工具、Claude Desktop 捆绑包，以及托管 GPU 版。发布说明：https://github.com/forcefieldsilicon/mdengine/releases

组成部分

产品	说明
MDEngine.app	Metal 查看器 — 环绕 / 平移 / 缩放相机，带有 20%/5% 刻度线的轨迹时间轴、CPK 元素颜色、XYZ / extended-XYZ、实时设置
mdengine-cli	对轨迹和输入文件执行 info / export / decimate / run
mdengine-mcp	MCP stdio 服务 — 轨迹工具，以及分离式 LAMMPS 任务运行器（submit_lammps / job_status / job_log / list_jobs / cancel_job）

构建

需要 macOS 14+ 和 Xcode 命令行工具。仅在使用 run / submit_lammps 时需要 LAMMPS（brew install lammps）。

swift build -c release            # all three products
./scripts/make_app.sh             # assemble + install /Applications/MDEngine.app

内置示例

示例	说明
lj_melt.xyz / lj_melt.in	Lennard-Jones 氩熔化 — 最简冒烟测试
fe_oxidation.xyz / fe_oxidation.in	ReaxFF 铁氧化：bcc Fe 板与 O₂ 气体接触，使用 LAMMPS 发行版中的 ffield.reax.Fe_O_C_H

轨迹读取器可安全读取正在写入的转储文件——即使运行中的模拟仍在写入文件，也会解析其中已完成的帧，因此你可以在运行过程中检查模拟。含有非有限（NaN/inf）坐标的行会被丢弃。

这两个输入文件均可直接用于 mdengine run 和 submit_lammps。裸力场名称会自动解析：如果未设置 $LAMMPS_POTENTIALS，MDEngine 会根据 LAMMPS 安装位置推导该路径。

MCP 服务

mdengine-mcp 是一个无需依赖的 MCP stdio 服务，已列入 MCP Registry，名称为 com.forcefieldsilicon/mdengine（本仓库中的 server.json）。每个版本都会附带一个已签名的 macOS MCP Bundle （mdengine-mcp-<version>-macos-arm64.mcpb）：双击即可安装到 Claude Desktop，或将其解包（mcpb unpack）以供其他客户端使用。从源代码构建后，可在 Claude Code 中注册：

claude mcp add mdengine /path/to/.build/release/mdengine-mcp

或在 Claude Desktop 的 claude_desktop_config.json 中注册：

{ "mcpServers": { "mdengine": { "command": "/path/to/.build/release/mdengine-mcp" } } }

工具	功能
trajectory_info	帧数、原子数、逐原子字段、元素、边界框、电荷范围
z_profile	沉积/氧化深度分析：基底表面平面、探针穿透深度（最小值/平均值/最大值）、表面处与飞行中的数量、结合探针电荷、z 轴直方图
render_video	通过 Metal 渲染器将轨迹转换为 MP4（H.264）或动画 GIF：摄像机角度、步长、电影级环绕、烘焙到视频中的比例尺/帧注释、逐元素 colors/sizes、style: "contrast" 自动可见性
render_image	将单帧转换为 PNG，并提供相同的摄像机/样式选项——让 Agent 查看模拟状态
export_frame	将单帧导出为 XYZ；charges: true → 带 q 列的 extended-XYZ
decimate	每隔 N 帧保留一帧（始终保留最后一帧）
submit_lammps	分离式 LAMMPS 作业：即使服务退出或机器显示器进入睡眠（caffeinate）也会继续运行，并在无人值守时记录退出代码
job_status / job_log	状态 + 实时 thermo 尾部 / 原始日志尾部
job_files	定位已完成作业的输出文件（运行目录 + 记录目录）
list_jobs / cancel_job	~/.mdengine/jobs/ 下的注册表 / 向运行进程发送 SIGTERM（状态变为 cancelled）
list_hosts	来自 ~/.mdengine/hosts.json 的执行主机及默认主机
fetch_job	将远程作业的运行目录（转储文件、数据）和日志拉取到本地作业目录的 results/ 下
run_lammps	仅用于短时测试的同步运行
buy_credits	打开充值页面，为托管 GPU 密钥充值

通过 MCP 使用托管 GPU 层级（无需安装）

通过托管端点的 Streamable HTTP 服务，任何使用 HTTP 的 MCP 客户端都可以访问相同的作业——Claude Code、Claude.ai 自定义连接器、Cursor、Goose：

claude mcp add --transport http mdengine-cloud https://api.forcefieldsilicon.com/mcp

客户端提示时请登录（OAuth 2.1：打开同意页面并粘贴一次 API 密钥；客户端会保留令牌，密钥仍由你保管）。脚本客户端也可以直接通过 --header "Authorization: Bearer mde_YOUR_KEY" 发送密钥。该密钥附带预付额度包 (forcefieldsilicon.com/mdengine)。initialize 和 tools/list 无需登录即可使用；未提供凭证的工具调用会返回 401，并附带 OAuth Windows 和 Linux。 两个平台都支持使用托管层级，这是受支持的使用方式，也是完整的付费产品：以下所有工具都能在 Windows 上通过 Claude Code 使用，效果与 Mac 上完全相同。在 PowerShell 中，以用户范围注册服务，这样无论你位于哪个文件夹，都能使用该服务；然后登录一次：

claude mcp add --scope user --transport http mdengine-cloud https://api.forcefieldsilicon.com/mcp

启动 claude，输入 /mcp，选择 mdengine-cloud，选择 Authenticate，然后在浏览器同意页面中粘贴密钥（切勿粘贴到聊天中）。在 Windows 上编写的 Deck（使用 CRLF 换行符）可直接使用。目前本地查看器、渲染器和 CPU 作业运行器仅支持 macOS；计划推出 Windows/Linux 本地版本，开发顺序将由需求决定，如有需要请告知。 发现指针，这正是客户端提供登录功能的原因。工具：account、capabilities、preflight_deck、submit_job（牌组内联，≤ 8 MB）、 create_job + start_job（大型牌组通过预签名 PUT 上传）、job_status、job_log、 job_results、list_jobs、delete_results、cancel_job（共 12 个工具）。发现卡片： https://api.forcefieldsilicon.com/.well-known/mcp/server-card.json。托管服务（端点、计费、GPU 启动器）由 ForceField Silicon 运营，其 源代码不属于本仓库；其客户端部分（HostedClient、CLI run --gpu、 MCP host=cloud）位于此处，采用与其他所有内容相同的许可证。

费用产生前进行预检（GJOB-118）。 GET /v1/capabilities 会公布托管镜像的 LAMMPS 版本、软件包以及所有带有 gpu 标志的样式：true = 由 KOKKOS 加速；false = 该样式 存在，但会以 GPU 费率在 pod 的 CPU 核心上运行。每个客户端都会先据此检查牌组 — mdengine capabilities deck.in、应用中的 Run Accelerated、submit_lammps host=cloud、托管服务的 submit_job — 若牌组使用了镜像不支持的样式（LAMMPS 会在启动时退出），就会拒绝运行；若 pair 样式没有 /kk 变体（运行时不会使用 GPU），则会发出警告。--force / force=true 可覆盖此行为；服务器仅提供建议（在启动响应中返回 preflight），不会阻止运行。

托管连接器故障排除：

症状	原因 / 解决方法
客户端提示需要身份验证 / 401	使用客户端登录（OAuth），并在授权页面粘贴你的 mde_… 密钥，或添加标头 Authorization: Bearer mde_…。密钥会在购买时发放，并且只显示一次。
授权页面提示无法识别密钥	密钥格式为 mde_ + 32 个十六进制字符；已撤销的密钥将无法继续使用。mdengine account 会显示已保存密钥的余额。
“insufficient balance”	前往 forcefieldsilicon.com/mdengine 充值；提交任务时的余额必须足以支付至少 15 分钟的 GPU 费率。
“gpu_runners_open_soon”（503）	运行器暂时关闭；余额不会受影响。
HTTP 429	来自同一 IP 的无密钥请求过多；请添加密钥或降低请求频率。
job_results 提示结果不可用	文件已被 delete_results 删除、运行未产生结果，或已执行 30 天清理。
任务以 runner_error / lammps_error 状态 failed	牌组本身运行失败；job_results（若有）或 job_log 中包含 LAMMPS 错误文本。
任务以 pod_lost / no_capacity / launch_timeout / gpu_unavailable 状态 failed	基础设施问题（pod 崩溃、GPU 库存不足、pod 未能启动，或主机未向 pod 提供 CUDA 设备）；不会收费，并会自动重新启动一次。如果仍然失败，请重新提交。

任务会在牌组自己的目录中运行（相对 read_data 路径可正常使用）， 并使用 -sf omp -pk omp N 启动，以确保 OPENMP 软件包确实启用； 若未设置 $LAMMPS_POTENTIALS，则会根据 LAMMPS 安装位置推导其值。

远程主机（在你自己的 Linux / GPU 设备上运行）

作业运行器可以在另一台机器上执行，并遵循相同的工具契约： 在 ~/.mdengine/hosts.json 中声明主机，并将 host 传给 submit_lammps （或设置 default）。牌组目录会通过 rsync 同步到远程主机（不包括轨迹、 检查点和日志）；LAMMPS 会在 nohup 下启动，并在远程记录退出代码； job_status / job_log / job_files / cancel_job 均可照常使用；fetch_job 会将结果取回，供 trajectory_info、 z_profile 和渲染器使用。

{
  "default": "gpu1",
  "hosts": {
    "gpu1": {
      "ssh": "[email protected]",
      "workdir": "~/mdengine-jobs",
      "lmp": "/usr/local/bin/lmp",
      "threads": 8,
      "launch": "{lmp} -in {input} -k on g 1 -sf kk -pk kokkos newton on neigh half -log {log}"
    }
  }
}

ssh 可以是 ssh 接受的任何形式（基于密钥、非交互式）；lmp 必须是 绝对路径（通过 ssh 无法获取登录 PATH）；launch 是可选的 — 默认使用 OpenMP 形式；只要模板中包含 KOKKOS 标志，该 GPU 主机就可用。远程牌组必须在其自身 目录中包含运行所需的全部文件。远程机器上的信任模型与本地运行相同。

平台与限制

macOS 14+（Apple Silicon 或 Intel）。轨迹会整体加载到内存中 — 对超过 2 GB 的文件会拒绝加载，并提示先抽样降采样或拆分文件。

安全说明

运行 LAMMPS 输入文件会执行其中的所有指令。 LAMMPS 输入文件是程序，而非数据——它们可以调用任意 shell 命令（LAMMPS 有一个字面命令 shell）。对待他人提供的输入文件，应与对待 shell 脚本完全一样：运行前先阅读。

这对 MCP 服务尤其重要：连接到 mdengine-mcp 的 AI Agent 可以提交输入文件，而提交的输入文件会在这台机器上以你的用户权限完整运行。 这与任何本地开发工具的信任模型相同（能运行 make 的 Agent 就能运行任何程序），但请谨慎决定将哪些输入文件以及哪些 Agent 交给作业运行器。沙盒执行（容器、禁用网络、限制资源）是未来托管服务层保障运行不可信输入文件安全的方式；本地服务不提供沙盒。

隐私

本地工具不会收集任何信息；请参阅 PRIVACY.md，其中也介绍了托管 GPU 服务层。

许可证

Business Source License 1.1（BUSL-1.1），© 2026 Gitinama Inc.（ForceField Silicon）。请参阅 LICENSE。

简而言之：你可以阅读、复制、修改和再分发 MDEngine，也可以在自己的机器或租用的机器上，将其用于自己的研究、工程或商业工作。许可证唯一禁止的是将 MDEngine 本身，或主要价值来自 MDEngine 的服务，作为托管、管理或嵌入式服务提供给第三方。每个版本都会在首次公开发布四年后转换为 Mozilla Public License 2.0。0.7.0 及更早版本以 MIT 许可证发布，并继续采用 MIT 许可证。 其他安排：[email protected]。