Game Asset Finder MCP

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

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

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.