# openmc-validator-mcp

[![Tests](https://github.com/zxkjack123/openmc-validator-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/zxkjack123/openmc-validator-mcp/actions/workflows/tests.yml)
[![Coverage](https://img.shields.io/badge/coverage-80%25-green)](https://github.com/zxkjack123/openmc-validator-mcp)
[![Python](https://img.shields.io/badge/python-3.10_|_3.11_|_3.12-blue)](https://github.com/zxkjack123/openmc-validator-mcp)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)

An **MCP (Model Context Protocol) server** that provides pre-flight validation
and post-processing tools for [OpenMC](https://docs.openmc.org/) 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](https://github.com/zxkjack123/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`](docs/error-codes.md).

## Installation

Requires **Python ≥ 3.10**.

```bash
# 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):

```bash
# 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`:

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

See [`examples/mcp-config.json`](examples/mcp-config.json) for a complete
example with `OPENMC_CROSS_SECTIONS` env.

### Programmatic Use

```python
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`](docs/tool-reference.md) | Full API reference for all 14 tools |
| [`docs/error-codes.md`](docs/error-codes.md) | Index of all validation error/warning codes |
| [`docs/changelog.md`](docs/changelog.md) | Version history |
| [`examples/agent-integration.md`](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`](CONTRIBUTING.md) for
development setup, test instructions, and pull request guidelines.

This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md) Code of
Conduct. Security vulnerabilities should be reported as described in
[`SECURITY.md`](SECURITY.md).

## License

MIT — see [`LICENSE`](LICENSE) for details.