MaterialPilot

A native, local-first MCP bridge for editable procedural materials in Material Maker

MaterialPilot lets MCP-compatible AI agents inspect, create, organize, validate, preview, save, and export real Material Maker projects. It works through Material Maker's native graph and undo APIs, not UI coordinates, and keeps the procedural graph editable for artists.

The current 0.1.0 implementation preview exposes 143 typed MCP tools, a generated catalog of 392 Material Maker 1.7 node definitions, revision-safe graph transactions, deterministic validation, bounded rendering, named recovery snapshots, native undo/redo, and verified Blender-profile PBR export.

Important

MaterialPilot is a tested implementation preview, not the complete 1.0 described in the long-range production plan. Unsupported and higher-risk operations are capability-gated instead of being simulated. See Current limitations.

Why MaterialPilot?

Procedural material graphs are valuable because they remain editable, reusable, and parameterized. Conventional text-to-texture workflows often stop at flattened images, while general desktop automation cannot reliably understand graph ports, project revisions, renderer state, or undo history.

MaterialPilot gives agents structured access to the underlying creative system:

• Editable output: the primary artifact is a native .ptex graph, not only exported images.
• Native integration: graph operations use Material Maker and Godot APIs rather than mouse coordinates.
• Observation before mutation: agents inspect the project, revision, catalog, and capabilities before editing.
• Atomic changes: a graph patch either commits as one undo step or restores its exact pre-state.
• Deterministic safety: schemas, port compatibility, path policy, revisions, and validation are enforced outside the language model.
• Visual evidence: live node outputs and sphere/plane previews provide bounded PNG evidence.
• Verified delivery: Blender exports include dimensions, file sizes, and SHA-256 hashes.
• Local-first operation: native communication is authenticated and bound to loopback.

How it works

flowchart LR
    Host["MCP host<br/>Codex · IDE · CLI"]
    Server["MaterialPilot MCP server<br/>TypeScript"]
    Bridge["Native bridge<br/>GDScript"]
    Maker["Material Maker 1.7<br/>Godot 4.7"]
    Core["Domain services<br/>schemas · graph engine · validator · security"]

    Host <-->|"MCP over STDIO or authenticated HTTP"| Server
    Server <-->|"Authenticated loopback WebSocket JSON-RPC"| Bridge
    Bridge <-->|"Native graph, renderer, save, export, undo"| Maker
    Server --- Core

Loading

Material Maker writes an authenticated discovery record while the native bridge is running. The MCP server reads that record, negotiates available capabilities, and connects locally. If no live bridge is available, the server can fall back to an offline reference engine for catalog, planning, schema, and transaction work; live-only capabilities remain false.

Every native graph mutation follows the same boundary:

inspect revision -> validate patch -> snapshot -> apply operations
                 -> structural validation -> commit one undo entry
                 -> emit revision, diff, diagnostics, and evidence

failure at any point -> restore serialized snapshot -> return a structured error

For the design rationale, see the architecture overview and architecture decision records.

Capabilities

Area	Current support
Application	Health, status, version, capability, limit, and live/offline-mode discovery
Projects	List, inspect, create native material tabs, save .ptex, and create named recovery snapshots
Catalog	Search and inspect 392 generated Material Maker 1.7 node descriptors, ports, parameters, aliases, and compatibility
Graphs	Read canonical snapshots, plan patches, dry-run, apply atomically, diff, validate, undo, and redo
Editing	Create, delete, connect, disconnect, move, parameterize, batch-edit, comment, and expose remote controls
Layout	Semantic stages, comments, positions, selection, graph organization, and output-preserving repair workflows
PBR	Albedo, roughness, metallic, normal, height/depth, ambient occlusion, emission, and related output inspection
Preview	Bounded node-output PNGs and renderer-backed sphere/plane material previews
Export	Policy-constrained Blender-profile PNG/EXR maps with temporary publication and hash verification
Diagnostics	Deterministic validation, transaction history, performance inspection, structured errors, and correlation evidence
Workflows	Cracked stone, basalt, sandstone, lava, oxidized metal, and a complete abandoned-industrial-floor workflow

The authoritative schema and behavior for each tool are documented in the tool reference.

Safety model

MaterialPilot treats user projects, graph comments, downloaded metadata, file paths, and model output as untrusted data.

The default security controls include:

• loopback-only native and HTTP listeners;
• an ephemeral authenticated bridge token;
• workspace read, write, and export roots;
• canonical path checks and explicit overwrite policy;
• optimistic concurrency through expectedRevision;
• idempotency keys for mutations and exports;
• snapshot-first transactions and rollback;
• native undo/redo integration;
• renderer-dependent capability negotiation;
• custom shader writes and network operations disabled by default; and
• stderr-only diagnostics for the STDIO MCP server.

Choose the narrowest permission mode that fits the workflow:

Mode	Behavior
observe	Read-only inspection; mutations require an approval token
assisted	Default; protected writes require single-use approval
workspace-autonomous	Allows reversible graph editing inside approved workspace roots
developer	Broader local development access; custom code and network permissions remain separate

Read SECURITY.md and the threat model before enabling automation in a sensitive workspace.

Requirements

Component	Supported version	Purpose
Node.js	22.13.0 or newer	MCP server, CLI, packages, and tests
pnpm	11.9.0	Source builds and development
Material Maker	1.7	Live procedural material editing
Godot	4.7 stable	Running or exporting Material Maker from source
MCP host	Current compatible release	Codex Desktop, Codex CLI, an IDE, or another MCP client

The TypeScript workspace and CI target Windows, Linux, and macOS. The native compatibility suite is pinned to Material Maker 1.7 and Godot 4.7. Renderer-backed preview and export operations require a real Godot rendering device and are deliberately unavailable in headless sessions.

Quick start

1. Build MaterialPilot

git clone https://github.com/SS-360/materialpilot.git
cd materialpilot
corepack enable
corepack prepare pnpm@11.9.0 --activate
pnpm install --frozen-lockfile
pnpm build
pnpm check

Run the diagnostic CLI:

node packages/cli/dist/main.js doctor

2. Install the native addon

Close Material Maker before installing or updating the addon. Copy:

apps/material-maker-bridge/addon/materialpilot

into the Material Maker 1.7 source project as:

addons/materialpilot

For example, in PowerShell:

$materialPilot = 'D:\path\to\materialpilot'
$materialMaker = 'D:\path\to\material-maker-1.7'
$target = Join-Path $materialMaker 'addons\materialpilot'

New-Item -ItemType Directory -Force $target | Out-Null
Copy-Item -Path (Join-Path $materialPilot 'apps\material-maker-bridge\addon\materialpilot\*') `
  -Destination $target -Recurse -Force

Open the Material Maker project in Godot and enable MaterialPilot Native Bridge under Project → Project Settings → Plugins. The plugin installs this autoload:

[autoload]
MaterialPilotBridge="*res://addons/materialpilot/bridge/bridge_server.gd"

Launch Material Maker normally. While it is running, the default discovery record is:

• Windows: %USERPROFILE%\.materialpilot\bridge.json
• Linux/macOS: ~/.materialpilot/bridge.json

The record contains an ephemeral token. Do not publish, commit, or share it.

Verify the live bridge:

node packages/cli/dist/main.js bridge status

3. Connect an MCP client

STDIO is the recommended transport for one local client. Configure the client to launch Node with the absolute MCP server path:

node /absolute/path/to/materialpilot/apps/mcp-server/dist/main.js

For Codex CLI on Windows:

codex mcp add materialpilot `
  --env MATERIALPILOT_PERMISSION_MODE=workspace-autonomous `
  -- 'C:\Program Files\nodejs\node.exe' `
  'D:\absolute\path\to\materialpilot\apps\mcp-server\dist\main.js'

Or add a source checkout directly to ~/.codex/config.toml:

[mcp_servers.materialpilot]
enabled = true
command = 'C:\Program Files\nodejs\node.exe'
args = ['D:\absolute\path\to\materialpilot\apps\mcp-server\dist\main.js']
cwd = 'D:\absolute\path\to\materialpilot'
startup_timeout_sec = 10
tool_timeout_sec = 60

[mcp_servers.materialpilot.env]
MATERIALPILOT_PERMISSION_MODE = "workspace-autonomous"

Start Material Maker before the MCP client. If the client started first and entered offline mode, restart it after the bridge record appears.

For packaged releases, Linux/macOS configuration, authenticated HTTP transport, and runtime-path overrides, follow the complete installation and run guide.

Verify a live session

Ask the MCP host to inspect status before modifying anything:

Use MaterialPilot's app_get_status and app_get_capabilities tools. Report whether the native
Material Maker bridge is connected, whether offline mode is active, the Material Maker and Godot
versions, the active project ID, and whether graph.read, graph.write, graph.transactions,
preview.material3d, and export.write are available. Do not change the graph.

A renderer-backed live session should report values equivalent to:

{
  "bridgeConnected": true,
  "offlineMode": false,
  "materialMakerVersion": "1.7",
  "godotVersion": "4.7-stable"
}

If offlineMode is true, do not expect visible Material Maker changes. See Troubleshooting.

Example agent workflow

Using MaterialPilot, inspect the active Material Maker project and node catalog. Create an editable,
seamlessly tiling industrial floor with cracked concrete, exposed metal plates, rust, oil stains,
wetness, chipped edges, and dirt concentrated in cracks.

Create a named recovery snapshot. Organize the graph into labeled Sources, Masks, PBR Surface,
Albedo, Controls, and Output stages. Plan and dry-run the complete patch before applying it as one
revision-safe transaction. Expose artist controls for scale, crack density and depth, metal, rust,
oil, wetness, dirt, wear, and random seed. Run strict validation, render channel and sphere/plane
previews, then export verified Blender maps. Stop and report any unavailable capability or warning.

MaterialPilot will not infer visual success from graph validation alone. Renderer-backed previews and exported artifacts remain separate evidence.

Flagship production workflow

The repository includes a complete, executable Abandoned Industrial Floor workflow that exercises the production path end to end:

1. catalog inspection and structured planning;
2. named recovery snapshots;
3. dry-run and atomic graph patches;
4. semantic stages, comments, and exposed controls;
5. strict deterministic validation;
6. native editable .ptex save;
7. 2048 × 2048 Blender channel export;
8. sphere, plane, and channel previews;
9. three controlled variations;
10. dimensions, pixel variance, file size, and SHA-256 verification; and
11. a generated Markdown material guide and artifact manifest.

Start Material Maker with the bridge enabled, choose a new artifact directory, and run:

$env:MATERIALPILOT_ARTIFACT_ROOT = 'D:\exports\abandoned-industrial-floor-run-01'
node .\scripts\create-abandoned-industrial-floor.mjs

Artifact directories must be new. The workflow intentionally denies silent overwrites.

For a faster 512-resolution smoke run of the base material:

$env:MATERIALPILOT_SMOKE = '1'
$env:MATERIALPILOT_ARTIFACT_ROOT = 'D:\exports\abandoned-industrial-floor-smoke-01'
node .\scripts\create-abandoned-industrial-floor.mjs

Development and testing

Standard repository checks

pnpm format
pnpm typecheck
pnpm lint
pnpm test
pnpm build

The combined typecheck, lint, and unit/integration gate is:

pnpm check

The suite covers schemas, stable IDs, canonical hashing, catalog compatibility, deterministic diagnostics, transaction rollback, revision conflicts, idempotency, undo/redo, path policy, bridge handshake, PTEX/MMPP round trips, CLI behavior, and MCP conformance.

Godot bridge contract

Set GODOT_BIN to an official Godot 4.7 executable:

$env:GODOT_BIN = 'C:\path\to\Godot_v4.7-stable.exe'
pnpm test:godot

This validates GDScript parsing, authenticated bridge initialization, stable IDs, handshake, and status behavior.

Full Material Maker contract

Install the current addon into a Material Maker 1.7 source checkout, then run:

$env:GODOT_BIN = 'C:\path\to\Godot_v4.7-stable.exe'
$env:MATERIAL_MAKER_PROJECT = 'D:\path\to\material-maker-1.7'
pnpm test:material-maker

The headless contract verifies graph creation, native parameters, dry-run restoration, commit, undo, redo, save, and safe rejection of renderer-dependent operations.

Run the GPU-backed preview and export contract with:

$env:MATERIALPILOT_WINDOWED_TEST = '1'
pnpm test:material-maker

The windowed contract renders real node output, rejects empty or magenta missing-material previews, tests sphere and plane capture, and verifies Blender export. The test window is positioned off-screen.

To run every compatible contract available in the environment:

pnpm compatibility

See Building and testing for details.

Repository structure

materialpilot/
├── apps/
│   ├── mcp-server/              MCP transports, tool schemas, resources, and translation
│   └── material-maker-bridge/   Native Godot/Material Maker addon and contracts
├── packages/
│   ├── bridge-protocol/         Authenticated native JSON-RPC client and schemas
│   ├── cli/                     Doctor, bridge health, lint, and normalization commands
│   ├── domain/                  Stable public graph, patch, diagnostic, and capability model
│   ├── graph-engine/            Offline transactions, revisions, idempotency, undo, and redo
│   ├── mmpp/                    Material Maker painting-project adapter
│   ├── node-catalog/            Generated and stable node descriptors
│   ├── ptex/                    Procedural texture project parsing and round trips
│   ├── security/                Permission, audit, canonical path, and workspace policy
│   └── validator/               Deterministic structural and PBR validation
├── docs/                        Architecture, ADRs, guides, security, and tool reference
├── fixtures/                    Compatibility and serialization fixtures
├── schemas/                     Published JSON-compatible schemas
└── scripts/                     Compatibility, release, SBOM, and production workflows

Architecture boundaries are intentional:

• apps/mcp-server owns MCP transport and translation only.
• apps/material-maker-bridge owns Godot and Material Maker integration only.
• packages/domain never exposes Godot objects.
• packages/graph-engine owns transactions and revision semantics.
• packages/validator remains deterministic and LLM-independent.
• packages/security owns path and permission decisions.

Current limitations

The following capabilities are intentionally unavailable or incomplete in 0.1.0:

• native project open and close mutations;
• export profiles beyond Blender and engine-specific packaging;
• arbitrary panel capture, histogram automation, and automated perceptual comparison;
• asset-library installation and community network operations;
• arbitrary subgraph mutation and generated custom shader writes;
• painting mutations and automated strokes; and
• remote or multi-user deployment beyond authenticated loopback HTTP.

Painting data is inspection-only, and custom shader writes remain disabled. Renderer-backed features are unavailable under Godot's headless/dummy renderer. These are explicit capability results, not silent fallbacks.

See the implementation status and production implementation plan for the roadmap and stable 1.0 definition.

Built with Codex and GPT-5.6

Codex powered by GPT-5.6 was used as the primary engineering collaborator throughout MaterialPilot’s development.

It helped:

• design the MCP server and native Godot bridge architecture;
• implement typed tools, schemas, transactions, snapshots, and rollback;
• inspect and organize Material Maker procedural graphs;
• diagnose missing textures, bridge failures, and rendering problems;
• create deterministic validation and automated tests;
• build the Abandoned Industrial Floor demonstration workflow;
• verify Blender exports, previews, hashes, and generated artifacts;
• review the repository, documentation, security boundaries, and release readiness.

The human developer directed the product vision, made architectural and creative decisions, tested the integration inside Material Maker, reviewed generated changes, and validated the final user experience.

Codex was used as a collaborative engineering agent—not simply as a code generator. It inspected the existing system, proposed changes, edited the repository, ran tests, diagnosed failures, and iterated based on real application results.

Documentation

• Installation and run guide
• First material
• Troubleshooting
• Tool reference
• Implementation status
• Architecture overview
• Transaction model
• Material Maker 1.7 integration map
• Building and testing
• Security threat model

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, preserve the package boundaries above, and include tests and documentation with behavior changes.

Before opening a pull request:

pnpm install --frozen-lockfile
pnpm format
pnpm check
pnpm build

Native bridge changes must also pass pnpm test:godot and the affected Material Maker contract. Mutations require optimistic concurrency, an idempotency key, transaction/rollback support, a schema, documentation, tests, and a threat classification.

Security

Report vulnerabilities privately to the maintainers. Never attach private projects, bridge tokens, HTTP bearer tokens, exported proprietary textures, or logs containing sensitive paths to a public issue. See SECURITY.md for the supported disclosure process.

License

MaterialPilot is licensed under the Apache License 2.0. Material Maker remains an independent upstream project distributed under its own license; retain upstream notices when redistributing integrated builds.

Acknowledgements

MaterialPilot builds on Material Maker, Godot Engine, and the Model Context Protocol. The project is designed to complement Material Maker's artist-facing workflow while preserving editable graphs and human control.