game-asset-mcp

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

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

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

서버는 구조적으로 공급자에 구애받지 않습니다. 현재는 3D용 Tripo와 참조 이미지 및 사운드 효과용 Leonardo.Ai를 세 개의 작은 인터페이스(ImageProvider, Model3DProvider, AudioProvider) 뒤에서 구동합니다. 공급자를 추가해도 도구 표면은 바뀌지 않습니다. 이렇게 구축한 이유는 docs/architecture.md를 참조하세요.

요구 사항

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

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

• 선택 사항: 로컬 Blender 4.x+ 설치가 있으면 normalize_mesh와 batch_prepare_meshes의 복구 기능을 사용할 수 있습니다. 다른 모든 도구는 Blender 없이도 작동합니다. Blender가 없으면 도구가 지침과 함께 거부합니다. macOS에서는 Blender가 PATH에 없으므로 BLENDER_PATH를 설정하거나 번들된 /Applications/Blender.app 기본값을 사용하세요.

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

Related MCP server: Context3D MCP Server

설치

GitHub에서 직접 설치합니다. 두 방식 모두 설치 중에 TypeScript를 빌드하므로 어느 쪽이든 실행 가능한 game-asset-mcp 바이너리를 얻습니다.

# run it without installing anything permanently
npx github:theisegoria/game-asset-mcp

# or add it to a project
npm install github:theisegoria/game-asset-mcp

# pin a specific version — recommended for anything you depend on
npm install github:theisegoria/game-asset-mcp#v0.3.8

버전을 고정하세요. #vX.Y.Z 접미사가 없으면 두 방식 모두 그 시점의 main을 가리키므로 안정적인 의존성이 아닙니다. 모든 릴리스에는 태그가 붙어 있으므로 #v0.3.8은 정확히 그 트리를 가져옵니다. 릴리스는 github.com/theisegoria/game-asset-mcp/releases에 나열되어 있으며, 각 릴리스는 해당 릴리스가 수정한 결함을 함께 명시합니다.

⛔ v0.3.0, v0.3.1, v0.3.2를 고정하지 마세요. 이후 검토에서 이 버전들에 전달한 메시를 파괴하고 성공을 보고하는 라이브 경로가 발견되었습니다. 이 버전들은 기록을 완전하게 유지하기 위해 태그만 붙어 있습니다. 릴리스 페이지에도 그렇게 명시되어 있습니다.

또는 클론에서 작업할 수도 있습니다. 무엇이든 변경하려는 경우에 적합한 방식입니다:

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

npm에는 없습니다. npm install @theisegoria/game-asset-mcp는 존재하지 않습니다 — 패키지는 GitHub에서만 배포됩니다. 그 외의 말은 모두 오래된 정보입니다.

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

구성

MCP 클라이언트의 env 블록에 다음을 설정하세요 — 아래 스니펫을 참조하세요. .env 로딩은 없습니다: 서버는 process.env만 읽고 그 외에는 아무것도 읽지 않으므로, 디스크의 .env 파일은 셸이나 클라이언트가 먼저 내보내지 않는 한 아무 효과가 없습니다.

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

거의 모든 사람이 여기서 걸립니다. Tripo Studio 웹 구독은 API 호출에 자금을 지원하지 않습니다. 이 둘은 서로 다른 제품이며 서로 다른 잔액을 가집니다. Studio 웹 앱에서 모델을 즐겁게 생성하다가 첫 create_3d_asset 호출이 크레딧 부족으로 거부된다면, 잘못 구성한 것이 아닙니다 — 개발자 플랫폼에서 API 크레딧이 필요합니다. Studio 앱이 아닌 platform.tripo3d.ai에서 구매하세요.

지출 상한 설정

ASSET_SPEND_LIMIT_CENTS를 설정하면 모든 크레딧 소모 도구가 공급자에 연락하기 전에 확인합니다 — 메시나 참조 이미지를 업로드하기 전에도 포함됩니다. 남은 잔액을 명시하면서 초과 지출 대신 거부합니다. 상한은 미국 센트 단위인데, 두 공급자가 서로 다른 단위로 청구하기 때문입니다 — Tripo는 $0.01 크레딧, Leonardo는 USD — 두 단위를 혼합한 한도는 의미가 없습니다.

공급자가 호출당 가격을 공개하는 경우 그 가격을 사용합니다. 공개하지 않는 경우 가드는 의도적으로 보수적인 자리 표시자를 사용하며 get_spend_report는 어떤 수치가 어떤 것인지 알려줍니다. 이는 가드이지 청구서가 아닙니다: 실제 청구는 추정치 이하로 나와야 하며, 초과해서는 안 됩니다.

공급자 하나면 충분합니다

자격 증명은 지연 검증됩니다. 도구가 필요로 하는 순간에만, 시작 시에는 절대 검증하지 않습니다. 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", "github:theisegoria/game-asset-mcp"],
  "env": {
    "TRIPO_API_KEY": "tsk_...",
    "LEONARDO_API_KEY": "...",
    "ASSET_OUTPUT_DIR": "/absolute/path/to/assets/generated"
  }
}

사용 가능한 도구

비용이 발생할 수 있는 도구는 9개뿐이며, 각 도구는 호출되기 전에 설명에 그 사실을 명시합니다.

무료 로컬 절반 (API 키 없음, 네트워크 없음)

20개 도구 중 11개는 크레딧을 소모하지 않으며, 그중 네트워크를 사용하는 도구는 단 2개입니다 — get_asset_job은 폴링하고, download_asset은 가져옵니다. 둘 다 무료이지만 네트워크 호출입니다. 나머지 9개는 오프라인으로 작동합니다. 아래 5개는 메시 파이프라인이며, 이미 메시가 있다면 이 5개가 제품의 전부입니다.

일반적인 루프는 validate → normalize → validate 순서이므로, 복구가 가정이 아니라 증명됩니다:

validate_game_asset  modelPath=/art/crate.glb
   → fails: uvs_present   ("nothing can texture this")
normalize_mesh       modelPath=/art/crate.glb  outputDir=/art/out
   → objectsUnwrapped=2, triangles 3183 → 1750
validate_game_asset  modelPath=/art/out/crate_normalized.glb
   → passes

batch_prepare_meshes는 해당 루프를 목록에 대해 실행하고 각 항목을 개별적으로 보고합니다. 이미 통과한 메시는 다시 쓰지 않고 그대로 두며, 하나의 잘못된 파일이 실행을 중단하지 않고, 같은 기본 이름을 공유하는 두 소스는 서로 덮어쓰지 않고 별도의 출력을 얻습니다.

UV 누락이 알아둬야 할 결함입니다. UV 좌표가 없는 메시는 어떤 도구로도 텍스처를 입힐 수 없습니다 — 이 도구도, 공급자도, 직접 손으로도 불가능합니다. 생성기와 마켓플레이스 에셋은 정기적으로 UV 없이 배포됩니다. validate_game_asset이 그 이유로 이를 첫 번째로 명시합니다.

정규화에는 Blender(4.x+)가 필요합니다. 없으면 도구는 여전히 검증하고 보고하지만 복구는 할 수 없습니다. macOS에서 Blender는 PATH에 없으므로 BLENDER_PATH를 설정하거나 번들된 /Applications/Blender.app 기본값에 의존하세요.

예제 워크플로우

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

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

유료 호출 1회가 2회 대신이며, 이미 승인한 지오메트리는 변경 없이 그대로 돌아옵니다.

비용 및 부작용

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

무료 호출: select_reference, get_asset_job, download_asset, inspect_asset, list_asset_jobs, preview_asset_prompt, extract_pbr_trio, normalize_mesh, validate_game_asset, batch_prepare_meshes, get_spend_report. 원하는 만큼 폴링, 검사, 분할, 다운로드하세요.

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

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

• 파일은 디스크에 기록됩니다. 다운로드된 자산은 ASSET_OUTPUT_DIR 아래에 저장되며, 작업공간 루트를 벗어나는 다운로드 경로는 거부됩니다. 세 가지 도구는 의도적으로 다르게 동작합니다: extract_pbr_trio, normalize_mesh, batch_prepare_meshes는 작업공간 외부를 포함하여 사용자가 지정한 위치에 기록합니다. 이는 이미 소유한 메시를 대상으로 하며, 해당 메시는 자산 생성 디렉토리에 있지 않기 때문입니다. 의도한 대상 경로를 지정하세요.

• download_asset과 generate_sound_effect는 destination을 허용하며, 해당 호출 한 번에 대해 ASSET_OUTPUT_DIR을 재정의합니다. 여전히 제한됩니다: 주어진 루트를 벗어나는 경로는 거부됩니다.

• ASSET_OUTPUT_DIR은 절대 경로여야 합니다. 상대 경로는 MCP 클라이언트가 선택하는 서버의 작업 디렉토리를 기준으로 해석됩니다 — 여러 클라이언트는 /에서 시작합니다. 서버는 해석된 경로와 그 경로가 비롯된 작업 디렉토리를 명시하는 메시지와 함께 시작을 거부합니다. 이 진단은 현실적으로 발생할 수 있는 8가지 errno(ENOENT, EACCES, EPERM, EROFS, ENOTDIR, ELOOP, ENAMETOOLONG, ENOSPC)를 포함하며, ASSET_OUTPUT_DIR이 디렉토리가 아닌 파일을 가리키는 경우도 포함합니다. 다른 모든 오류는 원시 상태로 전파됩니다.

• 아무것도 조용히 덮어쓰지 않습니다. 파생된 출력 이름에는 숫자 접미사(crate, crate_2, ...)가 붙어 이미 검토한 결과를 파괴하지 않으며, 이름은 배타적 생성으로 확보되므로 한 배치의 두 항목이 경쟁할 수 없습니다. 명시적인 outputPath는 파일이 이미 있으면 overwrite: true를 전달하지 않는 한 무조건 거부됩니다. 그리고 입력 메시로 해석되는 경우에는 옵트아웃 없이 무조건 거부됩니다. 이 해석은 심볼릭 링크, 하드 링크, 대소문자 구분 없는 볼륨, 그리고 익스포터가 확장자를 다시 쓰는 습관을 모두 고려합니다. 이 모든 경우가 여기서 소스 메시를 파괴한 적이 있기 때문입니다.

• 다운로드는 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

<asset_name>은 사양의 이름을 정리한 것입니다: 소문자로 변환되고, 영숫자가 아닌 문자는 밑줄로 축약됩니다. .jobs 디렉토리는 의도적으로 점 디렉토리입니다 — 자산 작업공간을 탐색할 때 장부가 아닌 자산이 보여야 하기 때문입니다.

문제 해결

모든 오류는 클래스를 명명하는 기계 판독 가능한 error 필드와 retryable 플래그를 전달하므로, 에이전트는 문장을 분석하지 않고 다음에 무엇을 할지 결정할 수 있습니다. 아래 이름은 해당 error 필드의 값입니다.

서버가 시작되자마자 종료됩니다 — 클라이언트는 "connection closed"라고만 말합니다. 세 가지 알려진 원인이 있으며, 서버는 이제 조용히 죽는 대신 처음 두 가지를 스스로 명명합니다.

• 상대 경로 ASSET_OUTPUT_DIR. 이는 서버의 작업 디렉토리를 기준으로 해석되며, MCP 클라이언트가 선택합니다 — 여러 클라이언트는 /에서 시작하므로 assets/generated가 /assets가 되어 생성할 수 없습니다. 절대 경로를 사용하세요. 거부 메시지는 해석된 경로와 그 경로가 비롯된 작업 디렉토리를 명시합니다.

• 프로세스가 쓸 수 없는 작업공간. 동일한 거부, 다른 errno.

• 오래된 빌드. dist/가 엔트리 포인트 변경보다 이전이면 다시 빌드하세요. npm run verify는 빌드한 다음 실제 MCP 핸드셰이크를 완료하므로, 고장난 서버와 고장난 클라이언트 구성을 구분하는 가장 빠른 방법입니다.

normalize_mesh 또는 batch_prepare_meshes가 "Blender not found"로 거부합니다. PATH에 로컬 Blender가 없습니다. macOS에서는 Blender가 설치되어 있어도 앱 번들이 PATH에 없습니다 — BLENDER_PATH를 번들 내부의 실행 파일로 설정하세요. batch_prepare_meshes는 실패하는 대신 성능이 저하됩니다: 모든 메시를 검증하고 무엇을 수리해야 할지 보고합니다.

CONFIG_MISSING — 자격 증명 누락. 호출한 도구에 구성하지 않은 공급자가 필요합니다. 메시지는 정확한 환경 변수를 명명합니다. MCP 클라이언트의 env 블록에 설정하고 클라이언트를 다시 시작하세요. .env 파일은 절대 읽지 않습니다: dotenv 의존성이 없으므로 변수는 서버를 실행하는 프로세스가 내보내야 합니다.

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

RATE_LIMITED — HTTP 429. 재시도 가능으로 표시됩니다. 폴링은 백오프하고 자동으로 재시도합니다(400ms, 800ms, 1600ms, 최대 8초). 다운로드는 재시도하지 않습니다 — download_asset은 한 번의 시도로 스트리밍하므로 직접 다시 실행하세요; 공급자 URL은 만료되므로 오래된 URL을 재시도하는 대신 먼저 get_asset_job으로 다시 폴링하세요. 생성 요청도 의도적으로 재시도하지 않습니다. 비용이 들기 때문입니다. 다운로드 중 429는 RATE_LIMITED가 아닌 상태 429의 PROVIDER_HTTP로 표시됩니다.

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

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

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

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

• 사운드 이펙트 생성은 검증되지 않았습니다. Leonardo는 Sound Effects v2 요청 계약(model, prompt, duration 1-22초, prompt_influence, loop, quantity)을 문서화하지만 응답 형태나 완성된 오디오를 검색하는 방법은 문서화하지 않습니다. 클라이언트는 여러 그럴듯한 형태에서 생성 ID와 오디오 URL을 읽고, 일치하는 것이 없으면 빈 성공을 보고하는 대신 응답의 최상위 키 이름(본문이 아닌 — 본문은 크거나 서명된 URL을 가질 수 있음)을 첨부하여 예외를 던집니다. 첫 실제 호출에서 수정이 필요할 것으로 예상하고, 본 페이로드 형태로 이슈를 열어주세요.

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

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

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

로컬 파이프라인의 일부 — inspect_asset, extract_pbr_trio, normalize_mesh, validate_game_asset — 는 픽스처가 아닌 실제 출시 게임 자산에 대해 추가로 검사됩니다. 합성 픽스처와 이를 읽는 파서는 동일한 실수를 공유할 수 있고 둘 다 녹색으로 보일 수 있기 때문입니다. 여기서 실제로 발생했습니다: 잘못된 glTF 매직 상수가 전체 합성 스위트를 통과했고 실제 파일에서만 발견되었습니다. 이들이 사용하는 UV 없는 메시는 형제 체크아웃에서 읽는 대신 여기에 커밋되어 있습니다. 이전에는 게임 저장소에서 실시간으로 읽었는데, 해당 메시가 수리되었을 때 이 테스트는 완전히 올바른 변경에 대해 빨간색으로 바뀌었습니다 — 이 프로젝트가 제어하지 않는 파일에 대한 사실을 고정하는 단언이었습니다. 테스트는 소유하지 않은 콘텐츠에 의존할 수 없습니다.

하나의 테스트는 심볼릭 링크된 bin — 즉 node_modules/.bin이 실제로 포함하는 것 — 을 통해 빌드된 서버를 실행하고 MCP로 통신합니다. 엔트리 포인트 가드가 실패한 지점이 바로 그곳이기 때문입니다. 서버는 다른 모든 테스트를 통과하면서도 매 설치마다 즉시 종료되었습니다. 이 테스트는 설치 대신 심볼릭 링크를 사용하므로 files나 prepare의 패키징 회귀를 잡을 수 없습니다. GitHub에서 실제 npm install을 수행하는 것은 여전히 수동 확인 사항입니다.

테스트 수가 핵심이 아닌 이유

0.3.4에서는 이전 릴리스의 다섯 가지 주요 수정 사항을 각각 하나씩 되돌리고 스위트를 다시 실행했습니다. 다섯 가지 모두 살아남았습니다 — 모든 뮤턴트가 완전히 그린이었습니다. 수정 사항은 실제였고, 스위트에는 이를 붙잡는 것이 아무것도 없었습니다. 원인은 하나의 공유된 가정이었습니다. 모든 스텁된 Blender가 0으로 종료되고 정확히 하나의 영수증을 출력했기 때문에, 서브프로세스 프로토콜 강화 중 어느 것도 어떤 테스트로도 관찰할 수 없었습니다.

이것은 README에 명시할 가치가 있습니다. 어떤 테스트 수에 대한 정직한 해석이기 때문입니다. 스위트는 작성자의 가정을 증명하며, 가정 내부에 존재하는 결함은 그 가정 아래에서 작성된 모든 테스트에 보이지 않습니다. 변한 것은 수가 아니라 훈련입니다. 수정 사항은 이제 되돌린 코드에 대해 실행되어 실패하는 것이 관찰된 테스트로 고정되며, 공유된 페이크는 인프라가 아닌 용의자로 취급됩니다.

같은 검증이 한 자리에서 두 번이나 잘못된 증명을 잡아냈습니다. 용접 임계값 수정을 증명하기 위해 작성된 두 개의 연속된 픽스처가 코드가 올바를 때와 깨졌을 때 동일한 삼각형 수를 보고했고, 둘 중 하나라도 증거로 배포되었을 것입니다. 픽스처는 수정된 코드와 깨진 코드 양쪽에서 실행되고 두 숫자가 출력되기 전까지는 증명이 아닙니다.

기여

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

라이선스

MIT © 2026 Ben Haire. LICENSE 참조.