feat: add unified simulation API, CLI, and MCP tools

[tdpham2]

Summary

MatKit's existing engine-specific interfaces do not provide a shared contract for running calculations, inspecting scientific outcomes, or retrieving artifacts through Python, CLI, and agent tools. This PR adds the first experimental unified execution layer: users can prepare a portable calculation bundle, execute it locally or in a separately configured environment, and inspect the same structured result through Python, CLI, or optional MCP tools.

The initial scientific scope is MLIP evaluation and fixed-cell relaxation, Zeo++ pore analysis, and single-component gRASPA CUDA adsorption. MatKit remains usable without an agent, MOFforge, or ChemGraph.

Changes

Simulation setup and parser fixes

• Pass the requested cutoff into unit-cell replication for gRASPA, gRASPA SYCL, pygRASPA, and RASPA2, including the cached cell-size paths used by gRASPA/pygRASPA batch preparation.
• Reject nonpositive, nonfinite, or boolean cutoffs and cells without three finite, independent vectors. Regression cases include skewed cells and multiple cutoffs.
• Set success=True for successfully parsed RASPA2 output and reject nonfinite adsorption values, nonpositive density, and negative reported errors.

Shared API and scientific contracts

• Add matkit.api with versioned Pydantic request, result, batch, structure, artifact, and failure models. Reject unknown fields, invalid numeric values, incompatible adapter settings, and inconsistent result states.
• Separate the scientific method/checkpoint, calculator adapter, and execution configuration. Keep engine-specific parameters explicit instead of forcing every engine into one calculator interface.
• Expose prepare, execute, run, inspect_run, run_batch, and operation-specific evaluation, relaxation, pore-analysis, and adsorption functions.
• Separate execution state, numerical validity, required scientific checks, and accepted. An unconverged relaxation retains its numerical payload but is not accepted; adsorption uncertainty is distinct from execution failure, and sampling quality remains unknown.
• Record energy/force/stress units and conventions, model-specific energy references, adsorption component/loading basis, requested settings, resolved settings, timing, and available environment/model identity evidence.
• Add capability discovery that reports caller-side availability, restrictions, and evidence without loading optional calculators, models, or CUDA.

Portable bundles, structure handoff, and execution

• Stage original structures, metadata sidecars, local model files, radii, templates, and force-field inputs. Hash prepared inputs, verify them before execution, and keep artifact references relative to the bundle so it can be relocated.
• Preserve atom identities, species, geometry, periodicity, supported arrays, labels, bonds, constraints, and lineage. Reject partial occupancies or CIF symmetry expansions without a provable atom mapping. Invalidate inherited geometry-dependent charges and properties after structural changes.
• Add atomic result/manifest writes and run ownership locks. Commit numerical results before updating manifests; retain completed results through later orchestration failures and recover a valid committed result when its manifest is unreadable.
• Support direct execution and supervised workers with an explicit interpreter, device, environment overrides, executable argument lists, logs, exit records, and timeouts. Worker configuration artifacts omit environment override values; selected numerical runtime settings remain in provenance.
• Add homogeneous batches with calculator reuse, native ALCHEMI chunking, stable item ordering, per-item outcomes, and incremental manifests. Preserve completed items on interruption and reject changed supporting inputs before calculator reuse.

Scientific adapters

• Reuse the existing direct ASE/MACE, Rootstock, and native ALCHEMI MACE implementations for evaluation and fixed-cell relaxation. Evaluation defaults to potential energy; forces and stress are explicit requests and fail if unavailable. Relaxation checks force convergence; native ALCHEMI retains its FIRE-only restriction.
• Extend the internal legacy MLIP runner to honor explicitly requested properties while preserving the existing callers' default energy/force behavior and legacy result layout.
• Add Zeo++ execution and parsing for diameter, surface area, volume, pore-size distribution, and channels. Require complete, finite requested output and a successful engine exit.
• Add pure-component gRASPA preparation, execution, and collection. Preserve the charged CIF bytes, validate atom-mapped charges and net charge, stage complete templates/definitions, and expose temperature, pressure, cutoff, cycle/block counts, fugacity, and uptake units. Parse uptake, heat of adsorption, and their reported uncertainties. Manual collection requires an actual recorded engine exit code and log.

CLI and optional MCP

• Add evaluate, relax, pores, adsorption prepare/run/analyze, prepare, execute, inspect, batch, and capabilities commands. Resolve input paths relative to specification files and support execution-profile JSON.
• Run CLI calculations in workers so scientific JSON stays on stdout and engine output goes to logs. Exit codes distinguish invalid arguments, unsuccessful/unaccepted calculations, and accepted results; inspection succeeds independently of the recorded calculation outcome.
• Add the optional matkit-mcp stdio server and seven tools: capabilities, evaluation, relaxation, pore analysis, general preparation, adsorption preparation, and inspection.
• Configure server-side execution profiles, input/run roots, a selectable tool catalog, and bounded synchronous execution. Timeouts and cancellation stop workers and preserve interrupted records.
• Return compact summaries and artifact links; serve hash-verified structures, arrays, and full result JSON through matkit://runs/{run_id}/artifacts/{digest} resources.

Packaging, documentation, examples, and CI

• Add core pydantic>=2,<3, optional mcp>=2,<3, and the matkit-mcp entry point. Include nested simulation templates and definitions in wheels.
• Add docs/unified-api.md covering installation, specifications, execution profiles, scientific outcomes, artifact/structure contracts, CLI, and MCP; add docs/capabilities.md distinguishing unified and legacy capabilities from scientific validation. Update README and changelog links/notes.
• Add a Polaris PBS example for executing a prepared bundle inside an existing allocation and an opt-in execution recorder that retains per-case evidence and continues after failures.
• Add contract, scientific-adapter, recovery, CLI, real local MCP stdio, packaging, and recorder tests, with a synthetic external-engine fixture.
• Change the Python 3.10–3.12 CI test matrix to install a wheel and run copied tests outside the source checkout. Add a separate optional MCP job and lint/format checks for the new tests and example.

Compatibility and scope

Existing engine APIs, CLI commands, and legacy MLIP result formats remain available. The unified schemas use their own names and version 1. This PR also intentionally corrects the cutoff and RASPA2 behaviors described above.

All new scientific adapters remain experimental. CPU fixtures and mocked/synthetic engine outputs validate interface behavior, not scientific accuracy or GPU compatibility. Real MACE/Rootstock/ALCHEMI, Zeo++, gRASPA, and Polaris execution evidence is still required before promotion; unresolved model identities, seeds, and sampling quality are not presented as verified.

Deferred work includes unified DFT/MD/cell optimization, normalized mixture adsorption results, MOFforge/charge workflows, scientific reference/parity benchmarks, automatic resume/result reuse, scheduler submission, persistent background jobs, HTTP MCP transport, and agent evaluations. Long calculations use prepared bundles and CLI/job-script execution.

Validation

• Python 3.12 source checkout: 336 passed, 1 skipped (pytest tests/ -q).
• Installed wheel in a separate environment, with tests copied outside the checkout and MATKIT_WHEEL_TEST=1: 336 passed, 1 skipped, including real local MCP stdio discovery, execution, resource retrieval, timeout, and cancellation tests.
• After the final capability-description clarification, installed-wheel contract, package-resource, and operation-CLI checks: 30 passed.
• Ruff lint and formatting checks passed for source, new tests/fixtures, and the execution-recorder example.
• Wheel and sdist builds passed; packaged CLI/MCP help and capability discovery were checked.
• git diff --check origin/main...HEAD passed.
• Local tests report upstream ASE/NumPy deprecation warnings. The GitHub Actions Python matrix and real external-engine/GPU validation are not claimed as locally completed.

The implementation is split into aa8d5c8 (setup/parser fixes) and e84b29e (unified API, interfaces, documentation, and tests).