Mandelbulber 2 MCP

A fail-closed MCP server for inspecting, cloning, safely patching, validating, and rendering preview images from Mandelbulber 2.34 .fract scenes.

This first release deliberately controls a small, verified part of Mandelbulber. It works from trusted templates, preserves scene bytes outside approved edits, invokes the CLI without a shell, and verifies the generated PNG instead of trusting Mandelbulber's exit code or Image saved message.

What it can do

Tool	Purpose
mandelbulber_probe	Verify the configured executable, SHA-256, and exact 2.34 version output
fract_inspect	Read lexical header, sections, records, duplicates, scripts, and scene hash
fract_clone	Create a byte-identical managed copy with a provenance manifest
fract_patch_safe	Atomically edit existing detail_level, image_width, or image_height records
fract_validate	Verify trusted-template provenance and the conservative static preview subset
fract_render_preview	Render one bounded CPU/PNG still and verify signature, IHDR, dimensions, and hash

Animations, queues, netrender, GPU flags, runtime scripts, custom formula code, arbitrary parameter overrides, arbitrary scene paths, and final-resolution renders are not exposed.

Requirements

• Node.js 24.12.x (the repository includes .nvmrc for nvm-windows)
• Mandelbulber 2.34
• A read-only trusted template directory
• A separate writable work directory

The executable is administrator-configured; MCP clients cannot supply a command, path, argv, environment variable, or output destination.

Quick start

nvm use 24.12.0
npm ci
npm run check
npm run build

Create two disjoint directories, copy approved .fract templates into the template root, and configure the server:

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

node .\dist\src\index.js

The process uses stdio for MCP traffic. Keep stdout reserved for the protocol.

MCP client configuration

Build first, then add a stdio server entry to your MCP client. Use absolute paths:

{
  "mcpServers": {
    "mandelbulber2": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\path\\to\\mandelbulber2-mcp\\dist\\src\\index.js"],
      "env": {
        "MANDELBULBER_EXECUTABLE": "C:\\Program Files\\Mandelbulber2\\mandelbulber2.exe",
        "MANDELBULBER_EXECUTABLE_ROOT": "C:\\Program Files\\Mandelbulber2",
        "MANDELBULBER_EXECUTABLE_SHA256": "<lowercase sha256>",
        "MANDELBULBER_TEMPLATE_ROOT": "C:\\mandelbulber-mcp\\templates",
        "MANDELBULBER_WORK_ROOT": "C:\\mandelbulber-mcp\\work"
      }
    }
  }
}

Logical template paths start with templates/; managed scenes are returned as workspaces/<uuid>/<name>.fract. A normal client workflow is:

probe → inspect template → clone → patch with expected SHA-256 → validate → render preview

Safety limits

• Exact supported CLI version: 2.34
• Preview dimensions: 5–512 per side, at most 262,144 pixels
• Default preview: 320×240; format: PNG only
• One render at a time; fixed 120-second timeout
• Maximum scene size: 8 MiB; bounded stdout/stderr capture: 64 KiB each
• Managed clones only; expected-hash concurrency checks and replayable edit manifests
• No shell invocation; timeout/cancellation terminates the process tree

Mandelbulber 2.34 on Windows can still resolve known profile directories outside environment-variable overrides. For production isolation, run this server and Mandelbulber under a dedicated restricted Windows account and grant that account access only to the executable, trusted templates, and managed work root.

Project status

0.1.0 is a complete, deliberately narrow MVP. The automated suite covers contracts, filesystem boundaries, parser behavior, provenance replay, process timeout/capture, PNG verification, SDK tool registration, and the multi-tool MCP workflow. A gated integration test also exercises an installed Mandelbulber 2.34 executable.

The source investigation and architecture rationale live in docs/. Start with implementation-plan-2.34.md, 2.34-baseline.md, and security-model.md.