# `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**.
> 
> - **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.

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

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

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