Game Asset Finder MCP

게임 개발을 위한 '검색 우선' MCP 서비스입니다. 여러 공개 에셋 소스와 선택적 로컬 에셋 라이브러리를 동시에 쿼리하여, 각 사이트의 결과를 동일한 필드로 통합하고, 중국어 키워드 확장, 라이선스 정규화, 관련성 정렬, 소스 간 중복 제거, 소스 다양화, 캐싱 및 커서 기반 페이지네이션을 수행합니다.

이 프로젝트는 현재 MCP TypeScript SDK v2를 기반으로 하며, stdio를 사용하여 실행되며, Codex, ChatGPT 데스크톱 및 기타 로컬 MCP를 지원하는 클라이언트에 적합합니다.

설계 및 최적화

프로젝트는 provider 레지스트리와 통합 결과 모델을 채택하고, 소스 간 검색 레이어에 중점을 두고 최적화했습니다:

• 단일 소스의 실패가 전체 검색을 중단시키지 않으며, 응답에 각 소스의 상태가 명확히 표시됩니다.

• 키워드 가중치와 중/영 게임 용어 확장으로 중국어 쿼리의 재현율을 향상시켰습니다.

• TTL/LRU 캐시, 동일 동시 요청 병합, provider 전체 시간 제한, 제한된 재시도 및 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

모든 provider, 활성화 상태, 지원되는 에셋 유형, 자격 증명 요구 사항, 캐시 구성 및 로컬 인덱스 상태를 나열합니다.

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 정규화, 중복 제거, 캐시 스탬피드 병합, 부분 provider 실패, 페이지네이션 및 커서, 로컬 증분 인덱스, 그리고 실제 stdio MCP 클라이언트의 tools/list / tools/call을 다룹니다.

결과 사용 팁

MCP는 에셋 발견 및 라이선스 메타데이터를 반환하며, 소스 페이지의 최종 약관을 대체하지 않습니다. 알 수 없는 라이선스는 명확히 id: null로 유지됩니다. 배포 전에 commercial, cc0 또는 no-attribution으로 범위를 좁히고, get_game_asset에서 소스 및 저작자 표시 정보를 저장할 수 있습니다.