Skip to main content
Glama

game-asset-mcp

MCP-сервер, который позволяет ИИ-агенту создавать готовые к использованию 3D-ассеты от начала до конца — референсное изображение, меш, PBR-текстуры, происхождение — и перетекстурировать меши, которые уже есть у вас.

Большинство инструментов для генерации ассетов останавливаются на «введите промпт, получите меш». Это лёгкая половина. Половина, которая на самом деле блокирует проект, — это меш, который у вас уже есть: кибаш, смоделированный на прошлой неделе, проп из маркетплейса, чьи материалы не подходят под ваше арт-направление, грейбокс, который к пятнице должен выглядеть как корродированная сталь. texture_existing_asset принимает предоставленный вами меш и даёт ему новые PBR-материалы, не перегенерируя геометрию, которую вы уже одобрили.

Всё записывается. Каждый джоб хранит промпт, сид, версию модели провайдера, идентификатор задачи провайдера и SHA-256 для каждого скачанного байта — так что через шесть месяцев вы всё ещё сможете ответить на вопрос «что создало этот файл?».

Сервер по своей конструкции не зависит от провайдера. Сегодня он использует Tripo для 3D и Leonardo.Ai для референсных изображений и звуковых эффектов, за тремя небольшими интерфейсами (ImageProvider, Model3DProvider, AudioProvider). Добавление провайдера не меняет поверхность инструментов. См. docs/architecture.md о том, почему он построен именно так.


Требования

  • Node.js >= 18.17 — сервер использует глобальные fetch, FormData, Blob и AbortController.

  • Никаких нативных модулей, сборочного тулчейна или базы данных. Он работает везде, где работает Node.

  • Необязательно: локальная установка Blender 4.x+ включает ремонтную часть normalize_mesh и batch_prepare_meshes. Все остальные инструменты работают без него; при отсутствии инструмент отказывает с инструкциями. На macOS Blender не находится в PATH, поэтому установите BLENDER_PATH или полагайтесь на встроенный по умолчанию /Applications/Blender.app.

  • Как минимум один ключ API провайдера (см. Конфигурация). Одного достаточно — они проверяются лениво.


Related MCP server: Context3D MCP Server

Установка

Установка прямо из GitHub. Обе формы компилируют TypeScript во время установки, так что вы получаете исполняемый бинарник game-asset-mcp в любом случае.

# run it without installing anything permanently
npx github:theisegoria/game-asset-mcp

# or add it to a project
npm install github:theisegoria/game-asset-mcp

# pin a specific version — recommended for anything you depend on
npm install github:theisegoria/game-asset-mcp#v0.3.7

Зафиксируйте версию. Без суффикса #vX.Y.Z обе формы разрешаются в то, что main находится в данный момент, что не является стабильной зависимостью. Каждый релиз помечен тегом, поэтому #v0.3.7 даёт вам именно это дерево. Релизы перечислены на github.com/theisegoria/game-asset-mcp/releases, каждый с указанием дефектов, которые он исправляет.

Не используйте v0.3.0, v0.3.1 или v0.3.2. Позднее ревью обнаружило в них живые пути, которые уничтожают переданный меш и сообщают об успехе. Они помечены тегами только для полноты истории. На их страницах релизов это тоже указано.

Или работайте из клона — это то, что вам нужно, если вы собираетесь что-то менять:

git clone https://github.com/theisegoria/game-asset-mcp.git
cd game-asset-mcp
npm install
npm run build     # emits dist/
node dist/server.js

Не на npm. Нет npm install @theisegoria/game-asset-mcp — пакет распространяется только через GitHub. Всё, что говорит иначе, устарело.

Сервер говорит по MCP через stdio. Запущенный напрямую в терминале, он просто будет ждать, пока клиент с ним заговорит — это правильное поведение, а не зависание. Логи идут в stderr; stdout принадлежит протоколу.


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

Установите эти переменные в блоке env вашего MCP-клиента — см. фрагменты ниже. Загрузки .env нет: сервер читает process.env и ничего больше, поэтому файл .env на диске ничего не делает, если ваша оболочка или клиент не экспортирует его заранее.

Переменная

Обязательная

По умолчанию

Назначение

TRIPO_API_KEY

для 3D-инструментов

Ключ API Tripo. Создайте на platform.tripo3d.ai.

LEONARDO_API_KEY

для инструментов изображений и аудио

Ключ Leonardo.Ai с включённым доступом к API. Один ключ покрывает и референсные изображения, и звуковые эффекты.

LEONARDO_MODEL_ID

нет

встроенный по умолчанию

Переопределяет модель изображений Leonardo по умолчанию. Также существует параметр modelId для каждого вызова.

ASSET_OUTPUT_DIR

нет

./assets/generated

Куда записываются ассеты и записи джобов. Относительно рабочей директории сервера.

ASSET_MAX_DOWNLOAD_BYTES

нет

268435456 (256 МиБ)

Жёсткий предел для любой отдельной загрузки, применяется во время потоковой передачи — и для любого ЛОКАЛЬНОГО файла, который вы предоставляете, так что слишком большой меш, который у вас уже есть, отклоняется с DOWNLOAD_TOO_LARGE.

ASSET_HTTP_TIMEOUT_MS

нет

60000

Таймаут HTTP для каждого запроса.

ASSET_LOG_LEVEL

нет

info

silent | error | warn | info | debug.

BLENDER_PATH

нет

автоопределение

Исполняемый файл Blender для normalize_mesh и batch_prepare_meshes. Переопределяет обнаружение.

TRIPO_BASE_URL

нет

конечная точка Tripo v3

Перенаправление 3D-провайдера. Должен быть https://; значение http:// отклоняется при первом использовании провайдера, а не при запуске, потому что провайдеры создаются лениво.

LEONARDO_BASE_URL

нет

конечная точка Leonardo

Перенаправление провайдера изображений/аудио. Должен быть https://, отклоняется при первом использовании, по той же причине.

ASSET_SPEND_LIMIT_CENTS

нет

без ограничений

Потолочный лимит расходов за сессию в центах США. Инструменты, потребляющие кредиты, отказываются после его достижения, до обращения к провайдеру.

⚠️ Кредиты API Tripo оплачиваются отдельно от подписки Tripo Studio

Это ловит почти всех. Веб-подписка Tripo Studio не финансирует вызовы API. Это два разных продукта с двумя разными балансами. Если вы с удовольствием генерировали модели в веб-приложении Studio и ваш самый первый вызов create_3d_asset вернулся с отказом из-за недостаточных кредитов, вы ничего не настроили неправильно — вам нужны API-кредиты на платформе разработчика. Купите их на platform.tripo3d.ai, а не в приложении Studio.

Ограничение расходов

Установите ASSET_SPEND_LIMIT_CENTS, и каждый инструмент, потребляющий кредиты, проверяет его до обращения к провайдеру — включая загрузку меша или референсного изображения — отказывая с указанием оставшегося баланса, а не перерасходуя. Потолок в центах США, потому что два провайдера выставляют счета в разных единицах — Tripo в кредитах по $0.01, Leonardo в USD — и лимит, смешивающий их, ничего бы не значил.

Где провайдер публикует цену за вызов, мы её используем. Где нет, защита использует намеренно пессимистичный плейсхолдер, и get_spend_report указывает, какие цифры какие. Это защита, а не счёт: реальные списания должны быть на уровне или ниже оценки, никогда выше.

Одного провайдера достаточно

Учётные данные проверяются лениво, в момент, когда инструменту они нужны, никогда при запуске. Если вы установили только TRIPO_API_KEY, сервер запускается нормально, и все 3D-инструменты работают; инструменты изображений возвращают понятную ошибку CONFIG_MISSING с указанием недостающей переменной. Обратное тоже верно. Вас никогда не заставляют иметь аккаунт, который вам не нужен, только чтобы использовать ту половину пайплайна, которая вам нужна.


Настройка MCP-клиента

Claude Code / Claude Desktop

Добавьте в вашу MCP-конфигурацию (claude_desktop_config.json или .mcp.json в проекте для Claude Code):

{
  "mcpServers": {
    "game-asset": {
      "command": "node",
      "args": ["/absolute/path/to/game-asset-mcp/dist/server.js"],
      "env": {
        "TRIPO_API_KEY": "tsk_...",
        "LEONARDO_API_KEY": "...",
        "ASSET_OUTPUT_DIR": "/absolute/path/to/your/project/assets/generated",
        "ASSET_LOG_LEVEL": "info"
      }
    }
  }
}

Используйте абсолютный путь для args и для ASSET_OUTPUT_DIR. Рабочая директория MCP-клиента не та, что вы думаете, и относительная выходная директория разбросает ассеты в неожиданных местах.

Любой другой MCP-клиент

Тот же сервер, описанный обобщённо — дочерний процесс stdio:

{
  "name": "game-asset",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "github:theisegoria/game-asset-mcp"],
  "env": {
    "TRIPO_API_KEY": "tsk_...",
    "LEONARDO_API_KEY": "...",
    "ASSET_OUTPUT_DIR": "/absolute/path/to/assets/generated"
  }
}

Доступные инструменты

Инструмент

Тратит кредиты

Что делает

preview_asset_prompt

Нет

Пробный запуск. Показывает точный промпт и негативный промпт, которые даст спецификация, чтобы арт-дирекцию можно было поправить до того, как за что-то заплатят.

generate_asset_reference

Да

Превращает спецификацию ассета в референсные изображения, созданные для реконструкции — изолированный объект, цельный силуэт, ровный свет, однотонный фон. Создаёт задание на ассет.

generate_reference_variations

Да

Исследует одну ось (силуэт, обработка материала, детализация, износ, пропорции, функциональные компоненты), сохраняя идентичность объекта неизменной.

select_reference

Нет

Отмечает, какой референсный кандидат будет реконструирован на 3D-этапе. Только локальный учёт.

create_3d_asset

Да

Реконструирует меш с PBR-текстурами из выбранного референса — или напрямую из текста, если референса нет. Возвращается немедленно с заданием для опроса.

texture_existing_asset

Да

Применяет новые PBR-материалы к мешу, которым вы уже владеете (GLB/GLTF/FBX/OBJ/STL) или к ранее сгенерированному. Геометрия не затрагивается.

get_asset_job

Нет

Опрашивает задание. Сопоставляет словарь статусов провайдера с одним нормализованным жизненным циклом и сохраняет исходный статус рядом.

download_asset

Нет

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

inspect_asset

Нет

Читает загруженный glTF/GLB и сообщает, что в нём на самом деле — меши, материалы, текстурные каналы, размеры.

extract_pbr_trio

Нет

Разделяет glTF-материал на независимые изображения альбедо, нормалей и шероховатости, распаковывая metallicRoughness (шероховатость = зелёный, металличность = синий). Пересэмплирует до точного размера, усредняя цвет в линейном свету и каналы данных напрямую.

normalize_mesh

Нет

Чинит меш, чтобы его можно было использовать: генерирует UV для объектов, у которых их нет (обычная причина, по которой меш нельзя текстурировать), сваривает совпадающие вершины, удаляет вырожденные треугольники, именует каждый материал и принудительно включает непрозрачное смешивание. Необязательная зависимость от Blender.

generate_sound_effect

Да

Генерирует короткий игровой звуковой эффект из описания — удары, выстрелы, UI-бипы или бесшовный цикл эмбиента. Опрашивает и скачивает встроенно.

create_game_prop

Да — только изображения

Точка входа, сформированная по намерению: запрос на простом языке на входе, спецификация ассета плюс референсные кандидаты на выходе. Намеренно останавливается перед 3D-затратами, чтобы человек или агент сначала выбрал референс.

list_asset_jobs

Нет

Перечисляет известные задания, сначала новые, в виде компактных сводок.

rig_asset

Да

Строит скелет и веса кожи для сгенерированного ассета, чтобы его можно было анимировать.

animate_asset

Да

Перенацеливает готовую анимацию на ассет, который уже был ригован. Отказывается от неригованного источника, а не выставляет счёт впустую.

retopologize_asset

Да

Перестраивает топологию, по умолчанию квадами — квады переживают последующее редактирование и квалификацию меша гораздо лучше, чем генераторный суп из треугольников.

validate_game_asset

Нет

Оценивает меш по политике выпуска и возвращает пройдено/не пройдено с причинами по каждой проверке — UV, нормали, касательные, бюджет треугольников, материалы, разрешение текстур, адекватность ограничивающего бокса. Каждый порог переопределяем.

batch_prepare_meshes

Нет

Запускает validate → normalize → validate по списку путей .glb/.gltf (до 500) и возвращает вердикт по каждому элементу. Меши, которые уже проходят, не трогаются; один плохой файл сообщается по своему элементу и никогда не останавливает запуск.

get_spend_report

Нет

Что потрачено в этом рабочем пространстве, по инструментам, с оставшимся запасом — и является ли каждая цифра опубликованной ценой или пессимистичным заполнителем.

Только девять инструментов могут стоить вам денег, и каждый из них сообщает об этом в своём описании до вызова.


Бесплатная локальная половина (без API-ключей, без сети)

Одиннадцать из двадцати инструментов никогда не тратят кредиты, и только два из этих одиннадцати вообще используют сетьget_asset_job опрашивает, а download_asset загружает; оба бесплатны, но это сетевые вызовы. Остальные девять работают офлайн. Пять ниже — это конвейер мешей, и если у вас уже есть меши, они и есть весь продукт.

Инструмент

На какой вопрос отвечает

inspect_asset

Что на самом деле внутри этого glTF? Меши, материалы, текстурные каналы, размеры, границы.

validate_game_asset

Готов ли он к выпуску? Пройдено/не пройдено с причинами по каждой проверке и каждый порог переопределяем.

normalize_mesh

Починить его: сгенерировать UV для объектов, у которых их нет, сварить совпадающие вершины, удалить вырожденные треугольники, именовать материалы.

batch_prepare_meshes

То же самое, по списку путей .glb/.gltf, с вердиктом по каждому элементу. Неудачный элемент всё равно может записать файл — когда нормализация успешна, но результат не проходит политику, меш сохраняется для проверки. Используйте outputsWritten, а не prepared, чтобы предсказать количество файлов.

extract_pbr_trio

Разделить материал на изображения альбедо / нормалей / шероховатости, корректно распаковав metallicRoughness.

Обычный цикл — validate → normalize → validate снова, чтобы ремонт был доказан, а не предполагаем:

validate_game_asset  modelPath=/art/crate.glb
   → fails: uvs_present   ("nothing can texture this")
normalize_mesh       modelPath=/art/crate.glb  outputDir=/art/out
   → objectsUnwrapped=2, triangles 3183 → 1750
validate_game_asset  modelPath=/art/out/crate_normalized.glb
   → passes

batch_prepare_meshes запускает этот цикл по списку и сообщает о каждом элементе отдельно. Меши, которые уже проходят, не переписываются, один плохой файл никогда не останавливает запуск, а два источника с одинаковым базовым именем получают разные выходные файлы вместо перезаписи друг друга.

Отсутствие UV — это дефект, о котором стоит знать. Меш без UV-координат не может быть текстурирован ничем — ни этим инструментом, ни провайдером, ни вами вручную. Генераторы и ассеты из маркетплейсов регулярно поставляются без них. validate_game_asset называет это первым по этой причине.

Для нормализации нужен Blender (4.x+). Без него инструменты всё равно проверяют и сообщают; они просто не могут чинить. На macOS Blender нет в PATH, поэтому либо задайте BLENDER_PATH, либо полагайтесь на встроенный /Applications/Blender.app по умолчанию.


Пример рабочего процесса

Полный конвейер: от идеи до проверенного ассета

1. generate_asset_reference   → spends image credits, returns assetJobId + N candidates
2. (inspect the images)       → look at the returned reference images and choose one
3. select_reference           → free; records which candidate wins
4. create_3d_asset            → spends 3D credits, returns a task to poll
5. get_asset_job              → free; poll until status is "ready" (or "failed")
6. download_asset             → free; pulls model + textures + previews into the workspace
7. inspect_asset              → free; confirms what actually landed on disk

Шаг 2 — не украшение. Выбор референса до траты 3D-кредитов — это вся причина, по которой конвейер разделён здесь: плохой референс даёт расплавленный меш, и вы обнаруживаете это только после оплаты реконструкции.

Перетекстурирование: короче, дешевле, и этот поток есть не у большинства инструментов

У вас уже есть меш. Нечего референсировать, нечего выбирать, нечего реконструировать:

1. texture_existing_asset     → spends texturing credits on a mesh you supply
2. get_asset_job              → free; poll until ready
3. download_asset             → free
4. inspect_asset              → free

Один платный вызов вместо двух, и геометрия, которую вы уже одобрили, возвращается неизменной.


Затраты и побочные эффекты

Вызовы, тратящие кредиты провайдера: generate_asset_reference, generate_reference_variations, create_3d_asset, texture_existing_asset, generate_sound_effect, rig_asset, animate_asset, retopologize_asset и этап генерации изображений внутри create_game_prop. Больше ничто в этом сервере не может быть оплачено.

Бесплатные вызовы: select_reference, get_asset_job, download_asset, inspect_asset, list_asset_jobs, preview_asset_prompt, extract_pbr_trio, normalize_mesh, validate_game_asset, batch_prepare_meshes, get_spend_report. Опрашивайте, проверяйте, разделяйте и скачивайте сколько угодно.

Требующий кредитов POST-запрос никогда не повторяется автоматически. Это осознанное, несущее нагрузку правило, и оно живёт в HTTP-слое, а не в каждой точке вызова. Когда запрос, создающий задачу генерации, завершается сбоем — таймаут, сброс сокета, 502 — клиент не может определить, принял ли провайдер запрос до разрыва соединения. Повтор может быть бесплатным; но он может и списать с вас двойную плату за сетку, которую вы так и не получите. Поэтому повтор не выполняется, ошибка возвращается напрямую, и решение о повторной попытке остаётся за вами. Идемпотентные чтения — опросы статуса, загрузки файлов — повторяются свободно с экспоненциальной задержкой, потому что их повтор ничего не стоит.

Другие побочные эффекты, о которых стоит знать:

  • Файлы записываются на диск. Скачанные ресурсы попадают в ASSET_OUTPUT_DIR, и путь загрузки, выходящий за пределы корня рабочей области, отклоняется. Три инструмента отличаются, и это намеренно: extract_pbr_trio, normalize_mesh и batch_prepare_meshes пишут туда, куда вы им укажете, включая выход за пределы рабочей области, потому что они работают с сетками, которые уже принадлежат вам, и те не живут в каталоге генерации ресурсов. Укажите им назначение, которое вы имели в виду.

  • download_asset и generate_sound_effect принимают destination, который переопределяет ASSET_OUTPUT_DIR для этого одного вызова. Ограничение сохраняется: путь, выходящий за пределы заданного корня, отклоняется.

  • ASSET_OUTPUT_DIR должен быть абсолютным. Относительное значение разрешается относительно рабочего каталога сервера, который выбирает ваш MCP-клиент — некоторые запускаются из /. Сервер отказывается запускаться с сообщением, называющим разрешённый путь и рабочий каталог, из которого он получен. Этот диагноз покрывает восемь errno, которые это может реально породить — ENOENT, EACCES, EPERM, EROFS, ENOTDIR, ELOOP, ENAMETOOLONG и ENOSPC, включая ASSET_OUTPUT_DIR, указывающий на файл, а не на каталог. Всё остальное по-прежнему пробрасывается в исходном виде.

  • Ничто не перезаписывается молча. Производное имя выходного файла получает числовой суффикс (crate, crate_2, …) вместо уничтожения результата, который вы, возможно, уже просмотрели, и имя закрепляется эксклюзивным созданием, так что два элемента в одном пакете не могут за него конкурировать. Явный outputPath отклоняется outright, если файл уже существует, если только вы не передадите overwrite: true — и он отклоняется безусловно, без возможности отказа, если он разрешается на входную сетку. Это разрешение учитывает симлинки, жёсткие ссылки, регистронезависимые тома и привычку экспортёра переписывать расширение, потому что каждая из этих причин уже уничтожала исходную сетку здесь.

  • Загрузки ограничены ASSET_MAX_DOWNLOAD_BYTES, и ограничение применяется во время потоковой передачи, а не из заголовка Content-Length — сервер, который лжёт о размере, не может исчерпать вашу память.

  • Только HTTPS. URL без HTTPS отклоняются outright, включая те, что приходят внутри ответа провайдера.

  • API-ключи централизованно вырезаются из логов, так что ни одна отдельная точка вызова логов не может их утечь.


Структура рабочей области

Каждый ресурс получает самодостаточный каталог. Откройте его в файловом браузере через шесть месяцев — и он всё ещё объясняет сам себя:

assets/generated/
├── .jobs/                          job records, one JSON file per job
│   └── asset_<uuid>.json
└── <asset_name>/
    ├── asset.json                  complete provenance: spec, prompt, seed,
    │                               model version, provider ids, file hashes
    ├── source/                     the reference image(s) the mesh was built from
    ├── model/                      the mesh (GLB by default)
    ├── textures/                   extracted PBR maps
    ├── previews/                   provider-rendered turnarounds

<asset_name> — это имя из вашей спецификации, санитизированное: в нижнем регистре, неалфавитно-цифровые символы схлопнуты в подчёркивания. Каталог .jobs — это dot-каталог намеренно: просмотр вашей рабочей области ресурсов должен показывать ресурсы, а не служебные данные.


Устранение неполадок

Каждая ошибка несёт машиночитаемое поле error, называющее класс, плюс флаг retryable, чтобы агент мог решить, что делать дальше, не разбирая прозу. Имена ниже — это значения поля error.

Сервер запускается и сразу завершается — клиент говорит только «соединение закрыто». Три известные причины, и сервер теперь сам называет первые две, а не умирает молча.

  • Относительный ASSET_OUTPUT_DIR. Он разрешается относительно рабочего каталога сервера, который выбирает ваш MCP-клиент — несколько запускаются из /, где assets/generated становится /assets и не может быть создан. Используйте абсолютный путь. Отказ называет разрешённый путь и рабочий каталог, из которого он получен.

  • Рабочая область, в которую процесс не может писать. Тот же отказ, другой errno.

  • Устаревшая сборка. Если dist/ старше изменения точки входа, пересоберите. npm run verify собирает, а затем выполняет реальное MCP-рукопожатие — это самый быстрый способ отличить сломанный сервер от сломанной конфигурации клиента.

normalize_mesh или batch_prepare_meshes отказывает с «Blender not found». На PATH нет локального Blender. На macOS пакет приложения не находится на PATH, даже когда Blender установлен — задайте BLENDER_PATH на исполняемый файл внутри пакета. batch_prepare_meshes деградирует, а не падает: он всё равно валидирует каждую сетку и сообщает, что потребовало бы ремонта.

CONFIG_MISSING — отсутствуют учётные данные. Вызванный вами инструмент требует провайдера, которого вы не настроили. Сообщение называет точную переменную окружения. Задайте её в блоке env вашего MCP-клиента и перезапустите клиент. Файл .env никогда не читается: нет зависимости dotenv, поэтому переменная должна быть экспортирована тем, что запускает сервер.

PROVIDER_HTTP со статусом 401/403 — недействительный API-ключ. Ключ неверен, отозван или принадлежит другому провайдеру. Две конкретные ловушки: для ключей Leonardo требуется включённый API-доступ на аккаунте (один лишь веб-вход его не даёт), а ключ Tripo без баланса API-кредитов может упасть на первом платном вызове, даже если сам ключ действителен. См. предупреждение о кредитах выше.

RATE_LIMITED — HTTP 429. Помечен как retryable. Опросы отступают и повторяются автоматически (400 мс, 800 мс, 1600 мс, с потолком 8 с). Загрузки не повторяютсяdownload_asset стримит за одну попытку, так что перезапустите его сами; поскольку URL провайдера истекают, сначала повторно опросите через get_asset_job, а не повторяйте устаревший URL. Запросы генерации тоже не повторяются, намеренно, потому что они стоят денег. 429 во время загрузки всплывает как PROVIDER_HTTP со статусом 429, а не как RATE_LIMITED.

PROVIDER_TASK_FAILED — задача провалилась на стороне провайдера. HTTP-вызов прошёл, а генерация — нет. Собственное сообщение провайдера сохраняется в деталях ошибки. Отказ модерации тоже попадает сюда: перепишите промпт, а не повторяйте его без изменений. Обратите внимание: ответ Tripo может нести HTTP 200 с ненулевым code в конверте; это сбой, и этот сервер трактует его как сбой, а не сообщает о фантомном успехе.

Загрузка падает с PROVIDER_HTTP 403/404 — URL истёк. Это самый частый сюрприз. URL моделей и превью провайдера живут недолго. Они подписаны, они истекают, и URL, который работал двадцать минут назад, теперь мёртв. Исправление — не повторять тот же URL: вызовите get_asset_job снова, чтобы повторно опросить провайдера на свежие URL, затем немедленно download_asset. Как привычка: скачивайте, как только задача сообщает ready, а не в конце долгой сессии.

INVALID_INPUT — неподдерживаемый формат изображения. Референсные изображения должны быть стандартными веб-безопасными растровыми форматами (PNG, JPEG, WebP). HDR, EXR, многослойный PSD, SVG и многостраничный TIFF не являются восстанавливаемыми входными данными. Для texture_existing_asset сетки должны быть GLB, GLTF, FBX, OBJ или STL. Конвертируйте сначала; провайдер за вас это не сделает.

PROVIDER_MALFORMED_RESPONSE — провайдер вернул что-то неожиданное. Не-JSON тело, пустой конверт, успех без данных или загрузка, не вернувшая токен файла. Обычно означает инцидент на стороне провайдера или дрейф версии API. Задайте ASSET_LOG_LEVEL=debug, чтобы увидеть форму запроса (ключи вырезаются), и проверьте страницу статуса провайдера, прежде чем предполагать, что баг локальный.

DOWNLOAD_TOO_LARGE. Файл превысил ASSET_MAX_DOWNLOAD_BYTES. Высококачественный PBR GLB может быть большим; поднимите лимит, если вы действительно хотите этот файл.

PATH_ESCAPE. Имя файла, предоставленное провайдером, попыталось разрешиться за пределами вашей рабочей области. Запись была отклонена. Этого не должно происходить при нормальной работе — пожалуйста, откройте issue, если это случится.


Статус

Это раннее программное обеспечение, и части, наиболее склонные к дрейфу, помечены как таковые, а не молча предполагаются стабильными.

Пути конечных точек v3 Tripo закреплены ровно в одном модуле (src/providers/model3d/tripo.ts) и задокументированы в комментарии в его начале. Публичная документация Tripo описывает поверхность v3 двумя разными способами — общий endpoint задач и пути для каждой операции — и оба присутствуют в текущей документации. Этот клиент реализует форму задачи, которая соответствует наблюдаемому поведению, что каждая генерация возвращает task_id для опроса, и предоставляет TRIPO_BASE_URL, чтобы вы могли перенацелить без правки кода. Если они неверны, вы увидите 404, который выглядит точно как неверный API-ключ, так что проверяйте путь раньше ключа.

Ни один вызов никогда не делался к живому API провайдера. Это самое важное предостережение здесь, поэтому оно сказано прямо, а не спрятано. Каждый из 384 тестов работает против моков или локальной файловой системы. Они покрывают построение промптов, маппинг статусов, безопасность путей, хранилище задач, правила повторов и редиректов HTTP-слоя и инспекцию glTF на реальных файлах — но зелёный набор тестов ничего не говорит о том, ведут ли себя Leonardo и Tripo так, как предполагает этот клиент.

Конкретно, остаются непроверенными:

  • Пути конечных точек v3 Tripo, описанные выше.

  • Принимает ли texture_model загруженную сетку (file_token) или только сетку, созданную предыдущей задачей Tripo (original_model_task_id). Это решает, можете ли вы перетекстурировать модель, которая уже у вас есть, — а это функция, ради которой существует этот сервер. Разрешение этого стоит один HD-вызов текстурирования.

  • Генерация звуковых эффектов непроверена. Leonardo документирует контракт запроса Sound Effects v2 (model, prompt, duration 1-22 с, prompt_influence, loop, quantity), но не форму его ответа и не то, как извлекается готовое аудио. Клиент читает id генерации и URL аудио из нескольких правдоподобных форм и выбрасывает исключение с именами ключей верхнего уровня ответа (не телом, которое может быть большим или нести подписанный URL), когда ни одна не совпадает, вместо того чтобы сообщать о пустом успехе. Ожидайте, что первый реальный вызов потребует исправления, и пожалуйста, откройте issue с формой полезной нагрузки, которую вы видели.

  • Id моделей Leonardo в src/providers/image/leonardo.ts, которые были транскрибированы из опубликованной документации. Сверьте их с GET /platformModels; устаревший id падает как HTTP 400, который читается как некорректное тело запроса. И LEONARDO_MODEL_ID, и modelId для отдельного вызова существуют как запасные выходы.

Если вы первый, кто запускает это с реальными ключами, ожидайте, что придётся исправить путь endpoint, и пожалуйста, откройте issue с тем, что вы нашли.

Что проверено: npm run verify собирает сервер, запускает его через stdio с реальным MCP-клиентом, выполняет рукопожатие и утверждает, что все двадцать инструментов регистрируются. Это протокольный round-trip, а не строка версии — сервер, которому не удаётся зарегистрировать свои инструменты, всё равно прекрасно запускается.

Части локального конвейера — inspect_asset, extract_pbr_trio, normalize_mesh, validate_game_asset — дополнительно проверяются на реальных поставляемых игровых ресурсах, а не на фикстурах, потому что синтетическая фикстура и парсер, который её читает, могут разделять одну и ту же ошибку, и оба выглядеть зелёными. Это здесь случалось: неверная магическая константа glTF пережила полный синтетический набор и была поймана только реальным файлом. Сетка без UV, которую они используют, закоммичена здесь, а не читается из соседнего чекаута. Раньше она читалась вживую из игрового репозитория, и когда эта сетка была отремонтирована, эти тесты покраснели из-за изменения, которое было полностью корректным — утверждение, закрепляющее факт о файле, которым этот проект не управляет. Тест не может зависеть от контента, которым он не владеет.

Один тест запускает собранный сервер через симлинк bin — то, что на самом деле содержит node_modules/.bin — и общается с ним по MCP, потому что именно там отказала защита точки входа: сервер мгновенно завершался при каждой установке, проходя все остальные тесты. Он использует симлинк, а не установку, поэтому не может поймать регрессию упаковки в files или prepare; реальный npm install из GitHub по-прежнему остаётся ручной проверкой.

Почему количество тестов не главное

В 0.3.4 каждый из пяти ключевых исправлений предыдущего релиза был откачен по одному, и набор тестов был запущен заново. Все пять выжили — каждый мутант был полностью зелёным. Исправления были реальными; ничто в наборе их не удерживало. Причиной было одно общее допущение: каждый заглушенный Blender завершался с кодом 0 и печатал ровно одну квитанцию, поэтому ни одно из усилений протокола подпроцесса не было наблюдаемо ни одним тестом.

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

Та же проверка дважды поймала плохое доказательство за один присест. Два последовательных фикстура, написанных для доказательства исправления порога сварки, сообщали одинаковое количество треугольников и с корректным кодом, и со сломанным, и любой из них мог бы быть отправлен как доказательство. Фикстура не является доказательством, пока она не была прогнана и через исправленный, и через сломанный код, и не были выведены два числа.


Вклад

Приветствуются issues и pull requests. Если вы добавляете провайдера, реализуйте ImageProvider или Model3DProvider и больше ничего не меняйте — если новый провайдер вынуждает изменить поверхность инструментов, значит, абстракция неверна, и это та ошибка, которую стоит обсудить в первую очередь.

Лицензия

MIT © 2026 Ben Haire. См. LICENSE.

A
license - permissive license
A
quality
A
maintenance

Maintenance

Maintainers
Response time
0dRelease cycle
15Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • Generate game assets with AI: sprites, 3D models, animations, sound effects, music, and voices.

  • Build, validate, and deploy multi-agent AI solutions from any AI environment.

  • AI visual generation agent: multi-pipeline rendering, prompt crafting, and image composition.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/theisegoria/game-development-studio'

If you have feedback or need assistance with the MCP directory API, please join our Discord server