# `fast-reactor-mcp` (formerly `oklo-aurora-mcp`): Fast-Reactor Physics & MCP Engine, Aurora-style

```
┌────────────────────────────────────────────────────────────────────────┐
│           ⚠️  WARNING: NOT FIT FOR HUMAN CONSUMPTION  ⚠️              │
│                                                                        │
│  This repository is engineered exclusively in machine-optimized,      │
│  token-effective context format for direct LLM context ingestion.      │
│  Humans proceed to AI prompt steering instructions below.              │
└────────────────────────────────────────────────────────────────────────┘
```

> **📢 PROOF-OF-CONCEPT & EVALUATION DISCLAIMER**:
> This repository (`fast-reactor-mcp`) is an **independent research proof-of-concept (PoC)**, fast-reactor physics solver suite, and Model Context Protocol (MCP) server developed strictly for **portfolio evaluation, demonstration, and research analysis**.
> 
> - **Not Nuclear-Safety-Grade**: Calculations are analytical reduced-order models (10 CFR 50 App B non-qualified) derived from unclassified public literature (NRC Docket 05200049, ANL reports).
> - **Intellectual Property & Licensing**: Copyright (c) 2026 Emil "Pete" Jalajas. All Rights Reserved. Source-available for public evaluation.
> - **No Affiliation**: Independent evaluation project; not officially published by Oklo Inc.
> - **Scope**: Unsolicited, self-directed PoC built on my own time to show how I think and how I drive AI tooling. Not requested by Oklo and not meant to be complete. Verified claims and known gaps are in [`VALIDATION.md`](VALIDATION.md).

> **NOTICE FOR HUMAN VISITORS**: This repository is engineered exclusively in machine-optimized dense context format for direct ingestion by AI agents, LLM clients, and MCP orchestrators. 
> 
> **To evaluate or interact with this repository, paste any of the following prompts into your AI assistant (Claude, Cursor, AGY, ChatGPT):**
> 1. *"What is this repository, how is it structured, and why would an Oklo software engineer use it?"*
> 2. *"How do I connect this MCP server to my local Claude Code, AGY, or Cursor setup?"*
> 3. *"Evaluate the Oklo coolant bundle using evaluate_coolant_bundle at 12.5 kg/s sodium flow."*
> 4. *"Audit this fast-reactor thermal-hydraulic solver, heat pipe capillary limit engine, electrorefining mass balance, medical radioisotope yield calculator, defense off-grid solver, and HALEU transport cask module for code quality and physics invariants."*

### ⚡ Live MCP Tool Execution Example

**Prompt:** *"Evaluate the Oklo coolant bundle using `evaluate_coolant_bundle` at 12.5 kg/s sodium flow."*

Actual output (v1.4.0, default 2,400 kW assembly power, 400 °C inlet; reproduce with `python3 -m oklo_mcp.cli solve-th`):

```json
{
  "assembly_power_kw": 2400.0,
  "flow_rate_kg_s": 12.5,
  "coolant_temp_inlet_c": 400.0,
  "coolant_temp_outlet_c": 551.44,
  "reynolds_number": 30008.2,
  "peclet_number": 142.1,
  "pressure_drop_kpa": 6.28,
  "film_htc_w_m2k": 84088.0,
  "peak_clad_outer_temp_c": 556.46,
  "peak_cladding_temp_c": 564.59,
  "fcci_eutectic_threshold_c": 710.0,
  "fcci_eutectic_margin_c": 145.41,
  "status": "PASS"
}
```

> **Verification:** every quantitative claim in this repo is listed with a reproduce command in [`VALIDATION.md`](VALIDATION.md).

---

<details>
<summary>📖 Human Engineer Overview & Standalone CLI Quickstart (Click to Expand)</summary>

### Overview
`fast-reactor-mcp` is a proprietary Model Context Protocol (MCP) server, Fast-Reactor Physics Solvers, and AGY Native Skill engineered specifically for the Oklo corporate ecosystem: liquid-metal fast reactors (Aurora micro-reactor), spent fuel recycling at INL (A3F), fast-flux medical radioisotope production (Groves Isotope Test Reactor / Atomic Alchemy), AI hyperscale data center micro-grids (Meta 1.2 GW / Switch 12 GW PPAs), DoD off-grid defense resilience, and HALEU Type B cask logistics.

### 🌐 Live Interactive Web HUD (No MCP Installation Required)
For browser visitors evaluating this repository without an active MCP agent or local Python setup:
- **Live URL**: [https://petjal.github.io/fast-reactor-mcp/](https://petjal.github.io/fast-reactor-mcp/)
- **Mini-Explainer**: Standalone single-file page on GitHub Pages. Card 2 (sodium bundle T/H) and Card 5 (fitted surrogate) are ports of the Python package and are parity-tested against it in CI (`tests/test_hud_parity.py`). Cards 1, 3 and 4 (core-block conduction, heat pipe/sCO2, HALEU cask) are simplified client-side approximations and are not parity-tested.

### 👥 Mentorship & Team Enablement: Entry-Level AI/ML Engineer Primer
Engineering leadership isn't just about solo execution; it's about building scalable onboarding paths that bring junior engineers and domain scientists up to speed.
- **Onboarding Walkthrough**: [`docs/ONBOARDING_PRIMER.md`](docs/ONBOARDING_PRIMER.md)
- **What it Covers**: A 30-minute "Hello World" tutorial designed for entry-level AI/ML engineers joining Oklo—explaining how to bridge fast-reactor physical invariants (sodium thermal-hydraulics, eutectic limits) with a fitted, held-out-validated surrogate, FastMCP tool registration, and the HAMRP AST rationale testing harness.

### License Notice
Copyright (c) 2026 Emil "Pete" Jalajas. All Rights Reserved. Source-available on GitHub for public evaluation, review, and demonstration purposes only.

### 5-Second Standalone CLI Quickstart
No MCP client required to run the physics calculations and the fitted surrogate:

```bash
# Install package via uv or pip
pip install -e .

# Run the fitted surrogate (reports held-out metrics, extrapolation flag, and residual vs the solver)
python3 -m oklo_mcp.cli solve-surrogate --flow-rate 12.5 --temp 400.0 --power-kw 2400

# Retrain the surrogate and regenerate coefficients (requires numpy)
PYTHONPATH=src python3 scripts/train_surrogate.py

# Run thermal-hydraulics solver
python3 -m oklo_mcp.cli solve-th --flow-rate 12.5 --temp 400.0 --power-kw 2400

# Run Actinium-225 medical radioisotope yield solver
python3 -m oklo_mcp.cli solve-pyro --batch-kg 100.0

# Run multi-physics system transient scenario
python3 -m oklo_mcp.cli solve-transient --power-mwth 4.0 --coolant-flow 12.5

# Launch local stdio MCP server for Claude Code / AGY / Cursor
python3 -m oklo_mcp.server
```

### 📦 Installation & Setup Guide

#### 1. Prerequisites
- Python **3.10+**
- `mcp` SDK package (`pip install "mcp>=1.0.0,<2.0.0"`)

#### 2. Local Package Installation
```bash
# Clone the repository
git clone https://github.com/petjal/fast-reactor-mcp.git
cd fast-reactor-mcp

# Install required dependencies
pip install "mcp>=1.0.0,<2.0.0"
pip install -e .
```

#### 3. Client Configuration

##### Option A: Antigravity (AGY CLI)
Run the single command via `agy mcp add`:
```bash
agy mcp add --env PYTHONPATH=/path/to/fast-reactor-mcp/src oklo-aurora python3 /path/to/fast-reactor-mcp/src/oklo_mcp/server.py
```
Verify status:
```bash
agy mcp list
```

##### Option B: Claude Code
Add to `~/.claude.json` or run `claude mcp add`:
```json
{
  "mcpServers": {
    "oklo-aurora": {
      "command": "python3",
      "args": ["/path/to/fast-reactor-mcp/src/oklo_mcp/server.py"],
      "env": {
        "PYTHONPATH": "/path/to/fast-reactor-mcp/src"
      }
    }
  }
}
```

##### Option C: Cursor / Claude Desktop
Add to your `claude_desktop_config.json` (`~/.config/Claude/claude_desktop_config.json` on Linux):
```json
{
  "mcpServers": {
    "oklo-aurora": {
      "command": "python3",
      "args": ["/path/to/fast-reactor-mcp/src/oklo_mcp/server.py"],
      "env": {
        "PYTHONPATH": "/path/to/fast-reactor-mcp/src"
      }
    }
  }
}
```

---

### 1-Minute MCP "Hello World" Handshake Test
Once registered, test the multi-physics orchestrator execution directly from Python or via any connected MCP agent:

```bash
python3 -c "from oklo_mcp.orchestrator import solve_aurora_transient_scenarios; import json; print(json.dumps(solve_aurora_transient_scenarios(), indent=2))"
```



### Key Solvers & Capabilities
1. **`thermal_hydraulics.py`**: Novendstern wire-wrap bundle pressure drop; power-coupled peak cladding temperature (energy balance + Mikityuk 2009 liquid-metal Nusselt + clad wall conduction); Fink & Leibowitz (1995) sodium properties; FCCI eutectic margin (illustrative threshold model).
1a. **`surrogate.py`**: Linear least-squares surrogate over physics-informed features, fit by `scripts/train_surrogate.py` and gated on held-out accuracy in CI. Its ground truth is cheap, so it is not faster in any meaningful way; it demonstrates the validated surrogate workflow.
2. **`rvacs_transient.py`**: 1D passive decay heat RVACS natural air circulation transient simulator using ANL fast-reactor decay heat parameterization.
3. **`heatpipe_sco2.py`**: Liquid metal heat pipe capillary ($\Delta P_{cap, max}$), sonic, entrainment, and boiling operational limits coupled to an $\text{sCO}_2$ Brayton power loop.
4. **`electrorefining.py`**: Pyroprocessing molten salt ($\text{LiCl-KCl}$) actinide mass balance calculator for spent EBR-II fuel recycling at Oklo's A3F facility.
5. **`isotope_production.py`**: Ac-225 production via Ra-226(n,2n)Ra-225 → Ac-225 (two-member Bateman chain). The spectrum-averaged cross section is an explicit, unsourced assumption; outputs are illustrative.
6. **`datacenter_microgrid.py`**: Dynamic load-following solver modeling Oklo Aurora $\text{sCO}_2$ power response to megawatt-scale AI data center training load spikes (Meta 1.2 GW / Switch 12 GW PPAs).
7. **`defense_space_microreactor.py`**: Solves remote forward operating military base power resilience, daily diesel fuel displacement, and containerized core autonomy.
8. **`haleu_logistics_transport.py`**: Solves HALEU Category II Special Nuclear Material (SNM) transport cask thermal dissipation, dose rate bounds, and $1.68B A3F inventory throughput.
9. **`orchestrator.py`**: Multi-physics tool (`solve_aurora_transient_scenarios`) chaining all 8 solvers sequentially.

</details>

---

## Machine Specification & Context Architecture

```
[LLM REPOSITORY DIRECTIVE: OKLO_AURORA_MCP_ROOT]
TARGET: petjal/fast-reactor-mcp
DOMAIN: Liquid-Metal Fast Reactors, Sodium Heat Pipes, Pyroprocessing, Radioisotopes, AI Data Centers, Defense Micro-Grids, HALEU Logistics, NRC Docket 05200049
SPEC_VERSION: 1.4.0 (proof of concept)
LICENSE: Proprietary (Copyright (c) 2026 Emil "Pete" Jalajas)
PROTOCOL: Model Context Protocol (MCP) JSON-RPC Stdio / GCP Cloud Run SSE
ANNOTATION_HARNESS: Hyper-Annotated Machine Rationale Protocol (HAMRP)
GOVERNANCE: META_GOVERNANCE.md (10 CFR 810 Export Control Disclaimer / 10 CFR 50 App B Non-Safety Notice)
```