Game Asset Finder MCP

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

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

Любой удаленный источник может временно быть недоступен или ограничен. В возвращаемом значении 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 все равно можно искать, но лицензия будет отображаться как неизвестная.

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

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

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 сохранить информацию об источнике и авторстве.