@hybridlabor-api/bdb-hardware-pcb 0.1.0

package/mcp_servers/openscad-mcp-server/src/openscad_mcp/engine.py

@@ -0,0 +1,94 @@
+"""OpenSCAD subprocess execution with verified, atomically replaced outputs."""
+
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+VIEWS = {
+    "perspective": "0,0,0,55,0,25,100",
+    "front": "0,0,0,90,0,0,100",
+    "top": "0,0,0,0,0,0,100",
+    "right": "0,0,0,90,0,90,100",
+}
+FORMATS = ("scad", "stl", "csg", "3mf")
+
+
+class OpenSCADError(RuntimeError):
+    pass
+
+
+class OpenSCAD:
+    def __init__(self, executable: str | None = None, timeout: float = 120):
+        requested = executable or os.environ.get("OPENSCAD_EXECUTABLE")
+        self.executable = requested or shutil.which("openscad")
+        if not self.executable:
+            for candidate in (
+                "/Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD",
+                "/Applications/OpenSCAD-2021.01.app/Contents/MacOS/OpenSCAD",
+            ):
+                if Path(candidate).is_file():
+                    self.executable = candidate
+                    break
+        if not self.executable:
+            raise OpenSCADError(
+                "OpenSCAD not found. Install it or set OPENSCAD_EXECUTABLE to its executable."
+            )
+        self.timeout = timeout
+
+    def _run(self, args: list[str]) -> subprocess.CompletedProcess:
+        try:
+            result = subprocess.run(
+                [self.executable, *args],
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise OpenSCADError(
+                f"OpenSCAD exceeded the {self.timeout:g}s timeout"
+            ) from exc
+        except OSError as exc:
+            raise OpenSCADError(f"Cannot launch OpenSCAD: {exc}") from exc
+        diagnostics = result.stderr + result.stdout
+        # Some OpenSCAD versions report errors (including failed assertions) with exit code zero.
+        if result.returncode or re.search(r"(?:ERROR|WARNING):", diagnostics):
+            raise OpenSCADError(f"OpenSCAD failed: {diagnostics[-6000:].strip()}")
+        return result
+
+    def version(self) -> str:
+        result = self._run(["--version"])
+        return (result.stdout + result.stderr).strip()
+
+    def export(self, source: Path, destination: Path, view: str | None = None) -> Path:
+        suffix = destination.suffix.lower()
+        if view is not None and view not in VIEWS:
+            raise ValueError(f"Unknown view: {view}")
+        if suffix not in {".stl", ".csg", ".3mf", ".png"}:
+            raise ValueError(f"Unsupported output extension: {suffix}")
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.TemporaryDirectory(
+            prefix=".render-", dir=destination.parent
+        ) as temporary:
+            output = Path(temporary) / destination.name
+            args = ["-o", str(output)]
+            if suffix == ".png":
+                args += [
+                    "--render",
+                    "--autocenter",
+                    "--viewall",
+                    "--imgsize=800,600",
+                    f"--camera={VIEWS[view or 'perspective']}",
+                ]
+            args.append(str(source.resolve()))
+            self._run(args)
+            if not output.is_file() or output.stat().st_size == 0:
+                raise OpenSCADError("OpenSCAD produced no geometry/output")
+            if suffix == ".png" and not output.read_bytes().startswith(
+                b"\x89PNG\r\n\x1a\n"
+            ):
+                raise OpenSCADError("OpenSCAD did not produce a PNG image")
+            os.replace(output, destination)
+        return destination

package/mcp_servers/openscad-mcp-server/src/openscad_mcp/geometry.py

@@ -0,0 +1,242 @@
+"""Small, explicit parametric templates; no inferred geometry or AI fallback."""
+
+import json
+import math
+import re
+
+DEFAULTS = {
+    "cube": {"width": 10, "depth": 10, "height": 10, "center": False},
+    "sphere": {"radius": 10, "segments": 48},
+    "cylinder": {"radius": 10, "height": 20, "center": False, "segments": 48},
+    "box": {"width": 30, "depth": 20, "height": 15, "thickness": 2},
+    "rounded_box": {
+        "width": 30,
+        "depth": 20,
+        "height": 15,
+        "radius": 3,
+        "segments": 32,
+    },
+    "tube": {
+        "outer_radius": 10,
+        "inner_radius": 8,
+        "height": 20,
+        "center": False,
+        "segments": 48,
+    },
+    "cone": {
+        "bottom_radius": 10,
+        "top_radius": 0,
+        "height": 20,
+        "center": False,
+        "segments": 48,
+    },
+    "torus": {"major_radius": 15, "minor_radius": 5, "segments": 48},
+    "prism": {"width": 20, "depth": 20, "height": 10},
+    "hexagonal_prism": {"radius": 10, "height": 20, "center": False},
+    "text": {"text": "OpenSCAD", "size": 10, "height": 3},
+}
+
+BODIES = {
+    "cube": "cube([width, depth, height], center=center);",
+    "sphere": "sphere(r=radius, $fn=segments);",
+    "cylinder": "cylinder(h=height, r=radius, center=center, $fn=segments);",
+    "box": """difference() {
+    cube([width, depth, height]);
+    translate([thickness, thickness, thickness])
+        cube([width-2*thickness, depth-2*thickness, height]);
+}""",
+    "rounded_box": """hull() {
+    for (x=[radius, width-radius], y=[radius, depth-radius], z=[radius, height-radius])
+        translate([x,y,z]) sphere(r=radius, $fn=segments);
+}""",
+    "tube": """difference() {
+    cylinder(h=height, r=outer_radius, center=center, $fn=segments);
+    translate([0,0,center ? 0 : -0.01])
+        cylinder(h=height+0.02, r=inner_radius, center=center, $fn=segments);
+}""",
+    "cone": "cylinder(h=height, r1=bottom_radius, r2=top_radius, center=center, $fn=segments);",
+    "torus": """rotate_extrude($fn=segments)
+    translate([major_radius,0,0]) circle(r=minor_radius, $fn=segments);""",
+    "prism": "linear_extrude(height=height) polygon([[0,0],[width,0],[0,depth]]);",
+    "hexagonal_prism": "cylinder(h=height, r=radius, center=center, $fn=6);",
+    "text": 'linear_extrude(height=height) text(text, size=size, halign="center", valign="center");',
+}
+
+
+def parameters_for(shape: str, values: dict | None = None) -> dict:
+    if shape not in DEFAULTS:
+        raise ValueError(
+            f"Unsupported model type {shape!r}. Supported: {', '.join(DEFAULTS)}"
+        )
+    values = values or {}
+    unknown = values.keys() - DEFAULTS[shape].keys()
+    if unknown:
+        raise ValueError(
+            f"Unsupported parameters for {shape}: {', '.join(sorted(unknown))}"
+        )
+    p = DEFAULTS[shape] | values
+    for key, value in p.items():
+        if key == "center":
+            if type(value) is not bool:
+                raise ValueError("center must be a boolean")
+        elif key == "text":
+            if not isinstance(value, str) or not value.strip() or len(value) > 200:
+                raise ValueError("text must contain 1–200 characters")
+        elif key == "segments":
+            if type(value) is not int or not 12 <= value <= 256:
+                raise ValueError("segments must be an integer between 12 and 256")
+        elif (
+            type(value) not in (int, float)
+            or value < 0
+            or value > 10000
+            or not math.isfinite(value)
+            or (value == 0 and key != "top_radius")
+        ):
+            raise ValueError(
+                f"{key} must be a finite positive number, at most 10000 mm"
+            )
+    if shape == "box" and (
+        2 * p["thickness"] >= min(p["width"], p["depth"])
+        or p["thickness"] >= p["height"]
+    ):
+        raise ValueError("thickness leaves no interior in the box")
+    if shape == "rounded_box" and 2 * p["radius"] > min(
+        p["width"], p["depth"], p["height"]
+    ):
+        raise ValueError("radius exceeds half the smallest box dimension")
+    if shape == "tube" and p["inner_radius"] >= p["outer_radius"]:
+        raise ValueError("inner_radius must be smaller than outer_radius")
+    if shape == "torus" and p["minor_radius"] >= p["major_radius"]:
+        raise ValueError("minor_radius must be smaller than major_radius")
+    return p
+
+
+def generate_source(shape: str, values: dict | None = None) -> tuple[str, dict]:
+    p = parameters_for(shape, values)
+    source = "// Dimensions in millimeters. Edit the parameters below.\n"
+    source += "\n".join(
+        f"{key} = {json.dumps(value, ensure_ascii=False)};" for key, value in p.items()
+    )
+    return source + "\n\n" + BODIES[shape] + "\n", p
+
+
+# Restricted description syntax is intentionally separate from arbitrary SCAD.
+SHAPES = [
+    ("rounded_box", r"rounded[ _]box"),
+    ("box", r"hollow box|container|tray|box"),
+    ("hexagonal_prism", r"hexagonal[ _]prism"),
+    ("tube", r"tube|pipe"),
+    ("cube", r"cube|cuboid|block"),
+    ("sphere", r"sphere|ball"),
+    ("cylinder", r"cylinder|rod"),
+    ("cone", r"cone"),
+    ("torus", r"torus|donut"),
+    ("prism", r"triangular prism|prism|wedge"),
+]
+UNITS = {
+    None: 1,
+    "mm": 1,
+    "cm": 10,
+    "m": 1000,
+    "in": 25.4,
+    "inch": 25.4,
+    "inches": 25.4,
+}
+NUMBER = r"(-?(?:\d+(?:\.\d*)?|\.\d+))\s*(mm|cm|m|inches|inch|in)?\b"
+
+
+def parse_description(
+    description: str, shape: str | None = None, existing: dict | None = None
+) -> tuple[str, dict]:
+    if not description.strip() or len(description) > 2000:
+        raise ValueError("description must contain 1–2000 characters")
+    if re.search(r"\b(ft|feet|foot)\b", description, re.I):
+        raise ValueError("Use mm, cm, m, or inches")
+    if re.search(
+        r"\b(hole|holes|cutout|subtract|union|difference|intersection)\b",
+        description,
+        re.I,
+    ):
+        raise ValueError("Use create_model_from_scad for composite geometry")
+    if shape is None:
+        for candidate, pattern in SHAPES:
+            match = re.search(rf"\b(?:{pattern})\b", description, re.I)
+            if match:
+                remainder = description[: match.start()] + description[match.end() :]
+                if any(
+                    re.search(rf"\b(?:{other})\b", remainder, re.I)
+                    for _, other in SHAPES
+                ):
+                    raise ValueError("Use create_model_from_scad for multiple shapes")
+                shape = candidate
+                break
+        else:
+            raise ValueError(
+                "No supported primitive found. Use explicit model_type/parameters or create_model_from_scad for complex models."
+            )
+    if shape not in DEFAULTS:
+        raise ValueError("This model cannot be edited with a primitive description")
+    values = dict(existing or {})
+    found = False
+    consumed_numbers = set()
+    for key in DEFAULTS[shape]:
+        if key in ("text", "center"):
+            continue
+        label = key.replace("_", "[ _]")
+        aliases = {
+            "width": "width|wide",
+            "height": "height|high|tall",
+            "depth": "depth|deep|long",
+            "thickness": "thickness|thick",
+        }.get(key, label)
+        patterns = [
+            rf"\b(?:{label})\s*(?:=|:|of|to)?\s*{NUMBER}",
+            rf"{NUMBER}\s*(?:{aliases})\b",
+        ]
+        matches = [
+            m for pattern in patterns for m in re.finditer(pattern, description, re.I)
+        ]
+        if matches:
+            match = max(matches, key=lambda m: m.start())
+            if key == "segments" and match.group(2):
+                raise ValueError("segments is a count, not a length")
+            value = (
+                float(match.group(1))
+                * UNITS[match.group(2).lower() if match.group(2) else None]
+            )
+            values[key] = (
+                int(value) if key == "segments" and value.is_integer() else value
+            )
+            consumed_numbers.update(m.span(1) for m in matches)
+            found = True
+    if "radius" in DEFAULTS[shape]:
+        diameter = re.search(
+            rf"\bdiameter\s*(?:=|:|of|to)?\s*{NUMBER}", description, re.I
+        )
+        if diameter:
+            values["radius"] = (
+                float(diameter[1])
+                * UNITS[diameter[2].lower() if diameter[2] else None]
+                / 2
+            )
+            consumed_numbers.add(diameter.span(1))
+            found = True
+    if "center" in DEFAULTS[shape] and re.search(
+        r"\bcent(er|re)(ed)?\b", description, re.I
+    ):
+        values["center"] = not bool(
+            re.search(r"\b(?:not|un)[ -]?cent(er|re)(ed)?\b", description, re.I)
+        )
+        found = True
+    if existing is not None and not found:
+        raise ValueError(
+            "No parameter changes recognized. Use e.g. 'height 30 mm' or explicit parameters."
+        )
+    number_spans = {
+        m.span() for m in re.finditer(r"-?(?:\d+(?:\.\d*)?|\.\d+)", description)
+    }
+    if number_spans - consumed_numbers:
+        raise ValueError(
+            "Dimensions were not understood. Name each parameter, e.g. 'width 30 mm height 20 mm'."
+        )
+    return shape, parameters_for(shape, values)

package/mcp_servers/openscad-mcp-server/src/openscad_mcp/server.py

@@ -0,0 +1,245 @@
+"""Official MCP transports plus local preview/download HTTP routes."""
+
+import argparse
+import asyncio
+import html
+import json
+import logging
+import os
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+from mcp.server.fastmcp import FastMCP, Image
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, validate_call
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+from . import __version__
+from .engine import OpenSCAD, OpenSCADError
+from .geometry import DEFAULTS
+from .service import ModelConflict, ModelNotFound, ModelService
+
+
+def create_server(service: ModelService) -> tuple[FastMCP, FastAPI]:
+    mcp = FastMCP(
+        "OpenSCAD",
+        stateless_http=True,
+        json_response=True,
+        instructions="Create parametric primitives with explicit dimensions in mm, or supply OpenSCAD source for complex models. Read the returned parameters. Only SCAD preserves editable source. This local server executes trusted SCAD with the current user's file access.",
+    )
+
+    async def create_3d_model(
+        description: str = "",
+        model_type: str | None = None,
+        parameters: dict | None = None,
+    ) -> dict:
+        """Create a primitive, STL and four PNG views. Prefer model_type and parameters; descriptions only recognize named primitive dimensions. Use get_capabilities for defaults."""
+        return await asyncio.to_thread(
+            service.create, description, model_type, parameters
+        )
+
+    async def create_model_from_scad(scad_code: str, description: str = "") -> dict:
+        """Compile trusted, self-contained 3D OpenSCAD source into STL and four PNG previews. No image reconstruction or implicit AI generation."""
+        return await asyncio.to_thread(service.from_scad, scad_code, description)
+
+    async def modify_3d_model(
+        model_id: str,
+        modifications: str = "",
+        parameters: dict | None = None,
+        scad_code: str | None = None,
+        expected_revision: str | None = None,
+    ) -> dict:
+        """Edit primitive dimensions or replace source using scad_code. Pass expected_revision from get_model/get_model_source to reject stale edits. Failed edits leave the previous revision intact."""
+        return await asyncio.to_thread(
+            service.modify,
+            model_id,
+            modifications,
+            parameters,
+            scad_code,
+            expected_revision,
+        )
+
+    async def export_model(model_id: str, format: str = "stl") -> dict:
+        """Export scad (editable source), stl/3mf (meshes), or csg (evaluated geometry tree)."""
+        return await asyncio.to_thread(service.export, model_id, format)
+
+    async def get_model(model_id: str) -> dict:
+        """Read a persisted model's parameters and local artifact paths."""
+        return await asyncio.to_thread(service.get, model_id)
+
+    async def get_model_source(model_id: str) -> dict:
+        """Read the saved UTF-8 SCAD source and revision over MCP, including inside Docker. Edit scad_code and pass its revision as expected_revision to modify_3d_model."""
+        return await asyncio.to_thread(service.source, model_id)
+
+    async def get_model_preview(model_id: str, view: str = "perspective") -> Image:
+        """Return an actual PNG image to the MCP client. Views: perspective, front, top, right."""
+        path = await asyncio.to_thread(service.preview, model_id, view)
+        return Image(path=str(path))
+
+    async def get_capabilities() -> dict:
+        """Report OpenSCAD version and supported primitives with defaults (all dimensions in mm)."""
+        version = await asyncio.to_thread(service.engine.version)
+        return {
+            "version": __version__,
+            "openscad": version,
+            "primitives": DEFAULTS,
+            "transports": ["stdio", "streamable-http"],
+            "mcp_path": "/mcp",
+        }
+
+    functions = [
+        create_3d_model,
+        create_model_from_scad,
+        modify_3d_model,
+        export_model,
+        get_model,
+        get_model_source,
+        get_capabilities,
+    ]
+    rest_tools = {}
+    for function in functions:
+        mcp.add_tool(function)
+        rest_tools[function.__name__] = validate_call(
+            config=ConfigDict(extra="forbid")
+        )(function)
+    mcp.add_tool(get_model_preview)
+    mcp_app = mcp.streamable_http_app()
+
+    @asynccontextmanager
+    async def lifespan(app):
+        async with mcp.session_manager.run():
+            yield
+
+    app = FastAPI(title="OpenSCAD MCP Server", version=__version__, lifespan=lifespan)
+    app.add_middleware(
+        TrustedHostMiddleware, allowed_hosts=["localhost", "127.0.0.1", "[::1]"]
+    )
+
+    @app.middleware("http")
+    async def local_origin(request: Request, call_next):
+        origin = request.headers.get("origin")
+        if origin:
+            from urllib.parse import urlsplit
+
+            parsed = urlsplit(origin)
+            if parsed.scheme not in ("http", "https") or parsed.hostname not in (
+                "localhost",
+                "127.0.0.1",
+                "::1",
+            ):
+                return JSONResponse(
+                    {"detail": "Only local browser origins are allowed"},
+                    status_code=403,
+                )
+        response = await call_next(request)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        return response
+
+    @app.exception_handler(ModelNotFound)
+    async def missing(request, exc):
+        return JSONResponse({"detail": str(exc)}, status_code=404)
+
+    @app.exception_handler(ModelConflict)
+    async def conflict(request, exc):
+        return JSONResponse(
+            {"detail": str(exc), "current_revision": exc.current_revision},
+            status_code=409,
+        )
+
+    @app.exception_handler(ValueError)
+    async def invalid(request, exc):
+        return JSONResponse({"detail": str(exc)}, status_code=422)
+
+    @app.exception_handler(OpenSCADError)
+    async def render_failed(request, exc):
+        return JSONResponse({"detail": str(exc)}, status_code=422)
+
+    @app.get("/")
+    async def root():
+        return {
+            "name": "OpenSCAD MCP Server",
+            "version": __version__,
+            "mcp_endpoint": "/mcp",
+            "tools": list(rest_tools) + ["get_model_preview"],
+        }
+
+    @app.get("/health")
+    async def health():
+        return await get_capabilities()
+
+    class ToolCall(BaseModel):
+        model_config = ConfigDict(extra="forbid")
+        tool_name: str
+        tool_params: dict = Field(default_factory=dict)
+
+    @app.post("/tool_call")
+    async def tool_call(body: ToolCall):
+        if body.tool_name not in rest_tools:
+            return JSONResponse({"detail": "Unknown tool"}, status_code=404)
+        try:
+            return await rest_tools[body.tool_name](**body.tool_params)
+        except ValidationError as exc:
+            return JSONResponse({"detail": str(exc)}, status_code=422)
+
+    @app.get("/preview/{view}/{model_id}")
+    async def preview(view: str, model_id: str):
+        path = await asyncio.to_thread(service.preview, model_id, view)
+        return FileResponse(
+            path, media_type="image/png", headers={"Cache-Control": "no-store"}
+        )
+
+    @app.get("/download/{model_id}")
+    async def download(model_id: str, format: str = "stl"):
+        data = await asyncio.to_thread(service.export, model_id, format)
+        return FileResponse(data["model_file"], filename=f"{model_id}.{format}")
+
+    @app.get("/ui/preview/{model_id}", response_class=HTMLResponse)
+    async def preview_page(model_id: str):
+        data = await asyncio.to_thread(service.get, model_id)
+        views = "".join(
+            f'<figure><img width="400" src="{url}" alt="{view}"><figcaption>{view}</figcaption></figure>'
+            for view, url in data["previews"].items()
+        )
+        links = " · ".join(
+            f'<a href="/download/{model_id}?format={fmt}">{fmt.upper()}</a>'
+            for fmt in data["supported_formats"]
+        )
+        return f'<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>OpenSCAD model</title><body><h1>{html.escape(data["description"] or data["model_type"])}</h1><pre>{html.escape(json.dumps(data["parameters"], indent=2))}</pre><nav>{links}</nav><main style="display:flex;flex-wrap:wrap">{views}</main></body></html>'
+
+    app.mount("/", mcp_app)
+    return mcp, app
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Local OpenSCAD MCP server")
+    parser.add_argument("--transport", choices=["stdio", "http"], default="stdio")
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument(
+        "--output-dir",
+        default=os.environ.get(
+            "OPENSCAD_OUTPUT_DIR", str(Path.home() / ".local/share/openscad-mcp/models")
+        ),
+    )
+    parser.add_argument("--openscad", default=os.environ.get("OPENSCAD_EXECUTABLE"))
+    parser.add_argument("--timeout", type=float, default=120)
+    args = parser.parse_args()
+    if args.timeout <= 0:
+        parser.error("--timeout must be positive")
+    logging.basicConfig(level=logging.INFO)
+    try:
+        engine = OpenSCAD(args.openscad, args.timeout)
+        engine.version()
+        mcp, app = create_server(ModelService(args.output_dir, engine))
+    except OpenSCADError as exc:
+        parser.exit(1, f"{exc}\n")
+    if args.transport == "stdio":
+        mcp.run(transport="stdio")
+    else:
+        import uvicorn
+
+        uvicorn.run(app, host="127.0.0.1", port=args.port)
+
+
+if __name__ == "__main__":
+    main()