Replace the legacy Rust procedural library with clean-room native primitives, typed function execution and FX-Map graphs. Save supported content as native SBS and organize the model, evaluators, codecs and editors into focused modules. Add shared graph editing behavior, flat filtered node menus, frame and comment editing, named Explorer outputs and an original atomic sample. Document the tested scope and remaining interoperability work.
11 KiB
Control protocol and MCP
Last reviewed: 2026-11-02 · Last updated: 2026-11-02 · Change: minor (portable materials for TextureCraft) · Target: the professional node-based material workflow
Agents drive MaterialCraft three ways, all dispatching the same engine commands:
- MCP (
materialcraft-cli mcp): headless (an in-process session, files only below--read-root/--write-root) or bridged to the running app (--bridge <port>). - JSON lines (
materialcraft-cli serve): the same methods on stdio, or on127.0.0.1:<port>behind a token. - The app's control channel (
materialcraft --control <port>): one JSON request per line,{"id", "method", "params"}→{"id", "ok": true, "result"}or{"id", "ok": false, "error"}. The first request must be{"method":"auth","params":{"token":"…"}}with the token fromMATERIALCRAFT_CONTROL_TOKEN(16 to 1024 printable ASCII characters) or the file<temp>/materialcraft-control-<port>.token, a fresh random 256-bit token written after the port is bound. On Unix the file is created new with mode 0600 (owner only); if an existing file there cannot be replaced, the control server stays off andMATERIALCRAFT_CONTROL_TOKENis the alternative. Clients (materialcraft-cli mcp --bridge) refuse a token file that is a symlink, not a regular file, not owned by them, or accessible to group or others. A connection gets one authentication attempt, within 10 s; a wrong token, any other first request or malformed JSON closes it. At most 16 connections are served at once. Whoever holds the token has full engine-command authority, including host file access. SetMATERIALCRAFT_NO_PREFS=1for scripted runs so the user's layout is left alone.
Methods
| Method | Where | What |
|---|---|---|
ping |
all | "pong" |
command.list {filter?} |
all | every command: id, label, menu, shortcut, params doc, enabled |
command.run {id, params?} |
all | run one command (programmatic: never opens a dialog) |
command.batch {steps} |
headless | run [{id, params}] in order, stop at the first error |
session.inspect |
all | package, graphs, the open graph's nodes (def, params, bindings, base, ports, cook error/size/mean/ms), wires, frames, comments, pins, exposed inputs, views, history |
package.open {path} / package.save {path?} |
headless | workspace-scoped package I/O |
bitmap.import {path, name?} |
headless | embed an image as a resource |
outputs.export {dir, format?, pattern?, depth?, size?, graph?} |
headless | cook at full size and write every output |
render {view?, width?, height?, yaw?, pitch?, scene?, node?, port?, full?, tiling?, hq?, displacement?} |
headless | PNG (base64) of the 3D view or of one node; hq is the beauty render (displaced mesh, ray-traced AO, shadowed key light, 3×3 supersampling), displacement its depth in scene radii |
ui.inspect |
app | UI state, the graph view rectangle, every node's screen rectangle, every port's identifier, display label and screen position, fps, toasts |
ui.menu.list / ui.menu.invoke {id} |
app | the menu catalog; behave like a click |
ui.set {...} |
app | merge fields into the UI state |
ui.input {events} |
app | synthetic input, below |
view.screenshot {view?: "3d"|"2d"} |
app | PNG of the 3D or 2D view |
ui.screenshot |
app | PNG of the whole window |
ui.resize {width, height} |
app | window size in points |
Synthetic input (ui.input)
Events are applied one frame at a time, so egui sees real presses, drags and releases. Positions are
window points (take them from ui.inspect's nodes and ports).
{"method": "ui.input", "params": {"events": [
{"type": "drag", "from": [512, 140], "to": [600, 220], "steps": 12},
{"type": "click", "pos": [700, 300], "button": "left", "modifiers": ["ctrl"]},
{"type": "doubleClick", "pos": [640, 180]},
{"type": "scroll", "pos": [640, 300], "delta": [0, -120]},
{"type": "key", "key": "Space"},
{"type": "text", "text": "perlin"},
{"type": "key", "key": "Enter"}
]}}
Types: move, down, up, click, doubleClick, drag, scroll, key (egui key names:
A, Enter, Space, Delete, F5, …), text. Buttons: left, right, middle.
Key commands
| Command | Params |
|---|---|
file.new |
{template?, name?, size?}; templates from graph.templates (empty, pbr, bricks, stone_tiles, wood, rusty_metal, fabric, ground) |
graph.node.edit |
{} resolves the selected FX-Map to {node, parameter}; use ui.menu.invoke to enter its subgraph in the graph panel |
graph.pattern.set |
{id, pattern} replaces an FX-Map subgraph with cycle validation and undo |
graph.node.add |
{def, at?, params?, connectFrom?: {node, port?}, label?} |
graph.connect / graph.disconnect |
{from, fromPort?, to, toPort?} / {to, toPort} |
graph.wire.insertDot |
{to, toPort, at?}: split the wire feeding to.toPort with a reroute Dot node at at (graph point, default midway), selected |
graph.wire.swap / graph.wire.delete |
{wires: [{to, toPort}, ...]}: swap (two) or reverse (more, in input order) where the wires come from / delete them, one undo step each |
graph.node.param |
{id?, param, value}: numbers, [x, y], "#rrggbb", enum index, curve [[x, y], …], gradient [[pos, color], …], or a typed value {"t": "function", "v": {...}} |
graph.node.base |
{id?, sizeMode?, size?, format?, seed?, tiling?} |
graph.exposed.add / graph.exposed.set |
{id, label?, default?, bind?: {node, param}} / {id, value} |
graph.node.function |
{id?, param, function} drives a parameter by a function graph of the graph's inputs (dynamic parameter); {id?, param, remove: true} removes it |
graph.preset.save / .apply / .delete |
{name}: store, restore or remove the current input values |
graph.createFromSelection |
{name?, ids?}: move nodes into a sub-graph and replace them with an instance |
view.2d / view.3d |
which node the 2D view shows, channel, tiling, histogram; scene, environment, camera, tiling, parallax depth, transparency (see through where the alpha is below one: the opacity output, else the base color's alpha), alphaView (show the alpha channel) |
view.3d.loadMesh |
{path} shows an OBJ, glTF or GLB mesh (scene custom) |
library.list |
{filter?, category?}: every node with ports and parameters |
Function graphs
file.new {"kind": "function", "name": "Calculation"} creates a standalone Function Graph.
Omit kind, or use "material", for a Graph. graph.function.set {"function": {...}} replaces
the active standalone function through one validated, undoable command.
A function has nodes and an optional output node id. Each node has id, native op,
inputs (source ids or null for unwired ports), optional value, type_code and pos.
For example, const_float1 supplies a scalar and mul multiplies its a and b inputs.
The catalog in crates/nodes/src/function/catalog.rs defines all native operation and port ids.
Processors and dynamic parameters use the same function representation. Graph validation and
execution use bounded iterative traversal and reject cycles.
graph.annotation.select {"kind": "frame"|"comment", "id": ...} selects an annotation.
graph.frame.edit accepts title, titleVisible, description, color and rect.
graph.frame.move {"id": ..., "by": [dx, dy], "snapToGrid": true} moves enclosed nodes,
comments, nested frames and pins together. graph.comment.edit accepts text, at and size.
session.inspect includes annotation selection and the standalone function; ui.inspect
includes frame and comment rectangles for synthetic input.
Portable materials (TextureCraft)
A .mcmat portable material is a zip: material.json (manifest), maps/<usage>.png and
source.sbs (the package). TextureCraft applies it as a fill layer and keeps the exposed inputs
editable, re-cooking through materialcraft-cli. The format is a convention the two apps share;
each has its own reader and writer (crates/formats/src/material.rs here), so keep them in step.
{ "format": "craft-material", "version": 2, "name": "Brick wall", "graph": "Brick_wall", "size": [2048, 2048],
"maps": [{"usage": "baseColor", "file": "maps/baseColor.png", "colorSpace": "srgb"}],
"parameters": [{"id": "wear", "label": "Wear", "default": {"t": "float", "v": 0.5}, "min": 0, "max": 1,
"value": {"t": "float", "v": 0.8}}],
"inputs": [{"identifier": "curvature", "kind": "gray"}],
"presets": [{"name": "Worn", "values": {"wear": {"t": "float", "v": 1.0}}}],
"source": "source.sbs" }
- Usages:
baseColor,normal,roughness,metallic,height,ambientOcclusion,emissive,opacity,specular(the first output of each). Color usages (baseColor,emissive,specular) are 8-bit sRGB PNGs, the rest 16-bit linear. Normals are tangent space, OpenGL (Y+); height is 0..1 with 0.5 at the surface. - Parameters are the exposed inputs other apps can set (float, float2-4, int, int2, bool, color,
enum), values in the typed form
{"t", "v"}; colors are linear RGBA. - Inputs are the graph's input nodes. Mesh maps feed them by identifier:
ambientOcclusion,curvature,thickness,position,worldNormal,normal,height,id,bentNormal,opacity,colorMap,worldDirection. - Readers ignore unknown fields and require manifest
version2.
| Command | Params |
|---|---|
file.exportMaterial |
{path, graph?, size? (px), values? {input: value}, inputs? {identifier: image path}}: cook and write a .mcmat. TextureCraft runs materialcraft-cli run source.sbs file.exportMaterial {...} to re-cook at its texture set's resolution with its own values and baked mesh maps |
file.sendToTextureCraft |
{graph?}: export into TextureCraft's library folder (Documents/TextureCraft/library), where its shelf lists it |
graph.input.bind / graph.input.unbind |
{identifier, resource? | path?} / {identifier}: a preview image for an input node (a mesh map exported from TextureCraft), saved in the package |
file.open |
opens native .sbs packages, and a .mcmat's source package, on its graph, with no file name. Returns warnings: what an SBS file holds that MaterialCraft can't read yet (missing nodes are kept as placeholders); also in session.inspect as package.warnings |
file.save |
{path?}: native SBS; .sbs is appended when the path does not end in .sbs |
MCP tools
session_inspect, command_list, command_run, command_batch, library_list, graph_new,
node_add, node_connect, node_param, package_open, package_save, bitmap_import,
outputs_export, view_render (headless) and, bridged to the app, view_screenshot,
ui_screenshot, ui_inspect, ui_menu_invoke, ui_input. package_open opens .mcmat files
too; exporting one is CLI-only for now (the workspace sandbox refuses file.* commands).
While an FX-Map subgraph is open, ui.inspect.subgraph identifies its owner and selection. Canvas
node IDs and ports refer to that embedded graph. ui.menu.invoke with ui.graph.parent returns
to the parent canvas.