# ⚗️ Alchemist-MCP

A fail-closed MCP verification layer that gates DFT-to-MLIP (MACE / RuNNer) migration-barrier workflows behind scientific, software, and numerical checks — so a broken calculation can never present itself as a valid one.

![Python >=3.11](https://img.shields.io/badge/python-%3E%3D3.11-blue)
![MCP 2.x](https://img.shields.io/badge/MCP-2.x-informational)
![227 tests passing](https://img.shields.io/badge/tests-227%20passing-brightgreen)
![engineering-demo-v1](https://img.shields.io/badge/milestone-engineering--demo--v1-orange)

## Why Alchemist-MCP?

- **Fail-closed by construction.** Every tool returns only `PASS | WARN | FAIL | QUARANTINE | NOT_RUN` — there is no code path that upgrades incomplete or unverified evidence into an apparent pass.
- **Verification before training.** MACE and RuNNer adapters can only ever build a dry-run `CommandPlan`; `execute=True` / `dry_run=False` is refused unconditionally at the MCP boundary.
- **Provenance-first data intake.** Quantum ESPRESSO parsing preserves atom order, canonical units, pseudopotential hashes, and paired input/output SHA-256 identity, with fail-closed quarantine on anything incomplete or ambiguous.
- **Honest status reporting.** The project distinguishes engineering validation (proven by tests) from real scientific validation (pending real DFT data) everywhere, including in this README.

## Architecture

```mermaid
flowchart TD
    A[Quantum ESPRESSO DFT] --> B[Scientific verification]
    B --> C[Software verification]
    C --> D[Numerical verification]
    D --> E[Frozen dataset]
    E --> F[MACE]
    E --> G[RuNNer 2G]
    F --> H[Common evaluation]
    G --> H
    H --> I[Reference / literature validation]
```

## What is validated today?

| Area | Status | Evidence |
|---|---|---|
| QE parsing, units, provenance, freeze/split | **Engineering — validated** | 227 automated tests |
| MACE / RuNNer adapters (dry-run only) | **Engineering — validated** | 227 automated tests |
| Common evaluator + reference-comparison contract | **Engineering — validated** | 227 automated tests |
| MCP server (8 tools, official SDK client) | **Engineering — validated** | Live stdio client run |
| rMD17 engineering trial (real, non-DFT dataset) | **Engineering — validated** | `reports/engineering_demo_validation.md` |
| Gate 1 — Scientific Correctness (real DFT data) | **NOT_RUN** | No production migration-barrier DFT dataset yet |
| Gate 2 — Software Correctness | **PASS** | 227 tests, `ruff`, `mypy` clean |
| Gate 3 — Numerical Correctness (real data) | **NOT_RUN** | No production HPC data yet |
| Gate 4 — Reference / Literature Validation | **NOT_RUN** | Blocked on Gates 1 and 3 |

Engineering validation proves the software does what it claims on real and synthetic inputs. It is not, and must not be read as, scientific validation of any migration-barrier result.

## Validated Engineering Demo

A real, non-synthetic 175 MB rMD17 azobenzene dataset is exercised end to end, purely as a software/engineering trial:

```text
SHA-256 verification
   -> NPZ schema/finiteness validation
   -> deterministic seeded selection (<= 1000 samples)
   -> kcal/mol -> eV unit conversion
   -> non-periodic extended-XYZ export
   -> ASE read-back
   -> dry-run MACE CommandPlan (never executed)
```

Every output is hard-labeled `trial_label = "ENGINEERING_TRIAL_ONLY"` and **`scientific_gate_eligible = false`**: azobenzene has no defect, no migration path, and no QE provenance, so this trial can never satisfy Gate 1, Gate 3, Gate 4, or `training_eligibility`. Full commands and live run output: [`reports/engineering_demo_validation.md`](reports/engineering_demo_validation.md).

## MCP Tools

| Tool | Purpose | Fail-closed behavior |
|---|---|---|
| `get_pipeline_status` | Lifecycle/gate snapshot | Never executes work |
| `inspect_dft_dataset` | Read-only QE dataset inspection | Structured quarantine errors per file |
| `verify_dft_dataset` | Run Scientific + Software + Numerical checks | Missing evidence -> `NOT_RUN`/`FAIL` |
| `freeze_verified_dataset` | Immutable, versioned manifest | Missing evidence/duplicates -> `FAIL`, no file written |
| `run_mace_pipeline` | MACE dry-run command plan | `execute=True` always refused |
| `run_runner2_pipeline` | Al-only RuNNer dry-run command plan | Non-Al data or execution request -> `FAIL` |
| `compare_models` | Energy/force/migration-profile comparison | Incomplete evidence -> `NOT_RUN`, never partial `PASS` |
| `validate_reference` | Compare against DFT CI-NEB + literature | Unverified evidence -> `NOT_RUN`; mismatch -> `FAIL` |

## Quick Start

```bash
# clone and enter the repo
git clone <repo-url> alchemist-mcp && cd alchemist-mcp

# install the locked environment (Python >=3.11)
uv sync --extra dev --locked

# run the test suite
uv run pytest -q

# lint and type-check
uv run ruff check .
uv run mypy src

# start the MCP server over stdio
uv run python -m alchemist_mcp.server
```

## Verification philosophy

Every gate resolves to exactly one of `PASS | WARN | FAIL | QUARANTINE | NOT_RUN`. There is no implicit success: missing, incomplete, or unverifiable evidence always resolves to `NOT_RUN` or `QUARANTINE`, never `PASS`. A critical `FAIL` blocks the next scientific action outright. Training (MACE/RuNNer) is gated behind Scientific, Software, and Numerical verification of the input data, and final scientific claims additionally require independent reference/literature validation and human review. Fixture and trial-dataset successes verify software contracts only — they never substitute for real scientific, numerical, or literature validation.

## Project status

Current milestone: **engineering-demo-v1** — the software pipeline, MCP surface, and a real (non-DFT) end-to-end engineering trial are implemented and fully tested. Real scientific Gates 1, 3, and 4 remain pending genuine production DFT evidence; no MACE or RuNNer training has been executed.

## Documentation

- [`architecture.md`](architecture.md) — system design and MCP tool surface
- [`scientific_gates.md`](scientific_gates.md) — the four-layer verification gate definitions
- [`definition_of_done.md`](definition_of_done.md) — phase-by-phase completion criteria and evidence
- [`reports/engineering_demo_validation.md`](reports/engineering_demo_validation.md) — full engineering demo evidence and live run output

## Current limitations

- No production migration-barrier DFT dataset exists in this repository; Gates 1, 3, and 4 are `NOT_RUN` for real data.
- The rMD17 trial is engineering-only and cannot satisfy any scientific gate.
- No MACE or RuNNer training has ever been executed, real or trial — only dry-run command construction.
- The known legacy Al 2x2x2-vs-3x3x3 finite-size delta (`0.1105 eV`) exceeds the versioned `<= 0.03 eV` Gate 3 threshold: a documented Gate 3 FAIL, not a passing result.
- MCP Inspector (interactive dev tool) is unverified non-interactively; the official MCP Python SDK stdio client covers startup, discovery, schema, and invocation instead.

## License

No license file is currently included in this repository. All rights reserved by the author unless a license is added.