game-asset-mcp

Un servidor MCP que permite a un agente de IA producir activos 3D listos para el juego de principio a fin — imagen de referencia, malla, texturas PBR, procedencia — y retexturizar mallas que ya posees.

La mayoría de las herramientas de generación de activos se detienen en "escribe un prompt, obtén una malla". Esa es la mitad fácil. La mitad que realmente bloquea un proyecto es la malla que ya tienes: el kitbash que modelaste la semana pasada, el prop del marketplace cuyos materiales no encajan con tu dirección de arte, el greybox que necesita parecer acero corroído para el viernes. texture_existing_asset toma una malla que tú proporcionas y le da nuevos materiales PBR sin regenerar la geometría que ya aprobaste.

Todo queda registrado. Cada trabajo conserva el prompt, la semilla, la versión del modelo del proveedor, el id de tarea del proveedor y un SHA-256 para cada byte descargado — para que dentro de seis meses aún puedas responder "¿qué produjo este archivo?".

El servidor es agnóstico respecto al proveedor por construcción. Hoy impulsa Tripo para 3D y Leonardo.Ai para imágenes de referencia, detrás de dos interfaces pequeñas (ImageProvider, Model3DProvider). Añadir un proveedor no cambia la superficie de herramientas. Consulta docs/architecture.md para saber por qué está construido así.

Requisitos

• Node.js >= 18.17 — el servidor usa fetch, FormData, Blob y AbortController globales.

• Sin módulos nativos, sin cadena de herramientas de compilación, sin base de datos. Funciona en cualquier lugar donde funcione Node.

• Al menos una clave de API de proveedor (consulta Configuración). Con una basta — se validan de forma diferida.

Instalación

Ejecútalo sin instalar nada de forma permanente:

npx game-asset-mcp

O instálalo en un proyecto:

npm install game-asset-mcp

O compílalo desde el código fuente:

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

El servidor habla MCP a través de stdio. Iniciado directamente en una terminal, simplemente se quedará esperando a que un cliente le hable — eso es un comportamiento correcto, no un cuelgue. Los registros van a stderr; stdout pertenece al protocolo.

Configuración

Copia .env.example a .env, o establece las variables en el bloque env de tu cliente MCP (que suele ser la mejor opción — consulta los fragmentos a continuación).

⚠️ Los créditos de API de Tripo se facturan por separado de una suscripción a Tripo Studio

Esto sorprende a casi todo el mundo. Una suscripción web a Tripo Studio no financia las llamadas a la API. Son dos productos diferentes con dos saldos diferentes. Si has estado generando modelos felizmente en la aplicación web de Studio y tu primera llamada a create_3d_asset vuelve rechazada por créditos insuficientes, no has configurado nada mal — necesitas créditos de API en la plataforma de desarrolladores. Cómpralos en platform.tripo3d.ai, no en la aplicación de Studio.

Con un proveedor basta

Las credenciales se validan de forma diferida, en el momento en que una herramienta las necesita, nunca al arrancar. Si solo estableces TRIPO_API_KEY, el servidor arranca correctamente y todas las herramientas 3D funcionan; las herramientas de imagen devuelven un error claro CONFIG_MISSING que nombra la variable que te falta. Lo contrario también se cumple. Nunca te ves obligado a tener una cuenta que no quieres solo para usar la mitad del pipeline que sí quieres.

Configuración del cliente MCP

Claude Code / Claude Desktop

Añade a tu configuración de MCP (claude_desktop_config.json, o .mcp.json en un proyecto para 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"
      }
    }
  }
}

Usa una ruta absoluta para args y para ASSET_OUTPUT_DIR. El directorio de trabajo de un cliente MCP no es el que crees, y un directorio de salida relativo dispersará los activos en algún lugar inesperado.

Cualquier otro cliente MCP

El mismo servidor, descrito genéricamente — un proceso hijo 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"
  }
}

Herramientas disponibles

Solo cinco herramientas pueden costarte dinero, y cada una lo dice en su descripción antes de ser llamada.

Flujo de trabajo de ejemplo

Pipeline completo: de la idea al activo inspeccionado

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

El paso 2 no es decoración. Elegir la referencia antes de gastar créditos 3D es toda la razón por la que el pipeline se divide aquí: una mala referencia produce una malla derretida, y solo lo descubres después de pagar por la reconstrucción.

Retexturizado: más corto, más barato, y el flujo que la mayoría de las herramientas no tienen

Ya tienes la malla. No hay nada que referenciar, nada que seleccionar, nada que reconstruir:

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

Una llamada de pago en lugar de dos, y la geometría que ya aprobaste vuelve sin cambios.

Costes y efectos secundarios

Llamadas que gastan créditos del proveedor: generate_asset_reference, generate_reference_variations, create_3d_asset, texture_existing_asset, y el paso de generación de imágenes dentro de create_game_prop. Nada más en este servidor puede cobrarse.

Llamadas gratuitas: select_reference, get_asset_job, download_asset, inspect_asset, list_asset_jobs. Consulta y descarga tantas veces como quieras.

Un POST que consume créditos nunca se reintenta automáticamente. Esta es una regla deliberada y de peso, y vive en la capa HTTP, no en cada punto de llamada. Cuando una solicitud que crea una tarea de generación falla — tiempo de espera agotado, reinicio de socket, 502 — el cliente no puede saber si el proveedor la aceptó antes de que se rompiera la conexión. Reintentar podría ser gratuito; también podría cobrarte el doble por una malla que nunca recibes. Así que no reintenta, el error vuelve directamente, y la decisión de intentarlo de nuevo es tuya. Las lecturas idempotentes — consultas de estado, descargas de archivos — se reintentan libremente con retroceso exponencial, porque repetirlas no cuesta nada.

Otros efectos secundarios que conviene conocer:

• Los archivos se escriben en disco. Todo cae bajo ASSET_OUTPUT_DIR. Nada se escribe fuera de él: las rutas se resuelven y cualquier ruta que escape de la raíz del espacio de trabajo se rechaza.

• Nada se sobrescribe silenciosamente. Un nombre de activo que colisiona recibe un sufijo numérico (crate, crate_2, …) en lugar de destruir un resultado que quizás ya has revisado.

• Las descargas tienen un límite de ASSET_MAX_DOWNLOAD_BYTES y el límite se aplica durante la transmisión, no desde la cabecera Content-Length — un servidor que miente sobre el tamaño no puede agotar tu memoria.

• Solo HTTPS. Las URLs que no son HTTPS se rechazan directamente, incluidas las que llegan dentro de una respuesta del proveedor.

• Las claves de API se redactan de los registros de forma centralizada, para que ningún punto de registro individual pueda filtrar una.

Estructura del espacio de trabajo

Cada activo recibe un directorio autocontenido. Ábrelo en un explorador de archivos dentro de seis meses y seguirá explicándose por sí mismo:

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> es el nombre de tu especificación, saneado: en minúsculas, los caracteres no alfanuméricos convertidos en guiones bajos. El directorio .jobs es un directorio oculto a propósito — navegar por tu espacio de trabajo de activos debería mostrar activos, no contabilidad.

Solución de problemas

Cada error lleva un code legible por máquina y una marca retryable, para que un agente pueda decidir qué hacer a continuación sin analizar prosa.

CONFIG_MISSING — falta una credencial. La herramienta que llamaste necesita un proveedor que no has configurado. El mensaje nombra la variable de entorno exacta. Establécelo en el bloque env de tu cliente MCP y reinicia el cliente — un archivo .env solo se lee si el directorio de trabajo del servidor es donde crees que está, que bajo un cliente MCP normalmente no lo es.

PROVIDER_HTTP con estado 401/403 — clave de API no válida. La clave es incorrecta, ha sido revocada, o es del proveedor equivocado. Dos trampas específicas: las claves de Leonardo necesitan acceso a API habilitado en la cuenta (un inicio de sesión web por sí solo no lo concede), y una clave de Tripo sin saldo de crédito de API puede fallar en la primera llamada de pago aunque la clave en sí sea válida. Consulta la advertencia de créditos más arriba.

RATE_LIMITED — HTTP 429. Marcado como reintentable. Las consultas y descargas retroceden y se reintentan automáticamente (400 ms, 800 ms, 1600 ms, con tope de 8 s). Las solicitudes de generación no lo hacen: reinténtalas tú mismo una vez que la ventana se despeje, deliberadamente, porque cuestan dinero.

PROVIDER_TASK_FAILED — la tarea falló del lado del proveedor. La llamada HTTP tuvo éxito y la generación no. El mensaje del propio proveedor se conserva en los detalles del error. Un rechazo de moderación también cae aquí: reescribe el prompt en lugar de reintentarlo sin cambios. Ten en cuenta que una respuesta de Tripo puede llevar HTTP 200 con un code de envoltorio distinto de cero; eso es un fallo, y este servidor lo trata como tal en lugar de informar un éxito fantasma.

La descarga falla con PROVIDER_HTTP 403/404 — la URL expiró. Esta es la sorpresa más común. Las URL de modelo y vista previa del proveedor son de corta duración. Están firmadas, expiran, y una URL que funcionaba hace veinte minutos ahora está muerta. La solución no es reintentar la misma URL: vuelve a llamar a get_asset_job para re-consultar al proveedor y obtener URL frescas, luego download_asset inmediatamente. Como hábito: descarga tan pronto como un trabajo informe ready, no al final de una sesión larga.

INVALID_INPUT — formato de imagen no compatible. Las imágenes de referencia deben ser formatos raster estándar seguros para web (PNG, JPEG, WebP). HDR, EXR, PSD con capas, SVG y TIFF de varias páginas no son entradas reconstruibles. Para texture_existing_asset, las mallas deben ser GLB, GLTF, FBX, OBJ o STL. Convierte primero; el proveedor no lo hará por ti.

PROVIDER_MALFORMED_RESPONSE — el proveedor devolvió algo inesperado. Cuerpo no JSON, envoltorio vacío, un éxito sin datos, o una subida que no devolvió token de archivo. Normalmente significa un incidente del lado del proveedor o una deriva de versión de API. Establece ASSET_LOG_LEVEL=debug para ver la forma de la solicitud (las claves están redactadas) y consulta la página de estado del proveedor antes de asumir que el error es local.

DOWNLOAD_TOO_LARGE. El archivo superó ASSET_MAX_DOWNLOAD_BYTES. Un GLB PBR de alta calidad puede ser grande; aumenta el límite si realmente quieres el archivo.

PATH_ESCAPE. Un nombre de archivo proporcionado por el proveedor intentó resolverse fuera de tu espacio de trabajo. La escritura fue rechazada. Esto nunca debería ocurrir en operación normal; por favor abre un issue si ocurre.

Estado

Este es software temprano, y las partes con más probabilidad de desviarse están marcadas como tales en lugar de asumirse silenciosamente.

Las rutas de endpoint v3 de Tripo están fijadas en exactamente un módulo (src/providers/model3d/tripo.ts) y documentadas en un comentario al principio del mismo. La documentación pública de Tripo describe la superficie v3 de dos maneras diferentes: un endpoint de tarea genérico y rutas por operación, y ambas aparecen en la documentación actual. Este cliente implementa la forma de tarea, que coincide con el comportamiento observable de que cada generación devuelve un task_id para consultar, y expone TRIPO_BASE_URL para que puedas redirigir sin editar código. Las rutas son lo primero que verifica la prueba de humo en vivo, porque una ruta incorrecta devuelve un 404 que se ve exactamente como una clave API incorrecta.

Nunca se ha hecho una llamada a una API de proveedor en vivo. Esta es la advertencia más importante aquí, por lo que se declara claramente en lugar de ocultarse. Cada una de las 165 pruebas se ejecuta contra mocks o el sistema de archivos local. Cubren la construcción de prompts, el mapeo de estados, la seguridad de rutas, el almacén de trabajos, las reglas de reintento y redirección de la capa HTTP, y la inspección de glTF contra archivos reales, pero una suite en verde no dice nada sobre si Leonardo y Tripo se comportan como este cliente asume.

Concretamente, estos permanecen sin verificar:

• Las rutas de endpoint v3 de Tripo descritas anteriormente.

• Si texture_model acepta una malla subida (file_token) o solo una malla producida por una tarea previa de Tripo (original_model_task_id). Esto decide si puedes retexturizar un modelo que ya posees, que es la característica para la que existe este servidor. Resolverlo cuesta una llamada de textura HD.

• Los ids de modelo de Leonardo en src/providers/image/leonardo.ts, que fueron transcritos de documentación publicada. Verifícalos contra GET /platformModels; un id obsoleto falla como un HTTP 400 que se lee como un cuerpo de solicitud malformado. Tanto LEONARDO_MODEL_ID como un modelId por llamada existen como vías de escape.

Si eres la primera persona en ejecutar esto con claves reales, espera tener que corregir una ruta de endpoint y por favor abre un issue con lo que encontraste.

Lo que sí está verificado: npm run verify construye el servidor, lo inicia sobre stdio con un cliente MCP real, completa el handshake y afirma que las once herramientas se registran. Eso es un viaje de ida y vuelta de protocolo, no una cadena de versión: un servidor que no logra registrar sus herramientas aún se inicia perfectamente.

Contribuciones

Se aceptan issues y pull requests. Si agregas un proveedor, implementa ImageProvider o Model3DProvider y no cambies nada más; si un nuevo proveedor obliga a cambiar la superficie de herramientas, la abstracción está mal y ese es el error que vale la pena discutir primero.

Licencia

MIT © 2026 Ben Haire. Ver LICENSE.