⚛️ MCP Atomic Toolkit

> [!NOTE]
> This project is under active development. Interfaces and behavior may evolve.

A FastMCP server for atomistic modeling workflows powered by ASE, pymatgen, and modern ML interatomic potentials.

It gives MCP clients a practical toolkit for:
- building structures,
- running geometry optimization + molecular dynamics,
- analyzing structures/trajectories,
- and downloading generated artifacts (data + plots).

---

✨ Why this repo

If you need atomistic workflows exposed as MCP tools (instead of hand-wiring scripts), this project gives you:

- ready-to-call MCP tools for common simulation tasks,
- file-first outputs that are easy to inspect/reuse,
- artifact download URLs so clients don’t need binary blobs in chat context,
- deployment-ready HTTP app with health and server-card endpoints.

---

🚀 Features

- MCP-native workflows via FastMCP tools
- Structure generation: bulk, surface, molecule, supercell, amorphous, liquid, bicrystal, polycrystal
- Optimization workflows with MLIPs (kim default, nequix/orb supported)
- Molecular dynamics workflows (Velocity Verlet, Langevin, NVT Berendsen)
- Analysis outputs:
- RDF + coordination stats
- MSD + thermodynamic trends
- VACF + diffusion (Green-Kubo)
- Downloadable artifacts (xyz, extxyz, cif, traj, png, svg, csv, dat, ...)
- Registry-friendly endpoints (/healthz, server card, Streamable HTTP root)

---

⚡ Quick Start

1) Requirements

- Python 3.11+

2) Install

pip install -r requirements.txt

3) Run locally

uvicorn mcp_atomictoolkit.http_app:app --host 0.0.0.0 --port 10000

Alternative:

python main.py

STDIO mode (for desktop MCP clients):

python -m mcp_atomictoolkit.mcp_server

> [!IMPORTANT]
> STDIO transports must keep stdout clean for JSON-RPC. Avoid print() or logging to stdout
> when running the server in STDIO mode.

4) Smoke check

curl -s http://localhost:10000/healthz

Expected response:

{"status":"ok"}

---

🧰 Tooling Overview

Main MCP tools exposed by the server:

- build_structure_workflow
- analyze_structure_workflow
- write_structure_workflow
- optimize_structure_workflow
- single_point_workflow
- run_md_workflow
- analyze_trajectory_workflow
- autocorrelation_workflow

Legacy aliases are also included for backward compatibility.

---

🌐 Endpoints

- POST / — primary MCP Streamable HTTP endpoint
- GET /healthz — health check
- GET /docs — lightweight documentation (README)
- GET /.well-known/mcp/server-card.json — MCP server card metadata
- GET /artifacts/{artifact_id}/{filename} — artifact download route
- /sse/ — compatibility alias path mounted to the MCP app

---

📦 Deployment

Render

render.yaml is included and ready to use.

Default start command:

uvicorn mcp_atomictoolkit.http_app:app --host 0.0.0.0 --port $PORT

Docker

docker build -t mcp-atomictoolkit .
docker run --rm -p 7860:7860 mcp-atomictoolkit

---

🗂️ Project Structure

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

---

🧪 Workflow Notes (for MCP clients)

Structure building coverage

build_structure_workflow supports:

- bulk (ASE bulk)
- surface (ASE surface)
- molecule (ASE molecule)
- supercell (multiplication of a base structure)
- amorphous/liquid (random packed structures)
- bicrystal and polycrystal (grain stacking/rotation)

For interfaces, doped structures, adsorbates, or custom slabs, prefer:

1. Generate the structure with ASE/pymatgen (or an external builder), then
2. Use write_structure_workflow to persist the final geometry for downstream steps.

This ensures MCP callers can still handle advanced structures even when a specialized
builder is required.

Builder kwargs cheat sheet

Common builder_kwargs for build_structure_workflow:

- surface: indices, layers, vacuum
- supercell: size, base_structure_type, base_crystal_system, base_lattice_constant, base_kwargs
- amorphous/liquid: num_atoms, box_length, relax, relax_steps, relax_fmax
- bicrystal: grain_size, interface_axis, rotation_angle, rotation_axis, interface_gap
- polycrystal: num_grains, grain_size, rotation_angle

Optimization options

optimize_structure_workflow exposes:

- max_steps, fmax (convergence)
- maxstep, alpha (BFGS step/damping controls)
- constraints (fixed_atoms, fixed_bonds, fixed_cell)

Single-point calculations

single_point_workflow computes energy, forces, and stress (if periodic)
without modifying the structure, making it suitable for quick evaluations.

MD integrators / ensembles

run_md_workflow supports:

- velocityverlet / nve (NVE)
- langevin / nvt-langevin (NVT)
- nvt / nvt-berendsen (NVT)

Tune temperature_K, friction, and taut to control thermostat behavior.

---

📈 GitHub Pulse

> Add your repository path in the URLs below to enable live charts.

Star history

---

🤝 Contributing

- Keep outputs file-based and artifact-friendly.
- When adding tools, usually update both:
- workflows/core.py
- mcp_server.py
- Preserve http_app.py compatibility behavior unless intentionally changing deployment contracts.

---

📄 License

MIT — see LICENSE.