game-art-mcp

2D RPG 게임 아트 방향성을 위한 AI 기반 픽셀 아트 스타일 시스템 및 MCP 서버.

목적

이 저장소는 프로젝트 아트 방향성에 대한 진실의 원천(source of truth) 입니다. 모든 AI 에이전트는 이 저장소에 접근하여 MCP를 통해 프로젝트 컨텍스트를 조회하고, 대화 기록에 의존하지 않고도 "우리의 아트 스타일"이 무엇을 의미하는지 정확히 이해할 수 있습니다.

Related MCP server: spritecook-mcp

아키텍처

game-art-mcp/
├── project.yaml              # Project config: which style is active
├── style/                    # Version-controlled style definitions
│   └── fantasy_pixel_v1/     # Style v1 (YAML rules + style bible)
├── registry/                 # Asset registry storage
│   ├── assets/               # One YAML file per registered asset
│   └── registry.yaml         # Auto-generated index of all assets
├── memory/                   # Art Memory storage (Phase 3)
│   ├── anchors/              # Style anchor YAML files
│   ├── references/           # Approved reference YAML files
│   ├── rejections/           # Rejection records
│   ├── decisions/            # Art decision records (ADR format)
│   ├── history.yaml          # Style version evolution log
│   └── memory.yaml           # Auto-generated memory index
├── src/
│   ├── style/                # Models, loader, validator
│   ├── assets/               # Asset registry (models + service)
│   │   ├── models/           # Zod schemas + TypeScript types
│   │   └── registry/         # AssetRegistry service (CRUD + query)
│   ├── memory/               # Art Memory (models, service, resolver)
│   │   ├── models/           # Zod schemas for anchors, references, rejections, decisions
│   │   ├── service/          # ArtMemoryService (CRUD + index)
│   │   └── resolver/         # ReferenceResolver (deterministic lookup)
│   ├── qa/                   # Art QA engine (Phase 4)
│   │   ├── models/           # QA types, report schema, rule interface
│   │   ├── rules/            # 13 deterministic rules (7 categories)
│   │   ├── runner/           # QARunner orchestrator
│   │   └── history/          # QA history persistence
│   ├── providers/            # Provider Adapters (Phase 5)
│   │   ├── models/           # ProviderAdapter interface, types, error codes
│   │   ├── adapters/         # Adapter implementations (mock-provider)
│   │   ├── registry/         # ProviderRegistry (adapter lookup + capabilities)
│   │   ├── gateway/          # ProviderGateway (dispatch + artifact storage)
│   │   └── artifacts/        # ArtifactStore (immutable provenance)
│   ├── production/           # Production Orchestrator (Phase 6)
│   │   ├── models/           # Types, state machine, error codes
│   │   ├── orchestrator/     # ProductionOrchestrator (coordinator)
│   │   └── store/            # ProductionStore (YAML manifest persistence)
│   ├── versioning/           # Versioning & Approval (Phase 7)
│   │   ├── models/           # Types, lifecycle states, error codes
│   │   └── services/         # VersioningService (approval, versioning, promotion, audit)
│   ├── context/              # ArtContextService
│   └── mcp/                  # MCP server + tools
│       └── tools/            # art-tools.ts, asset-tools.ts, memory-tools.ts, qa-tools.ts, provider-tools.ts, production-tools.ts, versioning-tools.ts
├── tests/                    # Unit + integration tests
└── docs/                     # Architecture, style system, phases

빠른 시작

npm install
npm run build
npm test

MCP 서버 실행

npm start
# or with custom root:
ART_MCP_ROOT=/path/to/project npm start

스타일 검증

npm run validate

MCP 도구

스타일 도구(읽기 전용)

에셋 도구(읽기 + 쓰기)

메모리 도구(읽기 + 쓰기)

QA 도구(읽기 전용)

공급자 도구(읽기 + 쓰기)

프로덕션 도구(읽기 + 쓰기)

버전 관리 도구(읽기 + 쓰기)

스타일 및 QA 도구는 읽기 전용입니다. 에셋, 메모리, 공급자, 프로덕션, 버전 관리 도구는 읽기와 쓰기를 모두 지원합니다.

에셋 레지스트리

에셋 레지스트리(2단계)는 구조화된 메타데이터로 프로젝트의 모든 아트 에셋을 추적합니다. 에셋은 registry/assets/ 디렉토리에 개별 YAML 파일로 저장되며 registry/registry.yaml에 인덱싱됩니다.

주요 기능:

• 의미론적 ID — 점으로 구분된 소문자 (예: character.goblin.001)

• 스타일 연결 — 모든 에셋은 스타일 ID + 버전을 참조

• 관계 — variant_of, derived_from, animation_of 등

• 상태 추적 — 초안, 승인됨, 거부됨, 더 이상 사용 안 함, 보관됨

• 전체 검증 — 스키마, 스타일 참조, 소스 파일 존재, 관계

전체 문서는 docs/ASSET-REGISTRY.md를, 메타데이터 스키마는 docs/ASSET-METADATA.md를 참조하세요.

아트 메모리

아트 메모리 시스템(3단계)은 저장소에 지속적인 시각적 지식을 제공합니다. 무엇이 승인되었고, 무엇이 거부되었으며, 그 이유가 무엇인지 기억하므로 에이전트는 프로젝트의 아트 방향성을 이해하기 위해 대화 기록이 필요하지 않습니다.

주요 개념:

• 스타일 앵커 — 스타일을 정의하는 표준 시각적 예시 ( docs/STYLE-ANCHORS.md 참조)

• 승인된 참조 — 역할과 차원이 있는 신뢰할 수 있는 에셋

• 거부 사항 — 스타일에 맞지 않는 것, 통제된 사유 어휘와 함께

• 아트 결정 — 시각적 방향성 선택에 대한 ADR 형식 기록 ( docs/ART-DECISIONS.md 참조)

• 참조 해석기 — 모든 생성 작업에 관련 컨텍스트를 반환하는 결정적 조회

전체 문서는 docs/ART-MEMORY.md를 참조하세요.

아트 QA

아트 QA 시스템(4단계)은 픽셀 아트 에셋에 대한 결정적이고 재현 가능한 품질 게이트를 제공합니다. 모든 검사는 기대값/실제값과 구조화된 개선 조치가 있는 규칙 기반입니다 — AI 비전, 임베딩, 자동 복구 없음.

주요 개념:

• 13개 규칙, 7개 카테고리(기술, 차원, 팔레트, 알파, 픽셀, 스타일, 메모리)

• 3개 프로필 — 엄격(경고 시 실패), 기본(오류 시 실패), 관대(치명적일 때만 실패)

• 기계 판독 가능 보고서 — 규칙별 결과, 심각도, 개선 조치가 포함된 JSON

• 스타일 통합 — 활성 스타일에서 캔버스 크기, 팔레트 제한, 픽셀 규칙 읽기

• 메모리 통합 — 거부된 방향성과 승인된 아트 결정 확인

• QA 게이트 — CI 및 승인 워크플로우용 통과/실패 판정

• QA 이력 — 에셋별 모든 실행의 영구 로그

전체 문서는 docs/ART-QA.md를 참조하세요.

공급자 어댑터

공급자 어댑터 시스템(5단계)은 외부 아트 생성 도구에 대한 공급자 중립 인터페이스를 추가합니다. 요청은 게이트웨이를 통해 흐르며, 게이트웨이는 작업을 검증하고 등록된 어댑터에 위임하며, 변경 불가능한 출처와 함께 생성된 아티팩트를 저장합니다.

주요 개념:

• ProviderAdapter 인터페이스 — 메타데이터, 역량, 상태, 실행, 취소

• 아티팩트 — 변경 불가능한 출처가 있는 원시 공급자 출력(아직 에셋이 아님)

• 역량 — 작업별 세부 정보(형식, 최대 해상도)

• 드라이런 — 출력을 생성하지 않고 요청 검증

• 목 공급자 — 실패/시간 초과 모드가 있는 내장 테스트 어댑터

• 자동 선택 없음 — 에이전트는 공급자를 명시적으로 선택해야 함

전체 문서는 docs/PROVIDERS.md를 참조하세요.

프로덕션 오케스트레이터

프로덕션 오케스트레이터(6단계)는 전체 아트 에셋 생성 수명 주기를 조정합니다: 요청 검증, 스타일/참조/공급자 해석, 실행, QA, 재시도, 승인 게이팅.

주요 개념:

• 코디네이터이지 진실의 원천이 아님 — 스타일, QA, 공급자, 레지스트리에 위임

• 상태 머신 — 검증된 전환을 가진 9가지 상태 (created부터 completed/failed/cancelled까지)

• 11개 프로덕션 단계 — REQUEST_VALIDATION부터 APPROVAL_GATE까지

• 제한된 재시도 — 구성 가능한 max_attempts(기본값 3) 및 QA 실패 시 복구 계획

• 승인 경계 — awaiting_approval에서 중지되며, 자동 승인하지 않음

• 계획 지연 감지 — 실행 전 스타일 버전 드리프트 감지

• YAML 영속성 — production/<job_id>/에 작업당 manifest.yaml 하나

• 이벤트 기록 — 작업별 모든 상태 변경의 추가 전용 로그

전체 문서는 docs/PRODUCTION.md를 참조하세요.

버전 관리 및 승인

버전 관리 및 승인 시스템(Phase 7)은 불변 자산 버전 관리, 명시적 승인 워크플로, 전체 감사 추적을 추가합니다. 어떤 버전도 삭제되지 않으며, 어떤 자산도 자동 승인되지 않습니다.

핵심 개념:

• 자산 수명 주기 — 8가지 상태: draft, pending_approval, approved, rejected, changes_requested, promoted, superseded, archived

• 승인 워크플로 — 구조화된 피드백과 함께 request, approve, reject, request_changes

• 승인 정책 — 구성 가능: requires_qa_pass, allow_agent_approval, requires_human

• 불변 버전 — 단조 증가, 부모 추적, 버전별 전체 출처

• 표준 포인터 — 현재 버전을 추적하며, 승격/롤백 시 업데이트

• 승격 — QA 게이트 및 승인 게이트가 있는 compare-and-swap

• 롤백 — 표준을 이전 버전으로 다시 지정하며, 기록을 삭제하지 않음

• 감사 로그 — 9가지 이벤트 유형, 추가 전용, 불변

• 행위자 식별 — 모든 레코드에서 human, agent, system, provider 추적

전체 문서는 docs/VERSIONING.md를 참조하세요.

현재 단계

Phase 7 — 버전 관리 및 승인 (완료)

전체 로드맵은 docs/PHASES.md를 참조하세요.

스타일 시스템

스타일은 기계가 읽을 수 있는 아트 디렉션을 나타내는 구조화된 YAML 파일입니다:

• style.yaml — 정체성, 캔버스 크기, 스케일링

• palette.yaml — 의미적 역할을 가진 색상

• pixel-rules.yaml — 픽셀 아트 제약

• outline.yaml — 윤곽선 규칙

• shape-language.yaml — 시각적 언어

• lighting.yaml — 조명 방향 및 규칙

• animation.yaml — 프레임 수, FPS, 제약

자세한 내용은 docs/STYLE-SYSTEM.md를 참조하세요.