fvtt-mcp-artificer

Сервер Model Context Protocol для генерации изображений, специфичный для Foundry, для артов настольных D&D, управляемый Claude Code. Он оборачивает headless-инстанс ComfyUI на локальной машине и предоставляет небольшой набор инструментов, заточенных под Foundry, чтобы Claude мог составлять промпты, генерировать пакеты иллюстраций, курировать результаты, буквально глядя на них, и передавать победителей в конвейер Foundry через соседний сервер fvtt-mcp-molten5e (upload-asset → set-actor-art / add-journal-image / фоновые изображения сцен).

Весь цикл достаточно быстр для диалогового режима на целевом оборудовании (RTX 5090): пакет из 6 черновых изображений готов за ~10 с, готовый рендер 2560×1600 — за ~19 с, а полный цикл промпт → черновик → курирование → финал → внутриигровой журнал подтверждён от начала до конца в notes/m3-loop-proof.md.

Почему такая форма

Это не универсальный мост к ComfyUI, по замыслу. Инструменты оперируют словарём Foundry — портреты актёров, токены, раздаточные материалы, фоновые изображения сцен — и свободно дорабатываются под задачи Foundry. И он остаётся отдельным от fvtt-mcp-molten5e: тот сервер предназначен для создания контента Foundry и не должен быть связан с генерацией изображений. Этот сервер никогда не общается с Foundry-мостом; передача между ними — файлы на диске плюс инструменты загрузки molten5e.

Та же домашняя философия, что и у всего семейства: инструменты делают, навыки решают. Корректность (исполнение рабочих процессов, размеры, конвейер апскейла, соглашения о файлах) живёт в протестированных инструментах; суждение (мастерство промптов, вкус при курировании, какой актёр или журнал получит арт, домашний стиль) — в последующем навыке illustration-builder.

Claude ──MCP──> fvtt-mcp-artificer ──HTTP──> ComfyUI (headless, local)
                      │
                      └── pinned workflow JSONs (draft / final / final-refine / upscale)

ComfyUI работает в headless-режиме через API; этот сервер отправляет закреплённые JSON рабочих процессов из workflows/ — никогда не произвольные графы — с подстановкой prompt/seed/batch/preset (по node id, под защитой проверок на дрейф типов классов). Инструменты возвращают абсолютные пути к файлам; Claude читает PNG напрямую, чтобы курировать.

Related MCP server: FoundryVTT MCP Server

Пресеты по назначению, а не сырые размеры

generate-image принимает kind, а не ширину/высоту:

Конвейер разрешения (зафиксирован): никогда не генерируйте в выходном размере — композиция ухудшается после ~1.5 МП. Генерируйте в нативном разрешении пресета, увеличивайте моделью ×4 через 4x-UltraSharp, уменьшайте ланцошем до готового размера — всё в одном закреплённом графе.

Модели

• FLUX.1-dev fp8 (Comfy-Org all-in-one) — рендеры финального качества: ~15–19 с на готовый результат.

• FLUX.2-klein 4B (Apache 2.0) — черновая модель: 4 шага, ~1–2 с/изображение, пакет 6–8, отбор и повторный рендер с помощью dev.

• 4x-UltraSharp — модель-апскейлер в хвосте конвейера.

Инструменты

Контракт подстановки между инструментами и закреплёнными графами документирован в workflows/README.md.

Требования

• Windows + NVIDIA GPU. Разработано и подтверждено на RTX 5090 (Blackwell требует PyTorch с CUDA 12.8+; текущая портативная сборка ComfyUI поставляется с ним).

• ComfyUI (автономная портативная сборка, v0.34+), запускаемый в headless-режиме, — см. scripts/launch-comfyui.ps1 о соглашении по запуску (режим API на 127.0.0.1:8188, фиксированный --output-directory).

• Файлы моделей в дереве models/ ComfyUI (~33 ГБ, все без ограничений): checkpoints/flux1-dev-fp8.safetensors, diffusion_models/flux-2-klein-4b.safetensors, text_encoders/qwen_3_4b.safetensors, vae/flux2-vae.safetensors, upscale_models/4x-UltraSharp.safetensors. artificer-status сообщает обо всём отсутствующем.

• Node.js 22+ для самого MCP-сервера.

Сборка

npm install
npm run build

Тесты: npm test (офлайн-набор модульных тестов; в качестве фикстур выступают закреплённые JSON рабочих процессов). Живой набор — реальный ComfyUI, реальные рендеры — запускается через npm run test:integration. Проверки качества: npm run typecheck, npm run check (biome), npm run knip.

Подключение к Claude Code

По принятому в проекте соглашению сервер регистрируется в области пользователя (новые инструменты MCP ⇒ перезапустите Claude Code). Либо используйте CLI:

claude mcp add -s user artificer -- node D:/path/to/fvtt-mcp-artificer/dist/index.js

или скопируйте .mcp.json.example в .mcp.json, который читает Claude Code (или объедините с mcpServers в ~/.claude.json) с абсолютными путями. В Windows укажите в command полный путь к node.exe, если Node нет в PATH.

Конфигурация

Скопируйте .env.example в .env (игнорируется git):

• COMFY_URL — headless-инстанс (по умолчанию http://127.0.0.1:8188).

• COMFY_OUTPUT_DIR — должен соответствовать --output-directory, с которым был запущен ComfyUI; сервер читает сгенерированные PNG прямо из этого пути.

• ARTIFICER_TIMEOUT_MS — максимальное время ожидания на задание (по умолчанию 300000).

Лицензия

Лицензия MIT — подробнее см. в LICENSE.