blenderwright 2.0.0__py3-none-any.whl

blenderwright/__init__.py

@@ -0,0 +1,3 @@
+"""blenderwright: MCP Server for Blender."""
+
+__version__ = "0.2.0"

blenderwright/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as python -m blenderwright."""
+
+from blenderwright.server import main
+
+main()

blenderwright/aliases.py

@@ -0,0 +1,86 @@
+"""Keep a renamed parameter's old spelling working.
+
+The same concept was spelled two ways. 75 tools took `object_name` for "which
+object"; 15 took a bare `name`, as did three tools referring to a collection
+or a scene. A caller reading one tool's schema could not predict the next, and
+strict.py turns a wrong guess into an error rather than a silent no-op, so
+each mismatch cost a round trip out of a fixed budget.
+
+Those 18 were renamed to the typed spelling the rest of the codebase already
+used -- `object_name`, `collection_name`, `scene_name`, alongside the existing
+`material_name`, `curve_name`, `node_name`. Renaming alone would break
+anything already calling with `name`, so the old spelling stays valid as a
+pydantic validation alias: the published schema advertises the new name only,
+and both are accepted.
+
+Nothing downstream changed. The function still receives the value under its
+own parameter name, and the wire payload sent to the addon still uses its
+original keys, so no handler needed editing.
+
+`name` is deliberately NOT aliased on the create_* tools. There it means the
+thing being made, which is a different concept, and accepting `object_name`
+for it would be a lie.
+"""
+
+from typing import Any
+
+from pydantic import AliasChoices
+
+# Tool -> the parameter that replaced its bare `name`. Held as data so the
+# tests can assert against the same list rather than a second copy of it.
+RENAMED_FROM_NAME: dict[str, str] = {
+    # transforms
+    "set_location": "object_name",
+    "set_rotation": "object_name",
+    "set_scale": "object_name",
+    "apply_transforms": "object_name",
+    "set_origin": "object_name",
+    "snap_to_grid": "object_name",
+    # objects
+    "delete_object": "object_name",
+    "duplicate_object": "object_name",
+    "get_object_info": "object_name",
+    "set_object_visibility": "object_name",
+    # lighting
+    "set_light_property": "object_name",
+    "delete_light": "object_name",
+    "set_shadow_settings": "object_name",
+    # camera
+    "set_camera_property": "object_name",
+    "set_active_camera": "object_name",
+    # collections and scenes: not objects, so typed to what they refer to
+    "set_collection_visibility": "collection_name",
+    "delete_collection": "collection_name",
+    "delete_scene": "scene_name",
+}
+
+LEGACY_SPELLING = "name"
+
+
+def attach_legacy_aliases(server: Any) -> int:
+    """Accept each renamed parameter's previous spelling.
+
+    Args:
+        server: A FastMCP instance whose registered tools should also accept
+            the older parameter name.
+
+    Returns:
+        The number of tools given an alias. Tools already aliased are not
+        counted, so calling this twice reports zero the second time.
+    """
+    count = 0
+    for tool_name, canonical in sorted(RENAMED_FROM_NAME.items()):
+        tool = server._tool_manager._tools.get(tool_name)
+        if tool is None:
+            continue
+        model = tool.fn_metadata.arg_model
+        field = model.model_fields.get(canonical)
+        if field is None or field.validation_alias is not None:
+            continue
+        # Canonical first: pydantic publishes the first choice in the JSON
+        # Schema, so the schema shows one name and only one.
+        field.validation_alias = AliasChoices(canonical, LEGACY_SPELLING)
+        model.model_config["populate_by_name"] = True
+        model.model_rebuild(force=True)
+        count += 1
+    return count

blenderwright/connection.py

@@ -0,0 +1,179 @@
+"""TCP socket client for communicating with the Blender addon."""
+
+import json
+import logging
+import socket
+import struct
+import threading
+import time
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class BlenderConnectionError(Exception):
+    """Raised when connection to Blender fails."""
+    pass
+
+
+class BlenderConnection:
+    """TCP socket client that connects to the Blender addon's socket server.
+
+    Protocol: Each message is a 4-byte big-endian length prefix followed by
+    a UTF-8 JSON payload.
+    """
+
+    DEFAULT_HOST = "127.0.0.1"
+    DEFAULT_PORT = 9876
+    DEFAULT_TIMEOUT = 30.0
+    BUSY_RETRY_DELAY = 2.0  # seconds between retries when Blender is rendering
+    BUSY_MAX_RETRIES = 150  # ~5 minutes of waiting at 2s intervals
+
+    def __init__(self, host: str = DEFAULT_HOST, port: int = DEFAULT_PORT, timeout: float = DEFAULT_TIMEOUT):
+        self._host = host
+        self._port = port
+        self._timeout = timeout
+        self._socket: socket.socket | None = None
+        self._lock = threading.Lock()
+
+    @property
+    def is_connected(self) -> bool:
+        return self._socket is not None
+
+    def connect(self) -> None:
+        """Connect to the Blender addon socket server."""
+        if self._socket is not None:
+            return
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.settimeout(self._timeout)
+            sock.connect((self._host, self._port))
+            self._socket = sock
+        except (ConnectionRefusedError, OSError) as e:
+            raise BlenderConnectionError(
+                f"Cannot connect to Blender at {self._host}:{self._port}. "
+                "Ensure Blender is running with the blenderwright addon enabled."
+            ) from e
+
+    def disconnect(self) -> None:
+        """Disconnect from Blender."""
+        if self._socket is not None:
+            try:
+                self._socket.close()
+            except OSError:
+                pass
+            self._socket = None
+
+    def _send_raw(self, data: bytes) -> None:
+        """Send length-prefixed data."""
+        if self._socket is None:
+            raise BlenderConnectionError("Not connected to Blender")
+        header = struct.pack(">I", len(data))
+        self._socket.sendall(header + data)
+
+    def _recv_raw(self) -> bytes:
+        """Receive length-prefixed data."""
+        if self._socket is None:
+            raise BlenderConnectionError("Not connected to Blender")
+        header = self._recv_exactly(4)
+        length = struct.unpack(">I", header)[0]
+        if length > 100 * 1024 * 1024:  # 100MB sanity limit
+            raise BlenderConnectionError(f"Response too large: {length} bytes")
+        return self._recv_exactly(length)
+
+    def _recv_exactly(self, n: int) -> bytes:
+        """Receive exactly n bytes."""
+        if self._socket is None:
+            raise BlenderConnectionError("Not connected to Blender")
+        chunks = []
+        remaining = n
+        while remaining > 0:
+            chunk = self._socket.recv(min(remaining, 65536))
+            if not chunk:
+                raise BlenderConnectionError("Connection closed by Blender")
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        return b"".join(chunks)
+
+    def send_command(self, command: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Send a command to Blender and return the response.
+
+        Args:
+            command: The command name (must be in the addon's allowlist).
+            params: Optional parameters for the command.
+
+        Returns:
+            Response dict with 'status' ('ok' or 'error') and 'result'.
+
+        Raises:
+            BlenderConnectionError: If not connected or communication fails.
+        """
+        with self._lock:
+            message = {"command": command}
+            if params:
+                message["params"] = params
+
+            # Try up to 2 times: reconnect on stale connection
+            last_error = None
+            for attempt in range(2):
+                if self._socket is None:
+                    self.connect()
+
+                try:
+                    payload = json.dumps(message).encode("utf-8")
+                    self._send_raw(payload)
+                    response_data = self._recv_raw()
+                    response = json.loads(response_data.decode("utf-8"))
+                except (OSError, json.JSONDecodeError, BlenderConnectionError) as e:
+                    last_error = e  # noqa: F841
+                    self.disconnect()
+                    if attempt == 0:
+                        continue  # retry with fresh connection
+                    raise BlenderConnectionError(
+                        f"Connection to Blender lost: {e}"
+                    ) from e
+                else:
+                    break
+
+            if not isinstance(response, dict):
+                raise BlenderConnectionError("Invalid response format from Blender")
+
+            # If Blender is rendering, wait and retry automatically
+            if response.get("status") == "busy":
+                for retry in range(self.BUSY_MAX_RETRIES):
+                    logger.info(
+                        "Blender is rendering, waiting %.1fs before retry %d/%d for '%s'",
+                        self.BUSY_RETRY_DELAY, retry + 1, self.BUSY_MAX_RETRIES, command,
+                    )
+                    time.sleep(self.BUSY_RETRY_DELAY)
+
+                    try:
+                        payload = json.dumps(message).encode("utf-8")
+                        self._send_raw(payload)
+                        response_data = self._recv_raw()
+                        response = json.loads(response_data.decode("utf-8"))
+                    except (OSError, json.JSONDecodeError, BlenderConnectionError):
+                        self.disconnect()
+                        self.connect()
+                        continue
+
+                    if not isinstance(response, dict):
+                        raise BlenderConnectionError("Invalid response format from Blender")
+
+                    if response.get("status") != "busy":
+                        return response
+
+                raise BlenderConnectionError(
+                    f"Blender was busy rendering for too long. "
+                    f"Command '{command}' was not processed after "
+                    f"{self.BUSY_MAX_RETRIES * self.BUSY_RETRY_DELAY:.0f}s of waiting."
+                )
+
+            return response
+
+    def __enter__(self):
+        self.connect()
+        return self
+
+    def __exit__(self, *args):
+        self.disconnect()

blenderwright/enum_hints.py

@@ -0,0 +1,118 @@
+"""Publish each tool's accepted values as a JSON Schema enum.
+
+27 parameters were enforced against an ALLOWED_* set and documented with
+nothing, or with two examples and an "e.g.". A model reading the schema had no
+way to know what was acceptable, so it guessed, and every wrong guess cost a
+round trip out of a fixed budget.
+
+Rather than hand-write 27 lists into docstrings, where they would drift from
+the constants exactly as the tool count drifted from the code, the pairing is
+read out of the source: `validate_enum(param, ALLOWED_THING)` says that
+`param` accepts `ALLOWED_THING`. The constant remains the single definition.
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib
+import inspect
+import re
+from typing import Any
+
+# validate_enum(value, ALLOWED_X, ...) inside a tool function body.
+_ENUM_CALL = re.compile(r"validate_enum\(\s*(\w+)\s*,\s*(ALLOWED_\w+)")
+
+
+def _enum_pairs(module: Any) -> dict[str, dict[str, list[str]]]:
+    """Map tool name -> parameter -> accepted values, for one tool module.
+
+    Args:
+        module: An imported module from blenderwright.tools.
+
+    Returns:
+        Nested mapping of function name to parameter to sorted values. A
+        parameter checked against more than one set is omitted, because the
+        choice depends on another argument and a single enum would be a lie.
+    """
+    try:
+        source = inspect.getsource(module)
+    except (OSError, TypeError):
+        return {}
+
+    found: dict[str, dict[str, set[str]]] = {}
+    tree = ast.parse(source)
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        body = ast.get_source_segment(source, node) or ""
+        for param, const_name in _ENUM_CALL.findall(body):
+            const = getattr(module, const_name, None)
+            if not isinstance(const, (set, frozenset, list, tuple)):
+                continue
+            if not all(isinstance(v, str) for v in const):
+                continue
+            found.setdefault(node.name, {}).setdefault(param, set())
+            found[node.name][param] |= {"", *const} - {""}
+
+    result: dict[str, dict[str, list[str]]] = {}
+    for func, params in found.items():
+        for param, values in params.items():
+            body = None
+            # A parameter validated against two different sets (the value of
+            # set_curve_property depends on which property) cannot be one enum.
+            if sum(1 for p, c in _ENUM_CALL.findall(
+                    ast.get_source_segment(source, next(
+                        n for n in ast.walk(tree)
+                        if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))
+                        and n.name == func)) or "") if p == param) > 1:
+                continue
+            result.setdefault(func, {})[param] = sorted(values)
+            del body
+    return result
+
+
+def attach_enum_hints(server: Any) -> int:
+    """Attach accepted values to every tool parameter that has a fixed set.
+
+    Args:
+        server: A FastMCP instance with tools already registered.
+
+    Returns:
+        The number of parameters given an enum.
+    """
+    modules: dict[str, dict[str, dict[str, list[str]]]] = {}
+    attached = 0
+
+    for tool in server._tool_manager._tools.values():
+        module_name = getattr(tool.fn, "__module__", "")
+        if not module_name.startswith("blenderwright.tools."):
+            continue
+        if module_name not in modules:
+            try:
+                modules[module_name] = _enum_pairs(importlib.import_module(module_name))
+            except Exception:
+                modules[module_name] = {}
+
+        params = modules[module_name].get(tool.fn.__name__, {})
+        if not params:
+            continue
+
+        model = tool.fn_metadata.arg_model
+        changed = False
+        for param, values in params.items():
+            field = model.model_fields.get(param)
+            if field is None or (field.json_schema_extra or {}).get("enum"):
+                continue
+            extra = dict(field.json_schema_extra or {})
+            extra["enum"] = values
+            field.json_schema_extra = extra
+            changed = True
+            attached += 1
+        if changed:
+            model.model_rebuild(force=True)
+            # FastMCP caches the JSON schema on the tool at registration, and
+            # that cached copy is what list_tools() serves. Rebuilding the
+            # model alone would leave clients reading the old one.
+            tool.parameters = model.model_json_schema()
+
+    return attached