openmc-validator-mcp

An MCP (Model Context Protocol) server that provides pre-flight validation and post-processing tools for OpenMC Monte Carlo transport simulations. Catch common authoring mistakes before the job hits the HPC queue — eliminate the costly "submit → queue → fail → fix → resubmit" loop.

Features

The server exposes 14 tools across four categories:

Validators (5) — Catch mistakes at authoring time

Tool	What it checks
validate_materials	Nuclide name typos, negative density, ao/wo fraction mixing, L2 round-trip
validate_geometry	Unclosed surface references, unknown universes/cells, DAGMC path validity
validate_settings	Batch/population sanity, source definition completeness, D-T energy check
validate_tallies	Energy bin ordering, mesh axis validity, score whitelist
validate_model	End-to-end model validation; optional openmc --geometry-debug subprocess

Cross-Checks (3) — Spot interface mismatches

Tool	What it checks
check_cross_section_library	Nuclide + temperature availability in cross_sections.xml
check_energy_filter_coverage	Energy filter upper edge vs. source max energy (e.g. 14.1 MeV)
check_tally_filter_consistency	Tally cell filters vs. geometry cells, mesh extent boundaries

Converters (2) — Bridge OpenMC to downstream codes

Tool	What it does
convert_spectrum_openmc_to_fispact	OpenMC energy tally → FISPACT-II ARBI spectrum file
extract_tally_summary	statepoint.h5 → structured JSON (mean / std / rel_err)

Template & Material Catalog (4) — Browse pre-built OpenMC templates

Tool	What it does
list_templates	List all available OpenMC model templates by category
get_template	Retrieve a specific template with all files (geometry, materials, settings)
list_materials	List all pre-defined material definitions across templates
get_material	Look up a specific material by name, get nuclide composition

Requires OPENMC_TEMPLATES_DIR environment variable pointing to an openmc-templates repository.

Error Code System

40+ structured error codes across 7 domains (MAT-*, SET-*, TAL-*, GEO-*, XS-*, EFC-*, TFC-*, MOD-*, ENV-*), each with severity, trigger description, and suggested fix. See docs/error-codes.md.

Installation

Requires Python ≥ 3.10.

# Basic install (L1 validation only, no OpenMC API required)
pip install openmc-validator

# Editable install for development
pip install -e ".[dev]"

For L2 validation (material round-trip through OpenMC API, geometry-debug):

# OpenMC is only available via conda-forge
conda create -n openmc-env -c conda-forge python=3.11 openmc
conda activate openmc-env
pip install -e ".[dev]"

Without OpenMC, L2-dependent checks degrade gracefully with ENV-W001 warnings.

Quick Start

As an MCP Server

Add to your VS Code mcp.json:

{
  "servers": {
    "openmc-validator": {
      "command": "openmc-validator",
      "args": []
    }
  }
}

See examples/mcp-config.json for a complete example with OPENMC_CROSS_SECTIONS env.

Programmatic Use

from openmc_validator.validators.materials import validate_materials
from openmc_validator.schemas import MaterialSpec, NuclideSpec

spec = MaterialSpec(
    name="Water",
    density=1.0,
    density_units="g/cm3",
    nuclides=[
        NuclideSpec(name="H1", fraction=2.0, fraction_type="ao"),
        NuclideSpec(name="O16", fraction=1.0, fraction_type="ao"),
    ],
)
report = validate_materials([spec])
print(report.passed, report.issues)

Documentation

Document	Description
docs/tool-reference.md	Full API reference for all 14 tools
docs/error-codes.md	Index of all validation error/warning codes
docs/changelog.md	Version history
examples/agent-integration.md	Using the server with AI coding agents

Project Layout

src/openmc_validator/
    schemas/        # pydantic input/output models
    validators/     # 5 validator modules
    crosschecks/    # 3 cross-check modules
    converters/     # 2 converter modules
    utils/          # subprocess helpers, logging
    server.py       # FastMCP entry point
tests/
    unit/           # pure-python unit tests (no openmc binary required)
    integration/    # end-to-end MCP protocol tests
    fixtures/
        valid/      # positive examples
        invalid/    # negative examples (expected to fail validation)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for development setup, test instructions, and pull request guidelines.

This project follows the Contributor Covenant Code of Conduct. Security vulnerabilities should be reported as described in SECURITY.md.

License

MIT — see LICENSE for details.