Game Asset Finder MCP

Ein suchorientierter MCP-Dienst für die Spieleentwicklung. Er durchsucht gleichzeitig mehrere öffentliche Asset-Quellen und eine optionale lokale Asset-Bibliothek, vereinheitlicht die Ergebnisse verschiedener Seiten in ein gemeinsames Feldenset und führt chinesische Schlüsselworterweiterung, Lizenznormalisierung, Relevanzsortierung, quellenübergreifende Deduplizierung, Quellenausgleich, Caching und Cursor-Paginierung durch.

Das Projekt basiert auf dem aktuellen MCP TypeScript SDK v2, läuft über stdio und ist für Codex, ChatGPT Desktop und andere Clients geeignet, die lokales MCP unterstützen.

Design und Optimierung

Das Projekt verwendet eine Provider-Registrierung und ein einheitliches Ergebnismodell und konzentriert sich auf die Optimierung der quellenübergreifenden Suche:

• Ein einzelner Quellenfehler bringt die globale Suche nicht zum Erliegen; die Antwort markiert den Status jeder Quelle deutlich.

• Die Schlüsselwortgewichtung und die Erweiterung um chinesische und englische Spielbegriffe verbessern die Recall-Rate bei chinesischen Abfragen.

• Hinzufügen von TTL/LRU-Caching, Zusammenführen identischer gleichzeitiger Anfragen, Provider-Timeout, begrenzte Wiederholungen und Retry-After.

• Hinzufügen von einheitlicher Lizenzfilterung, URL-Normalisierung und Deduplizierung, Zusammenführen von Spiegelquellen, stabilem Sortieren und Quellenvielfalt.

• Verwendung von limit + nextCursor zur Paginierung, um zu vermeiden, dass eine große Anzahl von Ergebnissen auf einmal in den Modellkontext gepackt wird.

• Der lokale Index verwendet inkrementelles Scannen, SHA-256, atomares Schreiben, erlaubt Root-Verzeichnisbeschränkungen und Überspringen von symbolischen Links.

• Die Werkzeugoberfläche wurde auf 4 komprimiert, um die Wahrscheinlichkeit zu verringern, dass der Agent das falsche Werkzeug auswählt.

Related MCP server: @codesift/mcp

Datenquellen

Jede entfernte Quelle kann vorübergehend ausfallen oder gedrosselt werden. Das Feld sourceStatuses in der Antwort gibt pro Quelle ok / partial / disabled / timeout / rate_limited / error an; andere erfolgreiche Quellen liefern weiterhin Ergebnisse.

Installation

Erfordert Node.js 20.18.1 oder höher.

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

Sie können auch Folgendes ausführen:

.\install.ps1

Starten Sie direkt:

node .\dist\index.js

Die Standardausgabe von stdio ist der MCP JSON-RPC-Kanal; Dienstprotokolle werden nur in die Standardfehlerausgabe geschrieben.

Integration in Codex

Fügen Sie in ~/.codex/config.toml oder in .codex/config.toml eines vertrauenswürdigen Projekts hinzu:

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

Wenn Freesound aktiviert ist, wird empfohlen, den Schlüssel aus der lokalen Umgebung weiterzuleiten, anstatt den Wert in die Konfiguration zu schreiben:

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

Sie können auch mit der Codex CLI einen stdio-Server hinzufügen:

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

Nach dem Speichern der Konfiguration starten Sie den Client neu und überprüfen Sie den Verbindungsstatus mit /mcp. Die Datei mcp-config.example.toml im Repository kann direkt kopiert und geändert werden.

MCP-Tools

search_game_assets

Quellenübergreifende Suche. Hauptparameter:

{
  "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 kann sein:

• any: Zeigt alle Ergebnisse an und markiert unbekannte Lizenzen explizit.

• commercial: Behält nur bekannte kommerziell nutzbare Lizenzen; mit include_unknown_license können unbekannte zurückgegeben werden.

• cc0: Behält nur CC0 / Public Domain Mark.

• no-attribution: Behält nur bekannte kommerziell nutzbare und nennungsfreie Einträge.

Für die nächste Seite setzen Sie den zurückgegebenen nextCursor unverändert in cursor ein, während andere Abfrageparameter unverändert bleiben. Die Verwendung eines alten Cursors nach Änderung der Abfragebedingungen gibt CURSOR_QUERY_MISMATCH zurück.

hasMore gibt an, dass im aktuellen Cache-Kandidaten-Snapshot eine weitere Seite vorhanden ist, nicht dass alle historischen Ergebnisse der entfernten Site abgerufen wurden. Wenn tiefere Ergebnisse benötigt werden, priorisieren Sie die Eingrenzung von Schlüsselwörtern, Typ oder Quellenbereich und führen Sie eine erneute Suche durch.

get_game_asset

Liest den vollständigen Datensatz der gerade gefundenen Assets:

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

Gibt Quelle, Autor, Lizenz, Vorschau, Dateivarianten, Spiegelquellen, Übereinstimmungsgrund und den direkt in Credits verwendbaren Attributionstext zurück. Remote-Einträge werden nach der Suche gelesen; lokale Einträge können auch direkt aus dem Index gelesen werden.

list_asset_sources

Listet alle Provider, Aktivierungsstatus, unterstützte Asset-Typen, Anmeldeinformationen, Cache-Konfiguration und lokalen Indexstatus auf.

index_local_assets

Scannt GAME_ASSET_LOCAL_ROOTS:

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

incremental verwendet SHA-256 für Dateien mit unveränderter Größe und Änderungszeit wieder; rebuild berechnet alles neu. Der Index wird in GAME_ASSET_DATA_DIR/local-assets.json geschrieben, ohne die Asset-Dateien zu verändern.

Lokales Asset-Sidecar

Platzieren Sie neben hero.png eine Datei hero.png.asset.json oder 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"
}

Lokale Dateien ohne Sidecar können weiterhin durchsucht werden, aber die Lizenz wird als unbekannt angezeigt.

Umgebungsvariablen

Entwicklung und Validierung

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

Die Tests decken chinesische Abfrageerweiterung, Typenerkennung, Lizenzrichtlinien, URL-Normalisierung, Deduplizierung, Cache-Durchbruch-Zusammenführung, teilweisen Provider-Ausfall, Paginierung und Cursor, lokale inkrementelle Indizierung sowie tools/list / tools/call eines echten stdio MCP-Clients ab.

Hinweise zur Verwendung der Ergebnisse

MCP gibt Asset-Erkennung und Lizenzmetadaten zurück, ersetzt jedoch nicht die endgültigen Bedingungen der Quellseite. Unbekannte Lizenzen werden explizit als id: null beibehalten; vor der Veröffentlichung kann mit commercial, cc0 oder no-attribution der Bereich eingegrenzt werden, und die Quellen- und Zuschreibungsinformationen können in get_game_asset gespeichert werden.