Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@crystal-energy-mcp show me the crystal-energy service status and available tools"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/ 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) 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.
Requires uv and Python 3.12 or later.
uv sync --locked
uv run crystal-energy status
uv run crystal-energy-mcp # MCP server on stdioThe 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).
Related MCP server: scientific-skills-hub
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..HEADPath | Contents | Owner |
| Public API stub, error codes, units, toy backend, JSON Schemas | Maintainer (signed commits) |
| Benchmark data, tolerances and | Maintainer (signed commits) |
| Contract, invariance, physics and agent tests | Tester role |
| Layered implementation; | Implementer role |
| Codex and Claude plugin manifests and the workflow skill | Implementer role |
| Contract, smoke, release and path-guard checks | Implementer role |
See AGENTS.md for the layering and role rules and RUNTIME_LIFECYCLE.md for process lifecycles.
MIT, see LICENSE. Third-party packages and model weights keep their own terms; see THIRD_PARTY_NOTICES.md.
Short guidance for one topic (overview, validate, lattice_energy, pairs, series, workflow, errors); topic workflow attaches the workflow JSON Schema.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Omitted means overview. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| text | No | |
| error | No | |
| topic | No | |
| schema | No | JSON Schema (draft 2020-12) of the topic's document, when it has one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description doesn't need to cover safety. It does add one behavioral fact—that the workflow topic returns a JSON Schema attachment—which is helpful and not in the schema. Otherwise it provides no additional behavioral context (e.g., output format, whether topics overlap).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the main purpose and then enumerates topics. It is efficient, though the parenthetical list makes it slightly dense. No wasted clauses.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one optional parameter, full schema coverage, annotations covering safety, and an output schema, the description is nearly complete. It tells the agent what topics exist and one special return behavior. It could mention that the output is textual guidance, but the output schema likely handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents the topic enum and the default (omitted means overview). The description lists the same topics and adds the workflow-schema detail, but the schema also covers parameter semantics fully, so the description adds minimal extra meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it returns 'short guidance for one topic' and enumerates the valid topics. However, the verb is passive ('Short guidance') and the description doesn't distinguish this help tool from siblings like crystal_status or crystal_inspect. The purpose is understandable but not sharp.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The enumeration of topics implies when to use each, but there is no explicit statement of when to call this tool versus others (e.g., for troubleshooting vs. planning). The one usage detail—that workflow attaches the JSON Schema—is useful but not a full guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a CIF: components with formal charges, atom count, warnings and per-model applicability. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| cif_path | Yes | Absolute path of the CIF file to inspect. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| error | No | |
| n_atoms | No | Atoms in the unit cell. |
| warnings | No | |
| components | No | |
| applicability_by_model | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so 'Read-only' in the description is redundant rather than additive. The description does disclose what the read surfaces (charges, atom count, warnings, per-model applicability), which is mild added context, but since an output schema exists it does not break new behavioral ground.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence that front-loads the verb and resource before listing outputs. The trailing 'Read-only' is redundant with the annotations and is the only wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With rich annotations, a fully documented single parameter, and an output schema covering return values, the description covers what an agent needs to select and invoke the tool. It is slightly thin on when this is the right choice versus siblings, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter and schema description coverage is 100%, with the schema fully documenting cif_path as an absolute path. The description adds no syntax, format, or constraint detail beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Read') and resource ('a CIF'), and enumerates what the read yields: formal charges, atom count, warnings, per-model applicability. It is clearly distinguishable from status/help/plan/run/job siblings by operation type, though it never names an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites (e.g., that the file must be a valid CIF on disk), and no mention of when another tool such as crystal_run or crystal_status would be preferred. The agent is left to infer intent from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Job state, new events after after_event_seq, up to 50 summary rows, result file paths and the provenance file. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| after_event_seq | No | Return only events with seq greater than this value. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| error | No | |
| state | No | |
| events | No | |
| warnings | No | |
| event_seq | No | Highest event seq so far. |
| error_code | No | Why the job failed; set exactly when state is failed. |
| result_paths | No | |
| summary_rows | No | |
| provenance_path | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description adds meaningful behavioral detail beyond annotations: a 50-row cap on summary rows and the fact that events are returned after a given sequence number, plus result file paths and the provenance file.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with no filler, and it front-loads the core content ('Job state'). The trailing 'Read-only' is a fragment that repeats the annotation but does not significantly harm conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be fully explained, yet the description usefully outlines them. The main gaps are missing usage guidance relative to sibling tools and no explanation of the required job_id parameter, making it minimally adequate rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%; after_event_seq is documented in the schema, and the description reinforces its meaning by saying events come after it. However, job_id has no description in either the schema or the tool description, leaving its format and role undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly enumerates what the tool returns — job state, events, summary rows, result paths, provenance — so an agent knows it retrieves job details. However, it does not differentiate itself from sibling tools like crystal_status or crystal_run, which an agent must infer on its own.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives such as crystal_status or crystal_run. The only usage-like statement is 'Read-only,' which describes safety rather than context or selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build and resolve a workflow for one task over one or more CIFs, write it to disk (idempotent) and estimate its size. Every default becomes explicit.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | ||
| model | No | Model card id; omitted means the packaged default model. | |
| options | No | Workflow overrides using ce-workflow/0.1 field names (see crystal_help topic=workflow). | |
| cif_paths | Yes | Absolute CIF paths; series needs two or more. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| error | No | |
| estimate | No | |
| resolved | No | The resolved ce-workflow/0.1 document at workflow_path. |
| workflow_path | No | |
| validation_errors | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, readOnlyHint=false and destructiveHint=false; the description restates idempotency and adds the useful detail that output is written to disk and that defaults are materialized explicitly. It does not say where files go, what permissions are needed, or what happens on re-run beyond the annotation. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler, and the core action is front-loaded. 'Every default becomes explicit' is slightly cryptic but earns its place by flagging output behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. Still missing for a tool that writes files: the write location, relationship to crystal_run as the follow-up step, and any auth context. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% and the schema itself documents model, options, and cif_paths constraints (series needs two or more). The description adds only 'one or more CIFs', which is weaker than the schema's minItems/maxItems. Baseline 3 since the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verbs and resources: build/resolve a workflow, write it to disk, estimate its size, over one or more CIFs. An agent can understand it is a pre-execution planning step. However it uses domain jargon ('resolve', 'size') and never distinguishes itself from siblings like crystal_run or crystal_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use, when-not-to-use, or alternative tool named. The pre-execution planning role is only implied by 'build and resolve a workflow'. Nothing tells the agent why to call this instead of crystal_run.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a resolved workflow as a job. Reusing an idempotency_key returns the same job_id instead of starting another job.
| Name | Required | Description | Default |
|---|---|---|---|
| workflow_path | Yes | Resolved workflow written by crystal_plan. | |
| idempotency_key | Yes | Reuse the same key when retrying; it returns the same job_id. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| error | No | |
| job_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds real value by spelling out what idempotency means concretely (same key → same job_id rather than a duplicate job), but says nothing about async execution, blocking behavior, or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no waste; the core action is front-loaded and the idempotency caveat follows. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, and the tool is only two parameters. What is missing is lifecycle context: the description never tells the agent this kicks off a background job whose progress is checked elsewhere, nor that workflow_path must come from a prior crystal_plan call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are already documented in the schema (workflow_path notes it comes from crystal_plan; idempotency_key describes the retry semantics). The description essentially restates the idempotency behavior already present in the schema, adding no syntax or format detail beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Start a resolved workflow as a job" gives a specific verb (start) and resource (resolved workflow → job), which separates it from crystal_plan (which produces the resolved workflow). It does not explicitly name a sibling, so an agent must infer the plan→run→job relationship from the schema's reference to crystal_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word "resolved" implies the prerequisite that crystal_plan must have already produced the workflow, and the idempotency sentence hints at retry usage. However, there is no explicit when-to-use/when-not guidance and no mention of how to observe the started job (crystal_status/crystal_job).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Version, device and available models with their element coverage, charge support and weight licence. Read-only; call first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| error | No | |
| device | No | |
| version | No | |
| backends | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint, so the safety profile is fully covered structurally; 'Read-only' merely restates it. The one piece of added behavior is the ordering constraint ('call first'), which is useful but thin — no auth, caching, or failure behavior is described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single front-loaded sentence with no filler, and the imperative 'Read-only; call first' is placed at the end for emphasis. The only cost is that the content list is dense jargon rather than tight prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and annotations cover the safety semantics. What remains missing is what the tool is for relative to its five siblings and what the cryptic fields mean — a status/setup tool should at least say it precedes crystal_plan/crystal_run.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool is 4. No parameter meaning is needed or missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun phrase listing what the tool surfaces (version, device, available models, element coverage, charge support, weight licence), which conveys the general purpose but never states a verb or a plain-language summary. The jargon ('charge support', 'weight licence') is opaque and it does not differentiate itself from siblings like crystal_help or crystal_inspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'call first' does give one genuine usage cue — invoke this before the other tools as a discovery/setup step. However, it names no alternatives and gives no when-not condition, so the agent must still infer when crystal_help or crystal_inspect would be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0crystal_helpcrystal_inspectcrystal_jobcrystal_plancrystal_runcrystal_statusScored 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.
Workflow diagnostics, capability routing, and x402 settlement for MCP-compatible agents.
Free agent-service discovery, OpenAPI document checks, and receipt verification. No API key needed.
Read-only QFactory catalog of agent workflows: search, get exact versions, schema, validate YAML.
Remote MCP utilities for agents: structured data, commerce checks, and x402 paid API discovery.