game-asset-mcp

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

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

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

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

Требования

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

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

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

Установка

Запустите без постоянной установки:

npx game-asset-mcp

Или установите в проект:

npm install game-asset-mcp

Или соберите из исходников:

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

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

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

Скопируйте .env.example в .env или задайте переменные в блоке env вашего MCP-клиента (обычно это лучший вариант — см. фрагменты ниже).

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

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

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

Учётные данные проверяются лениво, в момент, когда инструменту они нужны, а не при запуске. Если вы задали только 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", "game-asset-mcp"],
  "env": {
    "TRIPO_API_KEY": "tsk_...",
    "LEONARDO_API_KEY": "...",
    "ASSET_OUTPUT_DIR": "/absolute/path/to/assets/generated"
  }
}

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

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

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

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

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 и шаг генерации изображений внутри create_game_prop. Ничто другое в этом сервере не может быть оплачено.

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

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

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

• Файлы записываются на диск. Всё попадает в ASSET_OUTPUT_DIR. Ничего не записывается за его пределами: пути разрешаются, и любой, выходящий за корень рабочего пространства, отклоняется.

• Ничего не перезаписывается молча. Конфликтующее имя ассета получает числовой суффикс (crate, crate_2, …), а не уничтожает результат, который вы, возможно, уже просмотрели.

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

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

• Ключи 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
    └── metadata/                   raw provider payloads, kept for debugging

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

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

Каждая ошибка несёт машиночитаемый code и флаг retryable, чтобы агент мог решить, что делать дальше, не разбирая прозу.

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

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

RATE_LIMITED — HTTP 429. Помечен как повторяемый. Опросы и загрузки отступают и повторяются автоматически (400 мс, 800 мс, 1600 мс, с ограничением 8 с). Запросы генерации — нет: повторяйте их сами после того, как окно освободится, осознанно, потому что они стоят денег.

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 двумя разными способами — общая конечная точка задач и пути для каждой операции — и оба присутствуют в текущей документации. Этот клиент реализует форму задачи, которая соответствует наблюдаемому поведению, что каждая генерация возвращает task_id для опроса, и предоставляет TRIPO_BASE_URL, чтобы вы могли перенацелить без редактирования кода. Пути — первое, что проверяет живой смоук-тест, потому что неправильный путь возвращает 404, который выглядит точно так же, как неверный API-ключ.

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

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

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

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

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

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

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

Вклад

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

Лицензия

MIT © 2026 Ben Haire. См. LICENSE.