Mandelbulber MCP

Safe, exact-version scene control and verified rendering for Mandelbulber 2.34.

Mandelbulber MCP is a standalone stdio server for managed .fract workspaces. It inspects trusted templates, applies reviewed byte-preserving edits, runs fixed CPU stills and finite animations, and verifies every PNG/MP4 independently. Mandelbulber exit code zero and Image saved are diagnostic only—not proof of success.

What works today

The server exposes 26 strict tools:

• the stable probe, inspect, clone, safe-patch, static-validation, and synchronous-preview workflow;

• reviewed schema queries, typed batch edits, camera controls, lights 1–5, materials 1–64, and curated Mandelbulb/Mandelbox/Menger formula stacks;

• persistent manifest-v2 workspaces with status, diff, archive, token-gated delete, and explicit legacy upgrade;

• finite preview/production still jobs with submit, status, cancel, idempotency, recovery, and transaction-safe artifact admission.

• finite 1–10 second camera/light/material/Mandelbulb-power animations with camera banking, persistent submit/status/cancel jobs, 6–12 FPS, and verified H.264 MP4 output.

Three read-only MCP resource templates expose reviewed schemas and manifest-authorized PNG/MP4/log artifacts through opaque URIs. Clients never supply host paths, executables, codecs, flags, environments, shell commands, scripts, formula source, or network endpoints.

Related MCP server: MC-World-MCP

Requirements

• Windows x64

• Node.js 24.12.x (.nvmrc)

• exact Mandelbulber CLI 2.34

• an administrator-reviewed executable SHA-256

• administrator-reviewed FFmpeg and FFprobe SHA-256 values for animations

• disjoint trusted-template and private work roots

The checked-in Win32 Job Object supervisor is a hash-pinned unsigned development binary. The server actively rejects production launches unless the helper confirms a non-elevated NTFS host, reparse-free roots, writable work storage, and non-writable executable/template roots. A signed helper and a passing restricted-account deployment report are still required before a production 1.0 release.

Install and verify

nvm use 24.12.0
npm ci
npm run check
npm run build

The normal suite currently discovers 107 tests; 104 pass and three remain gated by real-binary or Windows privilege conditions.

Configure a preview server

$env:MANDELBULBER_EXECUTABLE = 'C:\Program Files\Mandelbulber2\mandelbulber2.exe'
$env:MANDELBULBER_EXECUTABLE_ROOT = 'C:\Program Files\Mandelbulber2'
$env:MANDELBULBER_EXECUTABLE_SHA256 = '<reviewed lowercase sha256>'
$env:MANDELBULBER_TEMPLATE_ROOT = 'C:\mandelbulber-mcp\templates'
$env:MANDELBULBER_WORK_ROOT = 'C:\mandelbulber-mcp\work'
$env:MANDELBULBER_CAPABILITY_PROFILE = 'preview'

node .\dist\src\index.js

Stdout is reserved for MCP protocol messages. Startup diagnostics go to stderr.

A normal workflow is:

probe -> inspect template -> clone -> patch with hash/revision
      -> validate static subset -> render -> read verified artifact

With the administrator advanced profile and reviewed encoder binaries, the final step may instead be animation_submit -> animation_status -> MP4 resource read.

Safety defaults

• exact adapter mandelbulber-2.34-windows; unknown versions fail closed;

• CPU/PNG still previews, 5–512 per side, at most 262,144 pixels, 120 seconds;

• production defaults up to 2048×2048, 600 seconds, 4 GiB process memory, and 10 GiB managed storage—only when explicitly enabled by the administrator;

• fixed argv with shell: false, isolated per-workspace profiles, bounded stdout/stderr, Job Object process-tree cleanup;

• immutable templates, managed logical paths, hash/revision preconditions, atomic edits, transaction journals, quarantine on contradictory recovery evidence;

• valid signature/IHDR, exact dimensions, size, containment, identity, hash, and manifest admission required for render success.

• animations are CPU-only H.264/yuv420p MP4, 1–10 seconds, 6–12 FPS, at most 120 verified frames and 512×512; reviewed tracks cover camera/roll, lights, material highlights, and Mandelbulb power while FFmpeg/FFprobe argv remains server-fixed.

Run the production deployment gate under the intended service identity:

npm run check:windows-production

It must report passed: true. This development checkout currently fails because its template fixture root is writable, which is the intended fail-closed result.

Scope boundary

Longer/production animations, approved assets, voxel export, GPU/OpenCL, Linux, and additional exact versions remain future modules. Netrender and trusted code-bearing templates are blocked on a structured upstream interface. GUI automation, arbitrary command/flag/override/codec access, client scripts/code/endpoints, and Mandelbulber common queue are permanently excluded.

Documentation

• Master plan and release matrix

• Operator setup

• Tool and resource reference

• Compatibility matrix

• Security model

• Runtime test matrix

• Exact 2.34 adapter history

The historical source investigation remains available in the other documents under docs/; it does not expand the supported runtime beyond exact Mandelbulber 2.34 on Windows.