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

Cross-Checks (3) — Spot interface mismatches

Converters (2) — Bridge OpenMC to downstream codes

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

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.

Related MCP server: obo-mcp

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

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.