Game Asset Finder MCP

ゲーム開発向けの「検索優先」MCP サービスです。複数の公開アセットソースとオプションのローカルアセットライブラリを同時にクエリし、異なるサイトの結果を統一されたフィールドにまとめ、中国語キーワード拡張、ライセンス正規化、関連性ソート、クロスソース重複排除、ソース多様化、キャッシュ、カーソルページネーションを提供します。

このプロジェクトは現在の MCP TypeScript SDK v2 に基づき、stdio で動作し、Codex、ChatGPT デスクトップ版、その他ローカル 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"]

Codex CLI を使用して stdio サーバーを追加することもできます：

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 に書き込まれ、アセットファイルは変更されません。

ローカルアセットサイドカー

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

サイドカーのないローカルファイルも検索可能ですが、ライセンスは不明と表示されます。

環境変数

開発と検証

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

テストは、中国語クエリ拡張、タイプ識別、ライセンスポリシー、URL 正規化、重複排除、キャッシュ破綻マージ、部分的なプロバイダ障害、ページネーションとカーソル、ローカルインクリメンタルインデックス、および実際の stdio MCP クライアントの tools/list / tools/call をカバーしています。

結果使用のヒント

MCP が返すのはアセット発見とライセンスメタデータであり、ソースページの最終的な利用規約に代わるものではありません。不明なライセンスは id: null として明確に保持されます。公開前に commercial、cc0、または no-attribution で範囲を絞り込み、get_game_asset でソースと帰属情報を保存できます。