engine-mcp 0.1.0__py3-none-any.whl

engine_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""engine-mcp: MCP tooling for game-engine work (Spine 2D server, Godot connector)."""
+
+__version__ = "0.1.0"

engine_mcp/godot_connect.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""godot_connect -- check a Godot MCP endpoint and register it with your MCP clients.
+
+A Godot MCP addon serves an HTTP endpoint from the running editor (default
+http://127.0.0.1:8000/mcp). This tool answers three separate questions:
+is the addon installed in the project, is the endpoint live, and which
+clients are registered to use it. Then it can register them in one command.
+
+  engine-mcp-godot --project path/to/godot_project doctor
+  engine-mcp-godot verify
+  engine-mcp-godot --clients claude,codex connect
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8")
+except (AttributeError, ValueError):
+    pass
+
+DEFAULT_URL = "http://127.0.0.1:8000/mcp"
+DEFAULT_ADDON = "godot_ai"
+CODEX_CONFIG = Path.home() / ".codex" / "config.toml"
+GROK_CONFIG = Path.home() / ".grok" / "config.toml"
+PROJECT_MCP = Path.cwd() / ".mcp.json"  # overridden by --mcp-json
+ALL_CLIENTS = ("claude", "codex", "grok", "hermes", "project")
+
+
+def dumps(value: Any) -> str:
+    """Pretty-print a value as UTF-8 JSON."""
+    return json.dumps(value, ensure_ascii=False, indent=2)
+
+
+def endpoint_parts(url: str) -> tuple[str, int]:
+    """Split an http(s) URL into (host, port); the port must be explicit."""
+    match = re.match(r"^https?://([^/:]+):(\d+)", url)
+    if not match:
+        raise ValueError(f"Godot MCP URL must include host and port: {url}")
+    return match.group(1), int(match.group(2))
+
+
+def is_live(url: str) -> bool:
+    """True if something accepts TCP connections on the URL's host and port."""
+    try:
+        host, port = endpoint_parts(url)
+        with socket.create_connection((host, port), timeout=0.5):
+            return True
+    except (OSError, ValueError):
+        return False
+
+
+def verify_endpoint(url: str) -> dict[str, Any]:
+    """Send an MCP `initialize` request and report whether the endpoint answers 200."""
+    body = json.dumps(
+        {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "2025-03-26",
+                "capabilities": {},
+                "clientInfo": {"name": "engine-mcp-godot-connect", "version": "1.0"},
+            },
+        }
+    ).encode("utf-8")
+    request = urllib.request.Request(
+        url,
+        data=body,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=5) as response:
+            payload = response.read(65536).decode("utf-8", errors="replace")
+            return {
+                "ok": response.status == 200,
+                "status": response.status,
+                "response": payload[:4000],
+            }
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        return {"ok": False, "error": str(exc)}
+
+
+def _upsert_toml(path: Path, name: str, url: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    text = path.read_text(encoding="utf-8") if path.is_file() else ""
+    # drop the old table (and its sub-tables) up to the next table header, so
+    # values containing "[" (arrays) are removed whole
+    pattern = re.compile(rf"(?ms)^\[mcp_servers\.{re.escape(name)}(?:\.[^\]\n]+)?\]\n.*?(?=^\[|\Z)")
+    text = pattern.sub("", text).rstrip()
+    path.write_text(
+        text + f'\n\n[mcp_servers.{name}]\nurl = "{url}"\nenabled = true\n', encoding="utf-8"
+    )
+
+
+def _upsert_project(name: str, url: str) -> None:
+    data = {"mcpServers": {}}
+    if PROJECT_MCP.is_file():
+        data = json.loads(PROJECT_MCP.read_text(encoding="utf-8-sig"))
+    data.setdefault("mcpServers", {})[name] = {"type": "http", "url": url}
+    PROJECT_MCP.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def _hermes_config() -> Path:
+    local = Path.home() / "AppData" / "Local" / "hermes" / "config.yaml"
+    return local if local.is_file() else Path.home() / ".hermes" / "config.yaml"
+
+
+def _upsert_hermes(name: str, url: str) -> None:
+    path = _hermes_config()
+    if not path.is_file():
+        raise FileNotFoundError(path)
+    text = path.read_text(encoding="utf-8")
+    block = f"  {name}:\n    url: {json.dumps(url)}\n    enabled: true\n    connect_timeout: 60.0\n"
+    text = re.sub(rf"(?m)^  {re.escape(name)}:\n(?:    .*\n)*", "", text)
+    if re.search(r"(?m)^mcp_servers:\s*$", text):
+        text = re.sub(r"(?m)^(mcp_servers:\s*\n)", r"\1" + block, text, count=1)
+    else:
+        text = text.rstrip() + "\n\nmcp_servers:\n" + block
+    path.write_text(text, encoding="utf-8")
+
+
+def register_client(client: str, name: str, url: str, scope: str) -> dict[str, Any]:
+    """Register the endpoint with one client; returns {"ok": bool, ...} and never raises."""
+    try:
+        if client == "claude":
+            exe = shutil.which("claude")
+            if not exe:
+                raise FileNotFoundError("claude CLI")
+            subprocess.run(
+                [exe, "mcp", "remove", name, "--scope", scope], capture_output=True, timeout=30
+            )
+            result = subprocess.run(
+                [exe, "mcp", "add", "--transport", "http", name, url, "--scope", scope],
+                capture_output=True,
+                text=True,
+                timeout=30,
+                encoding="utf-8",
+                errors="replace",
+            )
+            if result.returncode:
+                raise RuntimeError(
+                    (result.stderr or result.stdout or "claude mcp add failed").strip()
+                )
+        elif client == "codex":
+            exe = shutil.which("codex")
+            if exe:
+                subprocess.run([exe, "mcp", "remove", name], capture_output=True, timeout=30)
+                result = subprocess.run(
+                    [exe, "mcp", "add", name, "--url", url],
+                    capture_output=True,
+                    text=True,
+                    timeout=30,
+                    encoding="utf-8",
+                    errors="replace",
+                )
+                if result.returncode:
+                    raise RuntimeError(
+                        (result.stderr or result.stdout or "codex mcp add failed").strip()
+                    )
+            _upsert_toml(CODEX_CONFIG, name, url)
+        elif client == "grok":
+            _upsert_toml(GROK_CONFIG, name, url)
+        elif client == "hermes":
+            _upsert_hermes(name, url)
+        elif client == "project":
+            _upsert_project(name, url)
+        else:
+            raise ValueError(f"unknown client: {client}")
+        return {"ok": True, "client": client, "url": url, "restart_required": True}
+    except (OSError, RuntimeError, ValueError, json.JSONDecodeError) as exc:
+        return {"ok": False, "client": client, "url": url, "error": str(exc)}
+
+
+def registration_status(name: str) -> dict[str, Any]:
+    """Report, per client, whether a server called `name` is registered."""
+    result: dict[str, Any] = {}
+    for label, path in (("codex", CODEX_CONFIG), ("grok", GROK_CONFIG)):
+        text = path.read_text(encoding="utf-8") if path.is_file() else ""
+        result[label] = f"[mcp_servers.{name}]" in text
+    project = {}
+    if PROJECT_MCP.is_file():
+        try:
+            project = json.loads(PROJECT_MCP.read_text(encoding="utf-8-sig")).get("mcpServers", {})
+        except json.JSONDecodeError:
+            project = {}
+    result["project"] = name in project
+    hermes = _hermes_config()
+    result["hermes"] = hermes.is_file() and bool(
+        re.search(rf"(?m)^  {re.escape(name)}:", hermes.read_text(encoding="utf-8"))
+    )
+    result["claude"] = "probe with `claude mcp list`"
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point; returns a process exit code."""
+    global PROJECT_MCP
+    parser = argparse.ArgumentParser(description="Godot MCP multi-client connector")
+    parser.add_argument(
+        "--project", default=".", help="Godot project folder (contains project.godot)"
+    )
+    parser.add_argument("--addon", default=DEFAULT_ADDON, help="addon folder name under addons/")
+    parser.add_argument(
+        "--mcp-json", default="", help="project .mcp.json to update (default: ./.mcp.json)"
+    )
+    parser.add_argument("--name", default="godot-ai", help="server name to register")
+    parser.add_argument("--url", default=DEFAULT_URL)
+    parser.add_argument("--scope", choices=("local", "project", "user"), default="local")
+    parser.add_argument("--clients", default="all", help="claude,codex,grok,hermes,project or all")
+    sub = parser.add_subparsers(dest="command", required=True)
+    for name in ("status", "doctor", "verify", "connect"):
+        sub.add_parser(name)
+    args = parser.parse_args(argv)
+    if args.mcp_json:
+        PROJECT_MCP = Path(args.mcp_json)
+    project = Path(args.project).resolve()
+    addon = project / "addons" / args.addon / "plugin.cfg"
+
+    if args.command == "status":
+        print(
+            dumps(
+                {
+                    "url": args.url,
+                    "live": is_live(args.url),
+                    "registrations": registration_status(args.name),
+                }
+            )
+        )
+        return 0
+    if args.command == "doctor":
+        live = is_live(args.url)
+        payload = {
+            "ok": (project / "project.godot").is_file() and addon.is_file(),
+            "project": str(project),
+            "project_exists": (project / "project.godot").is_file(),
+            "addon_installed": addon.is_file(),
+            "endpoint": args.url,
+            "live": live,
+            "registrations": registration_status(args.name),
+            "next": "Run verify, then restart MCP clients after registration"
+            if live
+            else "Open Godot with the MCP addon enabled",
+        }
+        print(dumps(payload))
+        return 0 if payload["ok"] else 1
+    if args.command == "verify":
+        result = verify_endpoint(args.url)
+        print(dumps(result))
+        return 0 if result.get("ok") else 1
+    if args.command == "connect":
+        clients = (
+            list(ALL_CLIENTS)
+            if args.clients == "all"
+            else [c.strip() for c in args.clients.split(",") if c.strip()]
+        )
+        results = [register_client(c, args.name, args.url, args.scope) for c in clients]
+        print(dumps({"ok": all(r["ok"] for r in results), "results": results}))
+        return 0 if all(r["ok"] for r in results) else 1
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

engine_mcp/spine_core.py

@@ -0,0 +1,626 @@
+#!/usr/bin/env python3
+"""spine_core -- operations behind the Spine MCP server.
+
+Three lanes:
+  EDITOR lane -> official Spine CLI: version / export / import / pack / unpack / clean / open
+  PREP lane   -> repair skeleton JSON so the Spine 4.x editor importer accepts it
+  SCENE lane  -> pure-JSON multi-skeleton compositor and layout preview
+
+Every function returns a dict with an "ok" bool so MCP tools and scripts share one contract.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import math
+import os
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+SPINE_EXE = os.environ.get("SPINE_EXE", r"C:\Program Files\Spine\Spine.com")
+SPINE_UPDATE = os.environ.get("SPINE_UPDATE", "")  # pin editor version, e.g. "4.3.23"
+
+
+def _run(cmd: list[str], timeout: int = 600) -> dict[str, Any]:
+    start = time.time()
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+        )
+        return {
+            "ok": proc.returncode == 0,
+            "exit_code": proc.returncode,
+            "command": subprocess.list2cmdline(cmd),
+            "stdout": (proc.stdout or "")[-8000:],
+            "stderr": (proc.stderr or "")[-4000:],
+            "seconds": round(time.time() - start, 1),
+        }
+    except subprocess.TimeoutExpired:
+        return {
+            "ok": False,
+            "exit_code": -1,
+            "command": subprocess.list2cmdline(cmd),
+            "stdout": "",
+            "stderr": f"timeout after {timeout}s",
+            "seconds": timeout,
+        }
+    except OSError as exc:
+        return {
+            "ok": False,
+            "exit_code": -1,
+            "command": subprocess.list2cmdline(cmd),
+            "stdout": "",
+            "stderr": str(exc),
+            "seconds": 0,
+        }
+
+
+def _spine(args: list[str], timeout: int = 600) -> dict[str, Any]:
+    if not Path(SPINE_EXE).exists():
+        return {
+            "ok": False,
+            "stderr": f"Spine CLI not found at {SPINE_EXE}. "
+            "Set SPINE_EXE env var to Spine.com path.",
+        }
+    cmd = [SPINE_EXE]
+    if SPINE_UPDATE:
+        cmd += ["--update", SPINE_UPDATE]
+    return _run(cmd + args, timeout=timeout)
+
+
+def spine_version() -> dict[str, Any]:
+    """Report the Spine editor/launcher version and the CLI path in use."""
+    r = _spine(["-v"], timeout=180)
+    r["spine_exe"] = SPINE_EXE
+    return r
+
+
+def spine_export(
+    input_path: str, output_path: str, export: str = "json", clean: bool = False, version: str = ""
+) -> dict[str, Any]:
+    """Export a .spine project or data file. `export` is a shorthand
+    (json, binary, json+pack, binary+pack) or a path to an export settings JSON
+    saved from the editor's Export dialog (required for PNG/GIF/video)."""
+    args = []
+    if version:
+        args += ["--update", version]
+    args += ["-i", input_path, "-o", output_path]
+    if clean:
+        args += ["-m"]
+    args += ["-e", export]
+    r = _spine(args)
+    r["output"] = output_path
+    return r
+
+
+def spine_import(
+    data_path: str, project_path: str, name: str = "", scale: float = 0.0, prep: bool = True
+) -> dict[str, Any]:
+    """Import skeleton JSON / .skel data into a .spine project file.
+    prep=True (default) first runs rig_editor_prep (generated JSON -> editor-valid JSON).
+    Pass prep=False to import the file as-is."""
+    if prep and data_path.endswith(".json"):
+        prepped = rig_editor_prep(data_path)
+        if not prepped.get("ok"):
+            return prepped
+        data_path = prepped["editor_json"]
+    args = ["-i", data_path, "-o", project_path]
+    if scale:
+        args += ["-s", str(scale)]
+    args += ["-r"]
+    if name:
+        args += [name]
+    r = _spine(args)
+    r["project"] = project_path
+    return r
+
+
+def spine_pack(
+    images_dir: str,
+    output_dir: str,
+    name: str = "atlas",
+    pack_settings: str = "",
+    project: str = "",
+) -> dict[str, Any]:
+    """Pack a folder of images into a texture atlas."""
+    args = ["-i", images_dir]
+    if project:
+        args += ["-j", project]
+    args += ["-o", output_dir]
+    if pack_settings:
+        args += ["-n", name, "-p", pack_settings]
+    else:
+        args += ["-p", name]
+    return _spine(args)
+
+
+def spine_unpack(atlas_path: str, images_dir: str, output_dir: str) -> dict[str, Any]:
+    """Unpack a texture atlas back into individual images."""
+    return _spine(["-i", images_dir, "-o", output_dir, "-c", atlas_path])
+
+
+def spine_clean(project_path: str, output_path: str = "") -> dict[str, Any]:
+    """Run Spine animation cleanup on a project."""
+    out = output_path or project_path
+    return _spine(["-i", project_path, "-o", out, "-m", "-e", "json"])
+
+
+def spine_open_editor(project_path: str = "") -> dict[str, Any]:
+    """Open the Spine editor GUI (non-blocking), optionally with a project."""
+    exe = SPINE_EXE.replace("Spine.com", "Spine.exe")
+    if not Path(exe).exists():
+        exe = SPINE_EXE
+    try:
+        cmd = [exe] + ([project_path] if project_path else [])
+        subprocess.Popen(cmd, creationflags=getattr(subprocess, "DETACHED_PROCESS", 0))
+        return {"ok": True, "launched": exe, "project": project_path or "(none)"}
+    except OSError as exc:
+        return {"ok": False, "stderr": str(exc)}
+
+
+def analyze_alpha(image: str) -> dict[str, Any]:
+    """Inspect an image's alpha channel to decide whether it needs a cutout pass.
+    keyed=True (already transparent) -> skip cutout; otherwise cutout needed."""
+    try:
+        from PIL import Image
+    except ImportError:
+        return {"ok": False, "stderr": "Pillow not installed (pip install pillow)"}
+    p = Path(image)
+    if not p.exists():
+        return {"ok": False, "stderr": f"image not found: {p}"}
+    img = Image.open(p)
+    if img.mode != "RGBA":
+        return {
+            "ok": True,
+            "mode": img.mode,
+            "size": list(img.size),
+            "keyed": False,
+            "transparent_pct": 0.0,
+            "opaque_pct": 100.0,
+            "partial_pct": 0.0,
+            "verdict": "no alpha channel -> cutout needed",
+        }
+    hist = img.getchannel("A").histogram()
+    total = img.width * img.height
+    transparent = sum(hist[:16]) / total * 100
+    opaque = sum(hist[240:]) / total * 100
+    partial = 100 - transparent - opaque
+    keyed = transparent >= 3.0
+    return {
+        "ok": True,
+        "mode": "RGBA",
+        "size": list(img.size),
+        "keyed": keyed,
+        "transparent_pct": round(transparent, 1),
+        "opaque_pct": round(opaque, 1),
+        "partial_pct": round(partial, 1),
+        "verdict": "already keyed -> use alpha directly"
+        if keyed
+        else "opaque alpha -> cutout needed",
+    }
+
+
+def _world_transforms(bones: list[dict[str, Any]]) -> dict[str, Any]:
+    world = {}
+    for b in bones:  # assumes parents precede children, as in Spine JSON
+        rot = math.radians(b.get("rotation", 0))
+        sx, sy = b.get("scaleX", 1), b.get("scaleY", 1)
+        la, lb = math.cos(rot) * sx, -math.sin(rot) * sy
+        lc, ld = math.sin(rot) * sx, math.cos(rot) * sy
+        x, y = b.get("x", 0), b.get("y", 0)
+        p = world.get(b.get("parent"))
+        if p is None:
+            world[b["name"]] = (la, lb, lc, ld, x, y)
+        else:
+            pa, pb, pc, pd, px, py = p
+            world[b["name"]] = (
+                pa * la + pb * lc,
+                pa * lb + pb * ld,
+                pc * la + pd * lc,
+                pc * lb + pd * ld,
+                pa * x + pb * y + px,
+                pc * x + pd * y + py,
+            )
+    return world
+
+
+def _unweight_mesh(
+    att: dict[str, Any], world: dict[str, Any], bones: list[dict[str, Any]], slot_bone: str
+) -> bool:
+    verts = att.get("vertices")
+    uvs = att.get("uvs")
+    if not isinstance(verts, list) or not isinstance(uvs, list):
+        return False
+    n = len(uvs) // 2
+    if len(verts) == n * 2:
+        return False  # already unweighted
+    sa, sb, sc, sd, sx, sy = world[slot_bone]
+    det = sa * sd - sb * sc or 1e-9
+    ia, ib, ic, id_ = sd / det, -sb / det, -sc / det, sa / det
+    out = []
+    i = 0
+    for _ in range(n):
+        cnt = int(verts[i])
+        i += 1
+        wx = wy = 0.0
+        for _ in range(cnt):
+            bi, lx, ly, w = int(verts[i]), verts[i + 1], verts[i + 2], verts[i + 3]
+            i += 4
+            ba, bb, bc, bd, bx, by = world[bones[bi]["name"]]
+            wx += (ba * lx + bb * ly + bx) * w
+            wy += (bc * lx + bd * ly + by) * w
+        dx, dy = wx - sx, wy - sy
+        out += [ia * dx + ib * dy, ic * dx + id_ * dy]
+    att["vertices"] = out
+    return True
+
+
+def _clean_keys(frames: list[dict[str, Any]]) -> list:
+    out = []
+    for f in frames:
+        f = dict(f)
+        if f.get("curve") == "linear":
+            del f["curve"]
+        out.append(f)
+    return out
+
+
+_TIMELINE_VALUE_KEYS = {
+    "rotate": ("value",),
+    "translate": ("x", "y"),
+    "scale": ("x", "y"),
+    "shear": ("x", "y"),
+}
+
+
+def _fix_curves(frames: list[dict[str, Any]], val_keys: tuple) -> None:
+    """Convert 3.x normalized Bezier curves [a,b,c,d] to Spine 4.x absolute
+    control points (4 values per value component), in place."""
+    for i, f in enumerate(frames):
+        c = f.get("curve")
+        if not (isinstance(c, list) and len(c) == 4):
+            continue
+        if i + 1 >= len(frames):
+            f.pop("curve", None)
+            continue
+        nf = frames[i + 1]
+        t0, t1 = f.get("time", 0), nf.get("time", 0)
+        a, b, cx, d = c
+        new = []
+        for k in val_keys:
+            v0, v1 = f.get(k, 0), nf.get(k, 0)
+            new += [t0 + a * (t1 - t0), v0 + b * (v1 - v0), t0 + cx * (t1 - t0), v0 + d * (v1 - v0)]
+        f["curve"] = new
+
+
+def _normalize_animation(anim: dict[str, Any]) -> dict[str, Any]:
+    fixed = {}
+    for section, body in anim.items():
+        if section == "name":
+            continue  # stray key some generators write; not Spine JSON
+        if section == "bones":
+            new_bones = {}
+            for bone, tl in body.items():
+                if isinstance(tl, dict):
+                    new_tl = {}
+                    for kind, frames in tl.items():
+                        frames = _clean_keys(frames)
+                        if kind == "rotate":
+                            for f in frames:
+                                if "value" not in f:
+                                    f["value"] = f.pop("rotation", f.pop("angle", 0))
+                        if kind in _TIMELINE_VALUE_KEYS:
+                            _fix_curves(frames, _TIMELINE_VALUE_KEYS[kind])
+                        new_tl[kind] = frames
+                    new_bones[bone] = new_tl
+                elif isinstance(tl, list):  # raw per-bone keyframe list
+                    rot, trans, scale = [], [], []
+                    for f in _clean_keys(tl):
+                        base = {"time": f.get("time", 0)}
+                        if "curve" in f:
+                            base["curve"] = f["curve"]
+                        if "rotation" in f or "angle" in f:
+                            rot.append({**base, "value": f.get("rotation", f.get("angle", 0))})
+                        if "x" in f or "y" in f:
+                            trans.append({**base, "x": f.get("x", 0), "y": f.get("y", 0)})
+                        if "scaleX" in f or "scaleY" in f:
+                            scale.append({**base, "x": f.get("scaleX", 1), "y": f.get("scaleY", 1)})
+                    new_tl = {}
+                    if rot:
+                        _fix_curves(rot, _TIMELINE_VALUE_KEYS["rotate"])
+                        new_tl["rotate"] = rot
+                    if trans:
+                        _fix_curves(trans, _TIMELINE_VALUE_KEYS["translate"])
+                        new_tl["translate"] = trans
+                    if scale:
+                        _fix_curves(scale, _TIMELINE_VALUE_KEYS["scale"])
+                        new_tl["scale"] = scale
+                    if new_tl:
+                        new_bones[bone] = new_tl
+                else:
+                    new_bones[bone] = tl
+            fixed["bones"] = new_bones
+        elif section == "slots" and isinstance(body, dict):
+            new_slots = {}
+            for slot, tl in body.items():
+                if isinstance(tl, list):  # raw list -> attachment timeline
+                    new_slots[slot] = {
+                        "attachment": [
+                            {"time": f.get("time", 0), "name": f.get("name", f.get("attachment"))}
+                            for f in tl
+                        ]
+                    }
+                else:
+                    new_slots[slot] = tl
+            if new_slots:
+                fixed["slots"] = new_slots
+        else:
+            fixed[section] = body
+    return fixed
+
+
+def rig_editor_prep(rig_json: str, output: str = "") -> dict[str, Any]:
+    """Repair generated rig JSON into Spine-editor-importable form:
+    weighted meshes -> unweighted (editor re-binds weights natively),
+    loose keyframe lists -> valid Spine 4.x timelines. Writes a new file
+    (<stem>_editor.json by default); the source is left untouched."""
+    src = Path(rig_json)
+    if not src.exists():
+        return {"ok": False, "stderr": f"rig not found: {src}"}
+    data = json.loads(src.read_text(encoding="utf-8-sig"))
+    bones = data.get("bones", [])
+    world = _world_transforms(bones)
+    slot_bone = {s["name"]: s["bone"] for s in data.get("slots", [])}
+
+    unweighted = 0
+    skins = data.get("skins", [])
+    if isinstance(skins, dict):
+        skins = [{"name": k, "attachments": v} for k, v in skins.items()]
+        data["skins"] = skins
+    for skin in skins:
+        for slot, atts in skin.get("attachments", {}).items():
+            for att in atts.values():
+                if att.get("type") == "mesh" and slot in slot_bone:
+                    if _unweight_mesh(att, world, bones, slot_bone[slot]):
+                        unweighted += 1
+
+    anims = data.get("animations", {})
+    data["animations"] = {k: _normalize_animation(v) for k, v in anims.items()}
+
+    out = Path(output) if output else src.with_name(src.stem + "_editor.json")
+    out.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+    return {
+        "ok": True,
+        "editor_json": str(out),
+        "meshes_unweighted": unweighted,
+        "animations_normalized": len(anims),
+    }
+
+
+def _offset_attachment_bone_indices(att: dict[str, Any], offset: int) -> None:
+    verts = att.get("vertices")
+    if not isinstance(verts, list):
+        return
+    if "uvs" in att:
+        weighted = len(verts) != len(att["uvs"])
+    elif "vertexCount" in att:
+        weighted = len(verts) != att["vertexCount"] * 2
+    else:
+        return
+    if not weighted:
+        return
+    i = 0
+    while i < len(verts):
+        n = int(verts[i])
+        i += 1
+        for _ in range(n):
+            verts[i] = int(verts[i]) + offset
+            i += 4
+
+
+def _rename_anim_block(
+    anim: dict[str, Any],
+    bone_map: dict[str, Any],
+    slot_map: dict[str, Any],
+    con_map: dict[str, Any],
+    skin_map: dict[str, Any],
+) -> dict[str, Any]:
+    out = {}
+    for section, body in anim.items():
+        if section == "bones":
+            out[section] = {bone_map.get(k, k): v for k, v in body.items()}
+        elif section == "slots":
+            out[section] = {slot_map.get(k, k): v for k, v in body.items()}
+        elif section in ("ik", "transform", "path", "physics"):
+            out[section] = {con_map.get(k, k): v for k, v in body.items()}
+        elif section == "deform":
+            out[section] = {
+                skin_map.get(sk, sk): {slot_map.get(sl, sl): atts for sl, atts in slots.items()}
+                for sk, slots in body.items()
+            }
+        elif section == "drawOrder" or section == "draworder":
+            new = copy.deepcopy(body)
+            for frame in new:
+                for off in frame.get("offsets", []):
+                    off["slot"] = slot_map.get(off["slot"], off["slot"])
+            out["drawOrder"] = new
+        else:
+            out[section] = body
+    return out
+
+
+def scene_compose(
+    characters: list[dict[str, Any]], output_json: str, scene_name: str = "scene"
+) -> dict[str, Any]:
+    """Merge N rigged characters into ONE Spine skeleton JSON (a scene).
+
+    characters: list[dict[str, Any]] of dicts:
+      {"json": path, "prefix": name, "x": 0, "y": 0, "scale": 1.0, "rotation": 0}
+    Each character's bones/slots/skins/constraints/animations are prefixed and
+    grafted under a per-character root placed at (x, y) * scale. Weighted-mesh
+    bone indices are re-based so deformation survives the merge.
+    """
+    if not characters:
+        return {"ok": False, "stderr": "no characters given"}
+    merged = {
+        "skeleton": {"spine": "4.0", "hash": scene_name, "images": "./images/"},
+        "bones": [{"name": "root"}],
+        "slots": [],
+        "ik": [],
+        "transform": [],
+        "skins": [],
+        "animations": {},
+    }
+    default_skin = {"name": "default", "attachments": {}}
+    merged["skins"].append(default_skin)
+    report = []
+
+    for idx, spec in enumerate(characters):
+        path = Path(spec["json"])
+        if not path.exists():
+            return {"ok": False, "stderr": f"rig not found: {path}"}
+        data = json.loads(path.read_text(encoding="utf-8"))
+        prefix = (spec.get("prefix") or path.stem.split("_")[0] or f"char{idx}") + "_"
+
+        bones = copy.deepcopy(data.get("bones", []))
+        slots = copy.deepcopy(data.get("slots", []))
+        skins = copy.deepcopy(data.get("skins", []))
+        if isinstance(skins, dict):  # legacy 3.x dict form
+            skins = [{"name": k, "attachments": v} for k, v in skins.items()]
+        iks = copy.deepcopy(data.get("ik", []))
+        transforms = copy.deepcopy(data.get("transform", []))
+        anims = copy.deepcopy(data.get("animations", {}))
+
+        bone_map = {b["name"]: prefix + b["name"] for b in bones}
+        slot_map = {s["name"]: prefix + s["name"] for s in slots}
+        con_map = {c["name"]: prefix + c["name"] for c in iks + transforms}
+        skin_map = {s["name"]: (prefix + s["name"]) for s in skins if s["name"] != "default"}
+
+        bone_offset = len(merged["bones"])
+        for b in bones:
+            b["name"] = bone_map[b["name"]]
+            if "parent" in b:
+                b["parent"] = bone_map.get(b["parent"], b["parent"])
+            else:  # this character's root: place it in the scene
+                b["parent"] = "root"
+                b["x"] = float(b.get("x", 0)) + float(spec.get("x", 0))
+                b["y"] = float(b.get("y", 0)) + float(spec.get("y", 0))
+                if spec.get("scale"):
+                    b["scaleX"] = float(b.get("scaleX", 1)) * float(spec["scale"])
+                    b["scaleY"] = float(b.get("scaleY", 1)) * float(spec["scale"])
+                if spec.get("rotation"):
+                    b["rotation"] = float(b.get("rotation", 0)) + float(spec["rotation"])
+        merged["bones"].extend(bones)
+
+        for s in slots:
+            s["name"] = slot_map[s["name"]]
+            s["bone"] = bone_map.get(s["bone"], s["bone"])
+        merged["slots"].extend(slots)
+
+        for group, target in ((iks, "ik"), (transforms, "transform")):
+            for c in group:
+                c["name"] = con_map[c["name"]]
+                c["order"] = int(c.get("order", 0)) + idx * 100
+                c["bones"] = [bone_map.get(x, x) for x in c.get("bones", [])]
+                if "target" in c:
+                    c["target"] = bone_map.get(c["target"], c["target"])
+                merged[target].append(c)
+
+        for skin in skins:
+            new_atts = {}
+            for slot_name, atts in skin.get("attachments", {}).items():
+                for att in atts.values():
+                    # weighted-mesh bone indices point into the skeleton bones
+                    # array; this character's bone 0 now sits at bone_offset
+                    _offset_attachment_bone_indices(att, bone_offset)
+                new_atts[slot_map.get(slot_name, slot_name)] = atts
+            if skin["name"] == "default":
+                default_skin["attachments"].update(new_atts)
+            else:
+                merged["skins"].append({"name": skin_map[skin["name"]], "attachments": new_atts})
+
+        for anim_name, anim in anims.items():
+            merged["animations"][prefix + anim_name] = _rename_anim_block(
+                anim, bone_map, slot_map, con_map, skin_map
+            )
+
+        report.append(
+            {
+                "character": prefix.rstrip("_"),
+                "bones": len(bones),
+                "slots": len(slots),
+                "animations": len(anims),
+            }
+        )
+
+    out = Path(output_json)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(merged, ensure_ascii=False), encoding="utf-8")
+    return {
+        "ok": True,
+        "scene_json": str(out),
+        "characters": report,
+        "total_bones": len(merged["bones"]),
+        "total_slots": len(merged["slots"]),
+        "total_animations": len(merged["animations"]),
+    }
+
+
+def scene_preview(
+    characters: list[dict[str, Any]],
+    output_png: str,
+    width: int = 1920,
+    height: int = 1080,
+    background: str = "#202028",
+) -> dict[str, Any]:
+    """Composite each character's texture at its scene placement -> layout PNG.
+    Fast visual proof of a scene; full skeletal renders go through spine_export
+    with a saved PNG/GIF export-settings file."""
+    try:
+        from PIL import Image
+    except ImportError:
+        return {"ok": False, "stderr": "Pillow not installed (pip install pillow)"}
+    canvas = Image.new("RGBA", (width, height), background)
+    placed = []
+    for spec in characters:
+        tex_path = spec.get("texture", "")
+        if not tex_path:
+            rig = Path(spec.get("json", ""))
+            guess = rig.with_suffix(".png")
+            if not guess.exists():
+                stem = rig.stem.split("_")[0]
+                guess = rig.with_name(stem + ".png")
+            tex_path = str(guess)
+        if not Path(tex_path).exists():
+            return {"ok": False, "stderr": f"texture not found for scene preview: {tex_path}"}
+        img = Image.open(tex_path).convert("RGBA")
+        scale = float(spec.get("scale", 1.0))
+        if scale != 1.0:
+            img = img.resize(
+                (max(1, int(img.width * scale)), max(1, int(img.height * scale))), Image.LANCZOS
+            )
+        x = int(width / 2 + float(spec.get("x", 0)) - img.width / 2)
+        y = int(height - float(spec.get("y", 0)) - img.height)
+        canvas.alpha_composite(img, (x, y))
+        placed.append({"texture": tex_path, "at": [x, y], "scale": scale})
+    out = Path(output_png)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    canvas.save(out)
+    return {"ok": True, "preview": str(out), "placed": placed}
+
+
+def scene_to_project(
+    scene_json: str, project_path: str, scale: float = 0.0, prep: bool = True
+) -> dict[str, Any]:
+    """Import a composed scene JSON into a .spine project for editor polish.
+    prep=True (default) runs rig_editor_prep first so the editor importer
+    accepts generated or composed JSON, matching spine_import."""
+    return spine_import(scene_json, project_path, name="", scale=scale, prep=prep)

engine_mcp/spine_server.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Spine MCP server -- drive the Spine editor CLI and a JSON scene compositor
+from any MCP client (Claude Code, Codex CLI, Cursor, ...).
+
+Run (stdio):   engine-mcp-spine            (or: python -m engine_mcp.spine_server)
+Self-test:     engine-mcp-spine --selftest  (lists tools, starts no server)
+
+Env: SPINE_EXE (default C:\\Program Files\\Spine\\Spine.com), SPINE_UPDATE (pin editor version).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8")
+except (AttributeError, ValueError):
+    pass
+
+from mcp.server.fastmcp import FastMCP  # noqa: E402
+
+from engine_mcp import spine_core as core  # noqa: E402
+
+mcp = FastMCP("spine")
+
+
+@mcp.tool()
+def spine_version() -> dict[str, Any]:
+    """Report Spine editor/launcher version, license state, and the CLI path in use."""
+    return core.spine_version()
+
+
+@mcp.tool()
+def spine_export(
+    input_path: str, output_path: str, export: str = "json", clean: bool = False, version: str = ""
+) -> dict[str, Any]:
+    """Export a .spine project or skeleton data via the official Spine CLI.
+    `export`: shorthand 'json', 'binary', 'json+pack', 'binary+pack', OR a path to an
+    export-settings JSON saved from the editor's Export dialog (required for
+    PNG/GIF/APNG/video exports). `version` optionally pins the editor version."""
+    return core.spine_export(input_path, output_path, export, clean, version)
+
+
+@mcp.tool()
+def spine_import(
+    data_path: str, project_path: str, name: str = "", scale: float = 0.0, prep: bool = True
+) -> dict[str, Any]:
+    """Import skeleton JSON or .skel data into a .spine project file (creates it).
+    `prep` (default true) first repairs generated JSON into editor-valid form
+    (rig_editor_prep); `scale` scales on import; `name` picks one skeleton."""
+    return core.spine_import(data_path, project_path, name, scale, prep)
+
+
+@mcp.tool()
+def rig_editor_prep(rig_json: str, output: str = "") -> dict[str, Any]:
+    """Repair generated rig JSON so the Spine editor imports it: weighted
+    meshes -> unweighted (editor re-binds natively), loose keyframe lists ->
+    valid Spine 4.x timelines. Writes <stem>_editor.json; non-destructive."""
+    return core.rig_editor_prep(rig_json, output)
+
+
+@mcp.tool()
+def spine_pack(
+    images_dir: str,
+    output_dir: str,
+    name: str = "atlas",
+    pack_settings: str = "",
+    project: str = "",
+) -> dict[str, Any]:
+    """Pack a folder of images into a Spine texture atlas (.atlas + PNG pages)."""
+    return core.spine_pack(images_dir, output_dir, name, pack_settings, project)
+
+
+@mcp.tool()
+def spine_unpack(atlas_path: str, images_dir: str, output_dir: str) -> dict[str, Any]:
+    """Unpack a texture atlas back into individual images."""
+    return core.spine_unpack(atlas_path, images_dir, output_dir)
+
+
+@mcp.tool()
+def spine_clean(project_path: str, output_path: str = "") -> dict[str, Any]:
+    """Run Spine's animation cleanup on a project (removes redundant keys)."""
+    return core.spine_clean(project_path, output_path)
+
+
+@mcp.tool()
+def spine_open_editor(project_path: str = "") -> dict[str, Any]:
+    """Open the Spine editor GUI, optionally loading a project (non-blocking)."""
+    return core.spine_open_editor(project_path)
+
+
+@mcp.tool()
+def analyze_alpha(image: str) -> dict[str, Any]:
+    """Inspect an image's alpha channel (transparent/opaque/partial
+    percentages) and rule whether it's already keyed or needs a cutout pass."""
+    return core.analyze_alpha(image)
+
+
+@mcp.tool()
+def scene_compose(
+    characters: list[dict[str, Any]], output_json: str, scene_name: str = "scene"
+) -> dict[str, Any]:
+    """Merge N rigged characters into ONE Spine skeleton JSON (a scene).
+    characters: [{"json": rigPath, "prefix": name, "x": 0, "y": 0, "scale": 1.0,
+    "rotation": 0}, ...]. Bones/slots/skins/constraints/animations are prefixed
+    and grafted under per-character roots; weighted-mesh bone indices are re-based."""
+    return core.scene_compose(characters, output_json, scene_name)
+
+
+@mcp.tool()
+def scene_preview(
+    characters: list[dict[str, Any]], output_png: str, width: int = 1920, height: int = 1080
+) -> dict[str, Any]:
+    """Composite character textures at their scene placements -> layout preview PNG.
+    characters: [{"json" or "texture": path, "x": 0, "y": 0, "scale": 1.0}, ...]."""
+    return core.scene_preview(characters, output_png, width, height)
+
+
+@mcp.tool()
+def scene_to_project(scene_json: str, project_path: str, scale: float = 0.0) -> dict[str, Any]:
+    """Import a composed scene JSON into a .spine project for polish in the editor."""
+    return core.scene_to_project(scene_json, project_path, scale)
+
+
+def _selftest() -> int:
+    import asyncio
+
+    tools = asyncio.run(mcp.list_tools())
+    print(f"[spine-mcp] {len(tools)} tools registered:")
+    for t in tools:
+        print(f"  - {t.name}")
+    print(
+        f"[spine-mcp] SPINE_EXE = {core.SPINE_EXE} "
+        f"({'found' if Path(core.SPINE_EXE).exists() else 'MISSING'})"
+    )
+    return 0
+
+
+def main() -> int:
+    """Console entry point: run the stdio server, or --selftest to list tools."""
+    if "--selftest" in sys.argv:
+        return _selftest()
+    mcp.run()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

engine_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: engine-mcp
+Version: 0.1.0
+Summary: MCP tooling for game-engine work: a Spine 2D MCP server and a Godot MCP endpoint connector.
+Author: Kurtlon Earl Sta. Ines
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kurtstaines/engine-mcp
+Project-URL: Issues, https://github.com/kurtstaines/engine-mcp/issues
+Keywords: mcp,model-context-protocol,spine,spine2d,godot,ai-agents,game-dev
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.2
+Requires-Dist: pillow>=10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# engine-mcp
+
+[![CI](https://github.com/kurtstaines/engine-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kurtstaines/engine-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kurtstaines/engine-mcp/blob/main/LICENSE)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
+
+**Let an AI agent drive the Spine 2D animation editor, and plug a Godot MCP endpoint into every AI client with one command.**
+
+Game-engine tools are built for hands on a mouse. `engine-mcp` exposes them over the [Model Context Protocol](https://modelcontextprotocol.io) so an agent can export, import, pack, repair and compose skeletal animation assets itself, and get back a structured result it can branch on instead of a wall of console text.
+
+![A real MCP client session: listing the 12 tools, composing a scene and importing it into a Spine project](https://raw.githubusercontent.com/kurtstaines/engine-mcp/main/docs/screenshots/demo-terminal.gif)
+
+*A real client session against the server: connect, list tools, compose two characters into one scene, import it into a Spine project.*
+
+Status: **v0.1, early.** Small on purpose.
+
+## Features
+
+- **Spine MCP server**: 12 tools over stdio, usable from Claude Desktop, Claude Code, Cursor, Codex CLI or any other MCP client.
+- **Editor lane**: wraps the official Spine command-line interface (export, import, texture pack and unpack, animation clean-up, open the editor).
+- **Prep lane**: repairs generated skeleton JSON so the Spine 4.x importer accepts it. Converts weighted meshes to unweighted, loose keyframe lists to proper timelines, and 3.x Bezier curves to 4.x form. Pure Python, writes a new file, never touches the source.
+- **Scene lane**: merges several rigged characters into one skeleton with prefixed names and re-based mesh bone indices, and renders a layout preview PNG. Pure Python.
+- **Godot connector**: a small CLI that checks a Godot MCP addon's HTTP endpoint and registers it with Claude Code, Codex, Grok, Hermes and a project `.mcp.json`.
+- **One result contract**: every tool returns a dict with an `ok` flag.
+
+## Quickstart
+
+```bash
+pip install engine-mcp
+engine-mcp-spine --selftest
+```
+
+To run the examples, work from a clone instead:
+
+```bash
+git clone https://github.com/kurtstaines/engine-mcp.git
+cd engine-mcp
+pip install -e .
+python examples/compose_scene.py
+```
+
+`--selftest` lists the registered tools and reports whether the Spine CLI was found. The example composes two characters into one scene with no Spine install needed.
+
+<img src="https://raw.githubusercontent.com/kurtstaines/engine-mcp/main/docs/screenshots/sample-rig.gif" alt="The sample character playing its idle, wave and cheer animations" width="300">
+
+*The sample rig's `idle`, `wave` and `cheer` animations, recorded playing in the Spine editor.*
+
+### The sample rig
+
+[examples/build_rig.py](https://github.com/kurtstaines/engine-mcp/blob/main/examples/build_rig.py) turns one flat character image into a Spine skeleton:
+
+- keys out the background and cuts the art into six parts (body, head, upper arms, forearms)
+- writes `examples/mecha.json` with seven bones and region attachments
+- generates three animations as functions of time, with each part trailing the body a beat late so the idle loop breathes instead of bobbing
+
+The cut lines and joint positions are hand-picked for this one image; it is an example, not a general auto-rigger. The source art was generated with Grok Imagine.
+
+![The sample rig open in the Spine editor](https://raw.githubusercontent.com/kurtstaines/engine-mcp/main/docs/screenshots/spine-editor.jpg)
+
+*`examples/mecha.json` imported into a Spine project with `spine_import` and opened with `spine_open_editor`: seven bones, six image parts and three animations.*
+
+Requirements: Python 3.10+. The editor lane also needs a licensed [Spine](https://esotericsoftware.com) install; set `SPINE_EXE` if the CLI is not at `C:\Program Files\Spine\Spine.com`. The prep, scene and image tools work without it.
+
+## Connect an MCP client
+
+**Claude Code**
+
+```bash
+claude mcp add spine -- engine-mcp-spine
+```
+
+**Claude Desktop** (`claude_desktop_config.json`), **Cursor**, or a project **`.mcp.json`**:
+
+```json
+{
+  "mcpServers": {
+    "spine": {
+      "command": "engine-mcp-spine",
+      "env": { "SPINE_EXE": "C:/Program Files/Spine/Spine.com" }
+    }
+  }
+}
+```
+
+With [uv](https://docs.astral.sh/uv/) installed you can skip the install step and let the client fetch the package: set `"command": "uvx"` and `"args": ["--from", "engine-mcp", "engine-mcp-spine"]`.
+
+If the client cannot find `engine-mcp-spine` on its `PATH` (common when you installed into a virtual environment), point `command` at that environment's Python and use `"args": ["-m", "engine_mcp.spine_server"]`. A copy of this config lives in [examples/mcp.json](https://github.com/kurtstaines/engine-mcp/blob/main/examples/mcp.json).
+
+| Variable | Purpose |
+|---|---|
+| `SPINE_EXE` | Path to the Spine CLI. Default `C:\Program Files\Spine\Spine.com`. |
+| `SPINE_UPDATE` | Optional. Pins the editor version for every call, for example `4.2.43`. |
+
+## Tools
+
+| Tool | Inputs | What it does |
+|---|---|---|
+| `spine_version` | none | Reports the Spine version and the CLI path in use. |
+| `spine_export` | `input_path`, `output_path`, `export="json"`, `clean=False`, `version=""` | Exports a project or skeleton data. `export` is `json`, `binary`, `json+pack`, `binary+pack`, or a path to an export-settings JSON saved from the editor. |
+| `spine_import` | `data_path`, `project_path`, `name=""`, `scale=0.0`, `prep=True` | Imports skeleton JSON or `.skel` into a `.spine` project. Runs `rig_editor_prep` on JSON first unless `prep` is false. |
+| `spine_pack` | `images_dir`, `output_dir`, `name="atlas"`, `pack_settings=""`, `project=""` | Packs a folder of images into a texture atlas. |
+| `spine_unpack` | `atlas_path`, `images_dir`, `output_dir` | Unpacks a texture atlas back into images. |
+| `spine_clean` | `project_path`, `output_path=""` | Runs Spine's animation clean-up. |
+| `spine_open_editor` | `project_path=""` | Opens the Spine editor, optionally with a project. Does not block. Spine shows its launcher first and waits for **Start** unless "Start automatically" is ticked there. The editor closes when the MCP client disconnects. |
+| `rig_editor_prep` | `rig_json`, `output=""` | Repairs skeleton JSON for the editor importer. Writes `<stem>_editor.json`. |
+| `analyze_alpha` | `image` | Reports transparent, opaque and partial alpha percentages and whether the image is already keyed. |
+| `scene_compose` | `characters`, `output_json`, `scene_name="scene"` | Merges characters into one skeleton. Each character is `{"json", "prefix", "x", "y", "scale", "rotation"}`. |
+| `scene_preview` | `characters`, `output_png`, `width=1920`, `height=1080` | Composites each character's texture at its placement into a layout PNG. |
+| `scene_to_project` | `scene_json`, `project_path`, `scale=0.0` | Imports a composed scene into a `.spine` project. |
+
+### Godot connector
+
+Needs a Godot project with an MCP addon that serves HTTP from the running editor. Defaults: endpoint `http://127.0.0.1:8000/mcp`, addon folder `addons/godot_ai`, server name `godot-ai`; override with `--url`, `--addon`, `--name`.
+
+```bash
+engine-mcp-godot --project path/to/godot_project doctor
+engine-mcp-godot verify
+engine-mcp-godot --clients claude,codex connect
+```
+
+| Command | What it does |
+|---|---|
+| `status` | Shows whether the endpoint port is open and which clients are registered. |
+| `doctor` | Reports addon install, endpoint liveness and client registration as three separate facts, because each fails for a different reason. |
+| `verify` | Sends a real MCP `initialize` request and reports the response. |
+| `connect` | Registers the endpoint with `claude`, `codex`, `grok`, `hermes` and/or `project` (`.mcp.json`). |
+
+## Architecture
+
+```mermaid
+flowchart LR
+    client["MCP client<br/>Claude Desktop, Claude Code, Cursor"]
+    server["spine_server.py<br/>FastMCP, 12 tools"]
+    core["spine_core.py"]
+    cli["Spine CLI"]
+    json["Skeleton JSON<br/>prep and scene lanes"]
+    png["Pillow<br/>alpha check, preview"]
+    connector["godot_connect.py<br/>engine-mcp-godot"]
+    godot["Godot editor<br/>MCP addon over HTTP"]
+    configs["Client configs<br/>Claude, Codex, Grok, Hermes, .mcp.json"]
+
+    client -- stdio --> server --> core
+    core -- subprocess --> cli
+    core --> json
+    core --> png
+    connector -- "initialize probe" --> godot
+    connector -- registers --> configs
+    client -. "HTTP, after connect" .-> godot
+```
+
+The server is a thin layer: each tool is one call into `spine_core`, which you can also import directly from a script (see [examples/compose_scene.py](https://github.com/kurtstaines/engine-mcp/blob/main/examples/compose_scene.py)).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+24 tests cover the prep, scene and image lanes end to end on a synthetic rig, the MCP tool registration and a tool call round trip, and the Godot connector against a local stand-in HTTP endpoint. The editor lane is tested at the level of the arguments it passes to the Spine CLI; CI does not have Spine installed, so the CLI itself is not exercised there. Registration through the `claude` and `codex` CLIs is not covered.
+
+## Roadmap
+
+- Command-line front door for the Spine tools, for agents without an MCP client
+- Engine registry and status server (which engine adapters are installed and live)
+- Bone-marker tool: draw markers on art and save them as rig presets
+- Automatic rigging lane (image to rigged skeleton)
+- 3D animation workflow for Godot driven through MCP
+
+## Contributing
+
+Issues and pull requests are welcome. Before opening a PR:
+
+```bash
+ruff check . && ruff format --check . && pytest
+```
+
+Keep tools returning the `{"ok": bool, ...}` contract, and add a test for anything that does not need the Spine editor to run.
+
+## License
+
+MIT. See [LICENSE](https://github.com/kurtstaines/engine-mcp/blob/main/LICENSE).

engine_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+engine_mcp/__init__.py,sha256=k74wTEqpgQWCzONslkHnwWg6OC1PZOalckrtecsgADg,110
+engine_mcp/godot_connect.py,sha256=JZjQSWFNkujIrXfRvJ-5XC5-s_xyG_BbCKGqLUV8j04,10791
+engine_mcp/spine_core.py,sha256=nn7x0kYOp3isIuipy4yVJsuGemQBIaT4a4tbOi_06WI,23469
+engine_mcp/spine_server.py,sha256=z8yw01e61-jO4hwjT_OwUt9J_5FwTXe_rc6aYBkJGA4,5314
+engine_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=UhThRTv_qeZz8iSxoTXbUldXEWE1P-gUfB9qLfVU_8Q,1079
+engine_mcp-0.1.0.dist-info/METADATA,sha256=6XfeQauzeqA2VOuNDQbHQtMyu1iGD6oE17udHGS844U,11178
+engine_mcp-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+engine_mcp-0.1.0.dist-info/entry_points.txt,sha256=mRzMOCxRPPh4r6cah-HCgrHcHN6r4YqCkGWVpvdeZB0,115
+engine_mcp-0.1.0.dist-info/top_level.txt,sha256=W9MfJFVplVrgJ-nFhO4UwpiafQjLUGk-ba95f7Rl2pw,11
+engine_mcp-0.1.0.dist-info/RECORD,,

engine_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

engine_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+engine-mcp-godot = engine_mcp.godot_connect:main
+engine-mcp-spine = engine_mcp.spine_server:main

engine_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kurtlon Earl Sta. Ines
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

engine_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+engine_mcp