Skip to main content
Glama
Game Asset Finder MCP

Game Asset Finder MCP

by sudoriaa

Game Asset Finder MCP

CI License: MIT

Un servicio MCP orientado a la búsqueda para el desarrollo de juegos. Consulta simultáneamente múltiples fuentes de activos públicas y una biblioteca local opcional, unifica los resultados de diferentes sitios en un mismo conjunto de campos, y realiza expansión de palabras clave en chino, normalización de licencias, clasificación por relevancia, deduplicación entre fuentes, equilibrio de fuentes, almacenamiento en caché y paginación con cursor.

El proyecto se basa en el SDK actual de MCP TypeScript v2, se ejecuta mediante stdio y es compatible con Codex, ChatGPT de escritorio y otros clientes que admitan MCP local.

Diseño y optimización

El proyecto utiliza un registro de proveedores y un modelo de resultados unificado, con un enfoque optimizado en la capa de búsqueda entre fuentes:

  • El fallo de una fuente individual no derrumba la búsqueda global; la respuesta marca claramente el estado de cada fuente.

  • La ponderación de palabras clave y la expansión de términos de juegos en chino e inglés mejoran la tasa de recuperación de consultas en chino.

  • Se incorpora caché TTL/LRU, fusión de solicitudes concurrentes idénticas, tiempo límite total por proveedor, reintentos limitados y Retry-After.

  • Se añade filtrado unificado de licencias, deduplicación de URL normalizadas, fusión de fuentes espejo, ordenamiento estable y diversificación de fuentes.

  • Paginación con limit + nextCursor para evitar saturar el contexto del modelo con grandes cantidades de resultados.

  • El índice local utiliza escaneo incremental, SHA-256, escritura atómica, restricción de directorio raíz y omisión de enlaces simbólicos.

  • La superficie de herramientas se reduce a 4, disminuyendo la probabilidad de que el agente seleccione la herramienta equivocada.

Related MCP server: @codesift/mcp

Fuentes de datos

id

Contenido

Credenciales

Características de licencia

kenney

Paquetes de activos 2D, 3D, UI, audio, fuentes

Ninguna

CC0

opengameart

2D, 3D, música, efectos de sonido

Ninguna

Varía por elemento

itch

Listados de activos de juegos gratuitos

Ninguna

Varía por autor/página

openverse

Referencias de imágenes, texturas, iconos

Ninguna

CC / Dominio público

ambientcg

Materiales PBR, HDRI, 3D

Ninguna

CC0

polyhaven

Texturas, HDRI, 3D

Ninguna

CC0

freesound

Efectos de sonido, grabaciones

FREESOUND_API_KEY

Varía por elemento

local

Activos locales en el directorio configurado

Directorio local

Descrito por sidecar

Cualquier fuente remota puede experimentar timeouts o límites de tasa temporales. El campo sourceStatuses en el valor de retorno indica ok / partial / disabled / timeout / rate_limited / error por fuente; las fuentes exitosas aún devuelven resultados.

Instalación

Requiere Node.js 20.18.1 o superior.

git clone https://github.com/sudoriaa/game-asset-finder-mcp.git
cd game-asset-finder-mcp
npm ci
npm run build
npm test

También se puede ejecutar:

.\install.ps1

Iniciar directamente:

node .\dist\index.js

La salida estándar de stdio es el canal MCP JSON-RPC; los registros del servicio solo se escriben en el error estándar.

Integración con Codex

Agregue en ~/.codex/config.toml o en .codex/config.toml de un proyecto de confianza:

[mcp_servers.game_assets]
command = "node"
args = ["C:\\path\\to\\game-asset-finder-mcp\\dist\\index.js"]
cwd = "C:\\path\\to\\game-asset-finder-mcp"
startup_timeout_sec = 30
tool_timeout_sec = 90
enabled = true

[mcp_servers.game_assets.env]
GAME_ASSET_LOCAL_ROOTS = "D:\\GameAssets;E:\\SharedAssets"
GAME_ASSET_CACHE_TTL_SECONDS = "600"

Si se habilita Freesound, se recomienda reenviar la clave desde el entorno local en lugar de escribir el valor en la configuración:

[mcp_servers.game_assets]
env_vars = ["FREESOUND_API_KEY"]

También se puede agregar el servidor stdio con la CLI de Codex:

codex mcp add game-assets -- node "C:\path\to\game-asset-finder-mcp\dist\index.js"
codex mcp list

Después de guardar la configuración, reinicie el cliente y use /mcp para ver el estado de la conexión. El archivo mcp-config.example.toml en el repositorio se puede copiar y modificar directamente.

Herramientas MCP

search_game_assets

Búsqueda entre fuentes. Parámetros principales:

{
  "query": "像素风地牢角色",
  "types": ["sprite", "tileset"],
  "sources": ["kenney", "opengameart", "itch"],
  "formats": ["png"],
  "tags": ["retro"],
  "license_policy": "commercial",
  "include_unknown_license": false,
  "limit": 12,
  "refresh": false
}

license_policy puede tomar:

  • any: muestra todos los resultados y marca explícitamente las licencias desconocidas.

  • commercial: solo mantiene licencias conocidas como comercializables; se puede usar include_unknown_license para incluir elementos desconocidos.

  • cc0: solo mantiene CC0 / Public Domain Mark.

  • no-attribution: solo mantiene elementos conocidos como comercializables que no requieren atribución.

Para la página siguiente, coloque el nextCursor devuelto exactamente en cursor, manteniendo los demás parámetros de consulta sin cambios. Continuar usando un cursor antiguo después de modificar las condiciones de consulta devuelve CURSOR_QUERY_MISMATCH.

hasMore indica que la instantánea actual del caché candidato tiene una página siguiente; no representa que todos los resultados históricos del sitio remoto hayan sido obtenidos. Si se necesitan resultados más profundos, es mejor reducir el alcance de palabras clave, tipo o fuente y volver a buscar.

get_game_asset

Lee el registro completo recién buscado:

{ "asset_id": "kenney:roguelike-characters" }

Devuelve fuente, autor, licencia, vista previa, variantes de archivo, fuentes espejo, motivo de coincidencia y texto de atribución que se puede incluir directamente en los créditos. Los elementos remotos se buscan primero y luego se leen; los elementos locales también se pueden leer directamente desde el índice.

list_asset_sources

Lista todos los proveedores, estado de habilitación, tipos de activos admitidos, requisitos de credenciales, configuración de caché y estado del índice local.

index_local_assets

Escanea GAME_ASSET_LOCAL_ROOTS:

{ "mode": "incremental", "max_files": 20000 }

incremental reutiliza SHA-256 para archivos cuyo tamaño y hora de modificación no hayan cambiado; rebuild recalcula todo. El índice se escribe en GAME_ASSET_DATA_DIR/local-assets.json y no modifica los archivos de activos.

Sidecar de activos locales

Coloque hero.png.asset.json o hero.asset.json junto a hero.png:

{
  "title": "Azure Knight",
  "description": "32x32 pixel hero with idle and run frames",
  "type": "sprite",
  "tags": ["player", "knight", "pixel-art"],
  "author": "Studio Name",
  "author_url": "https://example.com",
  "license": "CC-BY-4.0",
  "license_url": "https://creativecommons.org/licenses/by/4.0/",
  "source_url": "https://example.com/azure-knight"
}

Los archivos locales sin sidecar aún se pueden buscar, pero la licencia se muestra como desconocida.

Variables de entorno

Variable

Valor predeterminado

Descripción

GAME_ASSET_LOCAL_ROOTS

Vacío

Directorios raíz de activos locales; separados por ; en Windows, por : en macOS/Linux

GAME_ASSET_DATA_DIR

data en el proyecto

Directorio del índice local

GAME_ASSET_CACHE_TTL_SECONDS

600

Segundos de caché de consulta

GAME_ASSET_CACHE_MAX_ENTRIES

200

Número máximo de entradas en la caché de consulta

GAME_ASSET_PROVIDER_TIMEOUT_MS

15000

Tiempo límite por proveedor

GAME_ASSET_MAX_RESPONSE_BYTES

16777216

Límite de respuesta remota única

GAME_ASSET_MAX_RETRIES

2

Número de reintentos para errores 429/temporales

GAME_ASSET_MAX_LOCAL_FILES

20000

Límite predeterminado de archivos en el índice local

GAME_ASSET_DISABLED_SOURCES

Vacío

IDs de proveedor separados por comas

FREESOUND_API_KEY

Vacío

Clave API opcional de Freesound

Desarrollo y validación

npm run check
npm test
npm run test:unit
npm run test:mcp

Las pruebas cubren expansión de consultas en chino, identificación de tipos, políticas de licencia, normalización de URL, deduplicación, fusión de fallos de caché, fallos de proveedores parciales, paginación y cursores, indexación local incremental, y tools/list/tools/call reales con clientes MCP stdio.

Consejos de uso de resultados

MCP devuelve metadatos de descubrimiento y licencias de activos, no reemplaza los términos finales de las páginas fuente. Las licencias desconocidas se mantienen explícitamente como id: null; antes de publicar, se puede reducir el alcance con commercial, cc0 o no-attribution, y guardar la fuente y la atribución en get_game_asset.

Available Tools

4 tools
get_game_assetGet game asset detailsA
Read-onlyIdempotent

Read the full normalized record for an asset returned by search_game_assets, including files, license guidance, alternates, and attribution text.

Inputs: asset_id (required).

index_local_assetsIndex local game assetsA
Idempotent

Incrementally scan GAME_ASSET_LOCAL_ROOTS, hash changed files, read optional .asset.json metadata, and atomically refresh the local search index. Symbolic links are skipped.

Inputs: mode, max_files.

list_asset_sourcesList game asset sourcesA
Read-onlyIdempotent

List provider ids, supported asset kinds, enablement state, local index state, and active limits.

Inputs: no named parameters.

search_game_assetsSearch game assetsA
Read-onlyIdempotent

Search enabled remote and local game-asset sources concurrently. Results are normalized, license-filtered, relevance-ranked, de-duplicated, source-diversified, cached, and cursor-paginated.

Inputs: query (required), tags, limit, types, +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct purpose: search, get details, list sources, and index. There is no overlap in functionality, making it easy for an agent to select the right tool.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (get_game_asset, list_asset_sources, search_game_assets, index_local_assets). This predictable structure aids agent understanding.

    Tool Count5/5

    Four tools cover the essential operations for a game asset finder: search, get detail, list sources, and index local assets. The count is well-scoped for the server's stated purpose.

    Completeness5/5

    The tools provide a complete workflow: index local assets, search across sources, retrieve detailed records, and list source info. No obvious gaps exist for the domain of finding and retrieving game assets.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A local MCP server for Nexus Mods mod discovery and research, backed by the v2 GraphQL API, enabling search of games, mods, collections, and users.
      61 npm
      1
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that aggregates web search results from multiple engines and optionally renders pages to Markdown, providing a unified search interface.
      3
      ISC