ldraw-mcp 0.1.0__py3-none-any.whl

ldraw_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""ldraw-mcp: render LDraw/LEGO models to images over MCP (headless Blender)."""
+
+__version__ = "0.1.0"

ldraw_mcp/blender_script.py

@@ -0,0 +1,137 @@
+"""
+Blender-side script: import an LDraw .ldr and render PNG views.
+
+Runs INSIDE Blender (never import this from the package):
+  blender -b -P blender_script.py -- \
+      --ldr model.ldr --out /dir/prefix --azimuths -60,120 [--samples 32]
+
+Renders one PNG per azimuth to <prefix>_<i>.png using Cycles CPU (works
+headless everywhere, including WSL2 without a GPU). Camera orbits the
+model bounding box at a fixed elevation.
+
+Requires the ImportLDraw addon (io_scene_importldraw) and an LDraw
+parts library (default ~/.ldraw).
+"""
+
+import argparse
+import math
+import sys
+from pathlib import Path
+
+import bpy
+
+
+def parse_args():
+    argv = sys.argv[sys.argv.index("--") + 1 :] if "--" in sys.argv else []
+    p = argparse.ArgumentParser()
+    p.add_argument("--ldr", required=True)
+    p.add_argument("--out", required=True, help="Output path prefix (no extension)")
+    p.add_argument("--azimuths", default="-60,120")
+    p.add_argument("--elevation", type=float, default=22.0)
+    p.add_argument("--samples", type=int, default=32)
+    p.add_argument("--resolution", type=int, default=800)
+    p.add_argument("--ldraw-dir", default=str(Path.home() / ".ldraw"))
+    return p.parse_args(argv)
+
+
+def enable_addon():
+    import addon_utils
+
+    for name in ("io_scene_importldraw", "importldraw"):
+        try:
+            addon_utils.enable(name, default_set=True)
+            return
+        except Exception:
+            continue
+    raise RuntimeError("ImportLDraw addon not found in Blender addons")
+
+
+def scene_bounds():
+    lo = [float("inf")] * 3
+    hi = [float("-inf")] * 3
+    for obj in bpy.context.scene.objects:
+        if obj.type != "MESH":
+            continue
+        for corner in obj.bound_box:
+            world = obj.matrix_world @ __import__("mathutils").Vector(corner)
+            for i in range(3):
+                lo[i] = min(lo[i], world[i])
+                hi[i] = max(hi[i], world[i])
+    if lo[0] == float("inf"):
+        raise RuntimeError("no mesh objects imported — empty or failed import")
+    return lo, hi
+
+
+def main():
+    args = parse_args()
+    enable_addon()
+
+    bpy.ops.wm.read_factory_settings(use_empty=True)
+    enable_addon()  # factory reset drops enabled addons
+
+    # the addon's look setup assumes a world exists; empty scenes have none
+    world = bpy.data.worlds.new("World")
+    world.use_nodes = True
+    world.node_tree.nodes["Background"].inputs[0].default_value = (1, 1, 1, 1)
+    world.node_tree.nodes["Background"].inputs[1].default_value = 1.0
+    bpy.context.scene.world = world
+
+    bpy.ops.import_scene.importldraw(
+        filepath=args.ldr,
+        ldrawPath=args.ldraw_dir,
+        addEnvironment=False,  # its ground plane would dominate the bounds
+        positionCamera=False,
+        importCameras=False,
+        positionOnGround=True,
+        useLogoStuds=False,
+        smoothParts=True,
+        addGaps=True,
+        bevelEdges=True,
+        look="normal",
+    )
+
+    lo, hi = scene_bounds()
+    center = [(a + b) / 2 for a, b in zip(lo, hi)]
+    span = max(b - a for a, b in zip(lo, hi))
+    distance = span * 2.2
+
+    scene = bpy.context.scene
+    scene.render.engine = "CYCLES"
+    scene.cycles.samples = args.samples
+    scene.cycles.device = "CPU"
+    scene.render.resolution_x = args.resolution
+    scene.render.resolution_y = args.resolution
+    scene.render.film_transparent = False
+
+    # sun light
+    sun = bpy.data.objects.new("Sun", bpy.data.lights.new("Sun", type="SUN"))
+    sun.data.energy = 4.0
+    sun.rotation_euler = (math.radians(50), 0, math.radians(-40))
+    scene.collection.objects.link(sun)
+
+    cam_data = bpy.data.cameras.new("Cam")
+    cam = bpy.data.objects.new("Cam", cam_data)
+    scene.collection.objects.link(cam)
+    scene.camera = cam
+
+    elev = math.radians(args.elevation)
+    for i, azim_str in enumerate(args.azimuths.split(",")):
+        azim = math.radians(float(azim_str))
+        cam.location = (
+            center[0] + distance * math.cos(elev) * math.cos(azim),
+            center[1] + distance * math.cos(elev) * math.sin(azim),
+            center[2] + distance * math.sin(elev),
+        )
+        direction = [c - l for c, l in zip(center, cam.location)]
+        import mathutils
+
+        cam.rotation_euler = (
+            mathutils.Vector(direction).to_track_quat("-Z", "Y").to_euler()
+        )
+        scene.render.filepath = f"{args.out}_{i}.png"
+        bpy.ops.render.render(write_still=True)
+        print(f"RENDERED {scene.render.filepath}")
+
+
+if __name__ == "__main__":
+    main()

ldraw_mcp/render.py

@@ -0,0 +1,127 @@
+"""
+High-quality LDraw rendering via headless Blender + ImportLDraw.
+
+The 'see the actual model' protocol: point at an LDraw model, render it
+with real part geometry (studs, slopes, window glass) in Blender, and
+stitch the views into one PNG.
+
+Availability requires: a blender binary, the io_scene_importldraw addon,
+and an LDraw parts library (~/.ldraw). Everything degrades gracefully:
+callers check is_available() or catch LDrawRenderError.
+
+Environment variables:
+  LDRAW_MCP_BLENDER   path to the blender binary (overrides PATH lookup)
+  LDRAW_MCP_DISABLE   set to "1" to force is_available() to False
+  LDRAW_LIBRARY_PATH   path to the LDraw parts library
+"""
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional, Sequence
+
+BLENDER_SCRIPT = Path(__file__).parent / "blender_script.py"
+DEFAULT_AZIMUTHS = (-60.0, 120.0)
+
+
+class LDrawRenderError(Exception):
+    """Blender render failed or is unavailable."""
+
+
+def find_blender() -> Optional[str]:
+    env = os.environ.get("LDRAW_MCP_BLENDER")
+    if env and Path(env).exists():
+        return env
+    found = shutil.which("blender")
+    if found:
+        return found
+    local = Path.home() / ".local" / "bin" / "blender"
+    return str(local) if local.exists() else None
+
+
+def ldraw_library_dir() -> Optional[Path]:
+    env = os.environ.get("LDRAW_LIBRARY_PATH")
+    candidates = [Path(env)] if env else []
+    candidates += [Path.home() / ".ldraw", Path("/usr/share/ldraw")]
+    for c in candidates:
+        if (c / "parts").is_dir():
+            return c
+    return None
+
+
+def is_available() -> bool:
+    if os.environ.get("LDRAW_MCP_DISABLE") == "1":
+        return False
+    return find_blender() is not None and ldraw_library_dir() is not None
+
+
+def render_ldraw(
+    ldr_path: str,
+    output_png: str,
+    azimuths: Sequence[float] = DEFAULT_AZIMUTHS,
+    samples: int = 32,
+    resolution: int = 800,
+    timeout: int = 600,
+) -> str:
+    """Render an .ldr file to a single side-by-side PNG of `azimuths` views."""
+    blender = find_blender()
+    library = ldraw_library_dir()
+    if blender is None or library is None:
+        raise LDrawRenderError(
+            "render unavailable (need blender + ImportLDraw addon "
+            "+ LDraw library in ~/.ldraw; run `ldraw-mcp-setup`)"
+        )
+    with tempfile.TemporaryDirectory() as td:
+        prefix = str(Path(td) / "view")
+        cmd = [
+            blender,
+            "-b",
+            "--factory-startup",
+            "-P",
+            str(BLENDER_SCRIPT),
+            "--",
+            "--ldr",
+            str(ldr_path),
+            "--out",
+            prefix,
+            "--azimuths=" + ",".join(str(a) for a in azimuths),
+            "--samples",
+            str(samples),
+            "--resolution",
+            str(resolution),
+            "--ldraw-dir",
+            str(library),
+        ]
+        try:
+            proc = subprocess.run(
+                cmd, capture_output=True, text=True, timeout=timeout
+            )
+        except subprocess.TimeoutExpired:
+            raise LDrawRenderError(f"blender render timed out after {timeout}s")
+        views = [Path(f"{prefix}_{i}.png") for i in range(len(azimuths))]
+        missing = [v for v in views if not v.exists()]
+        if proc.returncode != 0 or missing:
+            tail = "\n".join((proc.stdout + proc.stderr).splitlines()[-15:])
+            raise LDrawRenderError(
+                f"blender render failed (exit {proc.returncode}, "
+                f"missing {len(missing)} view(s)):\n{tail}"
+            )
+        _stitch(views, output_png)
+    return output_png
+
+
+def _stitch(view_paths, output_png: str) -> None:
+    """Combine view PNGs horizontally into one image."""
+    from PIL import Image
+
+    images = [Image.open(p) for p in view_paths]
+    height = max(im.height for im in images)
+    width = sum(im.width for im in images)
+    combined = Image.new("RGB", (width, height), (255, 255, 255))
+    x = 0
+    for im in images:
+        combined.paste(im, (x, (height - im.height) // 2))
+        x += im.width
+    combined.save(output_png)

ldraw_mcp/server.py

@@ -0,0 +1,101 @@
+"""
+ldraw-mcp server — render LDraw models to images over MCP.
+
+Tools:
+  render_ldraw_file(path, ...)  -> PNG image of the model
+  render_ldraw_text(ldr, ...)   -> PNG image of inline LDraw content
+  check_renderer()              -> availability diagnostics
+
+Run (stdio):
+  ldraw-mcp
+  python -m ldraw_mcp.server
+
+Register with Claude Code:
+  claude mcp add ldraw -- ldraw-mcp
+
+Requirements (see README.md):
+  - Blender on PATH (or LDRAW_MCP_BLENDER)
+  - ImportLDraw addon installed in Blender
+  - LDraw parts library at ~/.ldraw (or LDRAW_LIBRARY_PATH)
+  Run `ldraw-mcp-setup` to install the library + addon.
+"""
+
+import tempfile
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP, Image
+
+from . import render as ldraw_render
+
+mcp = FastMCP("ldraw")
+
+
+@mcp.tool()
+def check_renderer() -> str:
+    """Report whether the LDraw rendering stack is available and why not."""
+    blender = ldraw_render.find_blender()
+    library = ldraw_render.ldraw_library_dir()
+    lines = [
+        f"blender: {blender or 'NOT FOUND (install Blender or set LDRAW_MCP_BLENDER)'}",
+        f"ldraw library: {library or 'NOT FOUND (run ldraw-mcp-setup or set LDRAW_LIBRARY_PATH)'}",
+        f"available: {ldraw_render.is_available()}",
+    ]
+    return "\n".join(lines)
+
+
+def _render(ldr_path: str, azimuths: str, resolution: int, samples: int) -> Image:
+    azims = [float(a) for a in azimuths.split(",")]
+    with tempfile.TemporaryDirectory() as td:
+        out = str(Path(td) / "render.png")
+        ldraw_render.render_ldraw(
+            ldr_path, out, azimuths=azims, resolution=resolution, samples=samples
+        )
+        return Image(data=Path(out).read_bytes(), format="png")
+
+
+@mcp.tool()
+def render_ldraw_file(
+    path: str,
+    azimuths: str = "-60,120",
+    resolution: int = 640,
+    samples: int = 24,
+) -> Image:
+    """Render an LDraw model file (.ldr/.mpd/.dat) to a PNG image.
+
+    Views are rendered at each comma-separated azimuth (degrees) and
+    stitched side by side. Higher samples = cleaner but slower.
+    """
+    p = Path(path).expanduser()
+    if not p.exists():
+        raise FileNotFoundError(f"no such LDraw file: {p}")
+    return _render(str(p), azimuths, resolution, samples)
+
+
+@mcp.tool()
+def render_ldraw_text(
+    ldr: str,
+    azimuths: str = "-60,120",
+    resolution: int = 640,
+    samples: int = 24,
+) -> Image:
+    """Render inline LDraw content (the text of a .ldr file) to a PNG.
+
+    Useful for quick experiments without writing a file first.
+    """
+    with tempfile.NamedTemporaryFile(
+        "w", suffix=".ldr", delete=False
+    ) as f:
+        f.write(ldr)
+        tmp = f.name
+    try:
+        return _render(tmp, azimuths, resolution, samples)
+    finally:
+        Path(tmp).unlink(missing_ok=True)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

ldraw_mcp/setup_cli.py

@@ -0,0 +1,239 @@
+"""
+ldraw-mcp-setup — install the LDraw parts library and the ImportLDraw
+Blender addon so the renderer can run.
+
+What it does:
+  1. Download the LDraw parts library (complete.zip) into ~/.ldraw if the
+     library is not already present.
+  2. Download the latest ImportLDraw addon release from GitHub and install
+     it into every detected Blender addons directory under
+     ~/.config/blender/<version>/scripts/addons/.
+
+Blender itself is a prerequisite and is NOT installed by this script.
+When automatic detection fails, clear manual instructions are printed.
+"""
+
+import argparse
+import io
+import json
+import os
+import sys
+import urllib.request
+import zipfile
+from pathlib import Path
+
+LDRAW_LIBRARY_URL = "https://library.ldraw.org/library/updates/complete.zip"
+IMPORTLDRAW_LATEST_API = (
+    "https://api.github.com/repos/TobyLobster/ImportLDraw/releases/latest"
+)
+IMPORTLDRAW_RELEASES_PAGE = (
+    "https://github.com/TobyLobster/ImportLDraw/releases/latest"
+)
+
+
+def _log(msg: str) -> None:
+    print(msg, flush=True)
+
+
+def ldraw_library_present(ldraw_dir: Path) -> bool:
+    return (ldraw_dir / "parts").is_dir()
+
+
+def install_ldraw_library(ldraw_dir: Path, force: bool = False) -> bool:
+    """Download + unzip the LDraw parts library. Returns True if installed."""
+    if ldraw_library_present(ldraw_dir) and not force:
+        _log(f"[ldraw] library already present at {ldraw_dir} — skipping")
+        return True
+
+    ldraw_dir.mkdir(parents=True, exist_ok=True)
+    _log(f"[ldraw] downloading {LDRAW_LIBRARY_URL} ...")
+    try:
+        with urllib.request.urlopen(LDRAW_LIBRARY_URL) as resp:
+            data = resp.read()
+    except Exception as exc:  # noqa: BLE001
+        _log(f"[ldraw] download FAILED: {exc}")
+        _log(
+            "[ldraw] manual step: download complete.zip from\n"
+            f"          {LDRAW_LIBRARY_URL}\n"
+            f"        and unzip it so that {ldraw_dir}/parts/ exists."
+        )
+        return False
+
+    _log(f"[ldraw] unzipping ({len(data) // (1024 * 1024)} MB) ...")
+    # complete.zip contains a top-level 'ldraw/' directory; extract its
+    # contents directly into ldraw_dir.
+    with zipfile.ZipFile(io.BytesIO(data)) as zf:
+        for member in zf.namelist():
+            parts = member.split("/", 1)
+            if parts[0] == "ldraw" and len(parts) == 2 and parts[1]:
+                target = ldraw_dir / parts[1]
+                if member.endswith("/"):
+                    target.mkdir(parents=True, exist_ok=True)
+                else:
+                    target.parent.mkdir(parents=True, exist_ok=True)
+                    with zf.open(member) as src, open(target, "wb") as dst:
+                        dst.write(src.read())
+            else:
+                zf.extract(member, ldraw_dir)
+
+    if ldraw_library_present(ldraw_dir):
+        _log(f"[ldraw] installed at {ldraw_dir}")
+        return True
+    _log(f"[ldraw] extraction finished but {ldraw_dir}/parts/ not found — check layout")
+    return False
+
+
+def detect_blender_addon_dirs() -> list[Path]:
+    """Find Blender addons dirs under ~/.config/blender/<version>/scripts/addons."""
+    base = Path.home() / ".config" / "blender"
+    dirs: list[Path] = []
+    if base.is_dir():
+        for version_dir in sorted(base.iterdir()):
+            if version_dir.is_dir():
+                dirs.append(version_dir / "scripts" / "addons")
+    return dirs
+
+
+def _find_addon_asset_url() -> str | None:
+    req = urllib.request.Request(
+        IMPORTLDRAW_LATEST_API, headers={"Accept": "application/vnd.github+json"}
+    )
+    with urllib.request.urlopen(req) as resp:
+        release = json.load(resp)
+    for asset in release.get("assets", []):
+        name = asset.get("name", "")
+        if name.endswith(".zip"):
+            return asset.get("browser_download_url")
+    # fall back to the auto-generated source zip
+    return release.get("zipball_url")
+
+
+def _addon_root_in_zip(zf: zipfile.ZipFile) -> str | None:
+    """Return the path prefix inside the zip that contains the addon package.
+
+    The addon package is the directory containing __init__.py that also
+    holds loadldraw/ (or is named importldraw/io_scene_importldraw).
+    """
+    names = zf.namelist()
+    # Look for an __init__.py at depth 1 or 2 whose sibling tree looks like
+    # the addon.
+    inits = [n for n in names if n.endswith("__init__.py")]
+    # Prefer the shallowest __init__.py.
+    inits.sort(key=lambda n: n.count("/"))
+    for init in inits:
+        prefix = init[: -len("__init__.py")]
+        return prefix
+    return None
+
+
+def install_importldraw_addon(addon_dirs: list[Path], force: bool = False) -> bool:
+    """Download the latest ImportLDraw addon and install into each addon dir."""
+    if not addon_dirs:
+        _log(
+            "[addon] no Blender addons directory detected under "
+            "~/.config/blender/<version>/scripts/addons/.\n"
+            "[addon] manual step: launch Blender once (creates the config dir), "
+            "then re-run ldraw-mcp-setup, OR install the addon by hand:\n"
+            f"          download the latest release zip from {IMPORTLDRAW_RELEASES_PAGE}\n"
+            "          and use Blender > Edit > Preferences > Add-ons > Install."
+        )
+        return False
+
+    target_name = "io_scene_importldraw"
+    already = [d for d in addon_dirs if (d / target_name).is_dir()]
+    if already and not force:
+        _log(
+            f"[addon] {target_name} already installed in: "
+            + ", ".join(str(d) for d in already)
+            + " — skipping (use --force to reinstall)"
+        )
+        return True
+
+    _log(f"[addon] querying {IMPORTLDRAW_LATEST_API} ...")
+    try:
+        asset_url = _find_addon_asset_url()
+    except Exception as exc:  # noqa: BLE001
+        _log(f"[addon] could not query GitHub release: {exc}")
+        _log(
+            f"[addon] manual step: download the addon zip from {IMPORTLDRAW_RELEASES_PAGE}\n"
+            "          and install via Blender > Preferences > Add-ons > Install."
+        )
+        return False
+
+    if not asset_url:
+        _log("[addon] no downloadable zip asset found in the latest release")
+        return False
+
+    _log(f"[addon] downloading {asset_url} ...")
+    try:
+        req = urllib.request.Request(asset_url, headers={"User-Agent": "ldraw-mcp"})
+        with urllib.request.urlopen(req) as resp:
+            data = resp.read()
+    except Exception as exc:  # noqa: BLE001
+        _log(f"[addon] download FAILED: {exc}")
+        return False
+
+    ok = True
+    with zipfile.ZipFile(io.BytesIO(data)) as zf:
+        prefix = _addon_root_in_zip(zf)
+        if prefix is None:
+            _log("[addon] could not locate the addon package inside the zip")
+            return False
+        members = [
+            n for n in zf.namelist() if n.startswith(prefix) and not n.endswith("/")
+        ]
+        for addon_dir in addon_dirs:
+            dest = addon_dir / target_name
+            addon_dir.mkdir(parents=True, exist_ok=True)
+            _log(f"[addon] installing into {dest}")
+            for member in members:
+                rel = member[len(prefix):]
+                if not rel:
+                    continue
+                target = dest / rel
+                target.parent.mkdir(parents=True, exist_ok=True)
+                with zf.open(member) as src, open(target, "wb") as out:
+                    out.write(src.read())
+            if not (dest / "__init__.py").exists():
+                _log(f"[addon] WARNING: {dest}/__init__.py missing after install")
+                ok = False
+    if ok:
+        _log("[addon] installed. Enable it in Blender > Preferences > Add-ons if needed.")
+    return ok
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="ldraw-mcp-setup",
+        description="Install the LDraw parts library and ImportLDraw Blender addon.",
+    )
+    parser.add_argument(
+        "--ldraw-dir",
+        default=os.environ.get("LDRAW_LIBRARY_PATH") or str(Path.home() / ".ldraw"),
+        help="Where to install the LDraw parts library (default: ~/.ldraw)",
+    )
+    parser.add_argument("--skip-library", action="store_true", help="Don't install the LDraw library")
+    parser.add_argument("--skip-addon", action="store_true", help="Don't install the ImportLDraw addon")
+    parser.add_argument("--force", action="store_true", help="Reinstall even if present")
+    args = parser.parse_args()
+
+    ldraw_dir = Path(args.ldraw_dir).expanduser()
+    ok = True
+
+    if not args.skip_library:
+        ok = install_ldraw_library(ldraw_dir, force=args.force) and ok
+
+    if not args.skip_addon:
+        ok = install_importldraw_addon(detect_blender_addon_dirs(), force=args.force) and ok
+
+    _log("")
+    if ok:
+        _log("Setup complete. Verify with:  ldraw-mcp   (then call check_renderer)")
+        _log("Or:  python -c \"from ldraw_mcp.render import is_available; print(is_available())\"")
+    else:
+        _log("Setup finished with warnings — see messages above for manual steps.")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

ldraw_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: ldraw-mcp
+Version: 0.1.0
+Summary: MCP server that renders LDraw/LEGO models to images with real part geometry via headless Blender + ImportLDraw.
+Project-URL: Homepage, https://github.com/musharna/ldraw-mcp
+Author: Jaret Arnold
+License: MIT
+License-File: LICENSE
+Keywords: blender,ldraw,lego,mcp,render
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
+Requires-Python: >=3.10
+Requires-Dist: mcp
+Requires-Dist: pillow
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# ldraw-mcp
+
+**Give your MCP client eyes for LEGO® models.**
+
+Render LDraw files (`.ldr` / `.mpd` / `.dat`) to images with *real part
+geometry* — studs, slopes, window glass — using headless Blender and the
+ImportLDraw addon. The output looks like a BrickLink Stud.io render, with no
+GUI anywhere in the loop.
+
+[![PyPI](https://img.shields.io/pypi/v/ldraw-mcp?color=%230a7bbb&label=PyPI)](https://pypi.org/project/ldraw-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/ldraw-mcp)](https://pypi.org/project/ldraw-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-server-8A2BE2.svg)](https://modelcontextprotocol.io)
+
+<img src="docs/hero.png" alt="Two rendered views of a red LEGO car — real studs, transparent glass, rubber tires, steering wheel" width="100%">
+
+<sub>A ~90-line <code>.ldr</code> rendered front-left and rear-right — actual bricks, not a geometric proxy.</sub>
+
+</div>
+
+---
+
+Point a vision-capable model at a build and it sees the actual bricks:
+crossed rotation matrices, floating plates, sunken windows — the kinds of
+export bugs a geometric proxy render will happily hide.
+
+## Quickstart
+
+```bash
+# 1. install
+pip install ldraw-mcp
+
+# 2. install the LDraw parts library + ImportLDraw addon
+ldraw-mcp-setup
+
+# 3. register with Claude Code
+claude mcp add ldraw -- ldraw-mcp
+```
+
+Then ask things like *"render output/build.ldr and tell me what looks
+wrong"* — the model sees the render, not just the text.
+
+> **Blender is a prerequisite** (see [Requirements](#requirements)); it is
+> not installed by `ldraw-mcp-setup`.
+
+## Tools
+
+| tool | what it does |
+|---|---|
+| `render_ldraw_file(path, azimuths="-60,120", resolution=640, samples=24)` | Render a model file to a PNG (multi-view, stitched side by side) |
+| `render_ldraw_text(ldr, azimuths="-60,120", resolution=640, samples=24)` | Render inline LDraw content without writing a file first |
+| `check_renderer()` | Diagnose the Blender / addon / parts-library setup |
+
+`azimuths` is a comma-separated list of view angles in degrees; each is
+rendered and the views are stitched horizontally. Elevation is fixed at
+22°. Higher `samples` = cleaner but slower.
+
+## Requirements
+
+- **Blender 4.x** on `PATH`, or point `LDRAW_MCP_BLENDER` at the binary.
+  Install it yourself (package manager, blender.org, or a local build);
+  `ldraw-mcp-setup` does not install Blender.
+- **ImportLDraw addon** (`io_scene_importldraw`) in Blender's addons dir —
+  installed by `ldraw-mcp-setup`.
+- **LDraw parts library** at `~/.ldraw` (or `LDRAW_LIBRARY_PATH`) —
+  installed by `ldraw-mcp-setup`.
+
+### Environment variables
+
+| var | meaning |
+|---|---|
+| `LDRAW_MCP_BLENDER` | Path to the blender binary (overrides `PATH` lookup) |
+| `LDRAW_MCP_DISABLE` | Set to `1` to force `is_available()` to `False` |
+| `LDRAW_LIBRARY_PATH` | Path to the LDraw parts library (community convention) |
+
+### Manual setup
+
+If `ldraw-mcp-setup` can't detect things automatically:
+
+- **LDraw library:** download
+  [complete.zip](https://library.ldraw.org/library/updates/complete.zip)
+  and unzip so that `~/.ldraw/parts/` exists.
+- **ImportLDraw addon:** download the latest release from
+  [TobyLobster/ImportLDraw](https://github.com/TobyLobster/ImportLDraw/releases)
+  and install it via *Blender > Preferences > Add-ons > Install*, or unzip
+  into `~/.config/blender/<version>/scripts/addons/io_scene_importldraw/`.
+  (Launch Blender once first so the config directory exists.)
+
+## Troubleshooting
+
+- **`check_renderer` says NOT FOUND:** run `ldraw-mcp-setup`, or set the
+  relevant env var above.
+- **No GPU / WSL2 / containers:** rendering uses **Cycles on CPU**, which
+  works headless everywhere — no GPU or display needed. A ~150-part model
+  takes a few seconds at the default 640px / 24 samples.
+- **"no mesh objects imported":** the addon couldn't resolve parts —
+  usually a wrong or incomplete LDraw library path. Re-run setup or check
+  `LDRAW_LIBRARY_PATH`.
+- **Addon not enabled:** the render script enables it automatically per
+  run; if a manual Blender session complains, enable `io_scene_importldraw`
+  in Preferences > Add-ons.
+
+## Provenance
+
+This renderer was extracted from the **prompt2brick** project, where it
+started life as the vision critic's "see the actual model" path.
+prompt2brick keeps its own vendored copy of the render wrapper and Blender
+script, but **this repo is the canonical source going forward** — fixes and
+improvements to the renderer should land here first and be ported back into
+prompt2brick.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+<sub>LEGO® is a trademark of the LEGO Group, which does not sponsor,
+authorize, or endorse this project. This tool is not affiliated with the
+LEGO Group, BrickLink, or the LDraw.org organization.</sub>

ldraw_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ldraw_mcp/__init__.py,sha256=2oxLFbBdb5n_-AJl9vwHL04jn_5xtV6Skl2jj0XLHOU,104
+ldraw_mcp/blender_script.py,sha256=96CsQh5HNQ4HkTCtGU07Hq8upd6gwHBaUCQoZV96oZs,4510
+ldraw_mcp/render.py,sha256=Yp17gqVeluijHqlC9PUQ8D5ZYixuJwGJGPbIo0yh1MA,4108
+ldraw_mcp/server.py,sha256=Id9_t0tBgIn9ENVgKhDbyovzA6Vkejm88rE6Y4Dt3bQ,2829
+ldraw_mcp/setup_cli.py,sha256=D8cE2INJfsKLqbO7xU3LCgI5hYe0LWDKj3fapJG20fw,9042
+ldraw_mcp-0.1.0.dist-info/METADATA,sha256=h_NCudeEVd2Flts7IXhvXEcJop4TVoPJdacAi48jdis,5514
+ldraw_mcp-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+ldraw_mcp-0.1.0.dist-info/entry_points.txt,sha256=dec03rJ3-Hqg0yREC5N1n7-Xjt6Af3sl2BBDVrlidoc,95
+ldraw_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=MWMDpZryeVdiw9xv-WFds8l0UwiwMdANTddbgfMtu_I,1069
+ldraw_mcp-0.1.0.dist-info/RECORD,,

ldraw_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

ldraw_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ldraw-mcp = ldraw_mcp.server:main
+ldraw-mcp-setup = ldraw_mcp.setup_cli:main

ldraw_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaret Arnold
+
+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.