raspa-mcp
by lichman0405
README.md
# raspa-mcp
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](tests/)
[](https://github.com/astral-sh/ruff)
[](https://numpy.org/)
[](https://matplotlib.org/)
[](LICENSE)
[](https://github.com/iRASPA/RASPA2)
> **Turn any AI agent into a molecular simulation expert — overnight.**
`raspa-mcp` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that wraps [RASPA2](https://github.com/iRASPA/RASPA2) — the gold-standard molecular simulation engine for porous materials — into a clean, agent-friendly tool layer. Feed it a CIF file and a molecule name; let your agent handle the rest.
---
## Why raspa-mcp?
Running RASPA2 correctly requires deep expertise: choosing the right ensemble, setting unit cell replications, picking force fields, validating Ewald summation parameters, and parsing Fortran-style output files. Historically this knowledge lived in the heads of computational chemists and nowhere else.
`raspa-mcp` encodes that expertise as **20 structured MCP tools** — covering every major simulation type RASPA2 supports — so that an LLM agent like [featherflow](https://github.com/lichman0405/featherflow) can autonomously design, validate, execute, and interpret molecular simulations without human intervention.
---
## Features at a Glance
### Simulation Templates (12 types)
| Template | Purpose |
|----------|---------|
| `GCMC` | Grand Canonical Monte Carlo — adsorption isotherms |
| `Widom` | Widom test-particle insertion — Henry coefficient at infinite dilution |
| `VoidFraction` | Helium void fraction (prerequisite for GCMC) |
| `NVT-MC` | Fixed-N Monte Carlo — configurational sampling, RDF |
| `NPT-MC` | Variable-volume MC — equilibrium density, flexible cell |
| `MD` | NVT Molecular Dynamics — diffusion, transport |
| `NPT-MD` | Constant-pressure MD — thermal expansion |
| `NVE-MD` | Microcanonical MD — energy conservation benchmarking |
| `GCMCMixture` | Binary mixture GCMC — co-adsorption, selectivity |
| `CBMC` | Configurational-Bias MC — chain/flexible molecules (C4+) |
| `TI` | Thermodynamic Integration — free energy ΔA |
| `FlexibleMD` | Flexible-framework MD — breathing, gate opening |
### Output Parsing (7 parsers)
- **Adsorption loading** — mol/kg, mg/g, cm³(STP)/g, molecules/uc, ±errors
- **Isosteric heat Qst** — from energy fluctuations [kJ/mol]
- **Henry coefficient & μ_ex** — from Widom insertion, −RT ln(W)
- **Helium void fraction** — direct extraction
- **Radial distribution function g(r)** — peak detection, full r/g(r) arrays
- **MSD → Diffusion coefficients** — self D_s and collective D_c via Einstein relation (NumPy linear fit, latter 50% of trajectory)
- **3D density grid** — 2D slice extraction from `.grid` files
- **Thermodynamic Integration** — trapezoidal ∫⟨∂U/∂λ⟩dλ → ΔA [kJ/mol]
- **Multi-component mixture** — per-component loading with backward compatibility
### Analysis Tools
- **Selectivity S_AB** — `(x_A/x_B) / (y_A/y_B)` from mixture loadings
- **Isotherm plotting** — single and multi-MOF comparison PNGs (matplotlib)
- **Density slice plotting** — heatmap PNG from 3D grid data
### Built-in Knowledge Base
- **6 molecules**: CO2, N2, CH4, H2O, helium, n-butane (TraPPE / SPC-E)
- **5 force fields**: TraPPE-CO2/N2/CH4/H2O, UFF — with mixing rules, pseudo-atom definitions
- **Input validator** — catches 20+ common mistakes before RASPA2 ever runs
- **Environment checker** — reports RASPA2 readiness on server startup
---
## Installation
### 0. Install uv (if not already present)
```bash
# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
> [uv](https://github.com/astral-sh/uv) is a fast Python package manager. It replaces `pip` + `venv` with a single tool and handles the Python version automatically.
### 1. Clone and install the Python package
```bash
git clone https://github.com/lichman0405/raspa-mcp
cd raspa-mcp
uv sync
```
`uv sync` creates a virtual environment under `.venv/`, pins the Python version (3.11+), and installs all dependencies — no manual `venv` or `pip` needed.
### 2. Compile and configure RASPA2 (one-time setup)
```bash
uv run python -m raspa_mcp.installer
```
This single command:
- Checks for build tools (`git`, `gcc`, `make`, `autoconf`, `automake`, `libtool`) and **installs any that are missing automatically** via `apt-get` / `dnf` / `yum` / `brew` etc.
- Clones [RASPA2 from GitHub](https://github.com/iRASPA/RASPA2) and compiles from source
- Installs to `~/.local/raspa2` by default (override with `--prefix`)
- Writes `RASPA_DIR` and `PATH` exports to your shell RC file automatically
```bash
# custom install prefix:
uv run python -m raspa_mcp.installer --prefix /opt/raspa2
# force reinstall even if already present:
uv run python -m raspa_mcp.installer --force
```
After the command finishes, reload your shell:
```bash
source ~/.bashrc # or ~/.zshrc, ~/.profile, etc.
```
> **Compatibility**: Tested on Ubuntu 24.04 (GCC 14). The installer automatically applies `-std=gnu11` and other compiler flags to work around known issues in the RASPA2 source tree on modern GCC versions.
> RASPA2 source: [https://github.com/iRASPA/RASPA2](https://github.com/iRASPA/RASPA2)
> Reference: D. Dubbeldam, S. Calero, D.E. Ellis, R.Q. Snurr, *Mol. Simul.* **42**, 81–101 (2016)
---
## Quickstart — featherflow
Register raspa-mcp with one command (run in the featherflow project directory):
```bash
featherflow config mcp add raspa2 \
--command uv \
--arg run \
--arg --directory \
--arg /path/to/raspa-mcp \
--arg raspa-mcp \
--lazy \
--description "RASPA2 molecular simulation: GCMC, MD, adsorption isotherms, force fields, output parsing" \
--timeout 600
```
> `--lazy`: raspa-mcp exposes 20 tools — lazy mode registers a single gateway entry-point instead of all tools upfront, keeping per-call LLM token cost low.
> `--timeout 600`: RASPA2 simulations can take minutes; featherflow recommends 300–600 s for scientific computing MCP servers.
Verify:
```bash
featherflow config mcp list
```
Your agent can now autonomously:
```
User: Study CO2 adsorption in ZIF-8 at 298 K from 0.1 to 50 bar.
Agent:
1. raspa-mcp.get_simulation_template("VoidFraction") → run RASPA2
2. raspa-mcp.parse_raspa_output(...) → void fraction = 0.47
3. raspa-mcp.get_simulation_template("GCMC") → fill placeholders × 7 pressures
4. raspa-mcp.validate_simulation_input(...) → clean
5. shell_exec → RASPA2 × 7
6. raspa-mcp.parse_raspa_output(...) → isotherm data
7. raspa-mcp.plot_isotherm(...) → ZIF-8_CO2.png
8. feishu-mcp.upload_file_and_share(...) → report delivered
```
No human intervention required.
---
## MCP Tools Reference
| Tool | Category |
|------|----------|
| `list_simulation_types` | Discovery |
| `get_simulation_template` | Input generation |
| `get_parameter_docs` | Input generation |
| `list_available_forcefields` | Force field |
| `get_forcefield_files` | Force field |
| `recommend_forcefield` | Force field |
| `list_available_molecules` | Molecule |
| `get_molecule_definition` | Molecule |
| `create_workspace` | Workspace |
| `validate_simulation_input` | Validation |
| `parse_raspa_output` | Output parsing |
| `parse_rdf_output` | Output parsing |
| `parse_msd_output` | Output parsing |
| `parse_ti_output` | Output parsing |
| `parse_density_grid` | Output parsing |
| `calculate_selectivity` | Analysis |
| `plot_isotherm` | Visualization |
| `plot_isotherm_comparison` | Visualization |
| `plot_density_slice` | Visualization |
| `check_raspa2_environment` | Environment |
| `generate_force_field_def` | Custom workflow |
| `generate_force_field_mixing_rules_def` | Custom workflow |
| `generate_pseudo_atoms_def` | Custom workflow |
| `generate_molecule_def` | Custom workflow |
| `inspect_cif` | Custom workflow |
| `recommend_supercell` | Custom workflow |
| `preflight_workspace` | Custom workflow |
| `get_workflow_recipe` | Custom workflow |
---
## Custom-everything workflow
When you bring your own CIF, your own force field, and your own molecule
definitions, the tooling above gives you safe builders for every file RASPA2
expects:
```text
inspect_cif(cif) → formula, cell, charges, overlap warnings
recommend_supercell(cif, 12) → UnitCells line + ChargeMethod hint
create_workspace(work, name, cif)
generate_force_field_def(work) # safe "3 zeros" overwrite file
generate_force_field_mixing_rules_def(work, atom_types=[...]) # LJ ε/σ
generate_pseudo_atoms_def(work, atoms=[...]) # atom registry
generate_molecule_def(work, "MyAdsorbate", ...) # per-molecule .def
preflight_workspace(work) # cross-file sanity
```
> **`force_field.def` ≠ `force_field_mixing_rules.def`**.
> The first file is *overwrite rules* (use the "3 zeros" minimum for almost
> every job). The second file is where Lennard-Jones ε/σ live. Mixing them up
> is the single most common cause of cryptic `:#` parse errors from RASPA2.
> The generators emit the correct format for both.
For an end-to-end recipe call `get_workflow_recipe("custom_mof_gcmc")`.
All write operations are sandboxed under `RASPA_MCP_WORKSPACE_BASE`
(default `~/raspa_workspaces`) — paths outside that root are rejected.
---
## Testing
```bash
uv run pytest tests/ -q # 41 tests, ~1.5 s
uv run ruff check raspa_mcp/ tests/
```
---
## Architecture
```
raspa-mcp/
├── raspa_mcp/
│ ├── server.py # 20 MCP tools (FastMCP, stdio transport)
│ ├── parser.py # Output parsers (loading, RDF, MSD, TI, density)
│ ├── validator.py # Input validator (20+ rule checks)
│ ├── installer.py # RASPA2 env detection + source build + raspa-mcp-setup CLI
│ └── data/
│ ├── templates.py # 12 simulation.input templates
│ ├── molecules.py # 6 molecule definitions + metadata
│ └── forcefields.py # 5 force field file sets
├── tests/
│ └── test_server.py # 41 unit tests
└── docs/
└── workflow.md # Full autonomous research workflow walkthrough
```
---
## Full Business Workflow
See [docs/workflow.md](docs/workflow.md) for a complete end-to-end walkthrough of an autonomous MOF screening study using featherflow + raspa-mcp + RASPA2 + feishu-mcp, from a single chat message to a ranked report delivered to Feishu — approximately 120–140 tool calls, zero human steps.
---
## License
MIT
---
## Acknowledgements
Built on top of [RASPA2](https://github.com/iRASPA/RASPA2) by Dubbeldam, Calero, Ellis & Snurr. Force-field parameters from the [TraPPE](http://trappe.oit.umn.edu/) family (Martin, Siepmann et al.) and the [Universal Force Field](https://doi.org/10.1021/ja00051a040) (Rappé et al.).
TDQS
A3.9/5.0
Scored across 28 tools
Disambiguation5/5
Every tool targets a distinct concern: simulation type templates, force field generation, molecule definitions, workspace setup, output parsing, and plotting are clearly separated. Even closely related tools like generate_force_field_def and generate_force_field_mixing_rules_def are explicitly differentiated in their descriptions.
Naming Consistency5/5
All tool names follow a consistent snake_case verb_noun pattern (list_*, get_*, generate_*, parse_*, plot_*, etc.). There are no camelCase or mixed conventions, making the API predictable and easy to navigate.
Tool Count2/5
With 28 tools, the surface is oversized for the domain. While RASPA2 simulations involve many steps, several tools could be consolidated (e.g., plot_isotherm and plot_isotherm_comparison, or the various generate_*_def tools). The count exceeds the 25-tool threshold that indicates a bloated interface.
Completeness2/5
The toolset covers setup, input file generation, validation, and output parsing, but critically lacks any tool to actually execute the RASPA2 simulation. The workflow references running 'simulate' externally, which is a major gap for an MCP server dedicated to RASPA2. Additionally, there are no tools for restarting, monitoring, or canceling simulations.
Maintenance
ActivityInactive
ResponsivenessNo issues