Game Asset Finder MCP

A "search-first" MCP service for game development. It queries multiple public asset sources and an optional local asset library simultaneously, unifies results from different sites into a common set of fields, and performs Chinese keyword expansion, license normalization, relevance sorting, cross-source deduplication, source diversification, caching, and cursor-based pagination.

The project is built on the current MCP TypeScript SDK v2, runs over stdio, and is suitable for Codex, ChatGPT Desktop, and other clients that support local MCP.

Design and Optimizations

The project uses a provider registry and a unified result model, with a focus on optimizing the cross-source search layer:

• A single source failure does not bring down the entire search; the response explicitly marks the status of each source.

• Keyword weighting and Chinese/English game term expansion improve recall for Chinese queries.

• TTL/LRU caching, deduplication of identical concurrent requests, per-provider timeouts, limited retries, and Retry-After support are implemented.

• Unified license filtering, canonical URL deduplication, merging of mirror sources, stable sorting, and source diversification are included.

• Pagination uses limit + nextCursor to avoid dumping a large number of results into the model context.

• Local indexing uses incremental scanning, SHA-256, atomic writes, root directory constraints, and symlink skipping.

• The tool surface is compressed to 4 tools, reducing the chance of the agent picking the wrong tool.

Related MCP server: @codesift/mcp

Data Sources

Any remote source may be temporarily unavailable or rate-limited. The sourceStatuses in the return value gives ok / partial / disabled / timeout / rate_limited / error for each source; other successful sources still return results.

Installation

Requires Node.js 20.18.1 or higher.

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

Alternatively, you can run:

.\install.ps1

Start directly:

node .\dist\index.js

stdio's standard output is the MCP JSON-RPC channel; service logs go only to standard error.

Integration with Codex

Add to ~/.codex/config.toml or a trusted project's .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"

If Freesound is enabled, it is recommended to forward the key from the local environment rather than writing the value into the configuration:

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

You can also add a stdio server using the Codex CLI:

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

After saving the configuration, restart the client and check the connection status with /mcp. The mcp-config.example.toml in the repository can be copied and modified directly.

MCP Tools

search_game_assets

Cross-source search. Main parameters:

{
  "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 can be:

• any: Show all results, explicitly marking unknown licenses.

• commercial: Keep only known commercially usable licenses; use include_unknown_license to bring back unknown items.

• cc0: Keep only CC0 / Public Domain Mark.

• no-attribution: Keep only items that are known to be commercially usable and do not require attribution.

To get the next page, put the returned nextCursor into cursor unchanged, keeping other query parameters the same. Using an old cursor after modifying query conditions will return CURSOR_QUERY_MISMATCH.

hasMore indicates whether there is a next page in the current cached candidate snapshot, not that all historical results from the remote site have been fetched; for deeper results, prioritize narrowing the keyword, type, or source range and re-search.

get_game_asset

Read the full record of an asset just searched:

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

Returns source, author, license, preview, file variants, mirror sources, match reason, and attribution text that can be directly added to credits. Remote entries are first searched, then read; local entries can also be read directly from the index.

list_asset_sources

List all providers, enabled status, supported asset types, credential requirements, cache configuration, and local index status.

index_local_assets

Scan GAME_ASSET_LOCAL_ROOTS:

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

incremental reuses SHA-256 for files whose size and modification time have not changed; rebuild recomputes everything. The index is written to GAME_ASSET_DATA_DIR/local-assets.json and does not modify asset files.

Local Asset Sidecar

Place hero.png.asset.json or hero.asset.json next to 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"
}

Local files without a sidecar can still be searched, but the license will be shown as unknown.

Environment Variables

Development and Verification

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

Tests cover Chinese query expansion, type recognition, license policy, URL normalization, deduplication, cache-bust merging, partial provider failure, pagination and cursors, local incremental indexing, and tools/list / tools/call with a real stdio MCP client.

Usage Tips for Results

MCP returns asset discovery and license metadata, not a substitute for the final terms on the source page. Unknown licenses are explicitly kept as id: null; before publishing, you can narrow down with commercial, cc0, or no-attribution, and save source and attribution information from get_game_asset.