# MoonRay MCP

An independent Model Context Protocol server for rendering, inspecting, and
diagnosing OpenMoonRay scenes.

MoonRay MCP gives an MCP-compatible client typed control over a local MoonRay
runtime. It supports Houdini's `husk` and `HdMoonrayRendererPlugin`, an optional
native `hd_render` control host, and MoonRay's standalone viewer. Batch renders
run in separate processes so a renderer failure does not take down the MCP
server.

> [!IMPORTANT]
> This is an independent, early-stage integration project. It is not affiliated
> with, endorsed by, or an official release of DreamWorks Animation or the
> OpenMoonRay project.

## Naming

The GitHub repository is named `moonray_mcp` to follow the underscore-based
naming used by related MoonRay component repositories. The installable Python
distribution and command use `moonray-mcp`, while the Python import package is
`moonray_mcp`.

## What it provides

- `moonray_health`: verify the staged runtime, tools, and Hydra delegate
- `moonray_capabilities`: describe supported inputs and implemented controls
- `moonray_resources`: check memory, disk, load, and competing render processes
- `inspect_scene`: summarize a USD stage and recommend an authored camera
- `launch_interactive_viewer`: open USD or RDL in MoonRay's standalone viewer
- `switch_interactive_viewer_aov`: select a named AOV in the live viewer
- `set_interactive_viewer_exposure`: adjust live display exposure
- `set_interactive_viewer_denoising`: turn live denoising explicitly on or off
- `capture_interactive_viewer_snapshot`: save raw EXR and visible display PNG snapshots
- `interactive_viewer_preview`: return the visible viewer image directly to the client
- `interactive_viewer_status` / `stop_interactive_viewer`: inspect or close it
- `validate_scene`: preflight USD and RDL scenes
- `inspect_materials`: explain source shaders, MoonRay translations, textures,
  active lobes, and unsupported MaterialX nodes
- `start_render`: enqueue a process-isolated render and return a stable job ID
- `render_status`: inspect an active or saved job
- `pause_render` / `resume_render`: control an active native-host render
- `resume_from_checkpoint`: start a new native render from a saved recovery point
- `capture_render_snapshot`: write a live EXR and PNG from the native render buffer
- `render_preview`: return the latest live or completed PNG preview
- `cancel_render`: stop a queued or active render
- `render_result`: return the JSON report and PNG preview
- `compare_renders`: compare completed jobs or image files and return linear
  error metrics plus EXR and PNG difference images
- `run_comparison_manifest`: reproduce a named set of comparisons with optional
  expected RMS values and tolerances

Native jobs can select a primary Hydra AOV such as `color`, `normal`, `depth`,
`primId`, `primvars:name`, `lpe:expression`, or `shader:name`. Live and final
snapshots preserve that selection in the job report.

Native color and beauty jobs can also set `denoise=true` to apply Intel Open
Image Denoise (OIDN) to the beauty output. Denoising defaults to off, is
recorded in the job report, and is rejected for diagnostic AOVs and the `husk`
backend. Albedo and normal guidance remain off in this first control slice.

Set `samples=64` on a native job to request 64 uniform samples per pixel. The
MCP translates total samples per pixel into MoonRay's square-root convention,
so 64 is passed to the renderer as `pixel_samples=8`. Sample overrides must be
perfect squares; leaving `samples` unset preserves the value authored in the
scene.

Native color and beauty jobs can set `checkpoint_interval_seconds` to write a
resumable EXR while rendering. After a checkpoint is ready, canceling or losing
the original process does not discard that work: `resume_from_checkpoint`
starts a new job with the same request and records its parent job and source
checkpoint. Resume is rejected if the source USD changed after the checkpoint
was created. The normal beauty EXR and PNG preview are extracted without
modifying MoonRay's resumable channels and metadata.

Each job preserves its source hash, settings, resource preflight, native MoonRay
progress, estimated time remaining, renderer log, translated RDL, beauty EXR,
PNG preview, image statistics, diagnostics, timing, and peak process memory in a
versioned JSON report.

## Interactive viewer

`launch_interactive_viewer` opens a visible `moonray_gui_v2` window without a
Houdini viewport. USD input is converted to MoonRay RDL first with
`hd_usd2rdl`; RDL input opens directly. The tool accepts resolution, frame,
camera, free-camera mode, and `auto`, `xpu`, `vectorized`, or `scalar` execution
modes. It returns a stable viewer ID for `interactive_viewer_status` and
`stop_interactive_viewer`, plus paths to the translated scene, viewer log,
optional final EXR, and durable JSON report.

Viewer launches include beauty, albedo, normal, depth, and wireframe displays.
Use `switch_interactive_viewer_aov` to select one by name while the window is
open. Launches can also override the scene's samples per pixel with a perfect
square value. Exposure, denoising, and snapshots can be controlled while the
viewer remains open. Each snapshot includes a raw EXR for downstream work and
a PNG matching the currently visible AOV, exposure, denoising, and display
transform. Live status reflects changes made through either MCP or the viewer
UI. The viewer's native `,` and `.` keys still cycle backward and forward.

`interactive_viewer_preview` can capture and return that visible PNG as MCP
image content, so the current AOV and display treatment appear directly in a
client rather than only as a filesystem path. Set `capture=false` to return the
most recent viewer snapshot without writing a new one.

Only one viewer or batch renderer is admitted at a time. Closing the MCP server
also closes any viewer it owns, so an abandoned client cannot leave a hidden
renderer running.

## Scene inspection

`inspect_scene` opens a USD stage read-only through Houdini's OpenUSD runtime.
It reports stage units and time range, prim and scene-element counts, authored
cameras, lights, render products, unresolved asset attributes, and a suggested
camera. An authored render-product camera wins; otherwise a clearly named shot,
render, main, or hero camera is preferred before falling back to the first
camera. The recommendation is reported explicitly and never modifies the scene.

## Requirements

- macOS with Python 3.11 or newer
- Houdini 22 with `husk`, USD tools, and OpenImageIO tools
- a staged MoonRay Houdini runtime containing `HdMoonrayRendererPlugin`
- `libcomputation_progmcrt.dylib` in the runtime's `lib` directory
- `hd_usd2rdl` and `moonray_gui_v2` for standalone USD viewing

MoonRay itself is not bundled with this repository. Build and stage OpenMoonRay
separately, then point this server at that runtime.

## Install

```bash
python3.11 -m venv .venv
.venv/bin/pip install -e .
```

Configure the runtime and output directory:

```bash
export MOONRAY_MCP_RUNTIME=/absolute/path/to/openmoonray-houdini-runtime
export MOONRAY_MCP_OUTPUT_ROOT=/absolute/path/to/moonray-mcp-jobs
```

`MOONRAY_MCP_RUNTIME` defaults to `~/.local/share/moonray-mcp/runtime`, and
`MOONRAY_MCP_OUTPUT_ROOT` defaults to `~/.local/share/moonray-mcp/jobs`.
`MOONRAY_MCP_SETUP_SCRIPT` can override the expected runtime setup script.
`MOONRAY_MCP_NATIVE_HOST` optionally selects a controllable `hd_render` build;
otherwise the server looks for `bin/hd_render` inside the staged runtime.
`MOONRAY_MCP_USD_TO_RDL` and `MOONRAY_MCP_INTERACTIVE_VIEWER` can override the
translator and standalone viewer executables.

`start_render` uses the certified `husk` backend by default. Set its `backend`
argument to `native` to opt into live status, pause, resume, snapshot, and
cooperative cancellation through the control host. Set `aov` to select the
native render buffer; non-color AOV selection is intentionally rejected by the
default `husk` backend until a scene-safe render-product overlay is available.

Run the stdio server with:

```bash
.venv/bin/moonray-mcp
```

An MCP client registration example is available at
[`examples/mcp.json`](examples/mcp.json).

The Zeltner regression example at
[`examples/regressions/zeltner.json`](examples/regressions/zeltner.json) uses
`MOONRAY_ZELTNER_FIXTURE_ROOT` to locate its external image set and preserves
the historical RGBA metric convention explicitly.

## Safety model

The server binds no network port and exposes no arbitrary command execution.
Scene paths, camera paths, resolution, and job IDs are validated. Renders are
serialized through one worker, source scenes are never modified, and launch is
blocked when memory or disk space is critical or another local MoonRay render is
already active.

## Development

```bash
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall -q src/moonray_mcp
```

Run the opt-in Cornell render certification against a configured runtime with:

```bash
MOONRAY_MCP_INTEGRATION=1 \
MOONRAY_MCP_RUNTIME=/absolute/path/to/openmoonray-houdini-runtime \
  .venv/bin/python -m unittest tests.test_cornell_integration -v
```

Certify the native control path separately after installing a controllable
`hd_render` host:

```bash
MOONRAY_MCP_NATIVE_INTEGRATION=1 \
MOONRAY_MCP_RUNTIME=/absolute/path/to/openmoonray-houdini-runtime \
MOONRAY_MCP_NATIVE_HOST=/absolute/path/to/hd_render \
  .venv/bin/python -m unittest tests.test_cornell_integration -v
```

The current implementation plan and future phases are documented in
[`docs/roadmap.md`](docs/roadmap.md).

## Status

Version 0.1.0 establishes the MCP protocol, resource admission, persistent job
model, output validation, and failure reporting. The full Cornell-box path is
certified through the MCP at 128x128, including active-render cancellation with
durable provenance and orphan-process checks. Native MoonRay progress is
certified through both completed and actively canceled MCP jobs. Material
inspection covers source USD, translated RDL snapshots, missing textures,
UDIMs, and `.tx` availability. The comparison workflow adds durable RMS, mean,
peak-SNR, and maximum-error reports without grading visual equivalence. The
earlier render-preparation crash was traced to stale DwaBase-derived material
DSOs after an ABI-changing header update; rebuilding all dependent DSOs
resolved it. The native `hd_render` backend is certified through the MCP for
status, stable pause/resume, live snapshots, cooperative cancellation, and
orphan cleanup. Primary AOV selection and live retrieval are also certified
with the Cornell fixture's `normal` AOV. Automatic beauty checkpoints and
cross-process resume are certified through a 256x256 Cornell job that saved a
checkpoint, canceled its original process, and completed from a new process.

## License

The original code and documentation in this repository are licensed under the
[Apache License 2.0](LICENSE).

MoonRay, OpenMoonRay, Houdini, and other external applications, libraries, and
assets are not distributed as part of this repository. They remain subject to
their respective licenses and trademarks. The Apache 2.0 license for this
project does not grant rights to those separately distributed components.