# 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

```bash
npm install
npm run build
npm test
```

### Run MCP Server

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

### Validate Style

```bash
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](docs/ASSET-REGISTRY.md) for full documentation and [docs/ASSET-METADATA.md](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](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](docs/ART-DECISIONS.md))
- **Reference Resolver** — deterministic lookup returning relevant context for any creation task

See [docs/ART-MEMORY.md](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](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](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](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](docs/VERSIONING.md) for full documentation.

## Current Phase

**Phase 7 — Versioning & Approval** (complete)

See [docs/PHASES.md](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](docs/STYLE-SYSTEM.md) for details.