game-art-mcp

KI-gesteuertes Pixel-Art-Stilsystem und MCP-Server für die Art Direction von 2D-RPG-Spielen.

Zweck

Dieses Repository ist die maßgebliche Quelle für die Art Direction des Projekts. Jeder KI-Agent kann in dieses Repository wechseln, den Projektkontext über MCP abfragen und genau verstehen, was „unser Kunststil“ bedeutet — ohne auf den Gesprächsverlauf angewiesen zu sein.

Related MCP server: spritecook-mcp

Architektur

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

Schnellstart

npm install
npm run build
npm test

MCP-Server ausführen

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

Stil validieren

npm run validate

MCP-Werkzeuge

Stil-Werkzeuge (schreibgeschützt)

Asset-Werkzeuge (Lesen + Schreiben)

Memory-Werkzeuge (Lesen + Schreiben)

QA-Werkzeuge (schreibgeschützt)

Provider-Werkzeuge (Lesen + Schreiben)

Produktions-Werkzeuge (Lesen + Schreiben)

Versionsverwaltungs-Werkzeuge (Lesen + Schreiben)

Stil- und QA-Werkzeuge sind schreibgeschützt. Asset-, Memory-, Provider-, Produktions- und Versionierungs-Werkzeuge unterstützen Lese- und Schreibzugriffe.

Asset-Registry

Das Asset-Registry (Phase 2) erfasst jedes Art-Asset im Projekt mit strukturierten Metadaten. Assets werden als einzelne YAML-Dateien unter registry/assets/ gespeichert und in registry/registry.yaml indiziert.

Wichtige Merkmale:

• Semantische IDs — durch Punkte getrennt, klein geschrieben (z. B. character.goblin.001)

• Stil-Verknüpfung — jedes Asset referenziert eine Stil-ID + Version

• Beziehungen — variant_of, derived_from, animation_of usw.

• Statusverfolgung — draft, approved, rejected, deprecated, archived

• Vollständige Validierung — Schema, Stilreferenz, Existenz der Quelldatei, Beziehungen

Siehe docs/ASSET-REGISTRY.md für die vollständige Dokumentation und docs/ASSET-METADATA.md für das Metadaten-Schema.

Art-Memory

Das Art-Memory-System (Phase 3) verleiht dem Repository dauerhaftes visuelles Wissen. Es speichert, was genehmigt wurde, was abgelehnt wurde und warum — sodass Agenten keine Gesprächshistorie benötigen, um die Art Direction des Projekts zu verstehen.

Wichtige Konzepte:

• Stilanker — kanonische visuelle Beispiele, die den Stil definieren (siehe docs/STYLE-ANCHORS.md)

• Genehmigte Referenzen — vertrauenswürdige Assets mit Rollen-Preferenzen. Ablehnungen — was NICHT passt, mit einem kontrollierten Vokabular an Gründen

• Art-Entscheidungen — Datensätze im ADR-Format für visuelle Richtungsentscheidungen (siehe docs/ART-DECISIONS.md)

• Referenz-Resolver — deterministische Referenzauflösung, die für jede Erstellungsaufgabe relevanten Kontext zurückgibt

Siehe docs/ART-MEMORY.md für die vollständige Dokumentation.

Art-QA

Das Art-QA-System (Phase 4) bietet deterministische, reproduzierbare Qualitätsprüfungen für Pixel-Art-Assets. Jeder Check ist regelbasiert mit Soll-/Ist-Werten und strukturierten Korrekturmaßnahmen — keine Bilderkennung, keine Embeddings, keine automatische Reparatur.

Wichtige Konzepte:

• 13 Regeln in 7 Kategorien (Technik, Dimensionen, Palette, Alpha, Pixel, Stil, Memuery)

• 3 Profile — „strict“ (schlägt bei Warnung fehl), „default“ (schlägt bei Fehler fehl), „lenient“ (schlägt nur bei kritischen Fehlern fehl)

• Maschinenlesbare Berichte — JSON mit Ergebnissen pro Regel, Schweregrad und Korrekturmaßnahmen

• Stil-Integration — liest Canvas-Größen, Farbgrenzen und Pixel-Regeln aus dem aktiven Stil

• Memory-Integration — prüft total zurückgewiesene Richtungen und akzeptierte Art-Entscheidungen

• QA-Gate — Ergebnis „bestanden/nicht bestandefor for CI und Freigabeworkflows

• QA-Verlauf — persistentes Log aller Ausführungen pro Asset

Siehe docs/ART-QA.md für die vollständige Dokumentation.

Provider-Adapter

Das Provider-Adapter-System (Phase 5) fügt eine providerneutrale, anbieterunabhängige Schnittstelle zu externen Art-Generierungswerkzeugen hinzu. Anfragen laufen über ein Gateway, das Operationen validiert, an registrierte Adapter delegiert und generierte Artefakte mit unveränderlicher Provenienz speichert.

Wichtige Konzepte:

• ProviderAdapter-Schnittstelle — Metadaten, Fähigkeiten, Health, Ausführung, Abbruch

• Artefakte — Rohe Provider-Ausgabe mit unveränderlicher Provenienz (noch keine Assets)

• Capabilities — Details pro Operation (Formate, maximale Auflösung)

• Dry-run — Anfragen validieren, ohne Ausgabe zu generieren

• Mock-Provider — eingebauter Testadapter mit Fehler-/Timeout-Modi

• Keine automatische Auswahl — Agenten müssen einen Provider eExplicitly wählen

Siehe docs/PROVIDERS.md für die vollständige Dokumentation.

Produktions-Orchestrator

Der Produktions-Orchestrator (Phase 6) koordiniert den gesamten Lebenszyklus der Art-Asset-Generierung: request validation, Stil-/Referenz-/Provider-Auflösung, Ausführung, QA, Wiederholung und Freigabeprüfung.

Wichtige Konzepte:

• Koordinator, keine Quelle der Wahrheit — delegiert an Stil, Qualitätssicherung, Anbieter und Registry

• Zustandsmaschine — 9 Status mit validierten Übergängen (erstellt bis abgeschlossen/fehlgeschlagen/abgebrochen)

• 11 Produktionsstufen — REQUEST_VALIDATION bis APPROVAL_GATE

• Begrenzte Wiederholung — konfigurierbare max_attempts (Standard 3) mit Reparaturplänen bei QA-Fehlern

• Genehmigungsgrenze — stoppt bei awaiting_approval, genehmigt niemals automatisch

• Plan-Veraltung — erkennt Stilversionsabweichungen vor der Ausführung

• YAML-Persistenz — ein manifest.yaml pro Auftrag in production/<job_id>/

• Ereignishistorie — nur-anhängendes Protokoll aller Zustandsänderungen pro Auftrag

Siehe docs/PRODUCTION.md für die vollständige Dokumentation.

Versionierung & Genehmigung

Das Versionierungs- & Genehmigungssystem (Phase 7) fügt unveränderliche Asset-Versionierung, explizite Genehmigungsworkflows und eine vollständige Prüfpfad hinzu. Keine Version wird jemals gelöscht; kein Asset wird jemals automatisch genehmigt.

Wichtige Konzepte:

• Asset-Lebenszyklus — 8 Zustände: Entwurf, ausstehende_Genehmigung, genehmigt, abgelehnt, Änderungen_angefordert, befördert, ersetzt, archiviert

• Genehmigungsworkflow — anfordern, genehmigen, ablehnen, Änderungen_anfordern mit strukturiertem Feedback

• Genehmigungsrichtlinie — konfigurierbar: requires_qa_pass, allow_agent_approval, requires_human

• Unveränderliche Versionen — monotone Inkrementierung, Elternverfolgung, vollständige Herkunft pro Version

• Kanonischer Zeiger — verfolgt, welche Version aktuell ist; wird bei Beförderung/Rollback aktualisiert

• Beförderung — Vergleich-und-Tausch mit QA-Gate und Genehmigungs-Gate

• Rollback — setzt den kanonischen Zeiger auf eine frühere Version zurück, löscht niemals die Historie

• Prüfprotokoll — 9 Ereignistypen, nur-anhängend, unveränderlich

• Akteursidentität — Mensch, Agent, System, Anbieter bei jedem Datensatz verfolgt

Siehe docs/VERSIONING.md für die vollständige Dokumentation.

Aktuelle Phase

Phase 7 — Versionierung & Genehmigung (abgeschlossen)

Siehe docs/PHASES.md für die vollständige Roadmap.

Stilsystem

Stile sind strukturierte YAML-Dateien, die maschinenlesbare künstlerische Richtung darstellen:

• style.yaml — Identität, Leinwandgrößen, Skalierung

• palette.yaml — Farben mit semantischen Rollen

• pixel-rules.yaml — Pixel-Art-Einschränkungen

• outline.yaml — Konturregeln

• shape-language.yaml — visuelle Sprache

• lighting.yaml — Lichtrichtung und -regeln

• animation.yaml — Bildanzahl, FPS, Einschränkungen

Siehe docs/STYLE-SYSTEM.md für Details.