game-art-mcp

AI-driven pixel-art style system and MCP server for 2D RPG game art direction.

Purpose

This repository is the source of truth for the project's art direction. Any AI agent can enter this repository, query the project context via MCP, and understand exactly what "our art style" means — without relying on conversation history.

Related MCP server: spritecook-mcp

Architecture

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

Quick Start

npm install
npm run build
npm test

Run MCP Server

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

Validate Style

npm run validate

MCP Tools

Style Tools (read-only)

Asset Tools (read + write)

Memory Tools (read + write)

QA Tools (read-only)

Provider Tools (read + write)

Production Tools (read + write)

Versioning Tools (read + write)

Style and QA tools are read-only. Asset, memory, provider, production, and versioning tools support both reads and writes.

Asset Registry

The Asset Registry (Phase 2) tracks every art asset in the project with structured metadata. Assets are stored as individual YAML files in registry/assets/ and indexed in registry/registry.yaml.

Key features:

• Semantic IDs — dot-separated lowercase (e.g. character.goblin.001)

• Style linkage — every asset references a style ID + version

• Relationships — variant_of, derived_from, animation_of, etc.

• Status tracking — draft, approved, rejected, deprecated, archived

• Full validation — schema, style reference, source file existence, relationships

See docs/ASSET-REGISTRY.md for full documentation and docs/ASSET-METADATA.md for the metadata schema.

Art Memory

The Art Memory system (Phase 3) gives the repository persistent visual knowledge. It remembers what was approved, what was rejected, and why — so agents don't need conversation history to understand the project's art direction.

Key concepts:

• Style Anchors — canonical visual examples that define the style (see docs/STYLE-ANCHORS.md)

• Approved References — trusted assets with roles and dimensions

• Rejections — what does NOT fit, with controlled vocabulary of reasons

• Art Decisions — ADR-format records of visual direction choices (see docs/ART-DECISIONS.md)

• Reference Resolver — deterministic lookup returning relevant context for any creation task

See docs/ART-MEMORY.md for full documentation.

Art QA

The Art QA system (Phase 4) provides deterministic, reproducible quality gates for pixel-art assets. Every check is rule-based with expected/actual values and structured remediation — no AI vision, no embeddings, no auto-repair.

Key concepts:

• 13 rules across 7 categories (technical, dimensions, palette, alpha, pixel, style, memory)

• 3 profiles — strict (fail on warning), default (fail on error), lenient (fail on critical only)

• Machine-readable reports — JSON with per-rule results, severity, remediation

• Style integration — reads canvas sizes, palette limits, pixel rules from active style

• Memory integration — checks rejected directions and accepted art decisions

• QA Gate — pass/fail verdict for CI and approval workflows

• QA History — persistent log of all runs per asset

See docs/ART-QA.md for full documentation.

Provider Adapters

The Provider Adapter system (Phase 5) adds a provider-agnostic interface to external art generation tools. Requests flow through a gateway that validates operations, delegates to registered adapters, and stores generated artifacts with immutable provenance.

Key concepts:

• ProviderAdapter interface — metadata, capabilities, health, execute, cancel

• Artifacts — raw provider output with immutable provenance (not yet assets)

• Capabilities — per-operation detail (formats, max resolution)

• Dry-run — validate requests without generating output

• Mock Provider — built-in test adapter with failure/timeout modes

• No automatic selection — agents must explicitly choose a provider

See docs/PROVIDERS.md for full documentation.

Production Orchestrator

The Production Orchestrator (Phase 6) coordinates the full art asset generation lifecycle: request validation, style/reference/provider resolution, execution, QA, retry, and approval gating.

Key concepts:

• Coordinator, not source of truth — delegates to style, QA, providers, and registry

• State machine — 9 statuses with validated transitions (created through completed/failed/cancelled)

• 11 production stages — REQUEST_VALIDATION through APPROVAL_GATE

• Bounded retry — configurable max_attempts (default 3) with repair plans on QA failure

• Approval boundary — stops at awaiting_approval, never auto-approves

• Plan staleness — detects style version drift before execution

• YAML persistence — one manifest.yaml per job in production/<job_id>/

• Event history — append-only log of all state changes per job

See docs/PRODUCTION.md for full documentation.

Versioning & Approval

The Versioning & Approval system (Phase 7) adds immutable asset versioning, explicit approval workflows, and a full audit trail. No version is ever deleted; no asset is ever auto-approved.

Key concepts:

• Asset lifecycle — 8 states: draft, pending_approval, approved, rejected, changes_requested, promoted, superseded, archived

• Approval workflow — request, approve, reject, request_changes with structured feedback

• Approval policy — configurable: requires_qa_pass, allow_agent_approval, requires_human

• Immutable versions — monotonic increment, parent tracking, full provenance per version

• Canonical pointer — tracks which version is current; updated on promotion/rollback

• Promotion — compare-and-swap with QA gate and approval gate

• Rollback — repoints canonical to a previous version, never deletes history

• Audit log — 9 event types, append-only, immutable

• Actor identity — human, agent, system, provider tracked on every record

See docs/VERSIONING.md for full documentation.

Current Phase

Phase 7 — Versioning & Approval (complete)

See docs/PHASES.md for the full roadmap.

Style System

Styles are structured YAML files representing machine-readable art direction:

• style.yaml — identity, canvas sizes, scaling

• palette.yaml — colors with semantic roles

• pixel-rules.yaml — pixel-art constraints

• outline.yaml — outline rules

• shape-language.yaml — visual language

• lighting.yaml — light direction and rules

• animation.yaml — frame counts, FPS, constraints

See docs/STYLE-SYSTEM.md for details.