{
  "markdown": "# MDEngine\n\n*by ForceField Silicon*\n\nA native macOS molecular-dynamics workbench: a Metal trajectory viewer, a\ncommand-line tool, and an MCP server that lets AI agents inspect trajectories\nand run LAMMPS simulations as detached background jobs.\n\n> **Status: pre-release.** Not yet distributed; the app is ad-hoc signed\n> (builds run on the building machine only until notarization lands).\n\n## Parts\n\n| Product | What it is |\n|---|---|\n| **MDEngine.app** | Metal viewer — orbit / pan / zoom camera, trajectory timeline with 20%/5% tick marks, CPK element colours, XYZ / extended-XYZ, live settings |\n| **mdengine-cli** | `info` / `export` / `decimate` / `run` on trajectories and decks |\n| **mdengine-mcp** | MCP stdio server — trajectory tools plus a detached LAMMPS job runner (`submit_lammps` / `job_status` / `job_log` / `list_jobs` / `cancel_job`) |\n\n## Build\n\nRequires macOS 14+ and Xcode command-line tools. LAMMPS (`brew install lammps`)\nis needed only for `run` / `submit_lammps`.\n\n```sh\nswift build -c release            # all three products\n./scripts/make_app.sh             # assemble + install /Applications/MDEngine.app\n```\n\n## Bundled examples\n\n| Example | What it shows |\n|---|---|\n| `lj_melt.xyz` / `lj_melt.in` | Lennard-Jones argon melt — the minimal smoke test |\n| `fe_oxidation.xyz` / `fe_oxidation.in` | ReaxFF iron oxidation: a bcc Fe slab meeting O₂ gas, using `ffield.reax.Fe_O_C_H` from the LAMMPS distribution |\n\nTrajectory readers are safe on **in-flight dumps** — a file a running\nsimulation is still writing parses to its complete frames, so you can inspect\na run mid-flight. Rows with non-finite (NaN/inf) coordinates are dropped.\n\nBoth decks are ready inputs for `mdengine run` and `submit_lammps`. Bare\nforce-field names resolve automatically: if `$LAMMPS_POTENTIALS` is unset,\nMDEngine derives it from the LAMMPS install.\n\n## MCP server\n\n`mdengine-mcp` is a dependency-free MCP stdio server, listed in the\n[MCP Registry](https://registry.modelcontextprotocol.io) as\n`com.forcefieldsilicon/mdengine` (`server.json` in this repo). Each release ships a\nsigned macOS [MCP Bundle](https://github.com/modelcontextprotocol/mcpb)\n(`mdengine-mcp-<version>-macos-arm64.mcpb`): double-click it to install in Claude\nDesktop, or unpack it (`mcpb unpack`) for any other client. Built from source, register\nwith Claude Code:\n\n```sh\nclaude mcp add mdengine /path/to/.build/release/mdengine-mcp\n```\n\nor in Claude Desktop's `claude_desktop_config.json`:\n\n```json\n{ \"mcpServers\": { \"mdengine\": { \"command\": \"/path/to/.build/release/mdengine-mcp\" } } }\n```\n\n| Tool | Does |\n|---|---|\n| `trajectory_info` | Frames, atom counts, per-atom fields, elements, bbox, charge range |\n| `z_profile` | Deposition/oxidation depth analysis: substrate surface plane, probe penetration depths (min/mean/max), at-surface & in-flight counts, bound-probe charge, z histogram |\n| `render_video` | Trajectory → MP4 (H.264) or animated GIF via the Metal renderer: camera angles, stride, cinematic orbit, baked scale-bar/frame annotations, per-element `colors`/`sizes`, `style: \"contrast\"` auto-visibility |\n| `render_image` | One frame → PNG with the same camera/style options — lets an agent *see* a simulation state |\n| `export_frame` | One frame → XYZ; `charges: true` → extended-XYZ with the q column |\n| `decimate` | Keep every Nth frame (final frame always kept) |\n| `submit_lammps` | Detached LAMMPS job: survives the server exiting and machine display-sleep (`caffeinate`), exit code recorded unattended |\n| `job_status` / `job_log` | State + live thermo tail / raw log tail |\n| `job_files` | Locate a finished job's outputs (run dir + bookkeeping dir) |\n| `list_jobs` / `cancel_job` | Registry under `~/.mdengine/jobs/` / SIGTERM a run (state becomes `cancelled`) |\n| `list_hosts` | Execution hosts from `~/.mdengine/hosts.json` and which is the default |\n| `fetch_job` | Pull a remote job's run directory (dumps, data) + logs into the local job dir under `results/` |\n| `run_lammps` | Synchronous run for short tests only |\n\n### Hosted GPU tier over MCP (no install)\n\nThe same jobs are reachable from **any MCP client that speaks HTTP** — Claude Code, Claude.ai\ncustom connectors, Cursor, Goose — via the hosted endpoint's Streamable HTTP server:\n\n```sh\nclaude mcp add --transport http mdengine-cloud https://api.forcefieldsilicon.com/mcp\n```\n\n**Windows and Linux.** The hosted tier is the supported path on both, and it is the full paid\nproduct: every tool below works from Claude Code on Windows exactly as on a Mac. In PowerShell,\nregister at user scope so the server follows you into every folder, then sign in once:\n\n```powershell\nclaude mcp add --scope user --transport http mdengine-cloud https://api.forcefieldsilicon.com/mcp\n```\n\nStart `claude`, type `/mcp`, pick `mdengine-cloud`, choose Authenticate, and paste the key on the\nbrowser consent page (never into the chat). Decks written on Windows (CRLF line endings) are\naccepted as-is. The local viewer, renderer and CPU job runner are macOS-only today; a Windows/Linux\nlocal build is planned and demand decides its order, so say so if you need it.\n\nSign in when the client asks (OAuth 2.1: a consent page where you paste your API key once; the\nclient keeps a token, the key stays with you). Scripted clients may instead send the key directly\nas `--header \"Authorization: Bearer mde_YOUR_KEY\"`. The key comes with a prepaid credit pack\n([forcefieldsilicon.com/mdengine](https://forcefieldsilicon.com/mdengine)). `initialize` and\n`tools/list` work without signing in; tool calls without a credential return 401 with the OAuth\ndiscovery pointer, which is what makes clients offer the sign-in. Tools: `account`, `submit_job` (deck inline, ≤ 8 MB),\n`create_job` + `start_job` (big decks via presigned PUT), `job_status`, `job_log`,\n`job_results`, `list_jobs`, `delete_results`, `cancel_job`. Discovery card:\n`https://api.forcefieldsilicon.com/.well-known/mcp/server-card.json`. Server code:\n`hosted/endpoint/mde_mcp.py`.\n\nTroubleshooting the hosted connector:\n\n| Symptom | Cause / fix |\n|---|---|\n| Client says authentication required / 401 | Use the client's sign-in (OAuth) and paste your `mde_…` key on the consent page, or add the header `Authorization: Bearer mde_…`. Keys are issued at purchase and shown once. |\n| Consent page says the key was not recognised | Keys are `mde_` + 32 hex characters; a revoked key no longer works. `mdengine account` prints the balance for a saved key. |\n| \"insufficient balance\" | Top up at forcefieldsilicon.com/mdengine; submissions need credit for at least 15 min at the GPU rate. |\n| \"gpu_runners_open_soon\" (503) | Runners are temporarily closed; credits are safe. |\n| HTTP 429 | Too many keyless requests from one IP; add the key or slow down. |\n| `job_results` says results unavailable | Files were deleted by `delete_results`, the run produced none, or the 30-day purge ran. |\n| Job `failed` with `runner_error` / `lammps_error` | The deck itself failed; `job_results` (if present) or `job_log` holds the LAMMPS error text. |\n| Job `failed` with `pod_lost` / `no_capacity` | Infrastructure; not billed. Resubmit. |\n\nJobs run in the deck's own directory (relative `read_data` paths work) and\nlaunch with `-sf omp -pk omp N` so the OPENMP package is actually engaged;\n`$LAMMPS_POTENTIALS` is derived from the LAMMPS install when unset.\n\n## Remote hosts (run on your own Linux / GPU box)\n\nThe job runner can execute on another machine with the **same tool contract**:\ndeclare hosts in `~/.mdengine/hosts.json` and pass `host` to `submit_lammps`\n(or set a `default`). The deck's directory is rsynced up (trajectories,\ncheckpoints and logs excluded), LAMMPS starts under `nohup` with its exit code\nrecorded remotely, and `job_status` / `job_log` / `job_files` / `cancel_job`\nwork unchanged; `fetch_job` brings results back for `trajectory_info`,\n`z_profile` and the renderers.\n\n```json\n{\n  \"default\": \"gpu1\",\n  \"hosts\": {\n    \"gpu1\": {\n      \"ssh\": \"me@gpu1.example.net\",\n      \"workdir\": \"~/mdengine-jobs\",\n      \"lmp\": \"/usr/local/bin/lmp\",\n      \"threads\": 8,\n      \"launch\": \"{lmp} -in {input} -k on g 1 -sf kk -pk kokkos newton on neigh half -log {log}\"\n    }\n  }\n}\n```\n\n`ssh` is anything `ssh` accepts (key-based, non-interactive); `lmp` must be an\nabsolute path (login PATH is not available over ssh); `launch` is optional —\nthe default is the OpenMP form, and a GPU host is simply one whose template\ncarries the KOKKOS flags. A remote deck must be self-contained within its own\ndirectory. The same trust model as local runs applies, on the remote machine.\n\n## Platform & limits\n\nmacOS 14+ (Apple Silicon or Intel). Trajectories are loaded whole into memory\n— files over 2 GB are refused with guidance to decimate or split first.\n\n## Security note\n\n**Running a LAMMPS input executes whatever the deck says.** LAMMPS decks are\nprograms, not data — they can invoke arbitrary shell commands (LAMMPS has a\nliteral `shell` command). Treat a deck from someone else exactly like a shell\nscript: read it before running it.\n\nThis applies doubly to the MCP server: **an AI agent connected to\n`mdengine-mcp` can submit decks, and a submitted deck runs with your user's\nfull privileges on this machine.** That is the same trust model as any local\ndev tool (an agent that can run `make` can run anything), but be deliberate\nabout which decks — and which agents — you hand to the job runner. Sandboxed\nexecution (containers, no network, resource caps) is how a future hosted tier\nmakes running untrusted decks safe; the local server does not sandbox.\n\n## Privacy\n\nThe local tools collect nothing; see [PRIVACY.md](PRIVACY.md), which also covers the\nhosted GPU tier.\n\n## License\n\nMIT © Gitinama Inc. (d/b/a ForceField Silicon)\n",
  "bytes": 9719,
  "sha": "a26357a54c196579e2a213703c48cd23feabb01bd5633082b643f4064ae1134a",
  "repo_slug": "forcefieldsilicon/mdengine",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_forcefieldsilicon_mdengine_6963ed96/readme"
}