> **Status:** superseded by [sfr-tdd-mcp](https://github.com/petjal/sfr-tdd-mcp). Kept public as a record of what went wrong; see [PROVENANCE.md](PROVENANCE.md).

# `oklo-aurora-mcp` (Oklo Aurora Fast Reactor Systems & MCP Engine)

```
┌────────────────────────────────────────────────────────────────────────┐
│           ⚠️  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 (`oklo-aurora-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**.
> 
> - **Provenance audit (2026-10-06)**: Several constants are unsourced or wrong. Labels such as "ANL" on the density, viscosity, and decay-heat fits could not be traced. The surrogate's "R^2 > 0.998" claim is false (measured -2.55). See [PROVENANCE.md](PROVENANCE.md) before using any output.
> - **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.

> **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."*

```json
{
  "flow_rate_kg_s": 12.5,
  "coolant_temp_inlet_c": 500.0,
  "coolant_temp_outlet_c": 650.0,
  "density_kg_m3": 896.5,
  "velocity_m_s": 1.528,
  "reynolds_number": 21421.3,
  "friction_factor_bundle": 0.03256,
  "pressure_drop_kpa": 6.37,
  "peak_cladding_temp_c": 685.0,
  "fcci_eutectic_threshold_c": 710.0,
  "fcci_eutectic_margin_c": 25.0,
  "eutectic_violation": false,
  "status": "PASS"
}
```

---

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

### Overview
`oklo-aurora-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/oklo-aurora-mcp/](https://petjal.github.io/oklo-aurora-mcp/)
- **Mini-Explainer**: The Web HUD is a standalone, single-file client-side web application hosted on GitHub Pages. It provides interactive, instant calculations matching the FastMCP python solvers—including Monolithic Core Block conduction (Docket 05200049), Novendstern sodium coolant pressure drop, heat pipe Levy/Busse sonic limits, $\text{sCO}_2$ Brayton cycle thermal efficiency, 10 CFR Part 71 HALEU transport cask subcriticality, and fast-reactor Physics-Informed Digital Twin Neural Surrogate inference.

### 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 deterministic physics calculations & neural surrogate inference:

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

# Run physics-informed Digital Twin neural surrogate inference
python3 -m oklo_mcp.cli solve-surrogate --flow-rate 12.5 --temp 500.0

# Run thermal-hydraulics solver
python3 -m oklo_mcp.cli solve-th --flow-rate 12.5 --temp 550.0

# 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/oklo-aurora-mcp.git
cd oklo-aurora-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/oklo-aurora-mcp/src oklo-aurora python3 /path/to/oklo-aurora-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/oklo-aurora-mcp/src/oklo_mcp/server.py"],
      "env": {
        "PYTHONPATH": "/path/to/oklo-aurora-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/oklo-aurora-mcp/src/oklo_mcp/server.py"],
      "env": {
        "PYTHONPATH": "/path/to/oklo-aurora-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 liquid sodium bundle pressure drop & peak cladding temp ($T_{clad, peak}$) with FCCI eutectic threshold tracking.
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`**: Fast-neutron flux irradiation yield solver for high-margin targeted alpha-therapy medical radioisotopes (**Actinium-225 $\text{Ac-225}$**, Lead-212) at Oklo's Groves Isotope Test Reactor / Atomic Alchemy facility.
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/oklo-aurora-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.3.0-PRODUCTION
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)
```