game-art-mcp

Sistema de estilo de píxeles artísticos impulsado por IA y servidor MCP para la dirección de arte de juegos de rol 2D.

Propósito

Este repositorio es la fuente de verdad para la dirección de arte del proyecto. Cualquier agente de IA puede entrar en este repositorio, consultar el contexto del proyecto a través de MCP y entender exactamente qué significa "nuestro estilo artístico", sin depender del historial de conversación.

Related MCP server: spritecook-mcp

Arquitectura

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

Inicio rápido

npm install
npm run build
npm test

Ejecutar el servidor MCP

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

Validar estilo

npm run validate

Herramientas MCP

Herramientas de estilo (solo lectura)

Herramientas de activos (lectura y escritura)

Herramientas de memoria (lectura y escritura)

Herramientas de control de calidad (solo lectura)

Herramientas de proveedor (lectura y escritura)

Herramientas de producción (lectura y escritura)

Herramientas de versionado (lectura y escritura)

Las herramientas de estilo y control de calidad son de solo lectura. Las herramientas de activos, memoria, proveedor, producción y versionado admiten tanto lecturas como escrituras.

Registro de activos

El Registro de activos (Fase 2) rastrea cada activo artístico del proyecto con metadatos estructurados. Los activos se almacenan como archivos YAML individuales en registry/assets/ y se indexan en registry/registry.yaml.

Características principales:

• IDs semánticos — minúsculas separadas por puntos (p. ej. character.goblin.001)

• Vinculación de estilo — cada activo hace referencia a un ID de estilo + versión

• Relaciones — variant_of, derived_from, animation_of, etc.

• Seguimiento de estado — borrador, aprobado, rechazado, obsoleto, archivado

• Validación completa — esquema, referencia de estilo, existencia de archivo fuente, relaciones

Consulte docs/ASSET-REGISTRY.md para la documentación completa y docs/ASSET-METADATA.md para el esquema de metadatos.

Memoria artística

El sistema de Memoria artística (Fase 3) otorga al repositorio conocimiento visual persistente. Recuerda qué se aprobó, qué se rechazó y por qué, para que los agentes no necesiten el historial de conversación para comprender la dirección artística del proyecto.

Conceptos clave:

• Anclas de estilo — ejemplos visuales canónicos que definen el estilo (consulte docs/STYLE-ANCHORS.md)

• Referencias aprobadas — activos de confianza con roles y dimensiones

• Rechazos — lo que NO encaja, con un vocabulario controlado de motivos

• Decisiones artísticas — registros en formato ADR de las decisiones de dirección visual (consulte docs/ART-DECISIONS.md)

• Resolvedor de referencias — búsqueda determinista que devuelve el contexto relevante para cualquier tarea de creación

Consulte docs/ART-MEMORY.md para la documentación completa.

Control de calidad artístico

El sistema de Control de calidad artístico (Fase 4) proporciona puertas de calidad deterministas y reproducibles para activos de píxeles artísticos. Cada comprobación se basa en reglas con valores esperados/reales y corrección estructurada: sin visión por IA, sin incrustaciones, sin reparación automática.

Conceptos clave:

• 13 reglas en 7 categorías (técnica, dimensiones, paleta, alfa, píxel, estilo, memoria)

• 3 perfiles — estricto (fallar en advertencia), predeterminado (fallar en error), permisivo (fallar solo en crítico)

• Informes legibles por máquina — JSON con resultados por regla, gravedad y corrección

• Integración de estilo — lee tamaños de lienzo, límites de paleta y reglas de píxel del estilo activo

• Integración de memoria — comprueba direcciones rechazadas y decisiones artísticas aceptadas

• Puerta de control de calidad — veredicto de aprobado/rechazado para CI y flujos de aprobación

• Historial de control de calidad — registro persistente de todas las ejecuciones por activo

Consulte docs/ART-QA.md para la documentación completa.

Adaptadores de proveedor

El sistema de Adaptadores de proveedor (Fase 5) añade una interfaz independiente del proveedor para herramientas externas de generación de arte. Las solicitudes fluyen a través de una puerta de enlace que valida operaciones, delega en adaptadores registrados y almacena los artefactos generados con procedencia inmutable.

Conceptos clave:

• Interfaz ProviderAdapter — metadatos, capacidades, salud, ejecutar, cancelar

• Artefactos — salida bruta del proveedor con procedencia inmutable (aún no son activos)

• Capacidades — detalle por operación (formatos, resolución máxima)

• Ejecución en seco — validar solicitudes sin generar salida

• Proveedor simulado — adaptador de prueba integrado con modos de fallo/tiempo de espera

• Sin selección automática — los agentes deben elegir explícitamente un proveedor

Consulte docs/PROVIDERS.md para la documentación completa.

Orquestador de producción

El Orquestador de producción (Fase 6) coordina el ciclo de vida completo de generación de activos artísticos: validación de solicitudes, resolución de estilo/referencia/proveedor, ejecución, control de calidad, reintentos y puerta de aprobación.

Conceptos clave:

• Coordinador, no fuente de verdad — delega en estilo, QA, proveedores y registro

• Máquina de estados — 9 estados con transiciones validadas (desde created hasta completed/failed/cancelled)

• 11 etapas de producción — desde REQUEST_VALIDATION hasta APPROVAL_GATE

• Reintento limitado — configurable max_attempts (por defecto 3) con planes de reparación ante fallo de QA

• Límite de aprobación — se detiene en awaiting_approval, nunca autoaprueba

• Obsolescencia del plan — detecta la deriva de la versión del estilo antes de la ejecución

• Persistencia YAML — un manifest.yaml por trabajo en production/<job_id>/

• Historial de eventos — registro de solo adición de todos los cambios de estado por trabajo

Consulta docs/PRODUCTION.md para la documentación completa.

Versionado & Aprobación

El sistema de versionado y aprobación (fase 7) añade versionado inmutable de activos, flujos de aprobación explícitos y una traza de auditoría completa. Ninguna versión se elimina jamás; ningún activo se autoaprueba jamás.

Conceptos clave:

• Ciclo de vida del activo — 8 estados: draft, pending_approval, approved, rejected, changes_requested, promoted, superseded, archived

• Flujo de aprobación — request, approve, reject, request_changes con retroalimentación estructurada

• Política de aprobación — configurable: requires_qa_pass, allow_agent_approval, requires_human

• Versiones inmutables — incremento monótono, rastreo del predecesor, procedencia completa por versión

• Puntero canónico — rastrea la versión vigente; actualizado al promocionar o revertir

• Promoción — comparación e intercambio con compuerta de QA y compuerta de aprobación

• Reversión — repunta el canónico a una versión anterior, nunca elimina el historial

• Registro de auditoría — 9 tipos de eventos, de solo adición, inmutable

• Identidad del actor — humano, agente, sistema, proveedor, registrados en cada registro

Consulta docs/VERSIONING.md para la documentación completa.

Fase Actual

Fase 7 — Versionado & Aprobación (completa)

Consulta docs/PHASES.md para la hoja de ruta completa.

Sistema de Estilos

Los estilos son archivos YAML estructurados que representan una dirección de arte legible por máquina:

• style.yaml — identidad, tamaños de lienzo, escalado

• palette.yaml — colores con funciones semánticas

• pixel-rules.yaml — restricciones de pixel art

• outline.yaml — reglas de contorno

• shape-language.yaml — lenguaje visual

• lighting.yaml — dirección y reglas de luz

• animation.yaml — número de fotogramas, FPS, restricciones

Consulta docs/STYLE-SYSTEM.md para más detalles.