@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/skills/game-art/client/gemini_image_mcp.py

@@ -0,0 +1,1870 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+#
+# gemini_image_mcp.py — Self-contained MCP server for image generation via the
+# Google Gemini WEB session (cookie auth). No dependency on any git-HEAD fork,
+# no browser-cookie3, no AGPL code, single tool surface.
+#
+# WHAT THIS IS / IS NOT
+#   - It talks to Google's PRIVATE web endpoints using your own session cookies.
+#     This is unofficial and may violate Google's Terms of Service. Use a throwaway
+#     Google account, never a corporate one. Risk of account action is yours.
+#   - Code cannot remove that ToS/account risk. It only removes the *software*
+#     risks: unpinned moving dependency, browser cookie scanning, and AGPL entanglement.
+#
+#   - CẢNH BÁO: generate_image() ĐỌC file từ image_paths và GHI file vào out_dir.
+#     Bản gốc cố ý không có bề mặt file nào, để nếu expose qua tunnel thì caller
+#     không chạm được filesystem. Điều đó KHÔNG còn đúng nữa.
+#     => Server này CHỈ được chạy stdio local. KHÔNG tunnel/expose ra ngoài.
+#   - The private protocol (endpoints, RPC payload shape, model ids, image URL
+#     patterns) can change without notice. All such volatile constants are grouped
+#     in the PROTOCOL block below so you can fix them in one place.
+#
+# DEPENDENCIES (pin these exactly in your requirements.txt):
+#   mcp==1.12.*        curl_cffi==0.14.*
+#
+# COOKIES (env only — nothing is scraped from your browser):
+#   Cách BỀN nhất (khuyến nghị) — nạp NGUYÊN bộ cookie như browser để tự xoay vòng:
+#     GEMINI_COOKIES_FILE  đường dẫn file chứa nguyên chuỗi `Cookie:` copy từ DevTools
+#     GEMINI_COOKIES       (thay thế) chính chuỗi đó nhét thẳng vào env
+#   Có đủ họ SID/SAPISID thì server tự gọi RotateCookies đúc __Secure-1PSIDTS mới,
+#   session tự trôi tới khi __Secure-1PSID gốc hết hạn (hàng tuần→tháng).
+#
+#   Cách tối thiểu (dễ rơi hơn — thiếu cookie để rotate ổn định):
+#     GEMINI_1PSID      value of the __Secure-1PSID cookie   (required)
+#     GEMINI_1PSIDTS    value of the __Secure-1PSIDTS cookie (recommended)
+#
+# OPTIONAL ENV:
+#   GEMINI_IMAGE_DIR         where to save images (default ~/Pictures/gemini)
+#   GEMINI_IMAGE_MODEL_ID    model id used for the image model header
+#   GEMINI_ACCOUNT_INDEX     /u/<n> account slot (default 0)
+#   GEMINI_IMG_SIZE          CDN size suffix for full-res download (default s2048)
+#   GEMINI_TIMEOUT           per-request timeout seconds (default 300)
+
+import asyncio
+import hashlib
+import io
+import json
+import os
+import random
+import re
+import shutil
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+# .env PHẢI nạp TRƯỚC mọi import bên dưới: gemini_image_mcp (ngay file này), bgremove,
+# upscale và remote_proto đều đọc os.environ NGAY LÚC IMPORT. Đặt sau thì file .env coi như
+# không tồn tại, và triệu chứng là "đã tạo .env mà chẳng thấy tác dụng gì".
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import envfile as _envfile          # noqa: E402
+_envfile.load(base=Path(__file__).resolve().parent)  # .env cùng thư mục entry
+
+from curl_cffi import CurlHttpVersion, CurlMime  # noqa: E402
+from curl_cffi.requests import AsyncSession, Cookies
+
+import numpy as np
+from PIL import Image
+
+from mcp.server.fastmcp import FastMCP
+
+import imglib as L
+import bgremove
+import upscale as UP
+import remote_backend as RB
+
+# --------------------------------------------------------------------------- #
+# PROTOCOL — volatile constants. If Google changes their web app and generation
+# breaks, this is the only block you should normally need to touch.
+# --------------------------------------------------------------------------- #
+_BASE = "https://gemini.google.com"
+_INIT_PATH = "/app"                 # GET here to scrape auth tokens
+_GENERATE_PATH = "/_/BardChatUi/data/assistant.lamda.BardFrontendService/StreamGenerate"
+# Xoá hội thoại vừa tạo để không để lại rác trong tài khoản Gemini. Web app dùng chung
+# endpoint batchexecute với rpcid GzXR5e, payload là [conversation_id].
+_BATCH_PATH = "/_/BardChatUi/data/batchexecute"
+_DELETE_RPC = "GzXR5e"
+# Endpoint xoay vòng cookie của Google Accounts. Với đủ họ SID/SAPISID trong jar, POST vào
+# đây trả về __Secure-1PSIDTS mới qua Set-Cookie — không phải chờ /app tình cờ set lại.
+_ROTATE_URL = "https://accounts.google.com/RotateCookies"
+# Luồng "trang" mà browser thật dùng cho Gemini: GET trang này -> Google Set-Cookie 1PSIDTS
+# (đôi khi cả 1PSID) MỚI ngay trong response. Ta bắt Set-Cookie đó rồi GHI ĐÈ lại file cookie.
+_ROTATE_PAGE_URL = "https://accounts.google.com/RotateCookiesPage"
+
+# The "nano banana" image model id, injected via the model-selection header.
+_IMAGE_MODEL_ID = os.environ.get("GEMINI_IMAGE_MODEL_ID", "56fdd199312815e2")
+_MODEL_HEADER_KEY = "x-goog-ext-525001261-jspb"
+def _model_header() -> dict[str, str]:
+    return {_MODEL_HEADER_KEY: f'[1,null,null,null,"{_IMAGE_MODEL_ID}",null,null,0,[4],null,null,1]'}
+
+_BASE_HEADERS = {
+    "Content-Type": "application/x-www-form-urlencoded;charset=utf-8",
+    "Origin": _BASE,
+    "Referer": _BASE + "/",
+    "User-Agent": ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+                   "(KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36"),
+    "X-Same-Domain": "1",
+}
+
+# Tokens embedded in the /app HTML.  SNlM0e was removed by Google ~Feb 2025 and
+# may be empty; cfb2h (build label) and FdrFJe (session id) are what matter.
+_TOKEN_RE = {
+    "at":     re.compile(r'"SNlM0e":\s*"(.*?)"'),   # -> data["at"]
+    "bl":     re.compile(r'"cfb2h":\s*"(.*?)"'),    # -> params["bl"]
+    "f.sid":  re.compile(r'"FdrFJe":\s*"(.*?)"'),   # -> params["f.sid"]
+}
+
+# Image URLs Google returns inside the streamed response.
+_IMG_URL_RE = re.compile(r'https?://lh3\.(?:googleusercontent\.com|google\.com)/[A-Za-z0-9_\-./]+')
+
+# conversation_id của lượt chat vừa tạo (dạng "c_<hex>") — dùng để xoá hội thoại sau khi
+# lấy xong ảnh. Nằm trong metadata new-chat của response StreamGenerate.
+_CID_RE = re.compile(r'c_[0-9a-f]{10,}')
+
+# File upload — Gemini web đẩy ảnh lên đây rồi tham chiếu bằng id trả về.
+_UPLOAD_URL = "https://content-push.googleapis.com/upload/"
+_UPLOAD_PUSH_ID = "feeds/mcudyrk2a4khkz"
+_MAX_IMAGES = 4                       # Gemini web chỉ nhận tối đa 4 ảnh / lượt
+_MAX_IMAGE_BYTES = 7 * 1024 * 1024
+_ALLOWED_EXT = {".png", ".jpg", ".jpeg", ".webp"}
+_MIME_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+}
+# --------------------------------------------------------------------------- #
+
+_ACCOUNT = int(os.environ.get("GEMINI_ACCOUNT_INDEX", "0"))
+_IMG_SIZE = os.environ.get("GEMINI_IMG_SIZE", "s2048")
+_TIMEOUT = float(os.environ.get("GEMINI_TIMEOUT", "300"))
+# Mặc định XOÁ đoạn chat sau mỗi lượt sinh để không làm rác tài khoản Gemini.
+# Đặt GEMINI_DELETE_CHAT=0 (hoặc false/no) nếu muốn giữ lại lịch sử chat.
+_DELETE_CHAT = os.environ.get("GEMINI_DELETE_CHAT", "1").strip().lower() not in ("0", "false", "no", "off", "")
+_IMAGE_DIR = Path(os.environ.get("GEMINI_IMAGE_DIR", str(Path.home() / "Pictures" / "gemini")))
+
+
+def _prefix(idx: int) -> str:
+    return f"/u/{idx}" if idx > 0 else ""
+
+
+# __Secure-1PSIDTS XOAY VÒNG. Google trả giá trị mới qua Set-Cookie sau vài request, và giá trị
+# CŨ chết ngay. Bản gốc nạp cookie từ env mỗi lần gọi rồi vứt cookie mới đi -> chỉ cần Google xoay
+# một nhịp là session rơi về trạng thái ĐĂNG XUẤT. Triệu chứng rất dễ chẩn đoán nhầm: chat vẫn trả
+# lời bình thường (Gemini cho chat ẩn danh), chỉ TẠO ẢNH là bị từ chối -> trông như lỗi model/prompt.
+# Nên phải LƯU LẠI giá trị mới nhất và ưu tiên nó hơn env.
+_PSIDTS_CACHE = Path(
+    os.environ.get("GEMINI_PSIDTS_CACHE", str(Path.home() / ".cache" / "gemini_mcp" / "psidts"))
+)
+
+
+def _parse_cookie_header(raw: str) -> dict[str, str]:
+    """Tách chuỗi `Cookie:` (copy nguyên từ DevTools) thành dict tên->giá trị.
+
+    Chấp nhận cả xuống dòng lẫn "; " để dán thoải mái. Bỏ qua phần rỗng/không có "=".
+    """
+    out: dict[str, str] = {}
+    for part in raw.replace("\n", ";").split(";"):
+        part = part.strip()
+        if not part or "=" not in part:
+            continue
+        k, _, v = part.partition("=")
+        k = k.strip()
+        if k:
+            out[k] = v.strip()
+    return out
+
+
+def _raw_cookies() -> dict[str, str]:
+    """Bộ cookie ĐẦY ĐỦ (như browser) — ưu tiên file, rồi inline env, rồi rỗng.
+
+    GEMINI_COOKIES_FILE: đường dẫn file chứa nguyên chuỗi `Cookie:`.
+    GEMINI_COOKIES:      chính chuỗi đó, nhét thẳng vào env.
+    Rỗng -> quay về chế độ 2-cookie cũ (GEMINI_1PSID/1PSIDTS) trong _cookies().
+    """
+    path = os.environ.get("GEMINI_COOKIES_FILE", "").strip()
+    if path:
+        try:
+            raw = Path(path).read_text(encoding="utf-8").strip()
+            if raw:
+                return _parse_cookie_header(raw)
+        except OSError:
+            pass
+    inline = os.environ.get("GEMINI_COOKIES", "").strip()
+    if inline:
+        return _parse_cookie_header(inline)
+    return {}
+
+
+def _psidts_seed() -> str:
+    """Hạt giống 1PSIDTS hiện tại: lấy từ bộ cookie đầy đủ nếu có, không thì env cũ.
+
+    Cache cookie-đã-xoay khoá theo hạt giống này. Đổi cookie = đổi seed = cache cũ bị vứt,
+    đúng như thiết kế ở _load_psidts (tránh cache chết đè lên cookie tươi user vừa dán).
+    """
+    bag = _raw_cookies()
+    if bag.get("__Secure-1PSIDTS"):
+        return bag["__Secure-1PSIDTS"].strip()
+    return os.environ.get("GEMINI_1PSIDTS", "").strip()
+
+
+def _load_psidts() -> str:
+    """Cookie đã xoay (nếu có) thắng env — NHƯNG chỉ khi nó sinh ra từ đúng env hiện tại.
+
+    Cache phải nhớ HẠT GIỐNG đã sinh ra nó. Nếu không, kịch bản này sẽ xảy ra và rất khó
+    truy: cache đi vào trạng thái chết -> user đi lấy cookie tươi dán vào env -> _load_psidts
+    vẫn ưu tiên cache -> cookie tươi BỊ BỎ QUA, session vẫn đăng xuất, user tưởng cookie mình
+    lấy sai và đi lấy lại lần nữa, mãi không thoát. Env đổi = user chủ động reset, cache vứt.
+    """
+    seed = _psidts_seed()
+    try:
+        blob = json.loads(_PSIDTS_CACHE.read_text(encoding="utf-8"))
+        if blob.get("seed") == seed and blob.get("psidts"):
+            return blob["psidts"]
+    except (OSError, ValueError, AttributeError):
+        pass
+    return seed
+
+
+def _load_psid() -> str:
+    """__Secure-1PSID đã xoay (nếu Google có xoay và cache khớp seed) — cùng seed với
+    1PSIDTS nên khi user dán cookie mới thì cả hai cùng bị vô hiệu, không kẹt cache chết."""
+    seed = _psidts_seed()
+    try:
+        blob = json.loads(_PSIDTS_CACHE.read_text(encoding="utf-8"))
+        if blob.get("seed") == seed and blob.get("psid"):
+            return blob["psid"]
+    except (OSError, ValueError, AttributeError):
+        pass
+    bag = _raw_cookies()
+    return bag.get("__Secure-1PSID") or os.environ.get("GEMINI_1PSID", "").strip()
+
+
+def _sapisid_auth(session: AsyncSession) -> str | None:
+    """Header Authorization kiểu SAPISIDHASH mà Google Accounts đòi cho RotateCookies.
+
+    Dạng: '<prefix> <ts>_<sha1(f"{ts} {SAPISID} {origin}")>' cho cả 3 prefix (SAPISIDHASH,
+    SAPISID1PHASH, SAPISID3PHASH). Thiếu header này thì RotateCookies thường bỏ qua, không
+    đúc __Secure-1PSIDTS mới — nghi là mắt xích khiến rotate lâu nay không tự làm tươi được.
+    """
+    sapisid = _cookie_val(session, "SAPISID") or _cookie_val(session, "__Secure-3PAPISID")
+    if not sapisid:
+        return None
+    ts = int(time.time())
+    raw = f"{ts} {sapisid} {_BASE}"
+    digest = hashlib.sha1(raw.encode("utf-8")).hexdigest()
+    return " ".join(f"{p} {ts}_{digest}" for p in ("SAPISIDHASH", "SAPISID1PHASH", "SAPISID3PHASH"))
+
+
+def _rotate_headers(session: AsyncSession) -> dict[str, str]:
+    h = {"Content-Type": "application/json", "Origin": _BASE, "Referer": f"{_BASE}/"}
+    auth = _sapisid_auth(session)
+    if auth:
+        h["Authorization"] = auth
+    return h
+
+
+def _cookie_val(session: AsyncSession, name: str) -> str | None:
+    """Đọc giá trị cookie từ jar sau khi Google Set-Cookie. Thử cả domain có/không
+    chấm vì curl_cffi có thể lưu ở '.google.com' hoặc 'google.com'."""
+    for kw in ({"domain": ".google.com"}, {"domain": "google.com"}, {}):
+        try:
+            v = session.cookies.get(name, **kw)
+            if v:
+                return v
+        except Exception:
+            pass
+    return None
+
+
+def _save_psidts(session: AsyncSession) -> None:
+    """Bắt lấy __Secure-1PSIDTS (và __Secure-1PSID nếu Google xoay) mới nhất và ghi
+    xuống cache đĩa, KÈM hạt giống.
+
+    Không có bước này thì cookie chết sau vài phút và user phải đi lấy tay lại liên tục.
+    """
+    fresh = _cookie_val(session, "__Secure-1PSIDTS")
+    fresh_id = _cookie_val(session, "__Secure-1PSID")
+    if (not fresh or fresh == _load_psidts()) and (not fresh_id or fresh_id == _load_psid()):
+        return
+    try:
+        _PSIDTS_CACHE.parent.mkdir(parents=True, exist_ok=True)
+        _PSIDTS_CACHE.write_text(
+            json.dumps({
+                "seed": _psidts_seed(),
+                "psidts": fresh or _load_psidts(),
+                "psid": fresh_id or _load_psid(),
+            }),
+            encoding="utf-8",
+        )
+    except OSError:
+        pass          # không ghi được cache thì thôi, đừng làm hỏng lượt sinh
+
+
+def _persist_cookies(session: AsyncSession) -> None:
+    """GHI ĐÈ cookie mới (Google vừa Set-Cookie sau rotate) trở lại NGUỒN cookie.
+
+    Đây là điều user muốn: không chỉ nhớ 1PSIDTS trong cache riêng, mà cập nhật thẳng
+    file GEMINI_COOKIES_FILE để nguyên bộ `Cookie:` luôn tươi cho các request sau. Cập
+    nhật mọi cookie có trong file mà jar đã đổi + kéo thêm 1PSIDTS/1PSID nếu mới. Ghi
+    atomic (.tmp + os.replace) để không để lại file cụt. Luôn đồng bộ cache 1PSIDTS.
+    """
+    _save_psidts(session)     # cache luôn được cập nhật, kể cả khi không có file
+    path = os.environ.get("GEMINI_COOKIES_FILE", "").strip()
+    if not path:
+        return
+    try:
+        current = _parse_cookie_header(Path(path).read_text(encoding="utf-8"))
+    except OSError:
+        return
+    if not current:
+        return
+    changed = False
+    # Quét MỌI cookie google trong jar sau rotate (Google Set-Cookie cả nhóm *SIDCC:
+    # SIDCC, __Secure-1PSIDCC, __Secure-3PSIDCC... — đây mới là thứ giữ session sống),
+    # không chỉ vài tên cố định. Hợp nhất với tên đã có trong file + nhóm secure đã biết.
+    jar_names: set[str] = set()
+    try:
+        for c in session.cookies.jar:
+            if "google" in (getattr(c, "domain", "") or ""):
+                jar_names.add(c.name)
+    except Exception:
+        pass
+    names = set(current) | jar_names | {
+        "__Secure-1PSIDTS", "__Secure-3PSIDTS",
+        "__Secure-1PSID", "__Secure-3PSID",
+        "SIDCC", "__Secure-1PSIDCC", "__Secure-3PSIDCC",
+    }
+    for name in names:
+        v = _cookie_val(session, name)
+        if v and current.get(name) != v:
+            current[name] = v
+            changed = True
+    if not changed:
+        return
+    header = "; ".join(f"{k}={v}" for k, v in current.items())
+    try:
+        tmp = Path(f"{path}.tmp")
+        tmp.write_text(header, encoding="utf-8")
+        os.replace(tmp, path)     # atomic
+    except OSError:
+        pass
+
+
+def _cookies() -> Cookies:
+    """Dựng cookie jar. Ưu tiên bộ cookie ĐẦY ĐỦ (GEMINI_COOKIES[_FILE]) để RotateCookies
+    có đủ họ SID/SAPISID mà đúc 1PSIDTS mới — giống hệt browser đóng/mở lại vẫn vào được.
+    Không có bộ đầy đủ thì quay về chế độ 2-cookie cũ.
+
+    Dù ở chế độ nào, giá trị 1PSIDTS ĐÃ XOAY trong cache (nếu khớp seed) luôn thắng, vì nó
+    mới hơn cái nằm trong header cookie tĩnh user dán vào.
+    """
+    bag = _raw_cookies()
+    psid = bag.get("__Secure-1PSID") or os.environ.get("GEMINI_1PSID", "").strip()
+    if not psid:
+        raise RuntimeError(
+            "Thiếu cookie. Set GEMINI_COOKIES_FILE (hoặc GEMINI_COOKIES) = nguyên chuỗi "
+            "`Cookie:` copy từ DevTools trên gemini.google.com; hoặc tối thiểu GEMINI_1PSID "
+            "(+GEMINI_1PSIDTS)."
+        )
+    jar = Cookies()
+    if bag:
+        for k, v in bag.items():
+            jar.set(k, v, domain=".google.com")
+    else:
+        jar.set("__Secure-1PSID", psid, domain=".google.com")
+    # Giá trị ĐÃ XOAY (cache khớp seed) luôn thắng bản tĩnh trong file/env vì nó mới hơn.
+    rotated_id = _load_psid()
+    if rotated_id:
+        jar.set("__Secure-1PSID", rotated_id, domain=".google.com")
+    psidts = _load_psidts()
+    if psidts:
+        jar.set("__Secure-1PSIDTS", psidts, domain=".google.com")
+    return jar
+
+
+def _new_session() -> AsyncSession:
+    s = AsyncSession(
+        impersonate="chrome",                 # real TLS fingerprint; plain httpx gets blocked
+        http_version=CurlHttpVersion.V2_0,
+        allow_redirects=True,
+        timeout=_TIMEOUT,
+    )
+    s.headers.update(_BASE_HEADERS)
+    s.cookies = _cookies()
+    return s
+
+
+async def _rotate_psidts(session: AsyncSession) -> None:
+    """Chủ động bảo Google Accounts cấp __Secure-1PSIDTS mới, thay vì chờ /app.
+
+    Đây là cái làm session 'tự trôi' mà không cần dán tay: chừng nào các cookie BỀN
+    (__Secure-1PSID + họ SAPISID/SID) còn sống, endpoint này luôn đúc được token ngắn hạn mới.
+    Best-effort tuyệt đối — hỏng (mạng, 401, đổi payload) thì bỏ qua, /app phía sau vẫn là
+    lưới đỡ. Payload [0,"-0000000000000000000"] là dạng RotateCookies web app dùng.
+    """
+    try:
+        r = await session.post(
+            _ROTATE_URL,
+            json=[0, "-0000000000000000000"],
+            headers=_rotate_headers(session),
+        )
+        if r.status_code == 200:
+            _persist_cookies(session)   # bắt token mới Google vừa Set-Cookie, ghi lại file
+    except Exception:
+        pass
+    # Thử THÊM luồng "trang" của browser — GET RotateCookiesPage, Google Set-Cookie cả
+    # nhóm *SIDCC (+ đôi khi 1PSIDTS/1PSID) mới; ta ghi đè lại file cookie.
+    await _rotate_cookies_page(session)
+
+
+async def _rotate_cookies_page(session: AsyncSession) -> None:
+    """GET https://accounts.google.com/RotateCookiesPage như iframe browser mở cho Gemini.
+
+    Google trả Set-Cookie cookie tươi (SIDCC/__Secure-1PSIDCC/__Secure-3PSIDCC..., đôi khi
+    cả 1PSIDTS/1PSID) NGAY trong response GET này. Ta bắt hết rồi GHI ĐÈ về file cookie để
+    request sau dùng bộ mới. Nếu trang có nhúng token rotate thì POST tiếp lên /RotateCookies.
+    Best-effort tuyệt đối — hỏng thì thôi, /app phía sau vẫn là lưới đỡ.
+    """
+    try:
+        r = await session.get(
+            _ROTATE_PAGE_URL,
+            params={"og_pid": "658", "rot": "3", "origin": _BASE, "exp_id": "0"},
+            headers={
+                "Referer": f"{_BASE}/",
+                "Sec-Fetch-Dest": "iframe",
+                "Sec-Fetch-Mode": "navigate",
+                "Sec-Fetch-Site": "cross-site",
+                "Upgrade-Insecure-Requests": "1",
+            },
+        )
+        if r.status_code != 200:
+            return
+        _persist_cookies(session)     # Set-Cookie đã vào jar ngay ở GET -> lưu lại
+        # Trang có thể nhúng mảng [rot,"token"] để POST xác nhận rotate; thử bắt và gửi.
+        m = re.search(r'\[\s*(\d+)\s*,\s*"([^"]{10,})"\s*\]', r.text)
+        if m:
+            try:
+                rp = await session.post(
+                    _ROTATE_URL,
+                    json=[int(m.group(1)), m.group(2)],
+                    headers=_rotate_headers(session),
+                )
+                if rp.status_code == 200:
+                    _persist_cookies(session)
+            except Exception:
+                pass
+    except Exception:
+        pass
+
+
+class _LoggedOut(RuntimeError):
+    """Cookie đã chết/bị thu hồi -> /app trả trang đăng xuất. Tách riêng để lớp trên
+    biết mà TỰ REFRESH cookie từ Brave rồi thử lại, thay vì ném thẳng cho user."""
+
+
+# refresh_gemini_cookies.py là công cụ NODE, nằm ở ../server. Bản client mang đi KHÔNG có
+# nó — nhưng đường refresh chỉ chạy ở chế độ Gemini-local (client mượn-node không đụng),
+# và mọi chỗ dùng đều đã guard `.exists()`. Tìm ở server/ trước, rồi cạnh file (layout phẳng).
+_REFRESH_SCRIPT = Path(__file__).resolve().parent.parent / "server" / "refresh_gemini_cookies.py"
+if not _REFRESH_SCRIPT.exists():
+    _REFRESH_SCRIPT = Path(__file__).with_name("refresh_gemini_cookies.py")
+# Tự chạy refresh_gemini_cookies.py khi phát hiện đăng xuất. Tắt bằng GEMINI_AUTO_REFRESH=0.
+_AUTO_REFRESH = os.environ.get("GEMINI_AUTO_REFRESH", "1").strip().lower() not in ("0", "false", "no", "off", "")
+_REFRESH_TIMEOUT = float(os.environ.get("GEMINI_REFRESH_TIMEOUT", "120"))
+# Sau một lần refresh THẤT BẠI, khoá không thử lại trong ngần này giây. Không có nó thì
+# một lô n=3 với cookie chết sẽ chạy refresh Brave 3 lần -> treo lâu vô ích.
+_REFRESH_COOLDOWN = float(os.environ.get("GEMINI_REFRESH_COOLDOWN", "120"))
+_last_refresh_fail = 0.0
+
+
+async def _refresh_cookies_via_brave() -> bool:
+    """Rotate không cứu được session bị thu hồi — chỉ ĐĂNG NHẬP LẠI từ Brave mới đúc
+    credential mới. Chạy refresh_gemini_cookies.py (đọc cookie từ profile Brave qua CDP).
+    Exit 0 = cookie tươi và ĐÃ verify đăng nhập được -> trả True.
+
+    AN TOÀN: script đó GHI ĐÈ cookies.txt bằng cookie Brave TRƯỚC khi verify, nên nếu Brave
+    đang logout thì nó xoá mất cookie TỐT user vừa dán. Vì vậy ở đây SAO LƯU file trước, và
+    KHÔI PHỤC lại nếu refresh thất bại. Kèm cooldown để cookie chết không làm mỗi lượt gen treo.
+    """
+    global _last_refresh_fail
+    if not _AUTO_REFRESH or not _REFRESH_SCRIPT.exists():
+        return False
+    if time.monotonic() - _last_refresh_fail < _REFRESH_COOLDOWN:
+        return False   # vừa thất bại xong -> đừng thử lại Brave cho từng lượt trong lô
+
+    cookie_path = os.environ.get("GEMINI_COOKIES_FILE", "").strip()
+    backup = None
+    if cookie_path:
+        try:
+            backup = Path(cookie_path).read_bytes()
+        except OSError:
+            backup = None
+
+    ok = False
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            sys.executable, str(_REFRESH_SCRIPT),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.STDOUT,
+            env=dict(os.environ),
+        )
+        try:
+            await asyncio.wait_for(proc.communicate(), timeout=_REFRESH_TIMEOUT)
+            ok = proc.returncode == 0
+        except asyncio.TimeoutError:
+            try:
+                proc.kill()
+            except Exception:
+                pass
+    except Exception:
+        ok = False
+
+    if ok:
+        _last_refresh_fail = 0.0
+        return True
+    # Thất bại -> trả cookie cũ về (script có thể đã ghi đè bằng cookie Brave logout).
+    _last_refresh_fail = time.monotonic()
+    if backup is not None and cookie_path:
+        try:
+            Path(cookie_path).write_bytes(backup)
+        except OSError:
+            pass
+    return False
+
+
+async def _auth(session: AsyncSession) -> dict[str, str]:
+    """GET /app and scrape the auth tokens. Raises on expired/invalid cookies."""
+    await _rotate_psidts(session)      # đúc 1PSIDTS tươi TRƯỚC khi dùng, nếu có đủ cookie bền
+    url = f"{_BASE}{_prefix(_ACCOUNT)}{_INIT_PATH}"
+    r = await session.get(url)
+    r.raise_for_status()
+    if "consent.google.com" in str(r.url):
+        raise _LoggedOut("Redirected to consent page — cookies are expired/invalid. Refresh them.")
+    _persist_cookies(session)  # Google vừa có thể đã xoay cookie — giữ lấy, ghi lại file
+
+    html = r.text
+    tokens = {}
+    for key, rx in _TOKEN_RE.items():
+        m = rx.search(html)
+        tokens[key] = m.group(1) if m else ""
+    if not (tokens["bl"] or tokens["f.sid"] or tokens["at"]):
+        raise _LoggedOut("Could not find any auth token in /app — layout changed or cookies bad.")
+
+    # ĐĂNG XUẤT: bắt SỚM và nói THẲNG. Không có kiểm tra này, Gemini vẫn chat bình thường (chat
+    # ẩn danh được phép) nhưng TỪ CHỐI tạo ảnh, và lỗi hiện ra là "No image URL in response" —
+    # câu đó khiến người ta đi sửa nhầm model id hoặc prompt, trong khi vấn đề chỉ là cookie chết.
+    if not tokens["at"] and "accounts.google.com/ServiceLogin" in html:
+        raise _LoggedOut(
+            "Session ĐĂNG XUẤT và auto-refresh từ Brave KHÔNG cứu được (profile Brave riêng "
+            "chưa đăng nhập, hoặc Google đã bind/thu hồi). Mở cửa sổ Brave debug mà "
+            "refresh_gemini_cookies.py bật lên, ĐĂNG NHẬP Gemini một lần, rồi thử lại. "
+            "(Tắt auto-refresh bằng GEMINI_AUTO_REFRESH=0.)"
+        )
+    return tokens
+
+
+def _build_freq(prompt: str, files: list[tuple[str, str]] | None = None) -> str:
+    """Dựng lại payload f.req của StreamGenerate cho một lượt chat mới.
+
+    `files` = [(file_id, filename)]. Index 3 của message_content là chỗ Gemini web
+    đặt danh sách file đính kèm; để None nếu chỉ có text.
+    """
+    attachments = [[[fid, 1], name] for fid, name in (files or [])] or None
+    message_content: list[Any] = [prompt, 0, None, attachments, None, None, 0]
+    inner: list[Any] = [None] * 73
+    inner[0] = message_content
+    inner[2] = ["", "", "", None, None, None, None, None, None, ""]   # new-chat metadata
+    inner[7] = 1                                                      # snapshot streaming
+    return json.dumps([None, json.dumps(inner)])
+
+
+async def _resolve_image(session: AsyncSession, url: str) -> bytes | None:
+    """Some Google image hops return a text/plain body holding the next URL.
+    Follow up to a few hops, then return the raw image bytes."""
+    if "=" not in url.rsplit("/", 1)[-1]:
+        url = f"{url}={_IMG_SIZE}"
+    if _ACCOUNT > 0 and "authuser=" not in url:
+        url += f"{'&' if '?' in url else '?'}authuser={_ACCOUNT}"
+    for _ in range(5):
+        r = await session.get(url)
+        r.raise_for_status()
+        ctype = (r.headers.get("content-type") or "").lower()
+        if ctype.startswith("image/"):
+            return r.content
+        if ctype.startswith("text/plain"):
+            nxt = r.text.strip()
+            if nxt.startswith("http"):
+                url = nxt
+                continue
+        # Unknown but non-empty binary — assume it's the image.
+        if r.content and not ctype.startswith("text/html"):
+            return r.content
+        return None
+    return None
+
+
+async def _delete_conversation(session: AsyncSession, tokens: dict[str, str], cid: str) -> None:
+    """Xoá hội thoại vừa tạo trên Gemini (best-effort tuyệt đối).
+
+    Mỗi lượt generate mở một chat MỚI, để lại một mục trong lịch sử tài khoản. Sau khi đã
+    lấy xong ảnh (ảnh nằm trên CDN lh3, không phụ thuộc hội thoại) thì hội thoại vô dụng —
+    xoá luôn để không tích rác. Hỏng (mạng, đổi RPC, thiếu token) thì bỏ qua, KHÔNG được
+    làm hỏng lượt sinh: ảnh đã lưu rồi.
+    """
+    if not cid:
+        return
+    try:
+        params: dict[str, Any] = {"rpcids": _DELETE_RPC, "_reqid": random.randint(10000, 99999), "rt": "c"}
+        if tokens.get("bl"):
+            params["bl"] = tokens["bl"]
+        if tokens.get("f.sid"):
+            params["f.sid"] = tokens["f.sid"]
+        freq = json.dumps([[[_DELETE_RPC, json.dumps([cid]), None, "generic"]]])
+        data = {"f.req": freq, "at": tokens.get("at", "")}
+        url = f"{_BASE}{_prefix(_ACCOUNT)}{_BATCH_PATH}"
+        await session.post(url, params=params, data=data)
+    except Exception:
+        pass
+
+
+async def _upload(path: Path) -> tuple[str, str]:
+    """Đẩy 1 ảnh lên Gemini, trả (file_id, filename).
+
+    Dùng session RIÊNG, không tái dùng session chat: _BASE_HEADERS đặt sẵn
+    Content-Type: application/x-www-form-urlencoded, mà upload cần multipart/form-data
+    kèm boundary do curl tự sinh. Tái dùng session sẽ ghi đè content-type -> upload hỏng.
+
+    Endpoint này cũng KHÔNG cần cookie auth — nó nhận file rồi trả về một id đục,
+    id đó mới được nhét vào payload StreamGenerate.
+
+    LƯU Ý curl_cffi: KHÔNG dùng được `files=`/`data=` kiểu requests/httpx — curl_cffi ném
+    NotImplementedError("files is not supported, use `multipart`"). Phải dựng CurlMime.
+    """
+    blob = path.read_bytes()
+
+    mime = CurlMime()
+    mime.addpart(
+        name="file",
+        content_type=_MIME_BY_EXT.get(path.suffix.lower(), "application/octet-stream"),
+        filename=path.name,
+        data=blob,
+    )
+    mime.addpart(name="File name", data=path.name.encode("utf-8"))
+
+    try:
+        async with AsyncSession(impersonate="chrome", timeout=_TIMEOUT) as up:
+            r = await up.post(
+                _UPLOAD_URL,
+                headers={"push-id": _UPLOAD_PUSH_ID},
+                multipart=mime,
+            )
+    finally:
+        mime.close()
+
+    if r.status_code != 200:
+        raise RuntimeError(f"Upload thất bại cho {path.name}: HTTP {r.status_code}")
+    file_id = r.text.strip()
+    if not file_id:
+        raise RuntimeError(f"Upload cho {path.name} trả về id rỗng")
+    return file_id, path.name
+
+
+def _validate_images(image_paths: list[str]) -> list[Path]:
+    if len(image_paths) > _MAX_IMAGES:
+        raise RuntimeError(f"Tối đa {_MAX_IMAGES} ảnh, nhận được {len(image_paths)}")
+    out: list[Path] = []
+    for raw in image_paths:
+        p = Path(raw)
+        if not p.is_file():
+            raise RuntimeError(f"Không thấy file ảnh: {p}")
+        if p.suffix.lower() not in _ALLOWED_EXT:
+            raise RuntimeError(f"Đuôi file không hỗ trợ {p.suffix} ({p.name})")
+        if p.stat().st_size > _MAX_IMAGE_BYTES:
+            raise RuntimeError(f"Ảnh quá lớn (>7MB): {p.name}")
+        out.append(p)
+    return out
+
+
+# Xoá watermark ✦ ngay lúc tải về. Tắt bằng GEMINI_KEEP_WATERMARK=1.
+_KEEP_WM = os.environ.get("GEMINI_KEEP_WATERMARK", "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _strip_wm(blob: bytes) -> bytes:
+    """Bỏ ngôi sao ✦ Gemini đóng ở góc dưới-phải, TRƯỚC khi ảnh chạm đĩa.
+
+    Phải làm ở ĐÚNG đây — điểm hẹp duy nhất mọi ảnh Gemini web đi qua — vì watermark nằm
+    trong pixel màu: mọi bước sau (tách nền, cắt sheet, resize về size asset gốc) đều bôi nó
+    ra hoặc bake thẳng vào asset xuất ra, và khi ảnh đã bị resize/cắt thì hình học
+    48x48@96px không còn đúng nên KHÔNG còn cách lấy lại pixel gốc nữa.
+
+    Dùng verify=False: ảnh ở đây chắc chắn từ Gemini web nên không cần dò, và phép đảo trộn
+    alpha là chính xác (sai số ≤ ~1 mức, xem imglib.unwatermark_gemini).
+
+    Hỏng thì trả blob GỐC: watermark là lỗi nhỏ, mất ảnh vừa sinh mới là lỗi to.
+    """
+    if _KEEP_WM:
+        return blob
+    try:
+        with Image.open(io.BytesIO(blob)) as im:
+            im.load()
+            clean, info = L.unwatermark_gemini(im)
+            if info is None:
+                return blob
+            buf = io.BytesIO()
+            clean.save(buf, format="PNG")
+            return buf.getvalue()
+    except Exception:
+        return blob
+
+
+def dest_of(out_dir: str | None) -> Path:
+    """Thư mục lưu ảnh sinh ra. Tách riêng để đường local và đường mượn-máy dùng CHUNG."""
+    return Path(out_dir) if out_dir else _IMAGE_DIR
+
+
+async def _generate(
+    prompt: str,
+    image_paths: list[str] | None = None,
+    out_dir: str | None = None,
+) -> list[str]:
+    """Full flow: validate -> auth -> upload ảnh -> StreamGenerate -> tải ảnh về.
+
+    CHẾ ĐỘ MƯỢN MÁY: đặt GAMEART_REMOTE_URL/TOKEN thì cả khối này chạy trên MÁY CHỦ (nơi
+    có cookie Gemini) — máy khách chỉ gửi prompt + ảnh tham chiếu dạng base64 rồi nhận ảnh
+    về và tự ghi xuống đĩa CỦA NÓ. Mọi tool phía trên không hề biết, tên tool không đổi.
+    """
+    # Validate TRƯỚC khi mkdir: một lời gọi sai (quá 4 ảnh, sai đuôi, path không tồn tại)
+    # không nên để lại thư mục rác trên đĩa.
+    paths = _validate_images(image_paths or [])
+
+    if RB.enabled():
+        # KHÔNG rớt về local khi máy chủ hỏng: máy khách thường KHÔNG có cookie Gemini, nên
+        # "thử lại tại chỗ" chỉ đổi một lỗi rõ ràng thành một lỗi khó hiểu hơn.
+        return await RB.generate(prompt, [str(p) for p in paths], str(dest_of(out_dir)))
+
+    dest = dest_of(out_dir)
+    dest.mkdir(parents=True, exist_ok=True)
+
+    files = [await _upload(p) for p in paths]
+
+    session = _new_session()
+    try:
+        try:
+            tokens = await _auth(session)
+        except _LoggedOut:
+            # Cookie bị thu hồi -> rotate vô ích. TỰ đăng nhập lại từ Brave (profile vẫn
+            # login), ghi cookie tươi, rồi thử LẠI đúng 1 lần với session mới. Refresh hỏng
+            # (Brave chưa login/không có) thì ném _LoggedOut nguyên gốc cho user xử lý.
+            if not await _refresh_cookies_via_brave():
+                raise
+            await session.close()
+            session = _new_session()
+            tokens = await _auth(session)
+
+        params: dict[str, Any] = {"_reqid": random.randint(10000, 99999), "rt": "c"}
+        if tokens["bl"]:
+            params["bl"] = tokens["bl"]
+        if tokens["f.sid"]:
+            params["f.sid"] = tokens["f.sid"]
+
+        data = {"at": tokens["at"], "f.req": _build_freq(prompt, files)}
+        gen_url = f"{_BASE}{_prefix(_ACCOUNT)}{_GENERATE_PATH}"
+
+        r = await session.post(gen_url, params=params, data=data, headers=_model_header())
+        if r.status_code != 200:
+            raise RuntimeError(f"StreamGenerate failed: HTTP {r.status_code}")
+
+        body = r.text
+        if body.startswith(")]}'"):
+            body = body[4:]
+
+        # Robust extraction: pull every image URL out of the raw frames, dedup,
+        # preserve order. More resilient than depending on exact nested indices.
+        seen: set[str] = set()
+        urls: list[str] = []
+        for u in _IMG_URL_RE.findall(body):
+            u = u.replace("\\/", "/").rstrip("\\")
+            if u not in seen:
+                seen.add(u)
+                urls.append(u)
+        if not urls:
+            raise RuntimeError(
+                "No image URL in response. The prompt may have been refused, or the "
+                "image model id / URL pattern changed. Try a clearer 'generate an image of ...' prompt."
+            )
+
+        saved: list[str] = []
+        stamp = datetime.now().strftime("%Y%m%d%H%M%S")
+        for i, u in enumerate(urls):
+            try:
+                blob = await _resolve_image(session, u)
+            except Exception:
+                blob = None
+            if not blob:
+                continue
+            out = dest / f"{stamp}_{i}.png"
+            out.write_bytes(_strip_wm(blob))
+            saved.append(str(out))
+
+        # Ảnh đã tải xong (nằm trên CDN, độc lập với hội thoại) -> xoá chat vừa tạo để không
+        # làm rác tài khoản Gemini. Best-effort: chạy TRƯỚC khi kiểm 'saved' rỗng để cả lượt
+        # hỏng-download cũng không để lại chat treo.
+        if _DELETE_CHAT:
+            m = _CID_RE.search(body)
+            if m:
+                await _delete_conversation(session, tokens, m.group(0))
+
+        if not saved:
+            raise RuntimeError("Found image URLs but could not download any (cookies/redirect issue).")
+        return saved
+    finally:
+        await session.close()
+
+
+# --------------------------------------------------------------------------- #
+# RESTYLE HELPERS — port nguyên từ scripts/restyle.py (CLI cũ), giữ y hệt các
+# rào an toàn của `apply` vì đó là nơi có thể phá HỎNG asset gốc của người dùng.
+# --------------------------------------------------------------------------- #
+def _open_rgba(path: str) -> Image.Image:
+    return Image.open(path).convert("RGBA")
+
+
+def _parse_size(s: str) -> tuple[int, int]:
+    w, _, h = s.lower().partition("x")
+    return (int(w), int(h))
+
+
+# Auto-key: chroma-key trượt CẢ KHUNG khi model vẽ nền LỆCH màu key yêu cầu (đo thật:
+# yêu cầu #00FF00, agy/Nano Banana vẽ "xanh studio" #2ED246 kèm vignette -> coverage=1.0,
+# bad_background, dù bản sinh dùng tốt). Trước khi bắt sinh lại (tốn 1 lượt), dò màu nền
+# THẬT từ vành ảnh và key lại bằng màu đó. Chỉ áp cho đường chroma-key — BEN2 không quan
+# tâm màu nền nên không bao giờ cần cứu kiểu này.
+_AUTOKEY_MIN_PURITY = 0.85   # vành phải thuần 1 màu mới dám tin nó là nền phẳng
+_AUTOKEY_MIN_DIST = 40.0     # màu dò được phải LỆCH hẳn key yêu cầu (không thì key lại vô ích)
+
+
+def _postprocess_autokey(img, key_hex, src_img, size_wh, cutout, full_bleed=False, up=None):
+    """L.postprocess ở chế độ ĐA PHƯƠNG PHÁP. Trả (out_img, report).
+
+    report luôn có `key_auto` (bool); khi màu nền dò được lệch hẳn màu yêu cầu thì `key` là
+    màu ĐÃ DÙNG còn `key_requested` giữ màu ban đầu. Ngoài ra có `cutout_method` (cách đã
+    thắng) và `cutout_table` (điểm của MỌI ứng viên, kể cả bị loại).
+
+    KHÔNG còn tự dò `bg_hex` rồi truyền vào nữa — `L.best_cutout` bên trong postprocess làm
+    việc đó tốt hơn hẳn, và truyền tay sẽ CHẶN nó tự dò:
+      • nó dùng MODE trên vành đã lọc theo màu key, thay cho MEAN của sample_border_color.
+        Đo thật trên ảnh nền full-bleed (home_grass/gpt1.png): mean trả `#AC4978` purity
+        **0.0002** nên cửa `purity >= 0.85` không bao giờ mở và cả pipeline rơi về màu yêu
+        cầu; mode trả `#FB0EE0`, đúng màu model đã vẽ.
+      • nhịp "tự cứu" cũ (dò màu -> nếu bad_subject thì quay về màu yêu cầu) cũng bỏ được:
+        best_cutout luôn để CẢ HAI cách trong danh sách ứng viên rồi chấm điểm, nên không
+        cần chạy lại lần hai và không cần đoán trước cách nào đúng.
+    `sample_border_color` vẫn được đo và báo cáo (`bg_sampled`/`bg_purity`) để đối chiếu.
+
+    `full_bleed`: chuyển tiếp cho postprocess — xem docstring ở đó. Bật cho ảnh nền tràn viền.
+    `up`: backend phóng to (upscale.upscale_rgb) — chỉ có tác dụng khi bản sinh NHỎ hơn
+    khung đích. Ảnh sinh thường TO hơn asset game nên phần lớn lượt chạy sẽ không đụng tới.
+    """
+    out_img, report = L.postprocess(
+        img, key_hex, src=src_img, size=size_wh, cutout=cutout, full_bleed=full_bleed,
+        upscale=up,
+    )
+
+    # Hợp đồng báo cáo giữ nguyên như đời auto-key: key_auto=True khi màu THẬT DÙNG để key
+    # lệch hẳn màu yêu cầu; `key` là màu đã dùng, `key_requested` giữ màu ban đầu.
+    used = report.get("bg_color_used", key_hex)
+    auto = L.color_dist(L.hex_to_rgb(used), L.hex_to_rgb(key_hex)) >= _AUTOKEY_MIN_DIST
+    report["key_auto"] = auto
+    if auto:
+        report["key"] = used
+        report["key_requested"] = key_hex
+    bg_sampled, purity = L.sample_border_color(img)
+    report["bg_sampled"] = bg_sampled
+    report["bg_purity"] = purity
+    return out_img, report
+
+
+def _sanitize_drive_component(drive: str) -> str:
+    """Biến prefix ổ đĩa/UNC thành MỘT thành phần đường dẫn phẳng, an toàn.
+
+    Với dst là đường dẫn UNC (`\\\\server\\share\\art\\a.png`), `dst.drive` =
+    `\\\\server\\share` — CHÍNH nó đã là một anchor tuyệt đối theo pathlib. Nối trực tiếp
+    `Path("_abs") / dst.drive / ...` khiến pathlib coi vế phải là gốc mới và ÂM THẦM VỨT
+    BỎ mọi thứ bên trái (kể cả `backup_dir`) — backup thoát hẳn ra khỏi `backup_dir`, có
+    thể trùng khớp lên chính `dst`. Hàm này tước mọi separator/colon ở đầu-cuối rồi thay
+    separator còn lại bằng "_", đảm bảo kết quả KHÔNG BAO GIỜ được pathlib hiểu là rooted.
+    """
+    s = drive.strip("\\/")
+    s = s.replace(":", "").replace("\\", "_").replace("/", "_")
+    return s or "root"
+
+
+def _backup_path(backup_dir: Path, dst: Path, project_root: Path | None = None) -> Path:
+    """Backup mirror ĐƯỜNG DẪN của dst (tính từ `project_root`), không chỉ basename.
+
+    backup_dir/<basename> đụng nhau khi hai asset trùng tên (img/a/icon.png vs
+    img/b/icon.png). Guard "không ghi đè backup đã có" khi đó sẽ thấy backup của asset
+    ĐẦU, bỏ qua bước backup asset thứ hai, và bản gốc thứ hai bị ghi đè mà không lưu ở đâu
+    cả. Mirror path giữ mỗi asset một backup riêng.
+
+    `project_root` KHÔNG được ngầm định cwd ở đây — cwd lúc gọi là trạng thái AMBIENT.
+    Hai lần `apply` cùng `dst` gọi từ hai cwd khác nhau sẽ mirror ra HAI backup path khác
+    nhau, và bản ghi thứ hai coi asset "chưa có backup" rồi ghi đè lên biến thể #1 thay vì
+    bản gốc thật. Luôn truyền `project_root` cố định.
+    """
+    dst = dst.resolve()
+    root = (project_root if project_root is not None else Path.cwd()).resolve()
+    try:
+        rel = dst.relative_to(root)
+    except ValueError:
+        rel = Path("_abs", _sanitize_drive_component(dst.drive), *dst.parts[1:])
+    return backup_dir / rel
+
+
+# --------------------------------------------------------------------------- #
+# MCP surface. These tools NOW read image_paths and write out_dir/dst,
+# so exposing this over a network tunnel WOULD hand callers local file access.
+# stdio-local only. See CẢNH BÁO in the header docstring above.
+# --------------------------------------------------------------------------- #
+mcp = FastMCP("gemini-image")
+
+
+@mcp.tool()
+async def generate_image(
+    prompt: str,
+    image_paths: list[str] | None = None,
+    out_dir: str | None = None,
+) -> str:
+    """Sinh ảnh từ prompt, có thể kèm ảnh đầu vào (image-to-image).
+
+    Args:
+        prompt: Mô tả cần vẽ. Khi có image_paths, hãy nói rõ "the FIRST image",
+            "the SECOND image" để chỉ đúng ảnh nào.
+        image_paths: Tối đa 4 ảnh (.png/.jpg/.jpeg/.webp, mỗi ảnh <=7MB) gửi kèm
+            làm ảnh tham chiếu — dùng cho restyle giữ nguyên hình dạng.
+        out_dir: Thư mục lưu ảnh. Mặc định GEMINI_IMAGE_DIR.
+    Returns:
+        Các đường dẫn PNG đã lưu, cách nhau bằng xuống dòng.
+    """
+    try:
+        paths = await _generate(prompt.strip(), image_paths, out_dir)
+        return "Saved:\n" + "\n".join(paths)
+    except Exception as e:
+        return f"Error: {type(e).__name__}: {e}"
+
+
+@mcp.tool()
+async def plan_asset(src: str, avoid: list[str] | None = None) -> dict:
+    """Đọc asset gốc -> size, bbox, bảng màu, và MÀU KEY an toàn để tách nền.
+
+    Chạy TRƯỚC khi restyle: cho biết dùng màu key nào, có an toàn không, và kích thước
+    đích để bám 1-1 khi thay asset.
+
+    Args:
+        src: đường dẫn asset gốc (.png…).
+        avoid: danh sách hex ("#RRGGBB") của BẢNG MÀU STYLE PRESET — gộp vào việc chấm
+            điểm chọn key. BẮT BUỘC truyền khi đã có style: chroma key chạy trên ảnh ĐÃ
+            RESTYLE (palette mới), không phải palette asset gốc mà tool này tự đọc; bỏ qua
+            thì một style neon-xanh-lá trên asset đỏ vẫn có thể khiến chọn nhầm xanh lá.
+    Returns:
+        dict gồm width, height, bbox, palette, key, key_margin, key_safe.
+        key_safe=false -> màu key sát màu asset, chủ thể có nguy cơ ra mờ như bóng ma.
+    """
+    try:
+        img = _open_rgba(src)
+        avoid_rgb = [L.hex_to_rgb(h.strip()) for h in (avoid or []) if h.strip()]
+        key, margin = L.pick_key_color(img, avoid=avoid_rgb)
+        safe = margin == float("inf") or margin >= L.MIN_KEY_MARGIN
+        return {
+            "path": src,
+            "width": img.width,
+            "height": img.height,
+            "bbox": L.content_bbox(img),
+            "palette": L.extract_palette(img, n=8),
+            "key": key,
+            "key_margin": None if margin == float("inf") else round(margin, 1),
+            "key_safe": safe,
+        }
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+@mcp.tool()
+async def restyle_asset(
+    prompt: str,
+    image_paths: list[str],
+    src: str | None = None,
+    key: str | None = None,
+    size: str | None = None,
+    n: int = 3,
+    out_dir: str | None = None,
+    full_bleed: bool = False,
+) -> dict:
+    """Sinh N biến thể restyle rồi TÁCH NỀN + bám kích thước gốc cho từng bản (gộp
+    generate + postprocess). Trả đường dẫn ảnh input/output kèm cờ lỗi để duyệt.
+
+    Tách nền chạy NHIỀU cách rồi chấm điểm chọn bản tốt nhất — xem `process_raws`.
+
+    Mỗi biến thể là một lượt Gemini ĐỘC LẬP (chat mới). Ảnh thô lưu ở out_dir/_raw/,
+    ảnh đã tách nền lưu out_dir/v{i}.png.
+
+    Args:
+        prompt: prompt đầy đủ (đã nhét sẵn màu nền key vào — xem `key`).
+        image_paths: [asset_gốc, (anchor/ref…)] tối đa 4 ảnh cho mỗi lượt.
+        src: asset gốc để BÁM size+bbox 1-1 (thường = image_paths[0]). Bỏ qua nếu dùng `size`.
+        key: màu key HEX cho chroma key — PHẢI khớp màu nền mà `prompt` yêu cầu Gemini vẽ.
+            Bỏ trống -> suy ra từ `src` (chỉ đúng khi prompt cũng dùng đúng màu đó).
+        size: "WxH" ép kích thước khác thay vì bám `src`.
+        n: số biến thể (mặc định 3). Mỗi biến thể tốn 1 lượt Gemini.
+        out_dir: thư mục lưu. Mặc định GEMINI_IMAGE_DIR.
+        full_bleed: BẬT cho ảnh NỀN tràn viền — xem `process_raws`. Mặc định tắt (asset rời).
+    Returns:
+        dict: key, size, src, n_requested, n_produced, variants[] (mỗi phần tử có
+        out/raw/status/flags/coverage/solid_ratio/border_impurity/hole_ratio/
+        speckles_removed/key_auto/cutout_method/cutout_table — key_auto=true nghĩa là màu
+        nền dò được lệch hẳn key yêu cầu nên tool đã key theo màu dò được; khi đó
+        `key` là màu dò được, `key_requested` giữ màu ban đầu. `cutout_method` là cách tách
+        nền đã THẮNG điểm, `cutout_table` là điểm của mọi ứng viên kể cả bị loại), gen_errors[].
+    """
+    try:
+        if n < 1:
+            return {"error": "n phải >= 1"}
+        src_img = _open_rgba(src) if src else None
+        size_wh = _parse_size(size) if size else None
+        if src_img is None and size_wh is None:
+            return {"error": "cần `src` (bám gốc) hoặc `size` (WxH)"}
+
+        if key:
+            key_hex = key
+        elif src_img is not None:
+            key_hex = L.pick_key_color(src_img)[0]
+        else:
+            key_hex = L.KEY_CANDIDATES[0]
+
+        dest = Path(out_dir) if out_dir else _IMAGE_DIR
+        raw_dir = dest / "_raw"
+        raw_dir.mkdir(parents=True, exist_ok=True)
+
+        # Tách nền "xịn" bằng BEN2 nếu có torch+ben2; nếu thiếu thì rớt về chroma-key.
+        # Ưu tiên GPU TẠI CHỖ; không có thì mượn máy chủ. Thứ tự này là cố ý — chạy local
+        # luôn nhanh hơn và không tốn băng thông; mượn máy chỉ để cứu máy không có GPU.
+        cutout = (bgremove.remove_background if bgremove.available()
+                  else RB.cutout_backend())
+        # Backend PHÓNG TO — chỉ có tác dụng khi bản sinh NHỎ hơn khung đích. Không có ở đâu
+        # cả thì None và mọi thứ rơi về LANCZOS, KHÔNG lỗi.
+        up = UP.backend() or RB.upscale_backend()
+        # `remover` giờ là DANH SÁCH Ứng viên khả dụng, không phải cách sẽ dùng: tách nền chạy
+        # nhiều cách rồi chấm điểm, nên cách THẬT SỰ dùng cho từng ảnh nằm ở
+        # variants[i]["cutout_method"]. Báo "ben2" ở đây từng đúng khi BEN2 độc quyền,
+        # nhưng bây giờ nó sẽ NÓI SAI — đo thật trên 4 bản home_grass: remover="ben2"
+        # trong khi cả 4 đều thắng bằng `unmix`.
+        remover = "multi+ben2" if cutout else "multi"
+
+        variants: list[dict] = []
+        gen_errors: list[str] = []
+        idx = 0
+        for _ in range(n):
+            try:
+                raws = await _generate(prompt.strip(), image_paths, str(raw_dir))
+            except Exception as e:
+                gen_errors.append(f"{type(e).__name__}: {e}")
+                continue
+            for raw in raws:
+                idx += 1
+                out_img, report = _postprocess_autokey(
+                    _open_rgba(raw), key_hex, src_img, size_wh, cutout,
+                    full_bleed=full_bleed, up=up,
+                )
+                report["raw"] = raw
+                report["remover"] = report.get("cutout_method") or remover
+                report["cutout_candidates_available"] = remover
+                if out_img is None:
+                    report["out"] = None
+                else:
+                    out_path = dest / f"v{idx}.png"
+                    out_img.save(out_path, optimize=True)
+                    report["out"] = str(out_path)
+                variants.append(report)
+
+        return {
+            "key": key_hex,
+            "remover": remover,
+            "upscaler": UP.info(),
+            "remote": RB.info(),
+            "size": list(size_wh) if size_wh else None,
+            "src": src,
+            "out_dir": str(dest),
+            "n_requested": n,
+            "n_produced": len(variants),
+            "variants": variants,
+            "gen_errors": gen_errors,
+            "compare_group": _compare_group(src, dest, variants),
+        }
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+@mcp.tool()
+async def process_raws(
+    raws: list[str],
+    src: str | None = None,
+    key: str | None = None,
+    size: str | None = None,
+    out_dir: str | None = None,
+    prefix: str = "v",
+    full_bleed: bool = False,
+) -> dict:
+    """TÁCH NỀN + bám size gốc cho ảnh THÔ sinh từ backend NGOÀI (agy CLI / Codex CLI).
+
+    Đây là nửa postprocess của restyle_asset tách riêng: khi ảnh thô KHÔNG do Gemini
+    MCP sinh (Antigravity `agy` hoặc Codex `codex` đã sinh và lưu file), đưa danh sách
+    file vào đây để tách nền + bám size+bbox asset gốc, trả về cùng cấu trúc variants[]
+    như restyle_asset để duyệt chung một luồng.
+
+    TÁCH NỀN CHẠY NHIỀU CÁCH RỒI CHỌN BẢN TỐT NHẤT (không còn tin sẵn một cách): unmix đại
+    số theo màu nền đo được, chroma-key theo màu đo được, chroma-key theo màu yêu cầu, và
+    BEN2 nếu có. Mỗi bản được chấm bằng 4 tiêu chí đo được (viền còn ám màu nền / sai màu
+    tiền cảnh / ăn lòng chủ thể / nền còn sót); bản điểm tốt nhất được giao ra, tên nó ở
+    `cutout_method` và bảng điểm đủ mọi ứng viên ở `cutout_table`.
+
+    Args:
+        raws: ảnh thô đã sinh sẵn (.png/.jpg/.jpeg/.webp), theo thứ tự muốn đánh số.
+        src: asset gốc để BÁM size+bbox 1-1. Bỏ qua nếu dùng `size`.
+        key: màu key HEX — PHẢI khớp màu nền mà prompt đã yêu cầu backend vẽ.
+            Bỏ trống -> suy ra từ `src` (chỉ đúng khi prompt cũng dùng đúng màu đó).
+        size: "WxH" ép kích thước khác thay vì bám `src`.
+        out_dir: thư mục lưu ảnh đã tách nền. Mặc định GEMINI_IMAGE_DIR.
+        prefix: tiền tố tên file ra, dùng đánh dấu backend — "agy" -> agy1.png, agy2.png;
+            "gpt" -> gpt1.png... Mặc định "v". Chỉ nhận [A-Za-z0-9_-], tối đa 32 ký tự.
+        full_bleed: BẬT cho ảnh NỀN tràn viền (background plate) — tranh phủ kín khung nên
+            chủ thể CHẠM vành ảnh là đúng thiết kế. Nó tắt riêng cửa gác `border_impurity`
+            (cửa đó giả định vành ảnh toàn là nền). Không bật thì MỌI ảnh nền đều bị đánh
+            `bad_background` dù tách nền hoàn hảo — đo thật trên 4 bản home_grass: cast 0,
+            bg_residue 0.0000, vẫn bị báo hỏng. `bg_residue`/`coverage`/bộ chấm điểm vẫn gác
+            như thường. ĐỪNG bật cho asset rời (sprite/icon) — ở đó lề nền là yêu cầu thật.
+    Returns:
+        dict: key, remover, size, src, out_dir, n_raws, n_produced, variants[] (mỗi
+        phần tử có out/raw/status/flags/coverage/solid_ratio/border_impurity/
+        hole_ratio/speckles_removed/key_auto/cutout_method/cutout_table — xem restyle_asset
+        về ý nghĩa key_auto/key_requested), errors[] (raw không đọc được).
+    """
+    try:
+        if not raws:
+            return {"error": "raws rỗng — cần ít nhất 1 ảnh thô"}
+        # prefix đi thẳng vào tên file trong out_dir — chặn separator/'..' để không
+        # thoát ra ngoài thư mục đích.
+        if not re.fullmatch(r"[A-Za-z0-9_-]{1,32}", prefix):
+            return {"error": f"prefix không hợp lệ ({prefix!r}) — chỉ [A-Za-z0-9_-], <=32 ký tự"}
+        src_img = _open_rgba(src) if src else None
+        size_wh = _parse_size(size) if size else None
+        if src_img is None and size_wh is None:
+            return {"error": "cần `src` (bám gốc) hoặc `size` (WxH)"}
+
+        if key:
+            key_hex = key
+        elif src_img is not None:
+            key_hex = L.pick_key_color(src_img)[0]
+        else:
+            key_hex = L.KEY_CANDIDATES[0]
+
+        dest = Path(out_dir) if out_dir else _IMAGE_DIR
+        dest.mkdir(parents=True, exist_ok=True)
+
+        # Ưu tiên GPU TẠI CHỖ; không có thì mượn máy chủ. Thứ tự này là cố ý — chạy local
+        # luôn nhanh hơn và không tốn băng thông; mượn máy chỉ để cứu máy không có GPU.
+        cutout = (bgremove.remove_background if bgremove.available()
+                  else RB.cutout_backend())
+        # Backend PHÓNG TO — chỉ có tác dụng khi bản sinh NHỎ hơn khung đích. Không có ở đâu
+        # cả thì None và mọi thứ rơi về LANCZOS, KHÔNG lỗi.
+        up = UP.backend() or RB.upscale_backend()
+        # `remover` giờ là DANH SÁCH Ứng viên khả dụng, không phải cách sẽ dùng: tách nền chạy
+        # nhiều cách rồi chấm điểm, nên cách THẬT SỰ dùng cho từng ảnh nằm ở
+        # variants[i]["cutout_method"]. Báo "ben2" ở đây từng đúng khi BEN2 độc quyền,
+        # nhưng bây giờ nó sẽ NÓI SAI — đo thật trên 4 bản home_grass: remover="ben2"
+        # trong khi cả 4 đều thắng bằng `unmix`.
+        remover = "multi+ben2" if cutout else "multi"
+
+        variants: list[dict] = []
+        errors: list[str] = []
+        idx = 0
+        for raw in raws:
+            try:
+                img = _open_rgba(raw)
+            except Exception as e:
+                errors.append(f"{raw}: {type(e).__name__}: {e}")
+                continue
+            idx += 1
+            # Ảnh thô ở đây NGUỒN LẪN: `agy` cũng là Gemini nên có thể mang watermark ✦, còn
+            # Codex/GPT Image 2 thì không. Vì vậy verify=True — đảo trộn alpha chỉ khi đo được
+            # bằng chứng, bằng không sẽ đóng một ngôi sao TỐI vào ảnh Codex sạch. Phải xoá
+            # TRƯỚC _postprocess_autokey: bước đó tách nền + resize, sau đó thì hình học
+            # 48x48@96px không còn đúng và watermark bị bake luôn vào asset.
+            img, wm = L.unwatermark_gemini(img, verify=True)
+            out_img, report = _postprocess_autokey(
+                img, key_hex, src_img, size_wh, cutout, full_bleed=full_bleed, up=up
+            )
+            report["watermark_removed"] = bool(wm)
+            report["raw"] = str(raw)
+            report["remover"] = report.get("cutout_method") or remover
+            report["cutout_candidates_available"] = remover
+            if out_img is None:
+                report["out"] = None
+            else:
+                out_path = dest / f"{prefix}{idx}.png"
+                out_img.save(out_path, optimize=True)
+                report["out"] = str(out_path)
+            variants.append(report)
+
+        return {
+            "key": key_hex,
+            "remover": remover,
+            "upscaler": UP.info(),
+            "remote": RB.info(),
+            "size": list(size_wh) if size_wh else None,
+            "src": src,
+            "out_dir": str(dest),
+            "n_raws": len(raws),
+            "n_produced": len(variants),
+            "variants": variants,
+            "errors": errors,
+            "compare_group": _compare_group(src, dest, variants),
+        }
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+@mcp.tool()
+async def slice_sheet(
+    sheet: str,
+    key: str,
+    out_dir: str,
+    prefix: str = "cell",
+    mockup_frac: float = 0.5,
+    min_cell: int = 24,
+    pad: int = 4,
+) -> dict:
+    """Chế độ SCREEN SHEET: mổ một ảnh "màn hình + dải chi tiết" thành mockup + từng asset.
+
+    Đầu vào là MỘT ảnh do model sinh theo prompt screen-sheet (xem
+    reference/prompt-template.md § Screen sheet): phần TRÊN là mockup cả màn hình đã
+    restyle, phần DƯỚI là các chi tiết (nút, icon, panel…) vẽ RỜI NHAU trên nền phẳng màu
+    key. Tool cắt phần trên ra `<prefix>_mockup.png` (giữ nguyên, không tách nền), tự dò
+    từng mảng liên thông ở phần dưới làm một cell, tách nền từng cell (BEN2, fallback
+    chroma-key + auto-key như process_raws) và lưu `<prefix>1.png`… theo thứ tự đọc
+    (trên→dưới, trái→phải).
+
+    Args:
+        sheet: đường dẫn ảnh sheet model sinh ra.
+        key: màu key HEX mà prompt yêu cầu cho nền dải chi tiết. Nền lệch màu (xanh
+            studio…) sẽ được tự dò lại từ vành dải — xem `key_auto` trong kết quả.
+        out_dir: thư mục lưu mockup + cells.
+        prefix: đánh dấu backend, như process_raws ("agy" -> agy_mockup.png, agy1.png…).
+        mockup_frac: phần CAO của sheet là mockup (0..0.9, mặc định 0.5 = nửa trên).
+            Đặt 0 nếu sheet chỉ có dải chi tiết, không có mockup.
+        min_cell: mảng có CẢ hai chiều dưới ngưỡng này (px) bị coi là nhiễu, bỏ qua.
+        pad: nới bbox mỗi cell thêm ngần này px trước khi cắt.
+    Returns:
+        dict: mockup (path hoặc null), key (màu đã dùng thật), key_auto, remover,
+        n_cells, cells[] (mỗi phần tử: out, box [x0,y0,x1,y1] trên sheet, flags,
+        coverage, solid_ratio…), out_dir. Cells là asset MỚI kích thước tự nhiên —
+        muốn thay 1-1 asset cũ thì đưa cell qua process_raws với src=<asset gốc>.
+    """
+    try:
+        if not re.fullmatch(r"[A-Za-z0-9_-]{1,32}", prefix):
+            return {"error": f"prefix không hợp lệ ({prefix!r}) — chỉ [A-Za-z0-9_-], <=32 ký tự"}
+        if not (0.0 <= mockup_frac <= 0.9):
+            return {"error": f"mockup_frac phải trong [0, 0.9], nhận {mockup_frac}"}
+        img = _open_rgba(sheet)
+        # Watermark ✦ nằm ở góc dưới-phải sheet, tức LỌT VÀO dải chi tiết — không xoá trước
+        # thì nó vừa bị dò thành một "cell" rác, vừa bake vào cell nào nằm gần góc. verify=True
+        # vì sheet có thể do backend ngoài (agy/Codex) sinh, không riêng Gemini web.
+        img, wm_info = L.unwatermark_gemini(img, verify=True)
+        w, h = img.size
+        y_split = int(h * mockup_frac)
+
+        dest = Path(out_dir)
+        dest.mkdir(parents=True, exist_ok=True)
+
+        mockup_path = None
+        if y_split > 0:
+            mp = dest / f"{prefix}_mockup.png"
+            img.crop((0, 0, w, y_split)).save(mp, optimize=True)
+            mockup_path = str(mp)
+
+        strip = img.crop((0, y_split, w, h))
+        if strip.height < 4:
+            return {"error": "phần dải chi tiết quá mỏng — kiểm lại mockup_frac"}
+
+        # Nền dải có thể lệch màu key yêu cầu (xanh studio #2ED246…) — dò từ vành dải,
+        # cùng ngưỡng với _postprocess_autokey.
+        key_hex = key
+        key_auto = False
+        bg_hex, purity = L.sample_border_color(strip)
+        if (purity >= _AUTOKEY_MIN_PURITY
+                and L.color_dist(L.hex_to_rgb(bg_hex), L.hex_to_rgb(key_hex)) > _AUTOKEY_MIN_DIST):
+            key_hex, key_auto = bg_hex, True
+
+        rgb = np.asarray(strip.convert("RGB"), dtype=np.uint8)
+        dist = L._dist_map(rgb, L.hex_to_rgb(key_hex))
+        boxes = L.component_boxes(dist > 80.0, min_size=min_cell)
+
+        cutout = (bgremove.remove_background if bgremove.available()
+                  else RB.cutout_backend())
+        # `remover` giờ là DANH SÁCH Ứng viên khả dụng, không phải cách sẽ dùng: tách nền chạy
+        # nhiều cách rồi chấm điểm, nên cách THẬT SỰ dùng cho từng ảnh nằm ở
+        # variants[i]["cutout_method"]. Báo "ben2" ở đây từng đúng khi BEN2 độc quyền,
+        # nhưng bây giờ nó sẽ NÓI SAI — đo thật trên 4 bản home_grass: remover="ben2"
+        # trong khi cả 4 đều thắng bằng `unmix`.
+        remover = "multi+ben2" if cutout else "multi"
+
+        cells: list[dict] = []
+        for i, (x0, y0, x1, y1) in enumerate(boxes, start=1):
+            bx0 = max(0, x0 - pad)
+            bx1 = min(w, x1 + pad)
+            by0 = y_split + max(0, y0 - pad)
+            by1 = y_split + min(strip.height, y1 + pad)
+            cell = img.crop((bx0, by0, bx1, by1))
+            out_img, report = L.postprocess(
+                cell, key_hex, size=(cell.width, cell.height), cutout=cutout
+            )
+            report["box"] = [bx0, by0, bx1, by1]
+            if out_img is None:
+                report["out"] = None
+            else:
+                out_path = dest / f"{prefix}{i}.png"
+                out_img.save(out_path, optimize=True)
+                report["out"] = str(out_path)
+            cells.append(report)
+
+        return {
+            "mockup": mockup_path,
+            "key": key_hex,
+            "key_requested": key,
+            "key_auto": key_auto,
+            "remover": remover,
+            "watermark_removed": bool(wm_info),
+            "n_cells": len(cells),
+            "cells": cells,
+            "out_dir": str(dest),
+            # Sẵn sàng cho make_compare_sheet: nhóm mockup lấy CHÍNH sheet gốc làm `original`
+            # (lật để thấy layout có xê dịch không), nhóm cells `original: null` vì cell là
+            # asset MỚI, không có bản gốc 1-1.
+            "compare_groups": [
+                g for g in (
+                    {"name": "Màn hình (mockup)", "original": str(sheet),
+                     "variants": ([{"label": f"{prefix}_mockup", "image": mockup_path}]
+                                  if mockup_path else [])},
+                    {"name": "Cells cắt ra", "original": None,
+                     "variants": [{"label": Path(c["out"]).stem, "image": c["out"]}
+                                  for c in cells if c.get("out")]},
+                ) if g["variants"]
+            ],
+        }
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+@mcp.tool()
+async def make_contact_sheet(
+    labels: list[str], images: list[str], out: str, cell: int = 160
+) -> dict:
+    """Dựng contact sheet để DUYỆT BẰNG MẮT: mỗi ảnh 1 cột, 3 hàng nền (sáng/tối/caro).
+
+    Ba nền là có chủ đích — sáng lộ viền tối, tối lộ viền sáng+spill, caro lộ vùng bán
+    trong suốt. Đây là cửa gác THẬT SỰ trước khi apply, không phải các cờ tự động.
+
+    Args:
+        labels: nhãn mỗi cột (vd "original", "v1", "v2"…). Cùng độ dài với `images`.
+        images: đường dẫn ảnh mỗi cột (asset gốc + các biến thể).
+        out: đường dẫn PNG sheet xuất ra.
+        cell: cạnh ô (px), mặc định 160.
+    Returns:
+        dict: out, cells (nhãn).
+    """
+    try:
+        if len(labels) != len(images):
+            return {"error": f"labels ({len(labels)}) và images ({len(images)}) phải cùng độ dài"}
+        cells = [(labels[i], _open_rgba(images[i])) for i in range(len(images))]
+        Path(out).parent.mkdir(parents=True, exist_ok=True)
+        L.make_sheet(cells, cell=cell).save(out)
+        return {"out": out, "cells": labels}
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+@mcp.tool()
+async def make_web_sheet(
+    labels: list[str], images: list[str], out: str, cell: int = 240
+) -> dict:
+    """Dựng TRANG WEB duyệt cutout (review.html tự chứa) — bản web của make_contact_sheet.
+
+    Hơn PNG tĩnh ở chỗ đổi nền TRỰC TIẾP (caro/sáng/tối/màu tùy chọn) để soi mép và vùng
+    bán trong suốt, kéo slider phóng to, mở bằng trình duyệt nào cũng chạy. Một file HTML
+    duy nhất (ảnh nhúng base64), không phụ thuộc file ngoài — gửi đi/mở lại đều được.
+
+    Args:
+        labels: nhãn mỗi ảnh (vd "original", "v1", "v2"…). Cùng độ dài với `images`.
+        images: đường dẫn ảnh (asset gốc + các biến thể đã tách nền).
+        out: đường dẫn .html xuất ra.
+        cell: cạnh ô hiển thị mặc định (px), slider zoom chỉnh được sau.
+    Returns:
+        dict: out, cells (nhãn).
+    """
+    try:
+        if len(labels) != len(images):
+            return {"error": f"labels ({len(labels)}) và images ({len(images)}) phải cùng độ dài"}
+        cells = [(labels[i], _open_rgba(images[i])) for i in range(len(images))]
+        dest = Path(out)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(L.web_sheet(cells, cell=cell), encoding="utf-8")
+        return {"out": str(dest), "cells": labels}
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+@mcp.tool()
+async def make_thumbs(
+    sources: list[dict], out_dir: str, anchor: str = "center", prefix: str = "thumb"
+) -> dict:
+    """Chế độ THUMBNAIL: đưa ảnh thô về ĐÚNG 3 kích thước cửa hàng. KHÔNG tách nền.
+
+    Model sinh ảnh không cho chọn kích thước đầu ra, nên luồng đúng là sinh ở tỉ lệ gần nhất
+    rồi cắt bù + resize ở đây. Đo thật trên Gemini web: yêu cầu dọc → 864x1216, ngang →
+    1376x768, vuông → 1024x1024 — đều sát mục tiêu, cắt bù chỉ mất ≤1%.
+
+    Thumbnail là tranh FULL-BLEED: đừng đưa qua `process_raws`/`restyle_asset` (hai đường đó
+    tách nền + bám bbox asset gốc, sai hoàn toàn mục đích).
+
+    Args:
+        sources: mỗi phần tử `{"raw": "<đường dẫn ảnh thô>", "preset": "1:1"|"5:7"|"16:9"}`.
+            Thêm `"size": "WxH"` để ép kích thước khác preset. Thêm `"label"` để đặt tên file
+            (mặc định lấy theo preset).
+        out_dir: thư mục lưu thumb.
+        anchor: giữ phần nào khi cắt — "center" (mặc định), "top", "bottom", "left", "right".
+            Thumb dọc hay có logo ở trên → "top" an toàn hơn. Đặt riêng cho từng nguồn bằng
+            khoá `"anchor"` trong phần tử của `sources`.
+        prefix: tiền tố tên file. Chỉ [A-Za-z0-9_-], tối đa 32 ký tự.
+    Returns:
+        dict: out_dir, thumbs[] (out, preset, src, target, crop, lost_frac, upscaled),
+        warnings[] (ảnh phải PHÓNG TO — thumb sẽ mềm, nên sinh lại nguồn to hơn),
+        errors[] (nguồn không đọc được / preset sai).
+    """
+    try:
+        if not sources:
+            return {"error": "sources rỗng — cần ít nhất 1 ảnh thô"}
+        if not re.fullmatch(r"[A-Za-z0-9_-]{1,32}", prefix):
+            return {"error": f"prefix không hợp lệ ({prefix!r}) — chỉ [A-Za-z0-9_-], <=32 ký tự"}
+        dest = Path(out_dir)
+        dest.mkdir(parents=True, exist_ok=True)
+
+        thumbs: list[dict] = []
+        warnings: list[str] = []
+        errors: list[str] = []
+        # Hai nguồn cùng preset trong MỘT lời gọi sẽ ra cùng tên file và ghi đè nhau im lặng —
+        # gặp ngay khi mỗi preset có 2 bản để so sánh. Đếm để đánh số _2, _3.
+        used: dict[str, int] = {}
+        for i, s in enumerate(sources):
+            if not isinstance(s, dict):
+                errors.append(f"sources[{i}] phải là dict, nhận {type(s).__name__}")
+                continue
+            raw = s.get("raw")
+            preset = str(s.get("preset") or "")
+            if not raw:
+                errors.append(f"sources[{i}] thiếu `raw`")
+                continue
+            if s.get("size"):
+                try:
+                    target = _parse_size(str(s["size"]))
+                except Exception as e:
+                    errors.append(f"sources[{i}] size sai: {e}")
+                    continue
+            elif preset in L.THUMB_PRESETS:
+                target = L.THUMB_PRESETS[preset]
+            else:
+                errors.append(
+                    f"sources[{i}] preset {preset!r} không có — chọn "
+                    f"{'/'.join(L.THUMB_PRESETS)} hoặc truyền `size`: \"WxH\""
+                )
+                continue
+            try:
+                img = Image.open(str(raw))
+                img.load()
+            except Exception as e:
+                errors.append(f"{raw}: {type(e).__name__}: {e}")
+                continue
+
+            fitted, info = L.fit_thumb(img, target, anchor=str(s.get("anchor") or anchor),
+                                       upscale=UP.backend())
+            label = str(s.get("label") or (preset.replace(":", "x") or f"{target[0]}x{target[1]}"))
+            safe = re.sub(r"[^A-Za-z0-9_-]", "_", label)[:40]
+            used[safe] = used.get(safe, 0) + 1
+            if used[safe] > 1:
+                safe = f"{safe}_{used[safe]}"
+            out_path = dest / f"{prefix}_{safe}.png"
+            fitted.save(out_path, optimize=True)
+            info.update({"out": str(out_path), "preset": preset or None, "raw": str(raw)})
+            thumbs.append(info)
+            if info["upscaled"]:
+                how = info.get("upscale_method") or "lanczos"
+                tail = ("ảnh sẽ mềm" if how == "lanczos"
+                        else f"đã dựng nét lại bằng `{how}`, nhưng chi tiết là do model ĐOÁN")
+                warnings.append(
+                    f"{out_path.name}: nguồn {info['src'][0]}x{info['src'][1]} NHỎ hơn đích "
+                    f"{target[0]}x{target[1]} -> đã phóng to, {tail}. Sinh lại nguồn to hơn vẫn tốt hơn."
+                )
+        if not thumbs:
+            return {"error": "không tạo được thumb nào", "errors": errors}
+        return {
+            "out_dir": str(dest), "n_thumbs": len(thumbs),
+            "thumbs": thumbs, "warnings": warnings, "errors": errors,
+        }
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+@mcp.tool()
+async def remote_nodes() -> dict:
+    """Bảng TẢI + QUOTA của mọi node đang cấu hình — dùng để xem vì sao node nào được chọn.
+
+    Chỉ có nghĩa ở CHẾ ĐỘ MƯỢN MÁY (đã đặt GAMEART_REMOTE_NODES / GAMEART_REMOTE_URL).
+    Không tốn lượt sinh ảnh, không chạm GPU: `status` bên máy chủ cố tình KHÔNG khoá gì cả,
+    nên node đang bận vẫn trả lời được là nó đang bận.
+
+    Returns:
+        dict: enabled, env (nạp .env từ file nào + TÊN các biến đã có — không bao giờ trả
+        giá trị), nodes[] (url, name, available{gemini,codex,ben2,esrgan},
+        slots{running,waiting,capacity,queue_max,load,full},
+        quota{state,used_hour,used_day,limit_hour,limit_day,cooldown_left},
+        client_cooldown_left nếu máy khách đang tạm bỏ qua node đó).
+        `state`: ok | limited (chạm hạn mức tự khai) | exhausted (backend đã báo hết quota).
+    """
+    try:
+        # Báo luôn .env đã nạp từ đâu: "tạo .env rồi mà không ăn" là ca hỏng hay gặp nhất,
+        # và không có dòng này thì chẳng có cách nào biết file có được đọc hay không.
+        env = _envfile.info()
+        if not RB.enabled():
+            return {"enabled": False, "env": env,
+                    "hint": f"đặt {RB.P.ENV_NODES} hoặc {RB.P.ENV_URL} + {RB.P.ENV_TOKEN} "
+                            f"(trong .env cạnh SKILL.md, hoặc env hệ thống)"}
+        return {"enabled": True, "wait_budget_sec": RB.P.DEFAULT_WAIT, "env": env,
+                "nodes": RB.status_all(force=True)}
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+@mcp.tool()
+async def upscale_image(
+    image_paths: list[str],
+    out_dir: str,
+    size: str | None = None,
+    scale: float | None = None,
+    prefix: str = "up",
+) -> dict:
+    """PHÓNG TO ảnh đã có mà không sinh lại — khi bản AI sinh ra nhỏ hơn kích thước cần.
+
+    Chạy NHIỀU cách rồi chấm điểm chọn bản tốt nhất, giống đường tách nền: LANCZOS,
+    Real-ESRGAN x4plus_anime_6B, và biến thể "LANCZOS trước / model sau" cho hệ số > 4x.
+    Cách thắng nằm ở `upscale_method`, điểm của mọi ứng viên ở `upscale_table`.
+
+    Giữ nguyên alpha: RGB và matte được phóng riêng, và màu tiền cảnh được loang ra vùng
+    trong suốt TRƯỚC khi phóng — nếu không, màu nền key còn nằm lại ở đó (vô hình nhưng
+    model vẫn thấy) sẽ bị kéo vào mép và sinh viền màu.
+
+    ĐỪNG dùng thay cho việc sinh lại ở độ phân giải đúng: chi tiết thêm vào là model ĐOÁN,
+    không phải thông tin thật. Đây là cách chữa cháy khi không sinh lại được.
+
+    Args:
+        image_paths: ảnh cần phóng (.png/.jpg/.jpeg/.webp).
+        out_dir: thư mục lưu.
+        size: "WxH" — ép ĐÚNG kích thước này (bỏ qua tỉ lệ gốc nếu lệch).
+        scale: hệ số phóng, vd 2.0. Dùng khi không truyền `size`. Mặc định 2.0.
+        prefix: tiền tố tên file ra. Chỉ [A-Za-z0-9_-], tối đa 32 ký tự.
+    Returns:
+        dict: out_dir, upscaler (model/thiết bị), results[] (out/src/from/to/
+        upscale_method/upscale_score/upscale_table), errors[].
+    """
+    try:
+        if not image_paths:
+            return {"error": "image_paths rỗng"}
+        if not re.fullmatch(r"[A-Za-z0-9_-]{1,32}", prefix):
+            return {"error": f"prefix không hợp lệ ({prefix!r}) — chỉ [A-Za-z0-9_-], <=32 ký tự"}
+        if size and scale:
+            return {"error": "chỉ truyền MỘT trong `size` hoặc `scale`"}
+        size_wh = _parse_size(size) if size else None
+        if size_wh is None:
+            scale = 2.0 if scale is None else float(scale)
+            if not (1.0 < scale <= 16.0):
+                return {"error": f"scale phải trong khoảng (1, 16], nhận {scale}"}
+
+        dest = Path(out_dir)
+        dest.mkdir(parents=True, exist_ok=True)
+        up = UP.backend()
+
+        results: list[dict] = []
+        errors: list[str] = []
+        for i, p in enumerate(image_paths, start=1):
+            try:
+                img = _open_rgba(p)
+            except Exception as e:
+                errors.append(f"{p}: {type(e).__name__}: {e}")
+                continue
+            target = size_wh or (max(1, round(img.width * scale)), max(1, round(img.height * scale)))
+            out_img, rep = L.best_upscale(img, target, backend=up)
+            out_path = dest / f"{prefix}{i}.png"
+            out_img.save(out_path, optimize=True)
+            rep.update({"out": str(out_path), "src": str(p)})
+            results.append(rep)
+
+        if not results:
+            return {"error": "không phóng được ảnh nào", "errors": errors}
+        return {
+            "out_dir": str(dest),
+            "upscaler": UP.info(),
+            "n_produced": len(results),
+            "results": results,
+            "errors": errors,
+        }
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+def _compare_group(src: str | None, dest: Path, variants: list[dict]) -> dict:
+    """Dựng sẵn một `group` để truyền THẲNG vào make_compare_sheet.
+
+    Trả kèm trong kết quả của mọi tool sinh ảnh, vì trang đối chiếu là bản giao BẮT BUỘC sau
+    mỗi lượt (xem SKILL.md): tự lắp tay thì dễ ghép lệch `original` với biến thể của asset
+    khác, hoặc quên hẳn bản gốc — đúng cái làm mất khả năng đối chiếu. Nhãn lấy theo tên file
+    (`agy1`, `gpt2`…) nên biết ngay bản nào của AI nào.
+
+    Một asset thường qua HAI lượt gọi (prefix `agy` rồi `gpt`) → hai group cùng `name`;
+    người gọi GỘP chúng lại bằng cách nối `variants`, đừng dựng hai section cho một asset.
+    """
+    return {
+        "name": Path(src).stem if src else dest.name,
+        "original": str(src) if src else None,
+        "variants": [
+            {"label": Path(v["out"]).stem, "image": v["out"]}
+            for v in variants if v.get("out")
+        ],
+    }
+
+
+@mcp.tool()
+async def make_compare_sheet(groups: list[dict], out: str, cell: int = 240) -> dict:
+    """Dựng trang ĐỐI CHIẾU gốc↔mới (compare.html tự chứa) — BẢN GIAO sau MỖI lượt thiết kế.
+
+    Khác `make_web_sheet` (lưới phẳng, mọi ảnh ngang hàng): ở đây gom NHÓM THEO ASSET, bản
+    gốc nằm ngay cạnh biến thể của chính nó, và mỗi thẻ biến thể lật được về gốc NGAY TẠI CHỖ
+    (nhấn giữ / nháy đúp để khoá / nút xem tất cả bản gốc). Xếp chồng đúng một vị trí và một
+    kích thước mới thấy được lệch hình dạng nhỏ — hai thẻ nằm cạnh nhau thì mắt bỏ qua.
+
+    Args:
+        groups: mỗi phần tử là một asset:
+            {"name": "coin", "original": "<path asset gốc>|null",
+             "variants": [{"label": "agy1", "image": "<path>"}, ...]}
+            `original: null` cho thứ không có asset gốc 1-1 (vd cells screen-sheet) —
+            khi đó thẻ chỉ hiện bản mới, không có nút lật.
+        out: đường dẫn .html xuất ra.
+        cell: cạnh ô hiển thị mặc định (px); slider zoom chỉnh sau.
+    Returns:
+        dict: out, n_groups, n_variants, missing[] (ảnh không đọc được, đã bỏ qua).
+    """
+    try:
+        if not groups:
+            return {"error": "groups rỗng — cần ít nhất 1 asset"}
+        parsed: list[tuple[str, Image.Image | None, list[tuple[str, Image.Image]]]] = []
+        missing: list[str] = []
+        n_var = 0
+        for gi, g in enumerate(groups):
+            if not isinstance(g, dict):
+                return {"error": f"groups[{gi}] phải là dict, nhận {type(g).__name__}"}
+            name = str(g.get("name") or f"asset{gi + 1}")
+            orig = None
+            op = g.get("original")
+            if op:
+                try:
+                    orig = _open_rgba(str(op))
+                except Exception as e:
+                    missing.append(f"{op}: {type(e).__name__}: {e}")
+            variants: list[tuple[str, Image.Image]] = []
+            for vi, v in enumerate(g.get("variants") or []):
+                # Nhận cả {"label","image"} và ["label","path"] để gọi cho đỡ cứng nhắc.
+                if isinstance(v, dict):
+                    lbl, ip = str(v.get("label") or f"v{vi + 1}"), v.get("image")
+                elif isinstance(v, (list, tuple)) and len(v) == 2:
+                    lbl, ip = str(v[0]), v[1]
+                else:
+                    missing.append(f"{name}.variants[{vi}]: dạng không hiểu ({v!r})")
+                    continue
+                if not ip:
+                    continue
+                try:
+                    variants.append((lbl, _open_rgba(str(ip))))
+                except Exception as e:
+                    missing.append(f"{ip}: {type(e).__name__}: {e}")
+            if orig is None and not variants:
+                continue      # nhóm rỗng hoàn toàn -> bỏ, đừng dựng section trống
+            n_var += len(variants)
+            parsed.append((name, orig, variants))
+        if not parsed:
+            return {"error": "không đọc được ảnh nào", "missing": missing}
+
+        dest = Path(out)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(L.compare_sheet(parsed, cell=cell), encoding="utf-8")
+        return {
+            "out": str(dest), "n_groups": len(parsed),
+            "n_variants": n_var, "missing": missing,
+        }
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+@mcp.tool()
+async def apply_asset(
+    variant: str, dst: str, backup_dir: str, project_root: str | None = None
+) -> dict:
+    """Backup asset gốc rồi GHI ĐÈ bằng biến thể đã duyệt. Chỉ chạy sau khi người dùng
+    duyệt sheet.
+
+    An toàn (không bao giờ phá bản gốc):
+      - Chỉ ghi đè file .png (từ chối mọi loại khác).
+      - Backup mirror đúng đường dẫn dst dưới backup_dir (theo project_root, không theo cwd).
+      - KHÔNG BAO GIỜ ghi đè backup đã có -> luôn giữ bản gốc THẬT đầu tiên.
+      - Từ chối nếu backup resolve TRÙNG lên dst, hoặc THOÁT ra ngoài backup_dir. Không ghi gì.
+      - Copy backup atomic (.tmp + os.replace) để không để lại backup cụt.
+
+    Args:
+        variant: đường dẫn biến thể .png đã duyệt.
+        dst: asset gốc .png trong project (sẽ bị ghi đè).
+        backup_dir: thư mục lưu backup (vd tools/restyle/backup).
+        project_root: gốc project (tuyệt đối) để mirror path backup. PHẢI truyền tường minh
+            trong pipeline nhiều lệnh apply; mặc định cwd nếu bỏ trống.
+    Returns:
+        dict: {applied, backup} khi thành công, hoặc {error} — không ghi gì khi có error.
+    """
+    try:
+        src, dst_p = Path(variant), Path(dst)
+        if not src.is_file():
+            return {"error": f"không thấy variant: {src}"}
+        if not dst_p.is_file():
+            return {"error": f"không thấy asset đích: {dst_p}"}
+        if src.suffix.lower() != ".png":
+            return {"error": f"variant phải là .png, nhận: {src}"}
+        if dst_p.suffix.lower() != ".png":
+            return {"error": f"asset đích phải là .png, nhận: {dst_p}"}
+
+        root = Path(project_root) if project_root else Path.cwd()
+        bdir = Path(backup_dir)
+        bdir.mkdir(parents=True, exist_ok=True)
+        bdir_resolved = bdir.resolve()
+        dst_resolved = dst_p.resolve()
+
+        backup = _backup_path(bdir, dst_p, project_root=root)
+        backup_resolved = backup.resolve()
+
+        # Hai cách backup có thể trùng lên chính dst (vd `backup_dir=.` từ project root, hoặc
+        # dst là UNC). Nếu lọt, guard "không ghi đè backup đã có" sẽ thấy backup==dst tồn tại,
+        # BỎ QUA bước backup rồi ghi đè dst — bản gốc biến mất. KHÔNG GHI GÌ trước khi qua cả hai.
+        if backup_resolved == dst_resolved:
+            return {"error": (
+                f"backup path ({backup_resolved}) trùng với chính asset đích — "
+                "backup_dir/project_root không được resolve trùng lên dst. Không ghi gì cả."
+            )}
+        try:
+            backup_resolved.relative_to(bdir_resolved)
+        except ValueError:
+            return {"error": (
+                f"backup path ({backup_resolved}) thoát ra ngoài backup_dir "
+                f"({bdir_resolved}). Không ghi gì cả."
+            )}
+
+        if not backup.exists():
+            backup.parent.mkdir(parents=True, exist_ok=True)
+            # shutil.copy2 không atomic — ngắt giữa chừng để lại backup cụt mà `backup.exists()`
+            # vẫn True, guard bỏ qua backup, bản gốc bị ghi đè vĩnh viễn. .tmp + os.replace đảm
+            # bảo backup hoặc tồn tại ĐẦY ĐỦ hoặc không tồn tại.
+            tmp = backup.with_suffix(backup.suffix + ".tmp")
+            shutil.copy2(dst_p, tmp)
+            os.replace(tmp, backup)
+
+        shutil.copy2(src, dst_p)
+        return {"applied": str(dst_p), "backup": str(backup)}
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+@mcp.tool()
+async def auth_status() -> dict:
+    """Chẩn đoán cookie/đăng nhập Gemini — KHÔNG tốn lượt sinh ảnh.
+
+    Chạy rotate (POST RotateCookies + GET RotateCookiesPage, ghi cookie mới về file)
+    rồi GET /app, báo lại: có đăng nhập không, cookie nào Google vừa xoay, file cookie
+    có được cập nhật không. Dùng để kiểm luồng rotate mới có giữ session sống không.
+
+    Returns:
+        dict: logged_in, logged_out_marker, status_code, final_url,
+        psidts_changed / psid_changed (sau rotate), cookies_updated (tên cookie đã đổi
+        trong file), cookies_present.
+    """
+    if RB.enabled():
+        # Máy khách KHÔNG có cookie Gemini — hỏi thẳng máy chủ, đừng báo "logged_out" cho một
+        # cấu hình hoàn toàn bình thường.
+        pr = RB.probe(force=True)
+        return {
+            "mode": "remote",
+            "remote": RB.info(),
+            # Khả năng ở đây là của CẢ CỤM: một node có Gemini là cụm sinh ảnh được.
+            "logged_in": bool(pr.get("gemini")),
+            "codex": bool(pr.get("codex")),
+            "ben2": bool(pr.get("ben2")),
+            "esrgan": bool(pr.get("esrgan")),
+            "n_nodes": pr.get("n_nodes"),
+            "n_alive": pr.get("n_alive"),
+            "nodes": pr.get("nodes"),
+            "error": pr.get("error"),
+        }
+    try:
+        before = {
+            "1PSIDTS": _load_psidts(),
+            "1PSID": _load_psid(),
+            "file": _raw_cookies(),
+        }
+        async with _new_session() as session:
+            await _rotate_psidts(session)
+            url = f"{_BASE}{_prefix(_ACCOUNT)}{_INIT_PATH}"
+            r = await session.get(url)
+            _persist_cookies(session)
+
+            after_file = _raw_cookies()
+            updated = sorted(
+                k for k in set(before["file"]) | set(after_file)
+                if before["file"].get(k) != after_file.get(k)
+            )
+            html = r.text
+            at_m = _TOKEN_RE["at"].search(html)
+            at = at_m.group(1) if at_m else ""
+            logged_out = (not at) and "accounts.google.com/ServiceLogin" in html
+            return {
+                "logged_in": bool(at) and not logged_out,
+                "logged_out_marker": logged_out,
+                "status_code": r.status_code,
+                "final_url": str(r.url),
+                "psidts_changed": before["1PSIDTS"] != _load_psidts(),
+                "psid_changed": before["1PSID"] != _load_psid(),
+                "cookies_updated_in_file": updated,
+                "cookies_present": sorted(after_file.keys()),
+            }
+    except Exception as e:
+        return {"error": f"{type(e).__name__}: {e}"}
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()