gimp-mcp 0.2.0__py3-none-any.whl

gimp_mcp/__init__.py

@@ -0,0 +1,9 @@
+"""MCP server for inspecting and editing GIMP 3 projects."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Single source of truth: the `version` field of pyproject.toml.
+    __version__ = version("gimp-mcp")
+except PackageNotFoundError:  # pragma: no cover - running from an uninstalled tree
+    __version__ = "0+unknown"

gimp_mcp/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

gimp_mcp/bridge.py

@@ -0,0 +1,334 @@
+"""Client side of the local GIMP bridge (asyncio, Unix domain socket).
+
+Guarantees:
+
+* Requests are serialized: at most one request is in flight per client, so
+  mutations reach GIMP in the order the MCP server issued them and responses
+  can never be attributed to the wrong request.
+* Every wait is bounded (connect, handshake, request).
+* When a request times out or the connection drops before its response
+  arrives, the connection is discarded and the error says the outcome is
+  ``unknown``: the operation may still have run inside GIMP.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import select
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .errors import INSTALL_HINT, GimpMcpError
+from .versions import Compatibility, check_plugin_version
+
+log = logging.getLogger(__name__)
+
+PROTOCOL_VERSION = 1
+MIN_GIMP_VERSION = (3, 2)
+MAX_RESPONSE_BYTES = 64 * 1024 * 1024
+SOCKET_ENV = "GIMP_MCP_SOCKET"
+FLATPAK_APP = "org.gimp.GIMP"
+_POLLRDHUP = getattr(select, "POLLRDHUP", 0)
+
+
+@dataclass(frozen=True)
+class BridgeEndpoint:
+    socket_path: Path
+    token_path: Path
+
+    @classmethod
+    def for_socket(cls, socket_path: Path) -> BridgeEndpoint:
+        return cls(socket_path=socket_path, token_path=Path(str(socket_path) + ".token"))
+
+    @classmethod
+    def default(cls, environ: dict[str, str] | None = None) -> BridgeEndpoint:
+        return cls.for_socket(default_socket_path(environ))
+
+
+def default_socket_path(environ: dict[str, str] | None = None) -> Path:
+    """Socket path shared by the plug-in and the server (same rules on both sides)."""
+    env = os.environ if environ is None else environ
+    explicit = env.get(SOCKET_ENV)
+    if explicit:
+        return Path(explicit)
+    runtime = env.get("XDG_RUNTIME_DIR")
+    if runtime and os.path.isdir(runtime):
+        native = Path(runtime) / "gimp-mcp" / "bridge.sock"
+        # A Flatpak GIMP (org.gimp.GIMP) serves under the app directory shared with the host.
+        flatpak = Path(runtime) / "app" / FLATPAK_APP / "gimp-mcp" / "bridge.sock"
+        if not native.exists() and flatpak.exists():
+            return flatpak
+        return native
+    return Path("/tmp") / f"gimp-mcp-{os.getuid()}" / "bridge.sock"
+
+
+@dataclass(frozen=True)
+class SessionInfo:
+    gimp_version: str
+    session_id: str
+    pid: int | None
+    protocol: int
+    bridge_version: str | None = None
+
+    @classmethod
+    def from_wire(cls, data: dict[str, Any]) -> SessionInfo:
+        return cls(
+            gimp_version=str(data.get("gimp_version", "")),
+            session_id=str(data.get("session_id", "")),
+            pid=data.get("pid"),
+            protocol=int(data.get("protocol", 0)),
+            bridge_version=data.get("bridge_version"),
+        )
+
+
+def parse_version(text: str) -> tuple[int, ...]:
+    parts: list[int] = []
+    for piece in text.split("."):
+        digits = "".join(ch for ch in piece if ch.isdigit())
+        if not digits:
+            break
+        parts.append(int(digits))
+    return tuple(parts)
+
+
+class BridgeClient:
+    def __init__(
+        self,
+        endpoint: BridgeEndpoint | None = None,
+        *,
+        connect_timeout: float = 3.0,
+        request_timeout: float = 60.0,
+    ):
+        self.endpoint = endpoint or BridgeEndpoint.default()
+        self.connect_timeout = connect_timeout
+        self.request_timeout = request_timeout
+        self.session: SessionInfo | None = None
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._lock = asyncio.Lock()
+        self._next_id = 0
+
+    # -- public API ----------------------------------------------------------------
+
+    async def call(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+        *,
+        timeout: float | None = None,
+        mutating: bool = False,
+    ) -> Any:
+        async with self._lock:
+            await self._ensure_connected()
+            try:
+                return await self._request(method, params or {}, timeout or self.request_timeout, mutating)
+            except GimpMcpError as error:
+                # A read can safely be retried once on a fresh connection when the
+                # previous one turned out to be dead (e.g. GIMP was restarted).
+                if mutating or error.code != "DISCONNECTED":
+                    raise
+            await self._ensure_connected()
+            return await self._request(method, params or {}, timeout or self.request_timeout, mutating)
+
+    async def connect(self) -> SessionInfo:
+        async with self._lock:
+            await self._ensure_connected()
+            assert self.session is not None
+            return self.session
+
+    async def close(self) -> None:
+        writer, self._reader, self._writer = self._writer, None, None
+        if writer is not None:
+            writer.close()
+            try:
+                await asyncio.wait_for(writer.wait_closed(), timeout=1.0)
+            except (TimeoutError, OSError):
+                pass
+
+    # -- internals -----------------------------------------------------------------
+
+    async def _ensure_connected(self) -> None:
+        if (
+            self._writer is not None
+            and self._reader is not None
+            and not self._writer.is_closing()
+            and not self._reader.at_eof()
+            and not self._peer_went_away()
+        ):
+            return
+        await self.close()
+        socket_path = self.endpoint.socket_path
+        if not socket_path.exists():
+            raise GimpMcpError(
+                "GIMP_NOT_RUNNING",
+                f"no GIMP bridge socket at {socket_path}",
+                hint=INSTALL_HINT,
+            )
+        try:
+            token = self.endpoint.token_path.read_text(encoding="ascii").strip()
+        except OSError as exc:
+            raise GimpMcpError(
+                "BRIDGE_UNAVAILABLE",
+                f"cannot read bridge token {self.endpoint.token_path}: {exc.strerror}",
+                hint=INSTALL_HINT,
+            ) from exc
+        try:
+            reader, writer = await asyncio.wait_for(
+                asyncio.open_unix_connection(str(socket_path), limit=MAX_RESPONSE_BYTES),
+                timeout=self.connect_timeout,
+            )
+        except TimeoutError as exc:
+            raise GimpMcpError(
+                "BRIDGE_UNAVAILABLE",
+                f"timed out connecting to {socket_path} after {self.connect_timeout:g}s",
+                hint="GIMP may be busy or frozen. " + INSTALL_HINT,
+            ) from exc
+        except OSError as exc:
+            raise GimpMcpError(
+                "GIMP_NOT_RUNNING",
+                f"cannot connect to {socket_path}: {exc.strerror or exc}",
+                hint="The socket is stale: GIMP probably exited. " + INSTALL_HINT,
+            ) from exc
+        self._reader, self._writer = reader, writer
+        try:
+            hello = await self._request(
+                "hello", {"token": token, "protocol": PROTOCOL_VERSION}, self.connect_timeout, False
+            )
+        except GimpMcpError as exc:
+            await self.close()
+            if exc.code in ("TIMEOUT", "DISCONNECTED"):
+                raise GimpMcpError(
+                    "BRIDGE_UNAVAILABLE",
+                    f"bridge handshake failed: {exc.message}",
+                    hint=INSTALL_HINT,
+                ) from exc
+            raise
+        session = SessionInfo.from_wire(hello)
+        if session.protocol != PROTOCOL_VERSION:
+            await self.close()
+            raise GimpMcpError(
+                "VERSION_INCOMPATIBLE",
+                f"bridge speaks protocol {session.protocol}, this server needs {PROTOCOL_VERSION}",
+                hint="Reinstall the plug-in with `gimp-mcp install-plugin` and restart GIMP.",
+            )
+        if parse_version(session.gimp_version)[:2] < MIN_GIMP_VERSION:
+            await self.close()
+            minimum = ".".join(map(str, MIN_GIMP_VERSION))
+            raise GimpMcpError(
+                "VERSION_INCOMPATIBLE",
+                f"GIMP {session.gimp_version} is not supported (minimum {minimum})",
+                hint=f"Install GIMP {minimum} or newer.",
+                details={"gimp_version": session.gimp_version, "minimum": minimum},
+            )
+        verdict = check_plugin_version(__version__, session.bridge_version)
+        if verdict is Compatibility.INCOMPATIBLE:
+            await self.close()
+            raise GimpMcpError(
+                "PLUGIN_VERSION_MISMATCH",
+                f"the GIMP plug-in is version {session.bridge_version or 'unknown'} but this server is {__version__}",
+                hint="Run `gimp-mcp install-plugin`, then restart GIMP.",
+                details={"plugin_version": session.bridge_version or "unknown", "server_version": __version__},
+            )
+        if verdict is Compatibility.COMPATIBLE:
+            log.warning(
+                "GIMP plug-in %s differs from server %s (compatible patch versions); "
+                "run `gimp-mcp install-plugin` to align them",
+                session.bridge_version,
+                __version__,
+            )
+        if self.session is not None and self.session.session_id != session.session_id:
+            log.info("GIMP session changed: %s -> %s", self.session.session_id, session.session_id)
+        self.session = session
+
+    def _peer_went_away(self) -> bool:
+        """Detect a dead idle connection (e.g. GIMP restarted) before sending.
+
+        The bridge never sends unsolicited data, so an idle connection that is
+        readable or hung up has been closed by the other side.
+        """
+        assert self._writer is not None
+        sock = self._writer.get_extra_info("socket")
+        if sock is None:
+            return False
+        poller = select.poll()
+        poller.register(sock.fileno(), select.POLLIN | select.POLLHUP | select.POLLERR | _POLLRDHUP)
+        return bool(poller.poll(0))
+
+    async def _request(self, method: str, params: dict[str, Any], timeout: float, mutating: bool) -> Any:
+        assert self._reader is not None and self._writer is not None
+        self._next_id += 1
+        request_id = self._next_id
+        payload = json.dumps({"id": request_id, "method": method, "params": params}, separators=(",", ":"))
+        unknown = "unknown" if mutating else None
+        try:
+            self._writer.write(payload.encode("utf-8") + b"\n")
+            await asyncio.wait_for(self._writer.drain(), timeout=timeout)
+            line = await asyncio.wait_for(self._reader.readline(), timeout=timeout)
+        except asyncio.CancelledError:
+            # The caller gave up (e.g. the MCP request was cancelled). GIMP may
+            # still run the operation; its late answer must never be read as
+            # the answer to a later request, so drop the connection.
+            await self.close()
+            raise
+        except TimeoutError as exc:
+            await self.close()
+            raise GimpMcpError(
+                "TIMEOUT",
+                f"GIMP did not answer {method!r} within {timeout:g}s",
+                hint="GIMP may still be working. Inspect the image before retrying a modification.",
+                outcome=unknown,
+            ) from exc
+        except (OSError, asyncio.IncompleteReadError, ValueError) as exc:
+            await self.close()
+            raise GimpMcpError(
+                "DISCONNECTED",
+                f"connection to GIMP lost during {method!r}: {exc}",
+                hint="GIMP may have quit or crashed. " + INSTALL_HINT,
+                outcome=unknown,
+            ) from exc
+        if not line:
+            await self.close()
+            raise GimpMcpError(
+                "DISCONNECTED",
+                f"GIMP closed the connection during {method!r}",
+                hint="GIMP may have quit or crashed. " + INSTALL_HINT,
+                outcome=unknown,
+            )
+        try:
+            response = json.loads(line)
+        except ValueError as exc:
+            await self.close()
+            raise GimpMcpError("PROTOCOL_ERROR", f"invalid response from bridge: {exc}", outcome=unknown) from exc
+        if response.get("id") != request_id:
+            await self.close()
+            raise GimpMcpError(
+                "PROTOCOL_ERROR",
+                f"response id {response.get('id')!r} does not match request {request_id}",
+                outcome=unknown,
+            )
+        if "error" in response:
+            error = response["error"] or {}
+            code = str(error.get("code", "GIMP_ERROR"))
+            if code in ("UNAUTHORIZED", "PROTOCOL_ERROR", "REQUEST_TOO_LARGE"):
+                await self.close()
+            # Operations raise anticipated errors before changing anything; an
+            # unexpected GIMP failure may have happened half-way through.
+            if not mutating:
+                outcome = None
+            elif code == "GIMP_ERROR":
+                outcome = "unknown"
+            else:
+                outcome = "not_applied"
+            raise GimpMcpError(
+                code,
+                str(error.get("message", "unknown bridge error")),
+                details=error.get("details") or {},
+                hint=error.get("hint"),
+                outcome=outcome,
+            )
+        return response.get("result")

gimp_mcp/cli.py

@@ -0,0 +1,273 @@
+"""Command line entry point: ``gimp-mcp [serve|install-plugin|uninstall-plugin|doctor]``.
+
+stdout is reserved for the MCP protocol when serving; everything else goes to
+stderr.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+from pathlib import Path
+
+from . import __version__
+from .bridge import BridgeClient, BridgeEndpoint
+from .errors import GimpMcpError
+from .installer import default_gimp_config_dir, install_plugin, uninstall_plugin
+
+
+def _configure_logging(verbose: bool) -> None:
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.WARNING,
+        stream=sys.stderr,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        force=True,
+    )
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    from .server import build_server
+
+    endpoint = BridgeEndpoint.for_socket(Path(args.socket)) if args.socket else BridgeEndpoint.default()
+    server = build_server(BridgeClient(endpoint, request_timeout=args.timeout))
+    _configure_logging(args.verbose)
+    server.run("stdio")
+    return 0
+
+
+def cmd_install(args: argparse.Namespace) -> int:
+    config = Path(args.gimp_dir) if args.gimp_dir else default_gimp_config_dir()
+    target = install_plugin(config)
+    print(f"Installed the gimp-mcp bridge plug-in into {target}", file=sys.stderr)
+    print("Restart GIMP to load it.", file=sys.stderr)
+    return 0
+
+
+def cmd_uninstall(args: argparse.Namespace) -> int:
+    config = Path(args.gimp_dir) if args.gimp_dir else default_gimp_config_dir()
+    removed = uninstall_plugin(config)
+    print("Removed." if removed else f"Nothing installed in {config}.", file=sys.stderr)
+    return 0
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    import os
+
+    from .doctor import Probe, render_troubleshooting, run_doctor
+
+    if args.troubleshooting:
+        sys.stdout.write(render_troubleshooting())
+        return 0
+    endpoint = BridgeEndpoint.for_socket(Path(args.socket)) if args.socket else BridgeEndpoint.default()
+    probe = Probe(env=dict(os.environ), endpoint=endpoint, gimp_dir=Path(args.gimp_dir) if args.gimp_dir else None)
+    try:
+        code, output = asyncio.run(run_doctor(probe, as_json=args.json))
+    except Exception as exc:  # the doctor must never crash silently
+        print(f"error: the doctor could not run: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 2
+    print(output, file=sys.stdout if args.json else sys.stderr)
+    return code
+
+
+def cmd_inventory(args: argparse.Namespace) -> int:
+    import json
+
+    endpoint = BridgeEndpoint.for_socket(Path(args.socket)) if args.socket else BridgeEndpoint.default()
+
+    async def fetch() -> dict[str, object]:
+        client = BridgeClient(endpoint, request_timeout=args.timeout)
+        try:
+            return await client.call("pdb.inventory")
+        finally:
+            await client.close()
+
+    data = asyncio.run(fetch())
+    procedures = data["procedures"]
+    assert isinstance(procedures, list)
+    text = json.dumps(data, indent=1, sort_keys=True, ensure_ascii=False) + "\n"
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+        incomplete = sum(1 for p in procedures if "error" in p)
+        print(
+            f"{len(procedures)} procedures ({incomplete} with incomplete metadata) written to {args.output}",
+            file=sys.stderr,
+        )
+    else:
+        sys.stdout.write(text)
+    return 0
+
+
+def cmd_coverage(args: argparse.Namespace) -> int:
+    from .coverage import render_matrix
+
+    text = render_matrix(Path(args.inventory))
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+    else:
+        sys.stdout.write(text)
+    return 0
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    import os
+
+    from .setup import CLIENT_KEYS, SetupOptions, run_setup
+
+    endpoint = BridgeEndpoint.for_socket(Path(args.socket)) if args.socket else BridgeEndpoint.default()
+    clients: set[str]
+    if args.clients in (None, "all"):
+        clients = set(CLIENT_KEYS)
+    elif args.clients == "none":
+        clients = set()
+    else:
+        clients = {name.strip() for name in args.clients.split(",") if name.strip()}
+        unknown = clients - set(CLIENT_KEYS)
+        if unknown:
+            print(f"error: unknown client(s): {', '.join(sorted(unknown))}", file=sys.stderr)
+            return 2
+
+    def ask(question: str) -> bool:
+        try:
+            return input(question).strip().lower().startswith("y")
+        except EOFError:
+            return False
+
+    def say(text: str) -> None:
+        print(text, file=sys.stderr)
+
+    options = SetupOptions(
+        env=dict(os.environ),
+        endpoint=endpoint,
+        ask=ask,
+        say=say,
+        assume_yes=args.yes,
+        interactive=sys.stdin.isatty() and not args.yes,
+        run_doctor=not args.no_doctor,
+        gimp_dir=Path(args.gimp_dir) if args.gimp_dir else None,
+        clients=clients,
+    )
+    return asyncio.run(run_setup(options))
+
+
+def cmd_uninstall_all(args: argparse.Namespace) -> int:
+    import os
+
+    from .setup import SetupOptions, run_uninstall
+
+    def ask(question: str) -> bool:
+        try:
+            return input(question).strip().lower().startswith("y")
+        except EOFError:
+            return False
+
+    def say(text: str) -> None:
+        print(text, file=sys.stderr)
+
+    options = SetupOptions(
+        env=dict(os.environ),
+        endpoint=BridgeEndpoint.default(),
+        ask=ask,
+        say=say,
+        assume_yes=args.yes,
+        interactive=sys.stdin.isatty() and not args.yes,
+        run_doctor=False,
+        gimp_dir=Path(args.gimp_dir) if args.gimp_dir else None,
+    )
+    return asyncio.run(run_uninstall(options))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="gimp-mcp", description="MCP server for GIMP 3")
+    parser.add_argument("--version", action="version", version=f"gimp-mcp {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    serve = sub.add_parser("serve", help="run the MCP server on stdio (default)")
+    serve.add_argument("--socket", help="bridge socket path (default: $GIMP_MCP_SOCKET or runtime dir)")
+    serve.add_argument("--timeout", type=float, default=60.0, help="per-request timeout in seconds")
+    serve.add_argument("-v", "--verbose", action="store_true", help="debug logs on stderr")
+    serve.set_defaults(func=cmd_serve)
+
+    for name, func, text in (
+        ("install-plugin", cmd_install, "install the bridge plug-in into GIMP's config directory"),
+        ("uninstall-plugin", cmd_uninstall, "remove the bridge plug-in"),
+    ):
+        cmd = sub.add_parser(name, help=text)
+        cmd.add_argument("--gimp-dir", help="GIMP config dir (default: $GIMP3_DIRECTORY or ~/.config/GIMP/3.2)")
+        cmd.set_defaults(func=func)
+
+    doctor = sub.add_parser(
+        "doctor",
+        help="diagnose the installation and the connection to GIMP (exit 0 ok, 1 failures, 2 doctor error)",
+    )
+    doctor.add_argument("--socket")
+    doctor.add_argument("--gimp-dir", help="GIMP profile to check (default: the one GIMP uses)")
+    doctor.add_argument("--json", action="store_true", help="machine-readable result on stdout")
+    doctor.add_argument("--troubleshooting", action="store_true", help="print the troubleshooting table (Markdown)")
+    doctor.set_defaults(func=cmd_doctor)
+
+    setup = sub.add_parser(
+        "setup",
+        help="install the plug-in in GIMP's profile and register the server in your MCP clients",
+        description=(
+            "Detect GIMP, install or update the plug-in, register the MCP server in Claude Code, Claude Desktop, "
+            "VS Code and Cursor (each change is shown and needs your consent), then check the result. Safe to "
+            "run again."
+        ),
+    )
+    setup.add_argument("--yes", action="store_true", help="apply every change without asking (for scripts)")
+    setup.add_argument(
+        "--clients",
+        help="comma-separated clients to configure: claude-code, claude-desktop, vscode, cursor; or all / none "
+        "(default: all)",
+    )
+    setup.add_argument("--gimp-dir", help="GIMP profile (default: the one GIMP uses)")
+    setup.add_argument("--socket", help="bridge socket path (default: $GIMP_MCP_SOCKET or runtime dir)")
+    setup.add_argument("--no-doctor", action="store_true", help="skip the final doctor checks")
+    setup.set_defaults(func=cmd_setup)
+
+    uninstall = sub.add_parser(
+        "uninstall",
+        help="remove the plug-in from every GIMP profile and the MCP client entries gimp-mcp created",
+        description=(
+            "Remove what gimp-mcp added: the plug-in in every GIMP profile where it is installed and the 'gimp' "
+            "entries it created in MCP clients (entries pointing elsewhere are left). Each removal is shown and "
+            "needs your consent (or --yes). The package itself is removed with your installer (printed at the end)."
+        ),
+    )
+    uninstall.add_argument("--yes", action="store_true", help="remove without asking")
+    uninstall.add_argument("--gimp-dir", help="also consider this GIMP profile")
+    uninstall.set_defaults(func=cmd_uninstall_all)
+
+    inventory = sub.add_parser("inventory", help="dump the procedure database of the running GIMP as JSON")
+    inventory.add_argument("--socket")
+    inventory.add_argument("--output", help="file to write (default: stdout)")
+    inventory.add_argument("--timeout", type=float, default=300.0)
+    inventory.set_defaults(func=cmd_inventory)
+
+    coverage = sub.add_parser("coverage", help="render the coverage matrix (Markdown) from an inventory")
+    coverage.add_argument("--inventory", required=True)
+    coverage.add_argument("--output")
+    coverage.set_defaults(func=cmd_coverage)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        args = parser.parse_args(["serve", *(argv or [])])
+    try:
+        return args.func(args)
+    except GimpMcpError as error:
+        print(f"error: {error}", file=sys.stderr)
+        if error.hint:
+            print(f"hint: {error.hint}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gimp_mcp/colors.py

@@ -0,0 +1,48 @@
+"""Explicit colors: '#rgb', '#rrggbb', '#rrggbbaa' or a few names. Values are sRGB."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .errors import GimpMcpError
+
+NAMED = {
+    "white": "#ffffff",
+    "black": "#000000",
+    "red": "#ff0000",
+    "green": "#00ff00",
+    "blue": "#0000ff",
+    "transparent": "#00000000",
+}
+_HEX = re.compile(r"^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$")
+
+COLOR_DESCRIPTION = "sRGB color as '#rrggbb', '#rrggbbaa', '#rgb' or one of: " + ", ".join(NAMED)
+
+
+@dataclass(frozen=True)
+class Rgba:
+    r: float
+    g: float
+    b: float
+    a: float
+
+    def as_tuple(self) -> tuple[float, float, float, float]:
+        return (self.r, self.g, self.b, self.a)
+
+    def to_wire(self) -> list[float]:
+        return list(self.as_tuple())
+
+
+def parse_color(text: str) -> Rgba:
+    value = NAMED.get(text.strip().lower(), text.strip())
+    match = _HEX.match(value)
+    if match is None:
+        raise GimpMcpError("INVALID_ARGUMENT", f"invalid color {text!r}", hint=COLOR_DESCRIPTION)
+    digits = match.group(1)
+    if len(digits) == 3:
+        digits = "".join(ch * 2 for ch in digits)
+    if len(digits) == 6:
+        digits += "ff"
+    r, g, b, a = (int(digits[i : i + 2], 16) / 255 for i in range(0, 8, 2))
+    return Rgba(r, g, b, a)