fvtt-mcp-artificer

Foundry 특화 이미지 생성 Model Context Protocol 서버로, D&D 테이블 아트를 위해 Claude Code로 구동됩니다. 로컬 머신의 헤드리스 ComfyUI 인스턴스를 감싸고, Foundry에 맞춰진 작은 도구 세트를 노출하여 Claude가 프롬프트를 작성하고, 일러스트레이션 배치를 생성하고, 결과를 직접 눈으로 보며 선별하고, 선택된 결과물을 자매 서버인 fvtt-mcp-molten5e의 Foundry 파이프라인(upload-asset → set-actor-art / add-journal-image / 장면 배경)에 넘길 수 있게 합니다.

전체 루프는 대상 하드웨어(RTX 5090)에서 대화형으로 쓰기에 충분히 빠릅니다. 6개 이미지 초안 배치는 ~10초, 완성된 2560×1600 렌더는 ~19초, 그리고 전체 prompt → draft → curate → final → in-world-journal 주기는 notes/m3-loop-proof.md에서 종단 간 검증되었습니다.

이런 형태를 쓰는 이유

이것은 설계상 일반적인 ComfyUI 브리지가 아닙니다. 도구는 Foundry 어휘(액터 초상화, 토큰, 핸드아웃, 장면 배경)를 사용하며 Foundry 작업에 맞게 자유롭게 조정됩니다. 또한 fvtt-mcp-molten5e와 분리되어 있습니다. 그 서버는 Foundry 콘텐츠 저작에 한정되며 이미지 생성과 결합해서는 안 됩니다. 이 서버는 Foundry 브리지와 통신하지 않습니다. 둘 사이의 핸드오프는 디스크의 파일과 molten5e 업로드 도구로 이루어집니다.

다른 제품군과 같은 하우스 철학: 도구는 실행하고, 스킬은 결정합니다. 정확성(워크플로 실행, 치수, 업스케일 파이프라인, 파일 규칙)은 여기서 테스트된 도구에 있고, 판단(프롬프트 작성, 선별 취향, 어떤 액터나 저널에 아트를 넣을지, 하우스 스타일)은 이후의 illustration-builder 스킬에 있습니다.

Claude ──MCP──> fvtt-mcp-artificer ──HTTP──> ComfyUI (headless, local)
                      │
                      └── pinned workflow JSONs (draft / final / final-refine / upscale)

ComfyUI는 API 모드에서 헤드리스로 실행됩니다. 이 서버는 workflows/ 아래의 고정 workflow JSON을 제출합니다 — 절대 자유 형식 그래프가 아닙니다 — 프롬프트/시드/배치/프리셋이 대입됩니다(노드 ID 기준, 클래스 타입 드리프트 어서션으로 보호). 도구는 절대 파일 경로를 반환하며, Claude는 PNG를 직접 읽어 선별합니다.

Related MCP server: FoundryVTT MCP Server

용도 프리셋이지, 원시 해상도가 아닙니다

generate-image는 너비/높이가 아니라 kind를 받습니다:

해상도 파이프라인(고정): 출력 크기로는 절대 생성하지 마십시오 — ~1.5MP를 넘어가면 구도가 저하됩니다. 프리셋의 기본 해상도로 생성한 뒤 4x-UltraSharp로 모델 업스케일 ×4, lanczos 다운샘플로 완성 크기로 맞추며, 모두 하나의 고정 그래프에서 처리됩니다.

모델

• FLUX.1-dev fp8 (Comfy-Org all-in-one) — 최종 품질 렌더, 완성까지 ~15–19초.

• FLUX.2-klein 4B (Apache 2.0) — 초안 모델: 4-step, 이미지당 ~1–2초, 배치 6–8, 선택 후 dev로 재렌더링.

• 4x-UltraSharp — 파이프라인 끝의 모델 업스케일러.

도구

도구와 고정 그래프 사이의 대입 계약은 workflows/README.md에 문서화되어 있습니다.

요구 사항

• Windows + NVIDIA GPU. RTX 5090에서 개발 및 검증되었습니다(Blackwell에는 CUDA 12.8+ PyTorch가 필요하며, 현재 ComfyUI 포터블 빌드에 포함되어 있습니다).

• ComfyUI(독립형 포터블 빌드, v0.34+)를 헤드리스로 실행 — 실행 규칙은 scripts/launch-comfyui.ps1을 참조하세요(127.0.0.1:8188의 API 모드, 고정 --output-directory).

• ComfyUI models/ 트리의 모델 파일들(~33GB, 모두 접근 제한 없음): checkpoints/flux1-dev-fp8.safetensors, diffusion_models/flux-2-klein-4b.safetensors, text_encoders/qwen_3_4b.safetensors, vae/flux2-vae.safetensors, upscale_models/4x-UltraSharp.safetensors. artificer-status가 누락 항목을 보고합니다.

• MCP 서버 자체를 위한 Node.js 22+.

빌드

npm install
npm run build

테스트: npm test(오프라인 유닛 스위트; 고정 workflow JSON이 픽스처). 라이브 스위트 — 실제 ComfyUI와 실제 렌더 — 는 npm run test:integration으로 게이트되어 있습니다. 품질 게이트: npm run typecheck, npm run check(biome), npm run knip.

Claude Code에 연결

하우스 규칙은 서버를 **사용자 범위(user scope)**로 등록합니다(새 MCP 도구 ⇒ Claude Code 재시작). CLI를 사용하거나:

claude mcp add -s user artificer -- node D:/path/to/fvtt-mcp-artificer/dist/index.js

또는 .mcp.json.example을 Claude Code가 읽는 .mcp.json으로 복사(또는 ~/.claude.json의 mcpServers에 병합)하고 절대 경로를 사용하세요. Windows에서 Node가 PATH에 없으면 command를 전체 node.exe 경로로 지정하세요.

구성

.env.example을 .env로 복사하세요(gitignore됨):

• COMFY_URL — 헤드리스 인스턴스(기본값 http://127.0.0.1:8188).

• COMFY_OUTPUT_DIR — ComfyUI가 시작될 때 사용한 --output-directory와 일치해야 합니다. 서버는 생성된 PNG를 이 경로에서 직접 읽습니다.

• ARTIFICER_TIMEOUT_MS — 작업별 대기 상한(기본값 300000).

라이선스

MIT License — 자세한 내용은 LICENSE를 참조하세요.