Skip to main content
Glama
Game Asset Finder MCP

Game Asset Finder MCP

by sudoriaa

Game Asset Finder MCP

CI License: MIT

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

Проект основан на текущем MCP TypeScript SDK v2, работает через stdio и подходит для Codex, ChatGPT Desktop и других клиентов, поддерживающих локальный MCP.

Дизайн и оптимизация

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

  • Сбой одного источника не нарушает глобальный поиск, ответ четко помечает статус каждого источника.

  • Веса ключевых слов и расширение китайско-английских игровых терминов повышают полноту поиска по китайским запросам.

  • Добавлены TTL/LRU-кэш, объединение одновременных одинаковых запросов, общий таймаут провайдера, ограниченные повторные попытки и Retry-After.

  • Добавлены унифицированная фильтрация лицензий, дедупликация по нормализованным URL, объединение зеркальных источников, стабильная сортировка и диверсификация источников.

  • Используется пагинация limit + nextCursor, чтобы избежать загрузки большого количества результатов в контекст модели.

  • Локальный индекс использует инкрементальное сканирование, SHA-256, атомарную запись, ограничение корневых каталогов и пропуск символических ссылок.

  • Инструменты сжаты до 4, что снижает вероятность неправильного выбора инструмента агентом.

Related MCP server: @codesift/mcp

Источники данных

id

Содержание

Учетные данные

Особенности лицензий

kenney

2D, 3D, UI, аудио, шрифтовые наборы

Нет

CC0

opengameart

2D, 3D, музыка, звуковые эффекты

Нет

Разные для каждого элемента

itch

Список бесплатных игровых ресурсов

Нет

Разные для каждого автора/страницы

openverse

Изображения, текстуры, иконки для справки

Нет

CC / общественное достояние

ambientcg

PBR-материалы, HDRI, 3D

Нет

CC0

polyhaven

Текстуры, HDRI, 3D

Нет

CC0

freesound

Звуковые эффекты, записи

FREESOUND_API_KEY

Разные для каждого элемента

local

Локальные ресурсы в настроенном каталоге

Локальный каталог

Описывается sidecar-файлом

Любой удаленный источник может временно быть недоступен или ограничен. В возвращаемом значении sourceStatuses для каждого источника указывается ok / partial / disabled / timeout / rate_limited / error; другие успешные источники все равно возвращают результаты.

Установка

Требуется Node.js 20.18.1 или новее.

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

Также можно выполнить:

.\install.ps1

Запустить напрямую:

node .\dist\index.js

Стандартный вывод stdio — это канал MCP JSON-RPC, логи сервиса записываются только в стандартный поток ошибок.

Подключение к Codex

В ~/.codex/config.toml или .codex/config.toml доверенного проекта добавьте:

[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"

Если включен Freesound, рекомендуется передавать ключ из окружения хоста, а не записывать значение в конфигурацию:

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

Также можно добавить stdio-сервер с помощью Codex CLI:

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

После сохранения конфигурации перезапустите клиент, затем проверьте статус подключения с помощью /mcp. Файл mcp-config.example.toml в репозитории можно скопировать и изменить.

MCP-инструменты

search_game_assets

Кросс-источниковый поиск. Основные параметры:

{
  "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 может принимать значения:

  • any: показывать все результаты, явно помечая неизвестные лицензии.

  • commercial: оставлять только известные коммерчески допустимые лицензии; можно вернуть неизвестные с помощью include_unknown_license.

  • cc0: оставлять только CC0 / Public Domain Mark.

  • no-attribution: оставлять только известные коммерчески допустимые элементы без требования указания авторства.

Для следующей страницы передайте возвращенный nextCursor в cursor, остальные параметры запроса оставьте без изменений. Использование старого курсора после изменения условий запроса вернет CURSOR_QUERY_MISMATCH.

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

get_game_asset

Чтение полной записи только что найденного ресурса:

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

Возвращает источник, автора, лицензию, превью, варианты файлов, зеркальные источники, причину совпадения и текст для указания авторства, который можно использовать напрямую. Удаленные элементы сначала ищутся, затем читаются; локальные элементы можно читать напрямую из индекса.

list_asset_sources

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

index_local_assets

Сканирует GAME_ASSET_LOCAL_ROOTS:

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

incremental повторно использует SHA-256 для файлов, у которых не изменился размер и время модификации; rebuild пересчитывает все. Индекс записывается в GAME_ASSET_DATA_DIR/local-assets.json, файлы ресурсов не изменяются.

Sidecar для локальных ресурсов

Рядом с hero.png поместите hero.png.asset.json или hero.asset.json:

{
  "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"
}

Локальные файлы без sidecar все равно можно искать, но лицензия будет отображаться как неизвестная.

Переменные окружения

Переменная

Значение по умолчанию

Описание

GAME_ASSET_LOCAL_ROOTS

Пусто

Корневые каталоги локальных ресурсов; разделитель ; для Windows, : для macOS/Linux

GAME_ASSET_DATA_DIR

data в проекте

Каталог локального индекса

GAME_ASSET_CACHE_TTL_SECONDS

600

Время жизни кэша запросов в секундах

GAME_ASSET_CACHE_MAX_ENTRIES

200

Максимальное количество записей в кэше запросов

GAME_ASSET_PROVIDER_TIMEOUT_MS

15000

Таймаут для одного провайдера

GAME_ASSET_MAX_RESPONSE_BYTES

16777216

Максимальный размер одного удаленного ответа

GAME_ASSET_MAX_RETRIES

2

Количество повторных попыток при ошибках 429/временных ошибках

GAME_ASSET_MAX_LOCAL_FILES

20000

Максимальное количество файлов в локальном индексе

GAME_ASSET_DISABLED_SOURCES

Пусто

Список id провайдеров, разделенных запятыми

FREESOUND_API_KEY

Пусто

Опциональный ключ API Freesound

Разработка и проверка

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

Тесты охватывают расширение китайских запросов, определение типов, политику лицензий, нормализацию URL, дедупликацию, объединение при кэш-промахах, частичные сбои провайдеров, пагинацию и курсоры, инкрементальное индексирование локальных файлов, а также tools/list / tools/call для реального stdio MCP-клиента.

Советы по использованию результатов

MCP возвращает метаданные об обнаружении ресурсов и лицензиях, но не заменяет окончательные условия страницы источника. Неизвестные лицензии явно сохраняются как id: null; перед публикацией можно сузить диапазон с помощью commercial, cc0 или no-attribution, а в 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.
      82 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.
      6 npm
      3
      ISC