game-art-mcp

AI-управляемая система пиксель-арт стиля и MCP-сервер для арт-направления 2D RPG игр.

Назначение

Этот репозиторий — источник истины для арт-направления проекта. Любой ИИ-агент может войти в этот репозиторий, запросить контекст проекта через MCP и точно понять, что означает «наш арт-стиль», не полагаясь на историю переписки.

Related MCP server: spritecook-mcp

Архитектура

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

Быстрый старт

npm install
npm run build
npm test

Запуск MCP-сервера

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

Проверка стиля

npm run validate

MCP-инструменты

Инструменты стиля (только чтение)

Инструменты ассетов (чтение + запись)

Инструменты памяти (чтение + запись)

Инструменты контроля качества (только чтение)

Инструменты провайдеров (чтение + запись)

Производственные инструменты (чтение + запись)

Инструменты версионирования (чтение + запись)

Инструменты стиля и QA доступны только для чтения. Инструменты для работы с ассетами, памятью, провайдерами, производством и версионированием поддерживают как чтение, так и запись.

Реестр ассетов

Реестр ассетов (Фаза 2) отслеживает каждый арт-ассет в проекте со структурированными метаданными. Ассеты хранятся в виде отдельных YAML-файлов в registry/assets/ и индексируются в registry/registry.yaml.

Ключевые возможности:

• Семантические ID — строчные буквы, разделённые точками (например, character.goblin.001)

• Привязка к стилю — каждый ассет ссылается на ID стиля + версию

• Связи — variant_of, derived_from, animation_of и т.д.

• Отслеживание статуса — черновик, одобрено, отклонено, устарело, заархивировано

• Полная валидация — схема, ссылка на стиль, существование исходного файла, связи

Полную документацию см. в docs/ASSET-REGISTRY.md, а схему метаданных — в docs/ASSET-METADATA.md.

Художественная память

Система художественной памяти (Фаза 3) даёт репозиторию постоянные визуальные знания. Она запоминает, что было одобрено, что отклонено и почему, — чтобы агентам не нужна была история переписки для понимания арт-направления проекта.

Ключевые концепции:

• Якоря стиля — канонические визуальные примеры, определяющие стиль (см. docs/STYLE-ANCHORS.md)

• Одобренные ссылки — проверенные ассеты с ролями и размерами

• Отклонения — то, что не подходит, с контролируемым словарём причин

• Арт-решения — записи в формате ADR о выборе визуального направления (см. docs/ART-DECISIONS.md)

• Резолвер ссылок — детерминированный поиск, возвращающий релевантный контекст для любой задачи создания

Полную документацию см. в docs/ART-MEMORY.md.

Художественный контроль качества

Система художественного контроля качества (Фаза 4) обеспечивает детерминированные, воспроизводимые шлюзы качества для пиксель-арт ассетов. Каждая проверка основана на правилах с ожидаемыми/фактическими значениями и структурированными исправлениями — без компьютерного зрения, без эмбеддингов, без автопочинки.

Ключевые концепции:

• 13 правил в 7 категориях (технические, размеры, палитра, альфа-канал, пиксели, стиль, память)

• 3 профиля — строгий (ошибка при предупреждении), по умолчанию (ошибка при ошибке), мягкий (ошибка только при критической ошибке)

• Машиночитаемые отчёты — JSON с результатами по каждому правилу, серьёзностью, исправлениями

• Интеграция со стилем — считывает размеры холста, лимиты палитры, правила пикселей из активного стиля

• Интеграция с памятью — проверяет отклонённые направления и принятые арт-решения

• QA-шлюз — вердикт «пройдено/не пройдено» для CI и процессов согласования

• История QA — постоянный журнал всех запусков по каждому ассету

Полную документацию см. в docs/ART-QA.md.

Адаптеры провайдеров

Система адаптеров провайдеров (Фаза 5) добавляет независимый от провайдера интерфейс к внешним инструментам генерации арта. Запросы проходят через шлюз, который проверяет операции, делегирует их зарегистрированным адаптерам и сохраняет сгенерированные артефакты с неизменяемым происхождением.

Ключевые концепции:

• Интерфейс ProviderAdapter — метаданные, возможности, здоровье, выполнение, отмена

• Артефакты — необработанный вывод провайдера с неизменяемым происхождением (ещё не ассеты)

• Возможности — детали по каждой операции (форматы, максимальное разрешение)

• Пробный запуск — проверка запросов без генерации вывода

• Мок-провайдер — встроенный тестовый адаптер с режимами сбоя/таймаута

• Без автоматического выбора — агенты должны явно выбирать провайдера

Полную документацию см. в docs/PROVIDERS.md.

Производственный оркестратор

Производственный оркестратор (Фаза 6) координирует полный жизненный цикл генерации арт-ассетов: проверка запроса, разрешение стиля/ссылок/провайдера, выполнение, контроль качества, повторные попытки и шлюз одобрения.

Ключевые концепции:

• Координатор, а не источник истины — делегирует стилю, QA, провайдерам и реестру

• Конечный автомат — 9 статусов с проверяемыми переходами (created через completed/failed/cancelled)

• 11 производственных стадий — REQUEST_VALIDATION через APPROVAL_GATE

• Ограниченные повторные попытки — настраиваемый max_attempts (по умолчанию 3) с планами восстановления при сбое QA

• Граница утверждения — останавливается на awaiting_approval, никогда не утверждает автоматически

• Устаревание плана — обнаруживает расхождение версий стиля до выполнения

• Постоянное хранение в YAML — один manifest.yaml на задание в production/<job_id>/

• История событий — журнал только на добавление всех изменений состояния по каждому заданию

Полная документация: docs/PRODUCTION.md.

Версионирование и утверждение

Система версионирования и утверждения (Фаза 7) добавляет неизменяемое версионирование ассетов, явные рабочие процессы утверждения и полный аудиторский след. Ни одна версия никогда не удаляется; ни один ассет никогда не утверждается автоматически.

Ключевые понятия:

• Жизненный цикл ассета — 8 состояний: draft, pending_approval, approved, rejected, changes_requested, promoted, superseded, archived

• Рабочий процесс утверждения — запрос, утверждение, отклонение, запрос изменений со структурированной обратной связью

• Политика утверждения — настраиваемая: requires_qa_pass, allow_agent_approval, requires_human

• Неизменяемые версии — монотонное увеличение, отслеживание родительской версии, полное происхождение для каждой версии

• Канонический указатель — отслеживает, какая версия является текущей; обновляется при продвижении/откате

• Продвижение — сравнение-и-замена с QA-шлюзом и шлюзом утверждения

• Откат — перенаправляет канонический указатель на предыдущую версию, никогда не удаляет историю

• Журнал аудита — 9 типов событий, только на добавление, неизменяемый

• Идентичность субъекта — человек, агент, система, провайдер отслеживаются в каждой записи

Полная документация: docs/VERSIONING.md.

Текущая фаза

Фаза 7 — Версионирование и утверждение (завершена)

Полная дорожная карта: docs/PHASES.md.

Система стилей

Стили — это структурированные YAML-файлы, представляющие машиночитаемое художественное направление:

• style.yaml — идентичность, размеры холста, масштабирование

• palette.yaml — цвета с семантическими ролями

• pixel-rules.yaml — ограничения пиксель-арта

• outline.yaml — правила контуров

• shape-language.yaml — визуальный язык

• lighting.yaml — направление света и правила

• animation.yaml — количество кадров, FPS, ограничения

Подробности: docs/STYLE-SYSTEM.md.