MCP server reference

molen mcp starts a Model Context Protocol server over stdio that mirrors the CLI 1:1 — 45 tools over the same ops library, so an agent gets the identical behaviour with no shell parsing.

{
  "mcpServers": {
    "molen": { "command": "molen", "args": ["mcp"] }
  }
}

Discovery first

Call describe_op before guessing an I/O contract — it returns the entry below for any op at runtime, so an agent never has to read engine source.

Tools that return rendered PNGs as MCP image content (an agent can look at its own output): drive_scene, play_experience, screenshot_asset, worldgen_preview, figure_preview.

Validate and discover

Cheap, fast checks you run constantly. validate gives pinpointed, fixable errors; the rest let an agent learn the surface without reading source.

validate_asset

Validate a JSON asset against its schema (kind auto-detected from the envelope).

Field	Type	Required	Description
path	string	no	Path to a JSON document (or pass inline over MCP).
inline	object	no	Validate this inline document instead of reading a path (MCP).
kind	string	no	Force a schema kind; otherwise detected from "format".
projectPath	string	no	Project manifest for scene type references (default: discovered from the scene path).
verifyFiles	boolean	no	For terrain-package manifests, stream-check file containment, size, and SHA-256.
CLI equivalent: molen validate.

list_schemas

List all registered asset schema kinds.

No parameters. CLI equivalent: molen schema.

get_schema

Get a schema kind: JSON Schema + examples + docs reference.

Field	Type	Required	Description
kind	string	yes	Schema kind, e.g. scene, command, assert.
CLI equivalent: molen schema.

list_components

List the known component vocabulary (name, description, owning layer).

Field	Type	Required	Description
projectPath	string	no	Explicit project.json (default: walk up from cwd).
scenePath	string	no	A scene manifest whose custom components extend the vocabulary.
CLI equivalent: molen components.

get_component

Get one component schema + examples.

Field	Type	Required	Description
name	string	yes	Component name, e.g. transform, collider.
projectPath	string	no	Explicit project.json (default: walk up from cwd).
scenePath	string	no	A scene manifest whose custom components extend the vocabulary.
CLI equivalent: molen component.

describe_op

Machine-readable contracts for every molen operation (CLI + MCP).

Field	Type	Required	Description
name	string	no	Op/tool name or CLI fragment; omit for the full catalog.
CLI equivalent: molen describe.

search_docs

Lexical search over the shipped engine docs (docs-src bundle).

Field	Type	Required	Description
query	string	yes	Search terms.
k	int>0	no	Max results (default 5).
includeDesign	boolean	no	Also search the docs/ design plan (tagged).
CLI equivalent: molen docs.

Simulate and verify

The headless inner loop. Every run is deterministic, so a state hash is a meaningful regression signal and a replay mismatch localizes the diverging tick.

run_simulation

Run a scene headlessly for N ticks; returns tick, state hash, events, assertions.

Field	Type	Required	Description
scenePath	string	yes	Path to a scene manifest JSON.
ticks	int>0	yes	Number of ticks to simulate.
commandsPath	string	no	JSON array (or {commands:[...]}) of command envelopes.
assertPath	string	no	A molen/assert@1 document to evaluate after the run.
setupModule	string	no	ESM module exporting setup(world, manifest).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
CLI equivalent: molen sim.

run_replay

Replay a fixture and compare the state hash; localizes divergence on mismatch.

Field	Type	Required	Description
path	string	yes	Path to a *.replay.json fixture.
setupModule	string	no	ESM module exporting setup(world, manifest).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
record	boolean	no	Regenerate expected hashes from the current build.
CLI equivalent: molen replay.

diff_snapshots

Component-level diff between two keyframe JSON files.

Field	Type	Required	Description
a	string	yes	Before keyframe path.
b	string	yes	After keyframe path.
CLI equivalent: molen diff.

test_types

Smoke-test every registry type standalone: resolved shape validates, spawns, and survives N simulated ticks.

Field	Type	Required	Description
ticks	int>0	no	Ticks to simulate each type (default 30).
only	string[]	no	Restrict to these type ids.
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
CLI equivalent: molen types.

Render and play

Turn a scene into pixels without a browser — or drive a real built app with scripted input and collect screenshots and diagnostics.

screenshot_scene

Render one deterministic headless PNG of a scene; returns render stats.

Field	Type	Required	Description
scenePath	string	yes	Path to a scene manifest JSON.
outPath	string	yes	Output PNG path.
ticks	int>=0	no	Tick to simulate to before snapshotting (default 0).
setupModule	string	no	ESM module exporting setup(world, manifest).
camera	{position,lookAt}	no	Camera position and optional look-at target.
size	[w,h]	no	Image size (default 1280x720).
clearColor	string	no	Background colour (CSS/hex) instead of the scene default.
projectPath	string	no	Explicit project.json (default: walk up from cwd).
assetVariant	string	no	Render packed asset variants (e.g. "ktx2" from asset pack) where present.
terrain	{descriptorPath,heightmapPath}	no	Render a terrain descriptor + heightmap.
CLI equivalent: molen shot.

export_frames

Render a tick range to a PNG sequence, optionally following a camera track.

Field	Type	Required	Description
scenePath	string	yes	Scene manifest path.
outDir	string	yes	Output directory.
from	int>=0	yes	First tick.
to	int>=0	yes	Last tick.
step	int>0	no	Tick stride between frames (default 1).
setupModule	string	no	ESM module exporting setup(world, manifest).
trackPath	string	no	Camera track JSON followed across the range.
camera	{position,lookAt}	no	Fixed camera when no track is given.
size	[w,h]	no	Image size (default 1280x720).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
CLI equivalent: molen frames.

drive_scene

PLAY a scene deterministically: commands in at chosen ticks, screenshot frames out — a repeatable scenario the agent can look at.

Field	Type	Required	Description
scenePath	string	yes	Scene file path or project scene name.
actions	[{at, command?, screenshot?, camera?}]	yes	Tick-ordered actions: submit a command and/or capture a named frame.
until	int>=0	no	Step to this tick after the last action.
assertPath	string	no	molen/assert@1 doc evaluated at the end.
setupModule	string	no	ESM module exporting setup(world, manifest).
size	[w,h]	no	Frame size (default 1280x720).
outDir	string	no	Output directory for the frames (MCP returns them as images).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
CLI equivalent: molen drive.

play_experience

PLAY a built browser experience: timed inputs in, screenshots/probes/diagnostics out.

Field	Type	Required	Description
appDir	string	yes	Built browser app directory containing index.html.
scenario	molen/experience-play@1	yes	Declarative waits, keyboard input, drags, UI actions, probes, and screenshots.
outDir	string	no	Output directory for frames and experience-run.json (MCP uses a temp dir).
CLI equivalent: molen play.

screenshot_asset

Render an imported asset from N turntable angles (framed from its sidecar bounds).

Field	Type	Required	Description
ref	string	yes	Project asset id or sidecar path.
angles	int>0	no	Turntable angle count (default 4).
size	[w,h]	no	Frame size (default 1280x720).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
clip	string	no	Pose this animation clip.
clipTime	number>=0	no	Clip time in seconds (default 0).
assetVariant	string	no	Render this packed variant (e.g. "ktx2") instead of the canonical GLB.
CLI equivalent: molen asset.

Projects and types

Scaffold an experience (the starter, or a copy of a shipped sample) and manage the namespaced entity type registry.

new_experience

Scaffold a new experience (scene + scripts + commands + checks + AGENTS.md) ready for the loop, or a standalone copy of a shipped sample with --template.

Field	Type	Required	Description
name	string	yes	Experience name (also the output folder name).
template	string	no	Copy this sample instead of the built-in starter (list_templates / molen templates lists the ids).
dir	string	no	Parent directory (default: cwd).
force	boolean	no	Replace existing scaffold-owned files (default false).
CLI equivalent: molen new.

list_templates

List the sample templates new_experience can copy (id + one-line description); each scaffolds as a standalone npm project.

No parameters. CLI equivalent: molen templates.

get_project

Show the surrounding project.json: scenes, types, assets, reservations.

Field	Type	Required	Description
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
CLI equivalent: molen project.

list_types

List the entity types registered in the project type registry.

Field	Type	Required	Description
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
CLI equivalent: molen types.

check_types

Validate the type registry: duplicates, cycles, namespace ownership, asset refs, codegen staleness.

Field	Type	Required	Description
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
CLI equivalent: molen types.

reserve_type

Reserve a type/asset id namespace for an owner (multi-agent vocabulary partitioning).

Field	Type	Required	Description
namespace	string	yes	Dotted namespace, e.g. "train".
owner	string	yes	Owner identity, e.g. "agent:layout".
note	string	no	Free-form note recorded with the reservation.
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
CLI equivalent: molen types.

generate_types

Generate (or verify) the typed component/type-id module plus the ambient types beside each scripts directory.

Field	Type	Required	Description
check	boolean	no	Compare only; fail when a committed artifact is stale.
out	string	no	Output path override (default: project codegen.out).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
CLI equivalent: molen types.

Assets

Import glTF/GLB, inspect what was imported, and stage runtime bundles for the browser.

import_asset

Import a glTF/GLB: normalize, extract bounds + collision (hulls/trimesh), write the asset sidecar, register in project.json.

Field	Type	Required	Description
path	string	yes	Source .glb/.gltf file.
id	string	no	Asset id (default: slugged filename; dotted ids join a namespace).
trimesh	boolean	no	Also extract a whole-asset collision trimesh (collision.bin).
optimize	boolean	no	Normalize pass dedup/prune/weld/quantize (default true).
outDir	string	no	Assets root override; retains root/id layout. Mutually exclusive with assetDir.
assetDir	string	no	Exact bundle directory, relative to cwd. Mutually exclusive with outDir. Omit both to preserve an existing project asset directory.
projectPath	string	no	project.json to register into. Required when the source file sits in a different project than the cwd.
cwd	string	no	Directory to discover the project from (default: process.cwd()).
force	boolean	no	Replace an existing asset directory (default false).
CLI equivalent: molen asset.

inspect_asset

Read + validate an asset sidecar (by path or project asset id); --verify re-hashes files.

Field	Type	Required	Description
ref	string	yes	Sidecar path or registered asset id.
verify	boolean	no	Re-hash model.glb / collision.bin against the sidecar.
projectPath	string	no	Explicit project.json (default: walk up from cwd).
CLI equivalent: molen asset.

list_assets

List the assets registered in the surrounding project.

Field	Type	Required	Description
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
CLI equivalent: molen asset.

pack_asset

Derive a RUNTIME GLB variant: textures re-encoded as KTX2 (Basis) with mipmaps, power-of-two sized, so the GPU gets ASTC/BC7 instead of RGBA8 (4-8x less texture memory). Recorded as files.variants.<variant>.

Field	Type	Required	Description
ref	string	no	Project asset id or sidecar path (or pass all: true).
all	boolean	no	Pack every asset registered in the project.
variant	string	no	Variant name / file suffix (default "ktx2").
mode	`auto	etc1s	uastc`
maxSize	int>=4	no	Longest texture side after resizing (default 2048).
powerOfTwo	boolean	no	Snap sides to a power of two (default true).
etc1sQuality	int 1..255	no	ETC1S quality (default 128).
uastcQuality	int 0..4	no	UASTC pack quality (default 2).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
CLI equivalent: molen asset.

stage_assets

Copy registered assets' runtime files (packed variant when requested) into a browser-servable directory and write assets.index.json (id -> URL). Fails on stale assets.

Field	Type	Required	Description
outDir	string	yes	Output directory (created).
variant	string	no	Stage this packed variant instead of the main GLB.
requireVariant	boolean	no	Fail when an asset lacks the variant (default: warn).
clean	boolean	no	Remove a previous staging output first (default false).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
CLI equivalent: molen asset.

Audio

Hear what a scene would play without a browser, and build sound banks with provenance.

plan_audio

Run a scene headlessly and list the sounds it would play: looping voices with start/stop ticks, peak gain and pitch range, one-shots by tick, audio.* script events, and unknown sound ids or signals. Hear a scene's audio annotations without a browser.

Field	Type	Required	Description
scenePath	string	yes	Scene file path or project scene name.
ticks	int>0	yes	Ticks to simulate.
bankPaths	string[]	no	molen/soundbank@1 files (default: every provides.soundbank in the project's packs).
commandsPath	string	no	JSON array (or {commands:[...]}) of command envelopes.
setupModule	string	no	ESM module exporting setup(world, manifest).
listener	string	no	Entity whose transform is the listener (default: the scene camera).
mode	string	no	listener.mode for rules: walk, drive, fly…
weather	string	no	Weather profile: sunny, partly-cloudy, overcast, rain, snow, fog.
daylight	number	no	sky.daylight 0 (night) – 1 (day); default 1.
projectPath	string	no	Explicit project.json (default: walk up from cwd).
CLI equivalent: molen audio.

import_sound

Add an audio clip to a molen/soundbank@1 file: copy it beside the bank, hash it, probe its duration, and record license and provenance. --append adds a variation to an existing sound.

Field	Type	Required	Description
file	string	yes	Audio file (MP3 recommended; WAV and Ogg accepted).
id	string	yes	Sound id, e.g. "ambience.rain.medium".
bankPath	string	yes	Sound bank JSON to update (created when missing).
license	string	yes	SPDX license of the recording, e.g. "CC0-1.0".
source	string	no	Page of the original recording.
site	string	no	Origin site: freesound, kenney, opengameart, …
author	string	no	Recordist or creator.
prompt	string	no	Generation prompt, for generated clips.
generator	string	no	Generator/model name, for generated clips.
description	string	no	What it sounds like (agents choose sounds by it).
loop	boolean	no	Loop the clip (ambience, engines).
loopStart	number	no	Loop start in seconds.
loopEnd	number	no	Loop end in seconds.
bus	string	no	Default bus: music, ambience, sfx, ui, voice.
gain	number	no	Base gain (default 1).
durationS	number	no	Duration in seconds; overrides the probed value.
append	boolean	no	Add as another variation of an existing sound.
copyTo	string	no	Directory under the bank for copied files (default audio).
CLI equivalent: molen audio.

check_soundbank

Check a molen/soundbank@1 file and every clip it names: files present, hashes unchanged, durations and loop points consistent, provenance recorded; prints a license summary.

Field	Type	Required	Description
bankPath	string	yes	Sound bank JSON.
CLI equivalent: molen audio.

Materials and textures

Bake procedural material graphs and round-trip hand-painted UV templates.

rasterize_material

Bake a material graph / palette ref to a PNG texture.

Field	Type	Required	Description
path	string	no	Material graph JSON path.
inline	object	no	An inline molen/matgraph@1 document (MCP).
ref	string	no	A material ref, e.g. palette:#rrggbb.
outPath	string	yes	Output PNG path.
CLI equivalent: molen material.

apply_uv_paint

Import a painted UV template: mask to the island map and dilate the gutters.

Field	Type	Required	Description
paintedPath	string	yes	Painted texture (from an image model).
islandMapPath	string	yes	Island map (flat-filled islands on a dark background).
outPath	string	yes	Output PNG path.
maskToIslands	boolean	no	Mask paint to the islands (default true).
dilationPx	int>=0	no	Gutter dilation in pixels.
CLI equivalent: molen uvpaint.

Worldgen

Outlines and labeled polygons into styled buildings and deterministic props.

worldgen_preview

Generate buildings from a style pack in Node and render them headlessly (turntable PNGs). Default batch: one building of every footprint class.

Field	Type	Required	Description
stylePath	string	no	A standalone molen/archstyle@1 document to preview.
packPath	string	no	Style pack: a stylepack.json or its directory, or a content pack file, URL or source directory (default: the project's content packs).
styleId	string	no	Force every building onto this style id.
batchPath	string	no	A molen/worldgen-batch@1 document (default: the lineup).
scatterId	string	no	Scatter rule set for the batch scatter request.
ground	`'flat'	'slope'`	no
angles	int>0	no	Turntable angles (default 1).
size	[w,h]	no	Viewport in pixels (default 1280x720).
outPath	string	no	PNG path (CLI: --out); MCP returns the images directly.
CLI equivalent: molen worldgen.

worldgen_bake

Generate buildings from a batch document or one outline and bake them to a glTF asset with a molen/asset@1 sidecar.

Field	Type	Required	Description
batchPath	string	no	A molen/worldgen-batch@1 document.
outline	string	no	One building outline "x,z;x,z;..." in meters (with styleId).
styleId	string	no	Style id for the outline, or forced onto every building.
packPath	string	no	Style pack: a stylepack.json or its directory, or a content pack file, URL or source directory (default: the project's content packs).
outDir	string	yes	Assets root; the asset lands in <outDir>/<id>/.
id	string	no	Asset id (default: the batch name).
ground	`'flat'	'slope'`	no
projectPath	string	no	Explicit project.json (default: walk up from cwd).
force	boolean	no	Replace an existing asset directory.
CLI equivalent: molen worldgen.

worldgen_stats

Generate one real terrain-package tile in Node and report counts, histograms, sizes, timings, and determinism; optionally dump the adapted batch.

Field	Type	Required	Description
packagePath	string	yes	terrain-package.json path.
tile	string	no	"z/x/y" tile address (default: the package center).
auto	boolean	no	Search the tiles around the center for the most buildings.
packPath	string	no	Style pack: a stylepack.json or its directory, or a content pack file, URL or source directory (default: the project's content packs).
atlasPath	string	no	Region atlas: a world.atlas.json, or a content pack that provides one (default: the project's content packs).
styleId	string	no	Force every building onto this style id.
quality	`'economy'	'balanced'	'high'`
dumpPath	string	no	Write the adapted molen/worldgen-batch@1 here.
CLI equivalent: molen worldgen.

Ambient life

Bake real road, rail and path networks so NPC traffic can run in any scene.

network_bake

Bake the roads, railways and paths of a local terrain package into a molen/transport-network@1 document for ambient traffic in scenes without map tiles.

Field	Type	Required	Description
packagePath	string	yes	terrain-package.json path (local PMTiles archives).
tile	string	no	Centre tile "z/x/y" at the finest features level.
radius	number	no	Tiles around the centre tile to include (default 0).
bbox	number[4]	no	Area [west, south, east, north] in degrees, instead of tile.
classes	string[]	no	Classes to keep: 'road', 'rail', 'path' (default all).
outPath	string	yes	Write the transport-network document here.
heights	boolean	no	Include surface heights from the elevation (default flat).
CLI equivalent: molen network.

Figures

Stylized humans, bipeds and quadrupeds: presets, descriptors, rigs and gaits.

figure_preview

Render figure presets, a molen/figure@1 descriptor, or a built-in lineup headlessly from turntable angles or the art-review view set (PNGs).

Field	Type	Required	Description
preset	`string	string[]`	no
descriptorPath	string	no	A molen/figure@1 document to render.
descriptor	object	no	An inline descriptor (the figure component shape).
lineup	`'humans'	'bodies'	'species'
mode	`'idle'	'walk'	'run'
tick	int>=0	no	Simulation tick to pose at (default 15).
tier	`0	1	2`
angles	`int>0	'review'`	no
size	[w,h]	no	Viewport in pixels (default 1280x720).
outPath	string	no	PNG path (CLI: --out); MCP returns the images directly.
CLI equivalent: molen figure.

list_figure_presets

List the shipped figure presets with their resolved descriptors.

Field	Type	Required	Description
archetype	`'biped'	'quadruped'`	no
CLI equivalent: molen figure.

Other operations

Added since this page was last curated.

build_pack

Build a content pack (molen/pack@1 zip) from a source directory holding molen-pack.source.json. Writes <id>-<hash>.zip and updates index.json in outDir.

Field	Type	Required	Description
sourceDir	string	yes	Pack source directory (holds molen-pack.source.json).
outDir	string	yes	Output directory for the pack file and index.json.
solid	boolean	no	Group small text files into compressed solid blocks (default: the source's setting).
CLI equivalent: molen pack.

inspect_pack

Summarize a content pack: id, version, contentHash, sizes, solid blocks, asset ids, roles and the largest files.

Field	Type	Required	Description
source	string	yes	Built pack file, pack source directory, or http(s) URL.
CLI equivalent: molen pack.

verify_pack

Read every file of a content pack checking CRC and sha256, validate each JSON document against its registered schema, and check asset sidecar hashes against their models.

Field	Type	Required	Description
source	string	yes	Built pack file, pack source directory, or http(s) URL.
CLI equivalent: molen pack.

extract_pack

Write every file of a content pack into a directory, with a molen-pack.source.json that builds it back to the same content.

Field	Type	Required	Description
source	string	yes	Built pack file or http(s) URL.
outDir	string	yes	Directory to write the files into.
CLI equivalent: molen pack.

fetch_pack

Download content packs (a pack URL, or a molen/pack-index@1 URL) into the project, list them in index.json in the download directory (so a page can open them), and pin them in project.json packs with their contentHash, so the project runs offline.

Field	Type	Required	Description
url	string	yes	URL of a pack file, or of a pack index.
ids	string[]	no	With an index URL, fetch only these pack ids (default: all).
outDir	string	no	Download directory (default: packs/ beside project.json).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
CLI equivalent: molen pack.

check_scripts

Type-check the scene's scripts against their generated declarations: component typos, bad command payloads, unguarded reads.

Field	Type	Required	Description
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
CLI equivalent: molen scripts.