Material Workbench

Material Workbench

Recipe-driven, deterministic procedural materials and isometric terrain tiles for game engines — a Python engine, a desktop app, and an MCP server, all rendering from the same JSON recipe.

[](LICENSE) [](pyproject.toml) [](https://github.com/hoklims/material-workbench/actions/workflows/ci.yml)

---

A recipe is a small JSON document — an archetype plus a handful of parameters and a seed. Feed it to the engine and you get back textures: PBR map sets for 3D engines (Unreal/Godot/Unity), or hand-painted-looking isometric ground tiles for 2D/iso games. Same recipe, same seed, same bytes — every time. The render is content-addressed and cached by a hash of the recipe, so nothing is recomputed twice.

What you get

• Two archetypes today
• metal_rust — procedural rusted metal: 5 PBR maps (base color, normal, roughness, metallic, AO), tileable.
• painted_grass — Dofus-style painted terrain: a mottled green wash, grass tufts, and scattered blossoms, projected to a 2:1 isometric diamond with a transparent surround.
• Three ways to drive it
• CLI — material-workbench render recipe.json --out ./out writes the PBR maps to disk.
• Desktop app (Tauri + React + Three.js) — pick a preset, tweak sliders, preview in 3D (materials) or as an iso tile (terrain), and export.
• MCP server — expose the workbench as tools to an MCP-capable agent over stdio.
• Cached — every recipe carries a render_hash; identical recipes hit the cache instead of re-rendering.
• Adding an archetype is one registry entry plus a render function — no central refactor.

| Painted grass → iso tile | Rusted metal base color | | --- | --- | | | |

Prerequisites

The Python engine is cross-platform. The desktop app targets Windows 11 today (the Rust toolchain is pinned to stable-x86_64-pc-windows-msvc); the sidecar has a POSIX fallback but the Tauri shell is not yet wired/tested for macOS/Linux.

| Tool | Version | Needed for | | --- | --- | --- | | uv | latest | Python env + commands | | Python | 3.12 (>=3.12, **Order matters.** The Rust shell launches the Python engine as a sidecar by locating .venv/Scripts/python.exe (walking up from the binary). Run uv sync at the repo root **before** starting the app, or set PYTHONBIN` to a Python with the package installed.

uv sync                            # 1. create the .venv the app will find
cd tauri
npm install                        # 2. frontend deps
npm run tauri dev                  # 3. build the Rust shell + launch

Pick a preset (Prairie, Prairie fleurie, Herbe rase, or the metal_rust presets), hit Render (force), change the seed for variations, then Export tuile iso… to write a transparent 2:1 diamond PNG (terrain) — or Export to UE5… to write the BC/N/ORM PBR set (materials).

To build a distributable bundle: npm run tauri build.

MCP server

uv run material-workbench serve-mcp     # FastMCP over stdio

Register it with any MCP client (the tool surface mirrors the service: archetypes, recipes, render, cache).

How it works

recipe.json ──► normalize + validate ──► engine (numpy/PIL) ──► PBR maps ──► cache (by render_hash)
                                                                   │
                          ┌────────────────────────────────────────┼─────────────────────────┐
                        CLI                          JSON-RPC sidecar (Tauri app)        MCP server
                   (write maps)                  (render, iso-tile export, recipes)      (agent tools)

The engine is pure numpy + Pillow (no GPU, no external services). Transport adapters (CLI, JSON-RPC, MCP) are thin wrappers around a single MaterialWorkbenchService. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full layering.

Project layout

src/material_workbench/   Python engine, IR, cache, adapters (CLI / JSON-RPC / MCP)
tauri/                    Desktop app (React + Three.js frontend, Rust shell)
examples/                 Sample recipes
tests/                    pytest suite (engine, services, adapters)
tools/                    Calibration & snapshot scripts (dev only)
docs/                     Architecture & assets

Contributing

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, test/lint commands, and pull-request flow. By participating you agree to the [Code of Conduct](CODEOFCONDUCT.md).

License

[MIT](LICENSE) © 2026 hoklims

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hoklims
• Source: hoklims/material-workbench
• License: MIT

Install and usage instructions live in the source repository linked above.