crystal-energy-mcp
# Crystal Energy
Deterministic lattice energies, relaxed-structure validation and pair energy decompositions of molecular crystals (including hydrates and salts) from CIF files, using machine-learned interatomic potentials (UMA, MACE) through one Python API and one MCP server for agent hosts. Numbers come only from deterministic kernels; the agent orchestrates.
**Status: M1 — structure layer.** This preview publishes the contracts in [spec/](spec/) and implements:
- `crystal_energy.api.load_cif`, `build_crystal` and `enumerate_pairs`: CIF reading, symmetry expansion into whole molecules, components with formal charges, Z and Z', and symmetry-unique molecule pairs within a nearest-atom cutoff;
- `list_model_cards`, `get_backend` and `single_point` with the analytic `toy` backend ([spec/toy_backend.md](spec/toy_backend.md)) on the CPU;
- the MCP tools `crystal_status` and `crystal_help` (`crystal_inspect`, `crystal_plan`, `crystal_run` and `crystal_job` return `NOT_IMPLEMENTED`);
- the CLI commands `crystal-energy status` and `crystal-energy help`.
The only energy backend is `toy`; the UMA and MACE backends are placeholders, and real models and GPU execution follow in M2. No GPU, model-weight, host or delivery acceptance exists yet. Do not use this release for scientific results.
## Development setup
Requires [uv](https://docs.astral.sh/uv/) and Python 3.12 or later.
```
uv sync --locked
uv run crystal-energy status
uv run crystal-energy-mcp # MCP server on stdio
```
The structure layer (gemmi, networkx) is part of the required dependencies. Optional extras: `gpu`, `uma`, `mace` (`uma` and `mace` cannot be installed in the same environment because of conflicting e3nn pins).
## Checks
```
uv run ruff check .
uv run ruff format --check .
uv run pytest -q
uv run python scripts/check_contracts.py
uv run python scripts/smoke_mcp.py
uv run python scripts/check_release.py
uv run python scripts/path_guard.py main..HEAD
```
## Layout
| Path | Contents | Owner |
| --- | --- | --- |
| `spec/` | Public API stub, error codes, units, toy backend, JSON Schemas | Maintainer (signed commits) |
| `benchmarks/` | Benchmark data, tolerances and `MANIFEST.sha256` | Maintainer (signed commits) |
| `tests/` | Contract, invariance, physics and agent tests | Tester role |
| `src/crystal_energy/` | Layered implementation; `api.py` is the only public surface | Implementer role |
| `adapters/` | Codex and Claude plugin manifests and the workflow skill | Implementer role |
| `scripts/` | Contract, smoke, release and path-guard checks | Implementer role |
See [AGENTS.md](AGENTS.md) for the layering and role rules and [RUNTIME_LIFECYCLE.md](RUNTIME_LIFECYCLE.md) for process lifecycles.
## Licence
MIT, see [LICENSE](LICENSE). Third-party packages and model weights keep their own terms; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
TDQS
Scored across 6 tools
Each tool has a distinct role: status for environment, help for guidance, inspect for CIF parsing, plan for workflow construction, run for job submission, and job for monitoring. The read-only annotations and task-specific verbs make misselection unlikely.
All tools use the same `crystal_` prefix and lower snake_case suffix, with no casing or delimiter inconsistencies. Although suffixes mix nouns and verbs, the convention is uniform and predictable.
Six tools is well-scoped for a workflow-oriented MCP server. Each tool covers a necessary stage without redundancy or bloat.
The surface covers the core lifecycle: environment check, help, CIF inspection, workflow planning, job submission, and job monitoring/results. It lacks explicit job cancellation/listing and a standalone validation tool, but these are minor gaps for the main workflow.