game-asset-mcp

AI 에이전트가 참조 이미지, 메시, PBR 텍스처, 출처 기록까지 게임용 3D 에셋을 처음부터 끝까지 제작하고, 이미 보유한 메시에 텍스처를 다시 입힐 수 있게 해주는 MCP 서버입니다.

대부분의 에셋 생성 도구는 "프롬프트를 입력하면 메시가 나온다"에서 멈춥니다. 그것은 쉬운 절반입니다. 실제로 프로젝트를 막는 절반은 이미 보유한 메시입니다. 지난주에 모델링한 키트배시, 아트 디렉션에 맞지 않는 머티리얼을 가진 마켓플레이스 소품, 금요일까지 부식된 강철처럼 보여야 하는 그레이박스. texture_existing_asset은 사용자가 제공한 메시에 새 PBR 머티리얼을 적용하며, 이미 승인한 지오메트리는 재생성하지 않습니다.

모든 것이 기록됩니다. 모든 작업은 프롬프트, 시드, 제공자 모델 버전, 제공자 작업 ID, 그리고 다운로드된 모든 바이트의 SHA-256을 보관합니다. 그래서 6개월 후에도 "이 파일은 무엇으로 만들었지?"라는 질문에 답할 수 있습니다.

이 서버는 구조적으로 제공자(provider)에 독립적입니다. 현재는 3D용 Tripo와 참조 이미지용 Leonardo.Ai를 두 개의 작은 인터페이스(ImageProvider, Model3DProvider) 뒤에서 구동합니다. 제공자를 추가해도 도구 표면은 변하지 않습니다. 이런 구조로 만든 이유는 docs/architecture.md를 참조하세요.

요구 사항

• Node.js >= 18.17 — 서버는 전역 fetch, FormData, Blob, AbortController를 사용합니다.

• 네이티브 모듈, 빌드 도구 체인, 데이터베이스가 필요 없습니다. Node가 실행되는 곳이라면 어디서든 동작합니다.

• 제공자 API 키가 하나 이상 필요합니다 (Configuration 참조). 하나면 충분합니다 — 지연(lazy) 검증 방식입니다.

설치

영구 설치 없이 바로 실행:

npx game-asset-mcp

또는 프로젝트에 설치:

npm install game-asset-mcp

또는 소스에서 빌드:

git clone https://github.com/<your-account>/game-asset-mcp.git
cd game-asset-mcp
npm install
npm run build     # emits dist/
node dist/server.js

서버는 stdio를 통해 MCP를 사용합니다. 터미널에서 직접 시작하면 클라이언트가 연결할 때까지 대기 상태로 있을 뿐입니다 — 이는 멈춤이 아니라 정상 동작입니다. 로그는 stderr로 출력되며, stdout은 프로토콜 전용입니다.

설정

.env.example을 .env로 복사하거나, MCP 클라이언트의 env 블록에 변수를 설정하세요 (보통 후자가 더 좋은 방법입니다 — 아래 스니펫 참조).

⚠️ Tripo API 크레딧은 Tripo Studio 구독과 별도로 청구됩니다

이것 때문에 거의 모든 사람이 걸려 넘어집니다. Tripo Studio 웹 구독은 API 호출 비용을 충당하지 않습니다. 둘은 서로 다른 제품이고 잔액도 다릅니다. Studio 웹 앱에서 모델을 잘 생성해 오다가 첫 create_3d_asset 호출이 크레딧 부족으로 거부되더라도 설정을 잘못한 것이 아닙니다 — 개발자 플랫폼에서 API 크레딧을 구매해야 합니다. Studio 앱이 아닌 platform.tripo3d.ai에서 구매하세요.

제공자 하나면 충분합니다

자격 증명은 지연(lazy) 검증됩니다. 도구가 필요로 하는 순간에만 검증하며, 시작 시에는 절대 검증하지 않습니다. TRIPO_API_KEY만 설정하면 서버는 정상적으로 시작되고 모든 3D 도구가 동작합니다. 이미지 도구는 누락된 변수 이름을 명시하는 명확한 CONFIG_MISSING 오류를 반환합니다. 반대의 경우도 마찬가지입니다. 파이프라인의 절반만 사용하려는데 원하지도 않는 계정을 만들도록 강요받지 않습니다.

MCP 클라이언트 설정

Claude Code / Claude Desktop

MCP 설정에 추가하세요 (claude_desktop_config.json, 또는 Claude Code의 경우 프로젝트의 .mcp.json):

{
  "mcpServers": {
    "game-asset": {
      "command": "node",
      "args": ["/absolute/path/to/game-asset-mcp/dist/server.js"],
      "env": {
        "TRIPO_API_KEY": "tsk_...",
        "LEONARDO_API_KEY": "...",
        "ASSET_OUTPUT_DIR": "/absolute/path/to/your/project/assets/generated",
        "ASSET_LOG_LEVEL": "info"
      }
    }
  }
}

args와 ASSET_OUTPUT_DIR에는 절대 경로를 사용하세요. MCP 클라이언트의 작업 디렉터리는 생각하는 그 위치가 아니며, 상대 출력 디렉터리를 사용하면 에셋이 예상치 못한 곳에 흩어집니다.

기타 MCP 클라이언트

동일한 서버를 일반적인 방식으로 설명하면 — stdio 자식 프로세스:

{
  "name": "game-asset",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "game-asset-mcp"],
  "env": {
    "TRIPO_API_KEY": "tsk_...",
    "LEONARDO_API_KEY": "...",
    "ASSET_OUTPUT_DIR": "/absolute/path/to/assets/generated"
  }
}

사용 가능한 도구

비용이 드는 도구는 5개뿐이며, 각 도구는 호출되기 전에 설명에서 이를 명시합니다.

예제 워크플로우

전체 파이프라인: 아이디어에서 검사된 에셋까지

1. generate_asset_reference   → spends image credits, returns assetJobId + N candidates
2. (inspect the images)       → look at the returned reference images and choose one
3. select_reference           → free; records which candidate wins
4. create_3d_asset            → spends 3D credits, returns a task to poll
5. get_asset_job              → free; poll until status is "ready" (or "failed")
6. download_asset             → free; pulls model + textures + previews into the workspace
7. inspect_asset              → free; confirms what actually landed on disk

2단계는 장식이 아닙니다. 3D 크레딧을 쓰기 전에 참조를 선택하는 것이 파이프라인이 여기서 나뉘는 이유입니다. 잘못된 참조는 녹아내린 메시를 만들고, 그 사실은 재구성 비용을 지불한 후에야 발견하게 됩니다.

리텍스처링: 더 짧고, 더 저렴하며, 대부분의 도구가 제공하지 않는 흐름

메시는 이미 있습니다. 참조할 것도, 선택할 것도, 재구성할 것도 없습니다:

1. texture_existing_asset     → spends texturing credits on a mesh you supply
2. get_asset_job              → free; poll until ready
3. download_asset             → free
4. inspect_asset              → free

유료 호출이 두 번 대신 한 번이고, 이미 승인한 지오메트리는 변경 없이 그대로 돌아옵니다.

비용 및 부작용

제공자 크레딧을 소모하는 호출: generate_asset_reference, generate_reference_variations, create_3d_asset, texture_existing_asset, 그리고 create_game_prop 내부의 이미지 생성 단계. 이 서버에서 그 외의 어떤 것도 비용이 청구될 수 없습니다.

무료 호출: select_reference, get_asset_job, download_asset, inspect_asset, list_asset_jobs. 원하는 만큼 폴링하고 다운로드하세요.

크레딧을 소모하는 POST는 자동으로 재시도되지 않습니다. 이는 의도적이고 핵심적인 규칙이며, 각 호출 지점이 아닌 HTTP 계층에 존재합니다. 생성 작업을 만드는 요청이 실패했을 때(타임아웃, 소켓 리셋, 502) 클라이언트는 연결이 끊기기 전에 제공자가 요청을 수락했는지 알 수 없습니다. 재시도는 무료일 수도 있고, 받지도 못할 메시에 대해 이중 청구될 수도 있습니다. 따라서 재시도하지 않고 오류를 그대로 반환하며, 다시 시도할지 여부는 사용자의 결정입니다. 멱등성 읽기(상태 폴링, 파일 다운로드)는 반복해도 비용이 들지 않으므로 백오프와 함께 자유롭게 재시도합니다.

알아두면 좋은 다른 부작용:

• 파일이 디스크에 기록됩니다. 모든 것은 ASSET_OUTPUT_DIR 아래에 저장됩니다. 그 외부에는 아무것도 기록되지 않습니다: 경로는 확인되며 작업 공간 루트를 벗어나는 경로는 거부됩니다.

• 아무것도 조용히 덮어쓰지 않습니다. 이름이 충돌하는 에셋은 이미 검토한 결과를 파괴하는 대신 숫자 접미사(crate, crate_2, …)를 받습니다.

• 다운로드에는 상한이 있습니다. ASSET_MAX_DOWNLOAD_BYTES로 제한되며, Content-Length 헤더가 아닌 스트리밍 중에 강제됩니다 — 크기를 속이는 서버가 메모리를 고갈시킬 수 없습니다.

• HTTPS만 허용됩니다. HTTPS가 아닌 URL은 제공자 응답 내부에 포함된 것까지 포함해 완전히 거부됩니다.

• API 키는 로그에서 중앙 집중식으로 마스킹됩니다. 따라서 개별 로그 호출 지점에서 키가 유출될 수 없습니다.

작업 공간 구조

모든 에셋은 자체 포함된 디렉터리를 받습니다. 6개월 후 파일 브라우저에서 열어도 그 자체로 설명이 됩니다:

assets/generated/
├── .jobs/                          job records, one JSON file per job
│   └── asset_<uuid>.json
└── <asset_name>/
    ├── asset.json                  complete provenance: spec, prompt, seed,
    │                               model version, provider ids, file hashes
    ├── source/                     the reference image(s) the mesh was built from
    ├── model/                      the mesh (GLB by default)
    ├── textures/                   extracted PBR maps
    ├── previews/                   provider-rendered turnarounds
    └── metadata/                   raw provider payloads, kept for debugging

<asset_name>은 스펙의 이름을 정리한 것입니다: 소문자로 변환하고, 영숫자가 아닌 문자는 밑줄로 축약합니다. .jobs 디렉터리는 의도적으로 점(dot) 디렉터리입니다 — 에셋 작업 공간을 탐색할 때 장부가 아닌 에셋이 보여야 하기 때문입니다.

문제 해결

모든 오류는 기계가 읽을 수 있는 code와 retryable 플래그를 포함하므로, 에이전트가 문장을 파싱하지 않고 다음 행동을 결정할 수 있습니다.

CONFIG_MISSING — 자격 증명 누락. 호출한 도구가 설정하지 않은 제공자를 필요로 합니다. 메시지에 정확한 환경 변수 이름이 명시됩니다. MCP 클라이언트의 env 블록에 설정하고 클라이언트를 재시작하세요 — .env 파일은 서버의 작업 디렉터리가 생각하는 위치에 있을 때만 읽히며, MCP 클라이언트에서는 보통 그렇지 않습니다.

PROVIDER_HTTP 상태 401/403 — 잘못된 API 키. 키가 틀렸거나, 폐기되었거나, 다른 제공자의 키입니다. 두 가지 특정 함정: Leonardo 키는 계정에 API 액세스가 활성화되어 있어야 합니다(웹 로그인만으로는 부여되지 않습니다). 그리고 API 크레딧 잔액이 없는 Tripo 키는 키 자체는 유효해도 첫 유료 호출에서 실패할 수 있습니다. 위의 크레딧 경고를 참조하세요.

RATE_LIMITED — HTTP 429. 재시도 가능으로 표시됩니다. 폴링과 다운로드는 백오프 후 자동으로 재시도합니다(400ms, 800ms, 1600ms, 최대 8초). 생성 요청은 그렇지 않습니다. 비용이 발생하므로, 제한이 해제된 후 의도적으로 직접 재시도하세요.

PROVIDER_TASK_FAILED — 작업이 공급자 측에서 실패했습니다. HTTP 호출은 성공했지만 생성은 실패했습니다. 공급자의 자체 메시지는 오류 세부 정보에 보존됩니다. 콘텐츠 검열 거부도 여기에 해당합니다. 변경 없이 재시도하지 말고 프롬프트를 다시 작성하세요. Tripo 응답은 HTTP 200과 함께 0이 아닌 봉투 code를 전달할 수 있습니다. 이는 실패이며, 이 서버는 가짜 성공으로 보고하는 대신 실패로 처리합니다.

PROVIDER_HTTP 403/404로 다운로드 실패 — URL이 만료되었습니다. 이것이 가장 흔한 예상 밖의 상황입니다. 공급자 모델 및 미리보기 URL은 수명이 짧습니다. 서명되어 있고 만료되며, 20분 전에 작동했던 URL이 이제는 죽어 있습니다. 해결책은 동일한 URL을 재시도하는 것이 아니라 — get_asset_job을 다시 호출하여 공급자에게 새 URL을 다시 폴링한 다음, 즉시 download_asset을 호출하는 것입니다. 습관으로: 작업이 ready를 보고하는 즉시 다운로드하고, 긴 세션이 끝날 때까지 기다리지 마세요.

INVALID_INPUT — 지원되지 않는 이미지 형식. 참조 이미지는 표준 웹 안전 래스터 형식(PNG, JPEG, WebP)이어야 합니다. HDR, EXR, 레이어드 PSD, SVG 및 다중 페이지 TIFF는 재구성 가능한 입력이 아닙니다. texture_existing_asset의 경우 메시는 GLB, GLTF, FBX, OBJ 또는 STL이어야 합니다. 먼저 변환하세요. 공급자가 대신 변환해 주지 않습니다.

PROVIDER_MALFORMED_RESPONSE — 공급자가 예상치 못한 응답을 반환했습니다. JSON이 아닌 본문, 빈 봉투, 데이터 없는 성공, 또는 파일 토큰을 반환하지 않은 업로드. 일반적으로 공급자 측 장애 또는 API 버전 차이를 의미합니다. ASSET_LOG_LEVEL=debug를 설정하여 요청 형태를 확인하고(키는 마스킹됨), 버그가 로컬이라고 가정하기 전에 공급자의 상태 페이지를 확인하세요.

DOWNLOAD_TOO_LARGE. 파일이 ASSET_MAX_DOWNLOAD_BYTES를 초과했습니다. 고품질 PBR GLB는 클 수 있습니다. 파일이 정말로 필요하다면 한도를 높이세요.

PATH_ESCAPE. 공급자가 제공한 파일 이름이 작업 공간 밖으로 해석되려고 했습니다. 쓰기가 거부되었습니다. 정상 작동 중에는 발생해서는 안 됩니다. 발생한다면 이슈를 열어 주세요.

상태

이것은 초기 단계 소프트웨어이며, 변경될 가능성이 가장 높은 부분은 조용히 가정하지 않고 그렇게 표시되어 있습니다.

Tripo의 v3 엔드포인트 경로는 정확히 하나의 모듈(src/providers/model3d/tripo.ts)에 고정되어 있으며 해당 모듈 상단의 주석에 문서화되어 있습니다. Tripo의 공개 문서는 v3 표면을 두 가지 방식으로 설명합니다 — 일반 작업 엔드포인트와 작업별 경로 — 그리고 둘 다 현재 문서에 나타납니다. 이 클라이언트는 작업 형식을 구현하며, 이는 모든 생성이 폴링할 task_id를 반환한다는 관찰 가능한 동작과 일치하고, 코드를 수정하지 않고 대상을 변경할 수 있도록 TRIPO_BASE_URL을 노출합니다. 경로는 라이브 스모크 테스트가 가장 먼저 확인하는 항목입니다. 잘못된 경로는 잘못된 API 키와 똑같이 보이는 404를 반환하기 때문입니다.

라이브 공급자 API에 대한 호출은 한 번도 이루어진 적이 없습니다. 이것이 여기서 가장 중요한 주의 사항이므로 묻어두지 않고 명확히 명시합니다. 165개의 테스트는 모두 목(mock) 또는 로컬 파일 시스템에 대해 실행됩니다. 프롬프트 구성, 상태 매핑, 경로 안전성, 작업 저장소, HTTP 계층의 재시도 및 리디렉션 규칙, 실제 파일에 대한 glTF 검사를 다루지만 — 녹색 스위트는 Leonardo와 Tripo가 이 클라이언트가 가정하는 방식으로 동작한다는 것을 말해주지 않습니다.

구체적으로 다음은 검증되지 않은 상태입니다:

• 위에서 설명한 Tripo v3 엔드포인트 경로.

• texture_model이 업로드된 메시(file_token)를 허용하는지, 아니면 이전 Tripo 작업에서 생성된 메시(original_model_task_id)만 허용하는지. 이는 이미 소유한 모델을 리텍스처링할 수 있는지 여부를 결정하며, 이것이 이 서버가 존재하는 기능입니다. 해결하는 데 HD 텍스처 호출 한 번이 소요됩니다.

• src/providers/image/leonardo.ts의 Leonardo 모델 ID는 게시된 문서에서 전사한 것입니다. GET /platformModels와 대조하여 확인하세요. 오래된 ID는 잘못된 요청 본문처럼 보이는 HTTP 400으로 실패합니다. LEONARDO_MODEL_ID와 호출별 modelId 모두 탈출구로 존재합니다.

실제 키로 이 서버를 실행하는 첫 번째 사람이라면 엔드포인트 경로를 수정해야 할 것으로 예상하고, 발견한 내용으로 이슈를 열어 주세요.

검증된 것: npm run verify는 서버를 빌드하고, 실제 MCP 클라이언트로 stdio를 통해 시작하고, 핸드셰이크를 완료하고 11개 도구가 모두 등록되는지 확인합니다. 이는 버전 문자열이 아닌 프로토콜 왕복입니다. 도구 등록에 실패한 서버도 여전히 정상적으로 시작되기 때문입니다.

기여

이슈와 풀 리퀘스트를 환영합니다. 공급자를 추가하는 경우 ImageProvider 또는 Model3DProvider를 구현하고 다른 것은 변경하지 마세요. 새 공급자가 도구 표면의 변경을 강요한다면 추상화가 잘못된 것이며, 그것이 먼저 논의할 가치가 있는 버그입니다.

라이선스

MIT © 2026 Ben Haire. LICENSE 참조.