PixelForge MCP

AI 생성 일러스트를 인게임 도트 스프라이트로 변환하는 파이프라인을 MCP(Model Context Protocol) 서버로 노출한 도구입니다. Claude·Cursor 같은 AI 에이전트가 Tool-use 로 직접 호출해, 배경제거 → 픽셀화 → 팔레트 통일 → 아웃라인 → 스프라이트시트 패킹을 자동화합니다.

여러 게임/앱 프로젝트에서 손으로 반복하던 "AI 일러 → 도트 스프라이트" 작업을 재사용 가능한 MCP 툴로 코드화한 것입니다. 아트 파이프라인 자동화 = TA(테크니컬 아트) 업무의 핵심 반복작업입니다.

왼쪽부터: 입력 일러스트(1024px) · 32px 스프라이트 · 64px 스프라이트+selout 아웃라인 · 2프레임 스프라이트시트. 전부 동일 배율 nearest 업스케일. uv run python examples/demo.py 로 재생성.

스튜디오 워크플로우: 캐릭터셋을 잠긴 공통 팔레트로 통일

위 = 캐릭터별 독립 팔레트(제각각) · 아래 = 잠긴 20색 공통 팔레트로 통일(인덱스 PNG 출력) · 맨 아래 = Aseprite 로 임포트되는 실제 .gpl 팔레트. build_palette 로 키아트에서 프로젝트 팔레트를 뽑아 batch_pixelize 에 넘기면 모든 에셋이 정확히 같은 색을 공유한다. 아트 코히어런스 = TA 자동화의 실제 가치. uv run python examples/palette_workflow.py 로 재생성.

애니메이션 — 컷아웃 스켈레탈 리깅 (진짜 프레임 애니)

<p> <img src="examples/sample/anim_humanoid_walk.gif" width="150" alt="walk cycle"> <img src="examples/sample/anim_humanoid_run.gif" width="150" alt="run cycle"> <img src="examples/sample/anim_humanoid_punch.gif" width="150" alt="punch"> </p>

캐릭터를 파트(몸통·머리·상완·하완·허벅지·정강이)로 나눠 부모-자식 관절 트리(FK)에 붙이고, 관절 회전을 키프레임으로 돌려 프레임마다 서로 다른 포즈를 합성한다 — Spine/DragonBones/Godot Cutout 방식. 2관절 팔다리라 무릎·팔꿈치가 굽는 진짜 gait(걷기·달리기·펀치). 한 장을 흔드는 워프가 아님. 결정적·오프라인. uv run python examples/rig_demo.py 로 재생성.

리그 킷(계약서) — 리깅용 아트를 규격에 맞게 뽑기. 사후에 완성 스프라이트를 자르는 건 항상 타협이라, 처음부터 리깅용으로 그리는 게 정답. export_rig_kit 은 배치 가이드 + 파츠별 생성 프롬프트 + rig.json 을 뱉는다. 아티스트/AI 가 이 규격(슬롯·크기·피벗)에 맞춰 아트만 그리거나 생성해 PNG 를 교체하면 animate_rig 이 walk/run/idle/punch 를 자동 렌더한다.

<img src="examples/sample/rig_kit_guide.png" width="220" alt="rig layout guide">

배치 가이드: 각 파츠 슬롯의 위치·크기 + 피벗(빨간 점). 이 규격대로 그리면 리그가 자동으로 물린다.

프레임 조립 — 포즈 프레임이 이미 있으면(아티스트·AI 생성) assemble_animation 이 N 프레임을 공통 스케일·단일 팔레트로 맞춰(깜빡임 방지) 스프라이트시트+타이밍JSON+GIF 로 조립한다. pixelize=False 면 이미 도트인 프레임을 색 보존해 팩만.

절차적 juice(보조) — animate 는 정적 스프라이트 한 장에 결정적 변형(bob/breathe/sway/hop/pulse)을 얹어 가벼운 idle 움직임을 만든다. 진짜 캐릭터 애니가 아니라 살아있는 느낌용 보조 툴.

왜 MCP 인가

같은 PIL 스크립트를 매번 복붙하는 대신 MCP 서버로 만들면, AI 에이전트가 대화 중에 직접 "이 일러스트 64px 도트로 만들고, 프로젝트 팔레트로 통일해서 8프레임 시트로 묶어줘" 같은 요청을 툴 호출로 수행합니다. 에이전트 워크플로우 안에서 아트 파이프라인이 한 단계로 흡수됩니다.

품질이 어디서 나오나 (naive resize 와의 차이)

픽셀화의 품질은 다운스케일을 어떻게 하느냐에서 갈립니다. img.resize() 한 줄로는 색이 탁해지고 가장자리에 검은 띠가 낍니다. PixelForge 는:

• 감마보정 선형광 다운스케일 — sRGB 를 선형광으로 디코드한 뒤 리샘플. sRGB 값을 그대로 평균하면 색이 어두워지고 머디해지는 문제를 제거.
• 프리멀티플라이 알파 리샘플 — 투명 영역이 피사체 가장자리 색을 오염시키지 않게, 알파를 곱한 뒤 리샘플하고 나눠서 복원.
• OKLab k-means 팔레트 — MEDIANCUT/FASTOCTREE 보다 지각적으로 정확한 팔레트. 색 램프(shadow→mid→highlight)가 뚜렷해져 '축소한 일러'가 아니라 '도트 스프라이트'로 읽힌다. (테스트로 median-cut 대비 OKLab 오차가 낮음을 검증)
• 실루엣 정리 — 리샘플이 남기는 튀는 픽셀·가시·1px 구멍을 despeckle/hole-fill 로 제거. 깨끗한 실루엣이 픽셀아트의 핵심.
• 하드 알파 + selout 아웃라인 — 반투명 가장자리는 칼같이. selout(선택적 아웃라인)은 각 테두리 픽셀을 맞닿은 실루엣 색을 어둡게(OKLab 명도만 낮춤) 칠해, 균일 검정보다 훨씬 프로다운 결과를 낸다.
• Bayer 정렬 디더(옵션) — 필요 시 밴딩을 규칙적 패턴으로 완화. FS 오차확산 같은 컨페티가 아니라 의도된 디더. 스프라이트 스케일에선 보통 off.
• OKLab 팔레트 스냅 — 큐레이션/추출 팔레트로 여러 에셋을 통일(코히어런스). OKLab 거리라 색상 드리프트 없음.

스튜디오 연동

실제 도트 스튜디오 파이프라인(Aseprite·게임 엔진)에 그대로 들어가도록:

• 인덱스 컬러 PNG 출력(indexed=True) — 픽셀아트 표준 형식. Aseprite 에서 바로 열어 편집·팔레트 스왑 가능, 용량 작음, 인덱스 0 = 투명.
• 팔레트 파일 export — .gpl(GIMP/Aseprite)·.hex(lospec)·스와치 PNG.
• 잠긴 공통 팔레트(build_palette → palette= 인자) — 캐릭터 키아트에서 프로젝트 팔레트를 뽑아 전체 에셋셋에 강제. 수백 개 에셋의 색 일관성을 자동 유지.
• 스프라이트시트 + JSON 메타데이터 — 프레임 좌표를 엔진 임포트용으로 함께 출력.

제공 툴 (18종)

툴	하는 일
pixelize	일러 → 고품질 도트 스프라이트 (감마보정 다운스케일 + OKLab k-means + 실루엣 정리 + selout 아웃라인, 옵션: 팔레트 잠금·인덱스 PNG·업스케일)
animate_rig	컷아웃 스켈레탈 리그로 진짜 프레임 애니 (걷기/공격 등 실제 팔다리 움직임) → 프레임+시트+타이밍JSON+GIF
create_demo_rig	빌트인 2족 리그(파트+스켈레톤+walk/idle/wave)를 저장 (저작 시작 템플릿)
export_rig_kit	리깅용 아트 제작 킷 — 배치 가이드 + 파츠 생성 프롬프트 + rig.json (규격에 맞춰 아트만 뽑으면 리그 자동)
assemble_animation	여러 포즈 프레임 → 공유 팔레트·공통 스케일로 애니 조립 (시트+GIF)
animate	정적 스프라이트에 절차적 juice (bob/breathe/sway/hop/pulse) — idle 보조용
list_motions	절차적 juice 모션 목록/설명
pixelize_pair	2프레임 애니를 공통 스케일·공유 팔레트로 함께 도트화 (깜빡임 방지)
remove_background	네 모서리 flood fill 로 단색/오프화이트 배경 투명화 (배경제거 모델 폴백)
autocrop	투명 여백을 잘라 피사체만 남김
build_spritesheet	여러 프레임을 균일 격자 시트로 패킹 + 프레임 좌표 JSON(엔진 임포트용)
build_palette	여러 키아트에서 잠긴 공통 팔레트 생성 → .gpl/.hex (프로젝트 색 통일용)
export_palette	단일 이미지 팔레트를 .gpl/.hex 로 추출 (Aseprite 임포트)
quantize_palette	해상도 유지한 채 색 수만 축소
extract_palette	이미지에서 대표 팔레트(헥스) 추출 + 스와치 PNG
snap_to_palette	큐레이션 팔레트로 스냅 (아트 코히어런스)
list_palettes	내장 팔레트 목록 (pico8 / sweetie16 / db16 / edg32)
batch_pixelize	폴더 전체를 동일/잠긴 팔레트로 일괄 픽셀화 (인덱스 PNG 지원)

설치 & 실행

uv sync                 # 의존성 설치 (mcp, pillow, numpy)
uv run --extra dev pytest -q   # 테스트 38종
uv run pixelforge-mcp   # MCP 서버 실행 (stdio)

Claude Desktop / Claude Code 에 등록

{
  "mcpServers": {
    "pixelforge": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/pixelforge-mcp", "run", "pixelforge-mcp"]
    }
  }
}

등록 후:

~/art/dragon.png 배경 제거하고 56px 도트로 만들어줘. 아웃라인 넣고, idle 프레임 dragon_b.png 도 같이 페어로 도트화해서 스프라이트시트 + 메타데이터로 묶어줘.

에이전트가 remove_background → pixelize_pair → build_spritesheet 를 순서대로 호출합니다.

설계

• color.py — 색 공간/리샘플링 코어 (감마, 프리멀티플라이 리샘플, OKLab, k-means 양자화, 실루엣 정리, selout 아웃라인, 팔레트 추출/스냅). 품질의 핵심.
• palettes.py — 큐레이션 레트로 팔레트 (PICO-8 / Sweetie16 / DB16 / EDG32).
• export.py — 인덱스 PNG / .gpl / .hex / 스와치 export, 팔레트 스펙 해석.
• rig.py — 컷아웃 스켈레탈 애니 엔진(FK 관절 트리 + 키프레임 + 파트 회전 합성) + 빌트인 템플릿(2관절 휴머노이드/단순 2족) + 배치 가이드·프롬프트 생성.
• animate.py — 절차적 juice 리그(bob/breathe/sway/wave/hop/pulse) + 루프 GIF 렌더.
• pipeline.py — 위를 조합한 순수 함수 (MCP 비의존, 단위 테스트 대상).
• server.py — FastMCP 로 파이프라인을 툴로 노출하는 얇은 래퍼.

코어/파이프라인/서버 분리 덕분에 MCP 런타임 없이 직접 실행·테스트할 수 있고, CLI·CI 에서도 재사용됩니다. 테스트 38종(색 왕복, k-means vs median-cut 오차, 실루엣 정리, 인덱스 PNG 왕복, 잠긴 팔레트 배치 일관성, 애니 프레임/GIF/타이밍, 컷아웃 2관절 워크/런 등)으로 커버.

라이선스

MIT. 내장 팔레트는 각 커뮤니티 표준(퍼블릭/CC0).