⚗️ 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.

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.

Related MCP server: colabfit-mcp

Architecture

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?

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:

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.

MCP Tools

Quick Start

# 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 — system design and MCP tool surface

• scientific_gates.md — the four-layer verification gate definitions

• definition_of_done.md — phase-by-phase completion criteria and evidence

• 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.