OctaneX MCP

A local MCP server that lets Hermes Agent use Octane X as a shared visual canvas for geometry, data, math, and concept visualization.

Hermes MCP tool call -> Python MCP server -> JSON command queue -> Octane Lua bridge -> Octane X viewport/render target

The bridge intentionally avoids arbitrary Lua execution. The MCP server emits a small allowlisted command DSL, and the Octane-side Lua bridge validates and processes those commands inside Octane X.

Example visual products

Photoreal product studio

The recipe library starts with copyable visual targets, not just prose. The headline example above is a photoreal/PBR product-studio setup with glass, metal, softbox reflections, camera intent, material notes, and a native-render validation checklist. See examples/recipes/photoreal-product-studio/ for the reusable OBJ/MTL scene and MCP command metadata.

More recipe previews

Photoreal Earth	Saturn and moons	Data bars
Space rendering target with clouds, atmosphere, and sunlight.	Ringed-planet target with moons, bands, and Cassini division.	Fast generated chart geometry for numeric comparisons.

Math surface	Architecture flow	Animated orbit reveal
Damped radial surface for mathematical explanation.	Explain command flow as spatial geometry.	GIF/MP4 frame-sequence pattern for animated products.

Wave interference	Vision feedback loop
Two-source wave field with highlighted emitters.	Agent loop from scene queue to PNG preview to local vision review.

What this is for

Use this project when an agent needs to turn an explanation into a rendered scene:

• data as 3D bar charts or future chart grammars;
• math as surfaces and geometric objects;
• concepts as simple staged scenes;
• Hermes' avatar as a visual guide inside a render;
• quick render/preview/review loops for local visual R&D.

The documentation is written for rapid agentic learning, including smaller local models: start with the workflow cards below, then copy the exact examples.

Current status

Verified or implemented:

• octanex-mcp stdio MCP server.
• Hermes MCP config pattern for mcp_servers.octanex.
• Octane X sandbox/container workspace path.
• Ordered JSON command queue plus inbox.json compatibility fallback.
• Versioned typed command schema, structured validation error codes, queue validation, processing/ state, and per-command result JSON files.
• One-shot Lua bridge that drains queue/*.json and exits.
• Persistent Lua bridge window with manual Process next / Drain queue controls and timer fallback notes.
• Parity tests keep one-shot and persistent scene-command handlers semantically aligned; they should differ only in scheduling/UI behavior.
• Scene operations: import mesh, create material, assign material, set camera, set lighting, start/restart render, save preview.
• Visual tools: bar chart, math surface, Hermes avatar face.
• Generated visual assets include bounds metadata and use bounds-aware camera placement for more reliable framing.
• Self-improving recipe book tools: agents can read and append successes, failures, partials, and pitfalls.

Known constraints:

• Octane X is sandboxed on macOS. Hermes must write to the real app-container path, not the apparent ~/OctaneMCP path.
• Persistent Lua UI can block Octane's viewport refresh. Prefer one-shot queue draining for batches when the viewport looks stale.
• The core Python package stays lightweight: only mcp is required. Heavier geometry/science packages should be optional.

Install and run

From this repo:

uv sync
PYTHONPATH= uv run octanex-mcp init
PYTHONPATH= uv run octanex-mcp doctor
PYTHONPATH= uv run octanex-mcp --self-test

Hermes config in ~/.hermes/config.yaml:

mcp_servers:
  octanex:
    command: "uv"
    args: ["run", "--project", "/path/to/octane-mcp", "octanex-mcp"]
    timeout: 180
    connect_timeout: 30

For another checkout location, replace the --project path or set OCTANEX_MCP_REPO before running the MCP server.

Restart Hermes or use /reload-mcp after config changes, then verify:

hermes mcp test octanex

Workspace paths

By default, Hermes writes to the real Octane X sandbox container path for the current macOS user:

~/Library/Containers/com.otoy.rndrviewer/Data/OctaneMCP/

Octane Lua may appear to use this path in scripts:

~/OctaneMCP/

For reliability, generated scripts use the real container path directly. Override paths with environment variables when needed:

export OCTANEX_MCP_WORKSPACE="$HOME/Library/Containers/com.otoy.rndrviewer/Data/OctaneMCP"
export OCTANEX_MCP_REPO="/path/to/octane-mcp"
export OCTANEX_APP_PATH="/Applications/Octane X.app"
PYTHONPATH= uv run octanex-mcp init
PYTHONPATH= uv run octanex-mcp doctor

octanex-mcp init creates the workspace folders, writes octanex-mcp.config.json in the workspace, writes octane_lua/config.generated.lua, and generates portable bridge copies with the resolved workspace path injected. See docs/octane-bridge.md for bridge lifecycle and parity rules.

Required Octane X Preferences setup

Octane X must be told where to find the Octane MCP Lua bridge scripts. After running octanex-mcp init, open Octane X and set the Lua scripts directory:

1. Open Octane X.
2. Open Preferences.
3. Find the Scripts path setting.
4. Set Scripts path to this checkout's Lua script directory:

/path/to/octane-mcp/octane_lua

For this repository checkout, that is the octane_lua/ folder containing:

hermes_bridge_oneshot.generated.lua
hermes_bridge_persistent.generated.lua

If OCTANEX_MCP_REPO points somewhere else, use $OCTANEX_MCP_REPO/octane_lua. Restart Octane X after changing this preference if the scripts do not appear immediately.

Important files:

.../OctaneMCP/inbox.json          latest command fallback
.../OctaneMCP/queue/*.json        ordered command queue
.../OctaneMCP/processing/*.json   command currently being handled
.../OctaneMCP/processed/*.json    successful processed commands
.../OctaneMCP/failed/*.json       failed command payloads
.../OctaneMCP/results/*.json      per-command success/error/result metadata
.../OctaneMCP/artifacts/          generated non-OBJ/preview artifacts
.../OctaneMCP/assets/             generated OBJ assets
.../OctaneMCP/renders/            preview/render outputs
.../OctaneMCP/scenes/             saved semantic scene manifests
.../OctaneMCP/status.json         bridge status/heartbeat
.../OctaneMCP/bridge.log          bridge log

Octane-side bridge scripts

Preferred batch fallback: one-shot bridge

Open Octane X and run:

/path/to/octane-mcp/octane_lua/hermes_bridge_oneshot.generated.lua

This drains all ordered queue/*.json commands and exits so Octane's viewport/render loop can repaint. It also falls back to inbox.json for older single-command workflows.

Persistent bridge window

Open Octane X and run:

/path/to/octane-mcp/octane_lua/hermes_bridge_persistent.generated.lua

Leave the Hermes Octane MCP Bridge window open while using Hermes. If the timer mode is unavailable, use Process next for one command or Drain queue for a batch. Do not add sleep loops to Octane Lua; they run on the UI thread and can freeze Octane X.

If the persistent bridge closes with status released after start_render, that is intentional: it gives Octane's renderer a chance to repaint.

MCP tool catalogue

Status and learning

Tool	Purpose
octane_status()	App existence, queue, processed/failed files, bridge status.
octane_validate_command(command)	Validate one JSON command envelope.
octane_schema()	Return supported command operations, limits, path rules, and examples.
octane_validate_queue()	Validate queued command files in the workspace.
octane_recipe_book(limit_chars=12000)	Read local field notes for successes, failures, and pitfalls.
octane_record_recipe(title, outcome, context, steps, signals, follow_ups)	Append a lesson to docs/recipe-book.md.

Low-level scene commands

Tool	Purpose
octane_ping(message)	Queue a bridge ping.
octane_create_test_cube(name, size)	Generate a cube OBJ and queue import.
octane_import_geometry(path, name, format)	Queue OBJ/USD/FBX/Alembic import.
octane_create_material(name, kind, color, roughness, metallic)	Queue material create/update.
octane_assign_material(object_name, material_name)	Queue material assignment.
octane_set_camera(position, target, fov)	Queue camera placement.
octane_set_lighting(preset)	Queue lighting preset.
octane_start_render(samples, width, height)	Queue render restart and resolution update.
octane_save_preview(path, width, height, samples, min_samples, timeout_seconds)	Queue render-ready PNG preview save.
octane_review_preview(path)	Review saved PNG previews with metrics, diagnosis, likely causes, and recommended actions.
octane_suggest_camera_fix(preview_review, asset_bounds)	Suggest a camera patch from preview QA and asset bounds.
octane_suggest_lighting_fix(preview_review)	Suggest a lighting/render patch from preview QA.

Higher-level visual tools

Tool	Purpose
octane_visualize_bars(values, name)	Build a 3D bar chart OBJ and queue a full scene.
octane_visualize_surface(expression, name, x_min, x_max, y_min, y_max, steps)	Build a restricted z=f(x,y) surface and queue a full scene.
octane_visualize_scatter(points, name)	Build a 3D scatter plot OBJ from xyz triples and queue a full scene.
octane_show_avatar(name)	Show Hermes' geometric avatar face.
octane_build_scene(scene_plan)	Save a semantic scene manifest and queue validated scene commands.
octane_save_scene_manifest(scene_plan)	Save a semantic scene manifest without queueing commands.
octane_build_concept(prompt)	Deterministic MVP concept scaffold.

Workflow cards for agents

Card 1: Is the bridge alive?

1. Call octane_status().
2. If bridge_seen is false, ask the user to run one of the Lua bridge scripts in Octane X.
3. If queue grows but processed does not, run the one-shot bridge.
4. Record any non-obvious fix with octane_record_recipe(...).

Card 2: Show a simple object

1. Call octane_create_test_cube(name="agent_cube", size=1.0).
2. In Octane X, run hermes_bridge_oneshot_v2.lua.
3. Call octane_start_render(samples=128) if needed.
4. Call octane_save_preview(); the bridge restarts rendering, waits for ready samples, then saves PNG.
5. Call octane_review_preview() and verify ok=true before claiming success.

Card 3: Visualize data quickly

1. Call octane_visualize_bars(values=[3, 1, 4, 1, 5], name="pi_digits").
2. Run/drain the Lua bridge in Octane X.
3. Save a preview.
4. Call octane_review_preview(); if it reports blank/clipped/low-contrast output, adjust the generator or camera and record the lesson.

Card 4: Visualize a math surface

1. Call octane_visualize_surface(expression="sin(r) / max(r, 0.25)", steps=36).
2. Drain the queue with the one-shot bridge.
3. Save/inspect preview.
4. Keep expressions restricted to x, y, r, sin, cos, tan, sqrt, log, exp, pow, min, max, abs, pi, and e.

Card 5: Self-improve after use

After any successful, failed, or surprising run, append a concise recipe:

octane_record_recipe(
  title="One-shot bridge fixed stale viewport after bar chart import",
  outcome="success",
  context="Persistent bridge processed queue but Octane viewport stayed stale.",
  steps=[
    "Queued octane_visualize_bars with five values.",
    "Ran hermes_bridge_oneshot_v2.lua inside Octane X.",
    "Restarted render and saved preview."
  ],
  signals=["queue/ drained", "processed/ gained command files", "preview PNG existed"],
  follow_ups=["Prefer one-shot bridge for multi-command visual scenes"]
)

Keep entries small and operational. A future local model should be able to copy the pattern directly.

Development smoke tests

cd /path/to/octane-mcp
PYTHONPATH= uv run octanex-mcp --self-test
PYTHONPATH= uv run python -m octanex_mcp.client_smoke
PYTHONPATH= uv run python -m compileall src
hermes mcp test octanex

PYTHONPATH= avoids accidentally importing packages from Hermes' own runtime venv when developing inside the Hermes desktop terminal.

More docs

• docs/agent-quickstart.md — short examples designed for small/local models.
• docs/recipe-library.md — broad example scenes with reusable OBJ files, command metadata, and preview renders.
• docs/recipe-book.md — self-improving successes, failures, partials, and pitfalls.
• docs/canvas-roadmap.md — visual canvas roadmap.
• docs/local-model-rich-moa.md — local visual R&D process.

Example recipe library

Reusable sample scenes live under examples/recipes/. Each recipe directory contains:

• README.md — prompt, purpose, steps, and variations;
• scene.obj — reusable geometry;
• scene.json — camera and MCP command sequence metadata;
• preview.png or photoreal-preview.png — preview/target render for quick review.

Start with docs/recipe-library.md when exploring applications beyond the built-in bars/surface/avatar tools.

Animated examples live under examples/animations/. The first example, orbit-reveal, includes a GitHub-friendly GIF, MP4, PNG frame sequence, OBJ frame states, and storyboard metadata. The current robust animation pattern is frame-by-frame scene generation plus ffmpeg encoding; native Octane timeline control can be added later.

---

Links

• X / Twitter: @nobulart
• Support: Buy me a coffee