sprite-canon

AI가 생성한 게임 스프라이트가 하나의 게임처럼 보이게 유지하는 MCP 서버.

한 캐릭터, 세 벌의 의상 — 파란색과 빨간색 행은 sprite_repaint 호출이지 재생성이 아닙니다. 동일한 음영 순서, 동일한 실루엣, 매번 동일한 결과.

AI 생성기는 예쁜 스프라이트를 만드는 데는 뛰어나지만, 이전 것과 일치하게 만드는 데는 형편없습니다. 같은 캐릭터를 두 번 요청하면 팔레트가 어긋나고, 의상이 변형되며, 새 모자는 머리 위 3픽셀 위에 떠 있습니다 — 각 자산은 단독으로는 괜찮지만, 조합하면 게임이 어긋나 보입니다. "일치할 때까지" 재생성하는 것은 수렴하지 않으며, 비용만 소모하고 결과물을 비교할 수도 없습니다.

sprite-canon은 반대 접근 방식을 취합니다. 실제 게임 프로젝트에서 약 4,000프레임을 생성하면서 모든 교훈을 고통스럽게 얻은 경험에서 출발했습니다:

1. 일관성 규칙이 데이터가 됩니다 — 팔레트, 명명된 색상 영역(피부, 의상, 윤곽선…), 상대적 배율, 검사 임계값을 담은 sprite-canon.json("캐논")이 자산 옆에 커밋됩니다.

2. 검증은 숫자로, 시각적으로 하지 않습니다. 96가지 의상 변형 × 8방향 × 4프레임을 눈으로 확인할 수는 없습니다. sprite_verify는 실제로 문제가 되는 결함에 대해 명확한 통과/실패 수치를 반환합니다: 팔레트를 벗어난 픽셀, 프레임 간에 떨리는 액세서리, 뒤에서 보면 밝고 앞에서 보면 어두운 영역, 얼굴에 닿은 리페인트.

3. 수정은 결정적 픽셀 연산이지 재생성이 아닙니다. 영역을 새 색상 램프로 다시 칠하면 음영과 실루엣이 보존되고, 보호 영역에는 절대 닿지 않으며, 매번 동일한 결과를 생성합니다. 의상 변형은 프롬프트 복권이 아니라 도구 호출 한 번입니다.

설치

Claude Desktop — 파일 하나, 설정 불필요

1. 최신 릴리스에서 sprite-canon.mcpb를 다운로드합니다.

2. Claude Desktop에서 설정 → 확장 프로그램을 엽니다(Windows에서는 ☰ 메뉴 → 파일 → 설정).

3. .mcpb 파일을 확장 프로그램 페이지로 끌어다 놓고 검토 후 설치를 클릭합니다.

(운영체제에 .mcpb 연결이 등록되어 있다면 파일을 더블클릭해도 됩니다 — 끌어다 놓기가 항상 동작합니다. 대안: 확장 프로그램 → 고급 설정 → 확장 프로그램 설치 → 파일 선택.)

설치의 전부입니다: 번들은 자체 의존성을 포함하며, Claude Desktop이 Node 런타임을 제공합니다. Claude Desktop 앱이 필요합니다 — Claude Code는 아래를 참조하세요.

Claude Code / 기타 MCP 클라이언트

git clone https://github.com/useka12-eng/sprite-canon
cd sprite-canon && npm install

그런 다음 프로젝트의 .mcp.json(또는 기타 MCP 클라이언트 설정)에 등록합니다:

{
  "mcpServers": {
    "sprite-canon": {
      "command": "node",
      "args": ["/path/to/sprite-canon/src/mcp/server.mjs"]
    }
  }
}

Node 18+가 필요합니다. 네이티브 의존성 없음 — PNG/GIF 코덱은 자체 포함입니다.

직접 번들 빌드하기

npx @anthropic-ai/mcpb pack . dist/sprite-canon.mcpb

Related MCP server: mcp-spritesheet-forge

도구

입력은 PNG, 애니메이션 GIF, 또는 PNG 스프라이트시트(cellW/cellH)가 될 수 있습니다.

워크플로우

canon_init      → learn the palette from your existing good assets
canon_learn     → sample skin / outfit / outline once; mark face + outline protected
sprite_measure  → read the numbers before placing anything ("where do the eyes start?")
sprite_repaint  → make variants deterministically (outfits, teams, seasons)
sprite_verify   → prove it: face untouched, nothing left over, no jitter, on palette
sprite_sheet    → look at the result as a sheet, zoomed, before it enters the game

이 도구가 담은 교훈

이것들은 가상의 사례가 아니라 실제 결함으로 먼저 발생한 것들입니다:

• 비율을 추측하지 말고 측정하세요. "머리 높이의 52%"에 모자 챙을 배치했더니 정확히 눈 위에 떨어졌습니다: 20px 머리에서 눈은 위에서 7–9px에 있는데, 모든 고정 비율이 눈을 맞춥니다. sprite_measure는 프레임별로 얼굴이 실제로 시작하는 위치를 보고합니다.

• 고정 휘도 범위로 리페인트하세요. 이미지별 정규화는 영역이 보이는 정도에 따라 같은 소스 색상을 다른 출력으로 매핑합니다 — 우리 모자는 뒤에서 보면 밝고, 앞에서 보면 어두웠습니다. 캐논은 각 영역의 범위를 한 번 기록하고, 리페인트는 항상 그 범위를 사용합니다.

• 구조적으로 영역을 보호하세요. "얼굴 주변은 조심"은 규모가 커지면 실패합니다. protected: true는 리페인트가 절대 닿을 수 없게 하고, verify가 닿지 않았음을 증명합니다.

• GIF 팔레트를 패치하고, 재인코딩하지 마세요. 인덱스 GIF의 색상은 색상 테이블에 있습니다 — 전역 그리고 프레임별 로컬 테이블 모두(전역 테이블만 패치하는 것은 전형적인 절반 수정입니다). 테이블 항목을 대체하면 모든 프레임이 완벽한 동기화로, 제로 손실로 다시 옷을 입습니다.

• 영역 정의에 누락이 있습니다; 인구 조사를 하세요. 리페인트 후 남은 이전 색상 픽셀 12개는 육안으로는 보이지 않지만 leftover에는 명확합니다. 이 검사가 실행되면 canon_info의 인구 조사가 영역이 커버하지 않는 색상을 보여줍니다.

배율 테이블

sprite_verify의 scale 검사는 canon.scale.heights를 읽습니다 — 기준 자산(값이 1인 항목)에 대한 상대적 크기입니다. 아직 이 섹션을 작성하는 도구는 없습니다. sprite-canon.json에 직접 추가하세요:

"scale": { "heights": { "hero": 1, "house": 3.4, "chicken": 0.45 } }

그런 다음 scaleNames로 파일 베이스네임을 해당 키에 매핑합니다. 이렇게 하면 "집이 영웅보다 작다"는 고전적인 문제를 플레이어들이 발견하기 일주일 전에 잡아냅니다.

실용적인 참고 사항

• 항상 canonPath를 전달하세요 (또는 캐논이 그 위에 있는 파일). stdio MCP 서버의 작업 디렉터리는 클라이언트의 것이지 프로젝트의 것이 아니므로, 도구들은 cwd에서 추측하기를 거부합니다.

• 코덱 제한: PNG는 8비트, 논인터레이스, RGB/RGBA/팔레트여야 합니다(일반적인 픽셀아트 케이스; 16비트 또는 인터레이스 파일은 명확한 오류와 함께 거부됩니다). GIF 인코더는 파일당 255개의 불투명 색상까지 정확합니다 — 그 이상은 최근접 팔레트 스냅핑이 적용됩니다.

• sprite_sheet는 약 800KB까지 인라인 이미지로 반환합니다 — 더 큰 시트는 파일 경로만 반환합니다.

• 스프라이트시트는 셀 단위로 왕복됩니다: 빈 셀은 빈 채로 유지되며, 압축되거나 이동되지 않습니다.

이것은 무엇이 아닌가

• 생성기가 아닙니다. PixelLab, Aseprite, Gemini, 손으로 그린 픽셀 등 무엇으로 아트를 만들든 짝지어 사용하세요; sprite-canon은 결과물의 일관성을 유지하는 레이어입니다.

• 아틀라스 패커 / 충돌 도구가 아닙니다 — sprite-tools가 그 부분을 잘 다룹니다.

• 마법이 아닙니다: 프로젝트당 약 10분을 투자해 캐논을 가르치면, 그 투자가 이후 모든 검사와 수정을 신뢰할 수 있게 만듭니다.

개발

npm test          # unit + end-to-end MCP tests (22)

테스트 스위트는 v0.1에서 적대적 다중 에이전트 리뷰가 발견한 모든 버그에 대한 회귀 테스트를 포함합니다 — 시트 셀 압축, GIF 디스포저 의미론, 가짜 성공 응답, 무음 제로 검사 통과. 하나라도 실패하면, 한때 존재했던 버그가 다시 돌아온 것입니다.

MIT