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.

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)

Tool	Description
art.get_project_context	Full art context (project + style + all rules)
art.get_style	Active style definition
art.get_style_rules	Specific rule category (pixel_language, outline, etc.)
art.get_palette	Color palette with semantic roles
art.validate_style	Validate style configuration

Asset Tools (read + write)

Tool	Description
art.asset.get	Get asset by ID
art.asset.find	Search/filter assets (type, category, status, tags)
art.asset.exists	Check whether an asset ID is registered
art.asset.register	Register a new asset with full validation
art.asset.update	Update an existing asset (partial patch)
art.asset.deprecate	Mark an asset as deprecated
art.asset.archive	Archive an asset
art.asset.rebuild_index	Rebuild the registry index from asset files

Memory Tools (read + write)

Tool	Description
art.memory.get_summary	Memory overview: anchors, decisions, rejections, reference count
art.memory.explain_style	Full style explanation with rules, anchors, decisions, avoidances
art.memory.resolve_references	Deterministic reference lookup for a given context
art.memory.get_anchor	Get a style anchor by ID
art.memory.find_anchors	Search anchors (category, status, dimension filters)
art.memory.add_anchor	Add a new style anchor
art.memory.get_reference	Get an approved reference by ID
art.memory.find_references	Search references (role, status, asset_id filters)
art.memory.add_reference	Add a new approved reference
art.memory.get_rejection	Get a rejection record by ID
art.memory.find_rejections	Search rejections (type, status, reason filters)
art.memory.add_rejection	Add a new rejection record
art.memory.get_decision	Get an art decision by ID
art.memory.find_decisions	Search decisions (status filter)
art.memory.add_decision	Add a new art decision
art.memory.get_style_history	Get the full style evolution history

QA Tools (read-only)

Tool	Description
art.qa.asset	Run QA checks on a single asset (full report)
art.qa.batch	Run QA checks on multiple assets (batch report)
art.qa.gate	QA gate check — pass/fail verdict for approval workflows
art.qa.list_rules	List all available QA rules with definitions
art.qa.rule	Get the full definition of a specific QA rule by ID
art.qa.explain_failure	Explain why a specific rule failed for an asset
art.qa.history	Get QA run history, optionally filtered by asset ID

Provider Tools (read + write)

Tool	Description
art.provider.list	List all registered providers with metadata
art.provider.get	Get detailed metadata for a specific provider
art.provider.capabilities	Get provider capabilities (operations, formats, limits)
art.provider.health	Check provider health status
art.provider.execute	Execute an art generation operation via a provider
art.provider.cancel	Cancel a running provider operation
art.provider.operation	Get operation status by ID
art.provider.artifact	Get artifact details and provenance by ID

Production Tools (read + write)

Tool	Description
art.production.plan	Create a production plan (preview before executing)
art.production.create	Create a production job (plan + persist, does not start)
art.production.start	Start executing a production job
art.production.status	Get current job status (summary)
art.production.inspect	Get full job details (events, attempts, plan)
art.production.resume	Resume a failed job
art.production.cancel	Cancel a running job
art.production.attempts	Get attempt history for a job
art.production.approve	Approve a job awaiting approval
art.production.list	List all production job IDs

Versioning Tools (read + write)

Tool	Description
art.asset.current	Get the canonical (current) version of an asset
art.asset.inspect_version	Get details of a specific asset version
art.asset.history	Get the full version history of an asset
art.asset.compare	Compare two versions of the same asset
art.asset.provenance	Get version provenance including approval record
art.asset.approval.request	Request approval for a candidate asset
art.asset.approval.inspect	Get an approval record by ID
art.asset.approve	Approve a candidate asset
art.asset.reject	Reject a candidate asset
art.asset.request_changes	Request changes on a candidate asset
art.asset.promote	Promote an approved candidate to canonical version
art.asset.rollback	Rollback canonical to a previous version
art.asset.archive_version	Archive a canonical asset

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.