{"id":51189808,"url":"https://github.com/kitepon-rgb/sprite-forge-mcp","last_synced_at":"2026-06-27T14:01:42.927Z","repository":{"id":367661689,"uuid":"1273984551","full_name":"kitepon-rgb/sprite-forge-mcp","owner":"kitepon-rgb","description":"Local-GPU sprite studio for games: text → transparent RGBA sprites, character bibles \u0026 LoRAs. One backend, two faces — a human WebUI and a 15-tool MCP server (ComfyUI-backed).","archived":false,"fork":false,"pushed_at":"2026-06-27T00:40:23.000Z","size":1910,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T02:12:31.080Z","etag":null,"topics":["ai-art","claude","claude-code","comfyui","fastapi","fastmcp","gamedev","image-generation","lora","mcp","mcp-server","model-context-protocol","pixel-art","python","qwen-image-edit","rpg","sdxl","sprite","stable-diffusion"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kitepon-rgb.png","metadata":{"files":{"readme":"README.ja.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-19T04:30:18.000Z","updated_at":"2026-06-27T00:40:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kitepon-rgb/sprite-forge-mcp","commit_stats":null,"previous_names":["kitepon-rgb/sprite-forge-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kitepon-rgb/sprite-forge-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitepon-rgb%2Fsprite-forge-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitepon-rgb%2Fsprite-forge-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitepon-rgb%2Fsprite-forge-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitepon-rgb%2Fsprite-forge-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kitepon-rgb","download_url":"https://codeload.github.com/kitepon-rgb/sprite-forge-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitepon-rgb%2Fsprite-forge-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34855826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-art","claude","claude-code","comfyui","fastapi","fastmcp","gamedev","image-generation","lora","mcp","mcp-server","model-context-protocol","pixel-art","python","qwen-image-edit","rpg","sdxl","sprite","stable-diffusion"],"created_at":"2026-06-27T14:01:41.848Z","updated_at":"2026-06-27T14:01:42.920Z","avatar_url":"https://github.com/kitepon-rgb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/og.svg\" alt=\"sprite-forge-mcp — ローカルGPUのゲーム用スプライト生成スタジオ。人間のWebUIとAIエージェント(MCP)の二面\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# sprite-forge-mcp\n\n[![license: MIT](https://img.shields.io/github/license/kitepon-rgb/sprite-forge-mcp?color=blue)](LICENSE)\n[![python](https://img.shields.io/badge/python-3.11%2B-3776ab?logo=python\u0026logoColor=white)](requirements.txt)\n[![MCP](https://img.shields.io/badge/MCP-FastMCP-4c8dff?logo=anthropic\u0026logoColor=white)](https://modelcontextprotocol.io)\n[![backend: ComfyUI](https://img.shields.io/badge/backend-ComfyUI-7ee08a)](https://github.com/comfyanonymous/ComfyUI)\n\n[English](README.md) · **日本語**\n\n\u003e **発想を打つ → 透過済みのゲーム用キャラスプライトが出る。同じエンジンを、あなた(WebUI)でも、あなたのAIエージェント(MCP)でも動かせる。**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/character-bible.png\" alt=\"sprite-forge が生成したキャラバイブル（モデルシート）— ターンアラウンド・表情・アクション・別衣装を一貫したキャラで\" width=\"76%\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003eキャラバイブル1枚\u003c/b\u003e＝素体1枚から、一貫したターンアラウンド＋表情＋アクション＋別衣装。そして各スプライトはクリーンな透過RGBAで出力：\u003c/sub\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/example-output.png\" alt=\"チェッカー背景の透過RGBAスプライト出力（四隅透過・クリーンmatte）\" width=\"92%\"\u003e\n\u003c/p\u003e\n\n`sprite-forge` はローカルの [ComfyUI](https://github.com/comfyanonymous/ComfyUI) スタジオ。テキストの発想を、透過 **RGBA スプライト** → **キャラバイブル**（設定資料）→ **キャラLoRA** → **任意ポーズ** まで作る。制作で痛い目を見たルールを**品質ゲートとして焼き込んである**ので、壊れたアセットは出荷前に弾かれる。\n\n1つの Python バックエンドが **2つの顔**を持つ：人間向け**ステップ導線 WebUI** と、エージェント向け **FastMCP サーバ**（Claude / Codex / 任意の MCP クライアント）。両者は**同じ `backend/services.py`** を呼ぶので、どちらから来てもゲートを回避できない。重い生成は別マシンの ComfyUI が担い、バックエンドは決定的処理とゲート判定に徹する薄いオーケストレータ。\n\n\u003e *MCP = [Model Context Protocol](https://modelcontextprotocol.io)。Claude Code 等のエージェントにツールを差し込む公開標準。*\n\n**状態：** 実機（RTX 5090 + Mac）で E2E 稼働中 — 淡色キャラ matte / キャラバイブル / キャラLoRA はいずれも動作。MIT。**CUDA GPU で動く ComfyUI が必須**（[要件](#要件)）。\n\n## なぜ作ったか\n\n画像モデルで小さなゲームのキャラスプライトを作るのは独特の苦痛で、自作RPGの制作でその全部を踏んだ：\n\n- **クロマキーの黒漏れ** — 腕とリボンの隙間の「閉じた黒」が単純な flood-fill では残る。採用版1枚に **20万px超**の黒が残存したことも。\n- **ダメージ版のズレ** — `-damaged` 版が再ポーズされて数px ずれ、ゲーム内でベースと重ならず CSS 配置が崩れる。*「元画像を1ドットもずらすな」*。\n- **画風ドリフト** — レトロピクセルの必須語句を抜くと、艶のあるアニメ調に滑り落ちる。\n- **手作業の修正は効かない** — 布/肌/輪郭を手で描き足す成功率はゼロ。\n- **版の爆発** — 「どれが正解か」は主観なので、1枚が **v39** まで膨れ上がる。\n\nだから sprite-forge は単にモデルを呼ぶのではなく、**その傷の一つ一つをゲートに変えている**。出力は四隅透過の RGBA を強制、ダメージ版は base と bbox **≤1px** で機械照合、必須画風語句は自動注入、**手描きツールは持たない**（マスク/点で指す＝モデルが再生成）、採用ゲートを通らない限りゲームフォルダには届かない。壊れたアセットが黙ってゲームに入ることはなく、**ゲートで弾かれる**。\n\n## ComfyUI を直接使うのではダメなの？\n\nComfyUI はもう持っている＝ここでもそれがエンジン。sprite-forge は ComfyUI が持たない部分を足す：\n\n- **二つの顔・一つのロジック** — 導線付き WebUI **と** エージェント用 MCP サーバが、同じゲート付きバックエンドを共有。AIエージェントがパイプライン全体を回せる＝ノードグラフを手配線しない。\n- **単発画像でなくキャラのパイプライン** — 発想 → スプライト → *一貫した*バイブル → LoRA → 任意ポーズ、を一本の流れで。\n- **製造ゲート** — 四隅透過 RGBA、ダメージ版 ≤1px 一致、必須画風、監査付き採用。素の ComfyUI は壊れたスプライトも平気で返すが、これは返さない。\n- **再現可能・手描きなし** — マスク/点で指して再生成。手作業のピクセル救済はしない。\n\n## アーキテクチャ\n\n```mermaid\nflowchart LR\n    H[\"🧑‍🎨 人間\u003cbr/\u003eステップ導線 WebUI\"] --\u003e|HTTP / SSE| B\n    A[\"🤖 エージェント\u003cbr/\u003eClaude / Codex · MCP\"] --\u003e|/mcp · 自己文書化15ツール| B\n    subgraph control[\"制御マシン — Mac / Linux / Windows\"]\n      B[\"sprite-forge backend\u003cbr/\u003eFastAPI + FastMCP → 共有 services.py\u003cbr/\u003e\u003cb\u003e品質ゲートはここ\u003c/b\u003e\"]\n    end\n    subgraph gpu[\"GPU box — RTX級・~30GB VRAM\"]\n      C[\"ComfyUI\u003cbr/\u003eSDXL · Qwen-Image-Edit · ControlNet · LoRA\"]\n    end\n    B --\u003e|HTTP + WebSocket, LAN| C\n    B -.-\u003e|adopt（ゲート付き・任意）| G[\"あなたのゲームの sprites/\"]\n```\n\nバックエンドは ComfyUI と同一マシンでも別マシンでも動く（`SPRITEFORGE_COMFY_URL` で指すだけ）。**ローカル推論は持たない**＝設計どおり。\n\n## パイプライン\n\n```\nテキスト発想 → ① 素体スプライト → ② キャラバイブル → ③ キャラLoRA → ④ 任意ポーズ → 採用\n```\n\n1. **素体スプライト** — SDXL(Illustrious) txt2img ＋ matte → 透過 RGBA。任意で **AIプロンプト生成**：あなた自身の `claude`/`codex` CLI を呼んでラフ発想をタグプロンプトに展開（追加API課金なし）。白/淡色キャラは matte が崩れないよう高コントラスト背景に自動切替。\n2. **キャラバイブル** — Qwen-Image-Edit の「マスターシート」1枚を一貫性アンカーに、ターンアラウンド＋表情＋アクション＋別衣装を生成。整列シート **＋ 自己完結HTML** で出力。\n3. **キャラLoRA** — バイブルのパネルから1クリックで LoRA 学習。バックエンドが GPU box 上の kohya sd-scripts を SSH で駆動。\n4. **任意ポーズ** — キャラLoRA 付き `generate_sprite` でそのキャラを新ポーズ/衣装で量産。`adopt` で採用版をゲームへ書き出し（不可逆・任意・ゲート付き）。\n\n加えて **ダメージ版エディタ**（Qwen-Image-Edit の pose-lock ＋ 衣装マスクで bbox 完全一致）と **SAM2** 点マスク。\n\n## 要件\n\nこれは **リモートGPUオーケストレータ＝単体では何も生成しない**。必要なのは：\n\n- **CUDA GPU で動く ComfyUI**（HTTP+WS 到達可能）。**~30GB VRAM 目安**（RTX 5090 級）— 編集経路で ~20GB の DiT が常駐する。**小容量GPUでは現状そのままでは動かない**。\n- **モデル一式** ＋ 必須カスタムノード（Qwen-Image-Edit, Union ControlNet）— **[docs/models.md](docs/models.md)**。\n- backend 用に **Python 3.11+**。\n\n## クイックスタート\n\n\u003e 完全なセットアップ（GPU box・モデル・任意機能・正直な制約）は **[INSTALL.md](INSTALL.md)**。\n\n```bash\ngit clone https://github.com/kitepon-rgb/sprite-forge-mcp.git\ncd sprite-forge-mcp\npython3.12 -m venv .venv \u0026\u0026 . .venv/bin/activate     # 3.11+\npip install -r requirements.txt\ncp .env.example .env                                  # SPRITEFORGE_COMFY_URL を自分の ComfyUI に\nuvicorn backend.app:app --host 127.0.0.1 --port 8765\n```\n\n- **WebUI** → \u003chttp://127.0.0.1:8765/\u003e  ·  **疎通** → `curl localhost:8765/api/gpu`\n- **MCP** → `http://127.0.0.1:8765/mcp/` を Claude/Codex に URL 型サーバ登録。接続時に使い方マニュアルを返す。\n\n## MCP ツール（エージェントの顔）\n\n15ツールすべて WebUI と同じゲート付きサービスを共有。初期化時にパイプライン手順＋用語集を返す自己文書化済み。\n\n| 分類 | ツール |\n|---|---|\n| Discovery / 状態 | `gpu_status` · `list_sprites` · `list_loras` |\n| プロンプト | `craft_prompt`（あなたの `claude`/`codex` CLI を実行） |\n| 生成 / 編集 | `generate_sprite` · `generate_variant` · `make_transparent` · `pixelize` · `fit_to_base` |\n| キャラ | `generate_character_bible` · `bible_status` · `train_character_lora` |\n| 画風LoRA | `train_style_lora` · `train_status` |\n| 採用 | `adopt`（ゲート付きでゲームへ書き出し） |\n\n## 設計原則（瘢痕ルール）\n\n- **RGBA・四隅透過・黒背景禁止。** 透過は「願い」ではなくゲート。\n- **ダメージ版は base と canvas/bbox ≤1px 一致**（denoise ロック・衣装マスクで 0px 保証）。\n- **必須画風語句は自動注入**＝無言のドリフトを許さない。\n- **手描きしない。** 指す（マスク/点/線）＝モデルが再生成。修正は再生成であって手作業の救済ではない。\n- **静かなフォールバック禁止。** 失敗は段階と理由を明示。勝手に「直さない」。\n- **採用は明示・不可逆。** 依頼があるときだけゲームプロジェクトへ書き出す。\n\n## ドキュメント\n\n- **[INSTALL.md](INSTALL.md)** — セットアップ・任意機能・正直な制約\n- **[docs/models.md](docs/models.md)** — モデルの入手先・配置・必須ノード\n- **[CLAUDE.md](CLAUDE.md)** — 実装の正典\n- **[docs/](docs/)** — 設計ドキュメント（背景・調査・アーキ・出力契約 …）\n\n## ライセンス\n\n[MIT](LICENSE)。モデル重みは**含まない**＝各自でDL（[docs/models.md](docs/models.md)）。各モデルは独自ライセンス。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitepon-rgb%2Fsprite-forge-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitepon-rgb%2Fsprite-forge-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitepon-rgb%2Fsprite-forge-mcp/lists"}