Material Maker MCP

Сервер MCP, который позволяет ИИ-ассистенту создавать графы узлов Material Maker по описанию на естественном языке, рендерить их в PBR-карты текстур в headless-режиме и возвращать редактируемые файлы .ptex, которые вы дорабатываете в приложении.

Вы описываете материал одним предложением. Ассистент составляет граф узлов, сервер проверяет его по собственному каталогу узлов Material Maker и рендерит его с помощью Godot, а вы получаете карты и редактируемый граф. Ассистент доводит вас почти до конца; остальное вы дорабатываете в Material Maker.

⚠️ Очень, очень, очень ранняя альфа. Прочтите сначала.

Я художник и аниматор в игровой индустрии, а не инженер-программист. Я не очень хорошо разбираюсь в коде. Этот проект был создан в основном ИИ-ассистентами под моим руководством и находится на крайне ранней, сырой, экспериментальной стадии.

Что это значит для вас:

• Ждите поломок. Шероховатости, острые углы, вещи, которые работают только на той единственной машине, на которой их создали. Проект проверен ровно на одной конфигурации (Windows, конкретная сборка Godot, конкретный checkout Material Maker).

• Никаких гарантий стабильности. Всё может измениться или сломаться между версиями. Тестовое покрытие ограничено небольшим набором smoke- и модульных тестов.

• Не готово к продакшену. Пожалуйста, не полагайтесь на это ни для чего важного. Делайте резервные копии. Считайте, что оно будет вести себя неправильно.

• Планка «качества» материала намеренно низкая. Цель — «довести вас до 80% пути, чтобы вы доделали в приложении», а не «фотореализм». Смотрите таблицу результатов в quality/, чтобы увидеть, насколько хорошо (и плохо) он справляется с 15 промптами: сейчас он проходит 11 из них по щедрому стандарту «на глаз художника».

Я делюсь этим открыто, потому что это забавный эксперимент, и кому-то он может пригодиться или захочется развить его, а не потому, что он отполирован. Отзывы, issue и исправления в духе «вы делаете это неправильно» от настоящих разработчиков очень приветствуются.

Related MCP server: Blender MCP

Галерея

Каждый из этих материалов создан сервером по однострочному промпту рядом с ним, а затем отрендерен в headless-режиме. Полные графы и превью — в examples/.

Как это работает

Графы Material Maker — это обычный JSON (.ptex), и Material Maker поставляется с режимом headless-экспорта через CLI. Этот сервер работает поверх существующего checkout Material Maker:

1. Сборщик каталога преобразует определения узлов Material Maker (addons/material_maker/nodes/*.mmg) в машиночитаемый каталог, на основе которого ассистент создаёт графы.

2. Ассистент составляет граф в виде .ptex-JSON. Сервер проверяет его по каталогу (возвращая ошибки как данные, чтобы ассистент мог исправиться самостоятельно), затем рендерит его, запуская режим --export-material Godot.

3. Отрендеренные карты возвращаются в виде файлов изображений (albedo, normal, roughness/metallic, height), а .ptex сохраняется, чтобы вы могли открыть его в Material Maker.

Требования

• Python 3.13+

• Godot 4.7.x (стандартный desktop-бинарник; на Windows сервер при наличии предпочитает соответствующую сборку _console.exe, чтобы захватывать логи рендера)

• Checkout проекта Material Maker на диске. Сервер читает определения узлов и встроенные примеры этого checkout и запускает его headless-экспорт. Клонируйте его с github.com/RodZill4/material-maker. Material Maker требуется файл steam_appid.txt (содержащий 4110830) в корне checkout, иначе при headless-рендере приложение перезапускается само и выходит; в апстрим-клоне он уже есть.

Установка

git clone https://github.com/graysonchalmers/Tool-MaterialMaker-MCP.git
cd Tool-MaterialMaker-MCP
python -m venv .venv
# Windows:  .\.venv\Scripts\activate
# macOS/Linux:  source .venv/bin/activate
pip install -e .

Затем скопируйте шаблон окружения и укажите в нём пути для вашей машины:

cp .env.example .env

Отредактируйте .env:

MM_GODOT_BINARY=/path/to/Godot_v4.7.x_console.exe
MM_PROJECT_PATH=/path/to/material-maker
MM_OUTPUT_DIR=/path/to/where/rendered/maps/should/go

Файл .env находится в .gitignore. Конфигурацию также можно передавать через переменные окружения MM_*, которые имеют приоритет над .env.

Проверка

Два smoke-скрипта подтверждают, что путь рендера работает от начала до конца:

# Render a bundled example headlessly and confirm PNGs appear
python smoke/smoke_mcp.py

На Windows также есть smoke-скрипт на PowerShell, который рендерит напрямую через Godot:

pwsh smoke/smoke.ps1

Запустите тестовый набор (единственный тест, запускающий Godot, помечен как integration):

pytest -q -m "not integration"   # fast unit + validation tests
pytest -q                        # everything, including a real render

Подключение к MCP-клиенту

Сервер общается по MCP через stdio. После pip install -e . он доступен в PATH как mm-mcp. Укажите клиенту эту команду, задав три переменные MM_*.

Пример для Claude Desktop / Claude Code (claude_desktop_config.json или эквивалентного MCP-конфига):

{
  "mcpServers": {
    "material-maker": {
      "command": "mm-mcp",
      "env": {
        "MM_GODOT_BINARY": "C:\\path\\to\\Godot_v4.7.1-stable_win64_console.exe",
        "MM_PROJECT_PATH": "C:\\path\\to\\material-maker",
        "MM_OUTPUT_DIR": "C:\\path\\to\\output"
      }
    }
  }
}

Если mm-mcp нет в PATH клиента, используйте Python из виртуального окружения: "command": "/abs/path/.venv/bin/python", "args": ["-m", "mm_mcp.server"].

Конфигурация проверяется при запуске, поэтому отсутствующая или неверная MM_GODOT_BINARY / MM_PROJECT_PATH приводит к быстрой ошибке с понятным сообщением, а не к сбою в середине рендера.

Инструменты

Сервер предоставляет семь инструментов и один ресурс:

Ресурс catalog://nodes предоставляет полный каталог узлов.

Заметки и подводные камни

Накоплено при отладке надёжного headless-рендера (всё проверено на конфигурации этого проекта):

• Используйте --export-material, а не --export. В Godot 4 флаг --export зарезервирован для собственного экспорта сборки; флаг приложения Material Maker — --export-material.

• На Windows используйте бинарник _console.exe, чтобы захватывать stdout; GUI-exe возвращает пустые логи.

• Не передавайте --headless; рендер текстур требует реального контекста отрисовки.

• Для checkout Material Maker нужен файл steam_appid.txt (4110830), иначе он перезапускается сам и сразу выходит.

• Узел normal_map — составной: его настоящие параметры — param0 (размер буфера), param1 (сила), param2, param4, а не amount/size.

Статус проекта

Очень ранняя альфа (см. предупреждение в начале). Фазы 0–3 моего чернового плана выполнены и проверены на одной машине. Журнал контрольных точек см. в STATUS.md, а план фаз — в docs/PLAN.md. Качество авторинга измеряется по замороженному набору из 15 тестовых случаев в quality/; текущая таблица результатов — 11/15 пригодных по стандарту «на глаз художника» (см. quality/scorecards/). «Проверено» здесь означает «работало, когда я запускал», а не «испытано в бою».

Лицензия и атрибуция

Этот проект распространяется под лицензией MIT (см. LICENSE).

Material Maker распространяется под лицензией MIT, Copyright (c) Rodolphe Suescun и участники проекта. Этот проект использует отдельный checkout Material Maker и не модифицирует и не распространяет его.