game-art-mcp

2D RPGゲームのアートディレクションのためのAI駆動ピクセルアートスタイルシステムおよびMCPサーバー。

目的

このリポジトリは、プロジェクトのアートディレクションの信頼できる情報源です。AIエージェントはこのリポジトリに入り、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ツール（読み取り専用）

プロバイダーツール（読み取り＋書き込み）

プロダクションツール（読み取り＋書き込み）

バージョニングツール（読み取り＋書き込み）

スタイルツールとQAツールは読み取り専用です。アセット、メモリ、プロバイダー、プロダクション、バージョニングの各ツールは読み取りと書き込みの両方をサポートしています。

アセットレジストリ

アセットレジストリ（フェーズ2）は、構造化メタデータを使用してプロジェクト内のすべてのアートアセットを追跡します。アセットはregistry/assets/内の個別のYAMLファイルとして保存され、registry/registry.yamlにインデックス化されます。

主な機能：

• セマンティックID — ドット区切りの小文字（例：character.goblin.001）

• スタイル連携 — すべてのアセットがスタイルID＋バージョンを参照

• リレーションシップ — variant_of、derived_from、animation_ofなど

• ステータス追跡 — draft、approved、rejected、deprecated、archived

• 完全な検証 — スキーマ、スタイル参照、ソースファイルの存在、リレーションシップ

完全なドキュメントはdocs/ASSET-REGISTRY.md、メタデータスキーマはdocs/ASSET-METADATA.mdを参照してください。

アートメモリ

アートメモリシステム（フェーズ3）は、リポジトリに永続的な視覚的知識を与えます。何が承認されたか、何が拒否されたか、そしてその理由を記憶するため、エージェントはプロジェクトのアートディレクションを理解するために会話履歴を必要としません。

主要な概念：

• スタイルアンカー — スタイルを定義する正規の視覚的例（docs/STYLE-ANCHORS.mdを参照）

• 承認済み参照 — ロールとディメンションを持つ信頼できるアセット

• 拒否 — 適合しないもの。理由の管理された語彙付き

• アート決定 — 視覚的方向性の選択に関するADR形式のレコード（docs/ART-DECISIONS.mdを参照）

• 参照リゾルバー — あらゆる作成タスクに関連するコンテキストを返す決定的なルックアップ

完全なドキュメントはdocs/ART-MEMORY.mdを参照してください。

アートQA

アートQAシステム（フェーズ4）は、ピクセルアートアセットに対する決定的で再現可能な品質ゲートを提供します。すべてのチェックは、期待値／実測値と構造化された是正措置を備えたルールベースです。AIビジョン、埋め込み、自動修復はありません。

主要な概念：

• 13のルール、7カテゴリ（技術、ディメンション、パレット、アルファ、ピクセル、スタイル、メモリ）

• 3つのプロファイル — strict（警告で失敗）、default（エラーで失敗）、lenient（重大のみで失敗）

• 機械可読レポート — ルールごとの結果、重大度、是正措置を含むJSON

• スタイル統合 — アクティブなスタイルからキャンバスサイズ、パレット制限、ピクセルルールを読み取り

• メモリ統合 — 拒否された方向性と承認されたアート決定をチェック

• QAゲート — CIおよび承認ワークフロー用の合格／不合格判定

• QA履歴 — アセットごとの全実行の永続的なログ

完全なドキュメントはdocs/ART-QA.mdを参照してください。

プロバイダーアダプター

プロバイダーアダプターシステム（フェーズ5）は、外部アート生成ツールへのプロバイダー非依存のインターフェースを追加します。リクエストはゲートウェイを通過し、操作を検証し、登録済みアダプターに委任し、不変の来歴とともに生成されたアーティファクトを保存します。

主要な概念：

• ProviderAdapterインターフェース — メタデータ、機能、ヘルス、実行、キャンセル

• アーティファクト — 不変の来歴を持つ生のプロバイダー出力（まだアセットではない）

• 機能 — 操作ごとの詳細（フォーマット、最大解像度）

• ドライラン — 出力を生成せずにリクエストを検証

• モックプロバイダー — 失敗／タイムアウトモードを備えた組み込みテストアダプター

• 自動選択なし — エージェントはプロバイダーを明示的に選択する必要がある

完全なドキュメントはdocs/PROVIDERS.mdを参照してください。

プロダクションオーケストレーター

プロダクションオーケストレーター（フェーズ6）は、完全なアートアセット生成ライフサイクルを調整します：リクエスト検証、スタイル／参照／プロバイダー解決、実行、QA、再試行、承認ゲート。

主要な概念：

• コーディネーターであり、情報源ではない — スタイル、QA、プロバイダー、レジストリに委任する

• ステートマシン — 検証済みの遷移を持つ9つのステータス（created から completed/failed/cancelled まで）

• 11の本番ステージ — REQUEST_VALIDATION から APPROVAL_GATE まで

• 制限付きリトライ — 設定可能な max_attempts（デフォルト3）と、QA失敗時の修復プラン

• 承認境界 — awaiting_approval で停止し、自動承認は決して行わない

• プランの陳腐化検出 — 実行前にスタイルのバージョン差異を検出する

• YAML永続化 — ジョブごとに production/<job_id>/ 内の1つの manifest.yaml

• イベント履歴 — ジョブごとの全状態変更の追記専用ログ

完全なドキュメントは docs/PRODUCTION.md を参照してください。

バージョニングと承認

バージョニング＆承認システム（フェーズ7）は、不変のアセットバージョニング、明示的な承認ワークフロー、完全な監査証跡を追加します。バージョンが削除されることは決してなく、アセットが自動承認されることも決してありません。

主要な概念：

• アセットライフサイクル — 8つの状態: draft、pending_approval、approved、rejected、changes_requested、promoted、superseded、archived

• 承認ワークフロー — 構造化されたフィードバック付きの request、approve、reject、request_changes

• 承認ポリシー — 設定可能: requires_qa_pass、allow_agent_approval、requires_human

• 不変バージョン — 単調増加、親トラッキング、バージョンごとの完全な来歴

• 正規ポインタ — どのバージョンが現在のものかを追跡し、プロモーション/ロールバック時に更新

• プロモーション — QAゲートと承認ゲートを備えた比較交換（compare-and-swap）

• ロールバック — 正規ポインタを以前のバージョンに再指定し、履歴を決して削除しない

• 監査ログ — 9種類のイベントタイプ、追記専用、不変

• アクター識別 — すべてのレコードで human、agent、system、provider を追跡

完全なドキュメントは 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 を参照してください。