# Mandelbulber MCP

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

![Version](https://img.shields.io/badge/version-0.11.0-2f81f7)
![Node](https://img.shields.io/badge/Node.js-24.12-5fa04e)
![Mandelbulber](https://img.shields.io/badge/Mandelbulber-2.34-e67e22)
![Transport](https://img.shields.io/badge/MCP-stdio-6f42c1)
![Tests](https://img.shields.io/badge/tests-107-success)

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.

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

```powershell
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

```powershell
$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:

```text
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:

```powershell
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](docs/implementation-plan.md)
- [Operator setup](docs/operator-guide.md)
- [Tool and resource reference](docs/tool-reference.md)
- [Compatibility matrix](docs/compatibility.md)
- [Security model](docs/security-model.md)
- [Runtime test matrix](docs/unresolved-tests.md)
- [Exact 2.34 adapter history](docs/implementation-plan-2.34.md)

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.