keyshot-mcp 0.2.1 → 0.4.2

package/scripts/keyshot_bridge.py

@@ -31,6 +31,8 @@ def main():
             data = status()
         elif operation == "inspect_scene":
             data = inspect_scene()
+        elif operation == "list_cameras":
+            data = list_cameras()
         elif operation == "render":
             data = render(payload, output_files, warnings)
         elif operation == "batch_render":
@@ -96,6 +98,25 @@ def inspect_scene():
     }
 
 
+def list_cameras():
+    raw = safe_list_call("getCameras")
+    names = []
+    for camera in raw:
+        if isinstance(camera, str):
+            name = camera
+        else:
+            name = first_success(
+                lambda camera=camera: camera.getName(),
+                lambda camera=camera: camera.name(),
+                lambda camera=camera: camera.name,
+                default=None,
+            )
+        if name is None:
+            name = repr(camera)
+        names.append(name)
+    return {"cameras": names, "count": len(names)}
+
+
 def render(payload, output_files, warnings):
     output_path = payload.get("outputPath") or default_output_path(payload, "render", payload.get("format") or "png")
     ensure_parent(output_path)
@@ -116,16 +137,35 @@ def render(payload, output_files, warnings):
     samples = payload.get("samples")
     max_time = payload.get("maxTimeSeconds")
 
-    call_variants(
-        "render image",
-        lambda: lux.renderImage(output_path, width, height),
-        lambda: lux.renderImage(output_path, width, height, samples) if samples else None,
-        lambda: lux.renderImage(output_path, width, height, samples, max_time) if samples and max_time else None,
-        lambda: lux.renderImage(output_path),
-    )
+    if samples is not None and max_time is not None:
+        raise RuntimeError("samples and maxTimeSeconds cannot be used together; choose one render mode.")
+
+    render_options = build_render_options(samples, max_time)
+
+    if render_options is None:
+        call_variants(
+            "render image",
+            lambda: lux.renderImage(output_path, width, height),
+            lambda: lux.renderImage(output_path),
+        )
+    else:
+        # Current KeyShot versions accept a RenderOptions object. Keep positional
+        # and keyword variants for older headless scripting builds.
+        call_variants(
+            "render image with options",
+            lambda: lux.renderImage(output_path, width, height, opts=render_options),
+            lambda: lux.renderImage(output_path, width, height, render_options),
+            lambda: lux.renderImage(output_path, opts=render_options),
+        )
 
     output_files.append(output_path)
-    return {"rendered": output_path, "width": width, "height": height}
+    return {
+        "rendered": output_path,
+        "width": width,
+        "height": height,
+        "samples": samples,
+        "maxTimeSeconds": max_time,
+    }
 
 
 def batch_render(payload, output_files, warnings):
@@ -177,11 +217,19 @@ def batch_render(payload, output_files, warnings):
 def import_model(payload, output_files, warnings):
     model_path = payload.get("modelPath")
     output_scene_path = payload.get("outputScenePath")
+    base_scene_path = payload.get("baseScenePath")
     if not model_path or not os.path.exists(model_path):
         raise RuntimeError("Model file not found: %s" % model_path)
     if not output_scene_path:
         raise RuntimeError("outputScenePath is required")
 
+    if base_scene_path:
+        if not os.path.exists(base_scene_path):
+            raise RuntimeError("Base scene file not found: %s" % base_scene_path)
+        open_scene(base_scene_path, warnings)
+    else:
+        new_scene(warnings)
+
     call_variants(
         "import model",
         lambda: lux.importFile(model_path),
@@ -189,7 +237,33 @@ def import_model(payload, output_files, warnings):
     )
     save_to(output_scene_path)
     output_files.append(output_scene_path)
-    return {"importedModel": model_path, "savedScene": output_scene_path}
+    return {
+        "importedModel": model_path,
+        "baseScene": base_scene_path,
+        "savedScene": output_scene_path,
+    }
+
+
+def open_scene(scene_path, warnings):
+    call_variants(
+        "open base scene",
+        lambda: lux.openScene(scene_path),
+        lambda: lux.openFile(scene_path),
+        lambda: lux.loadScene(scene_path),
+        lambda: lux.openProject(scene_path),
+    )
+
+
+def new_scene(warnings):
+    try:
+        call_variants(
+            "create new scene",
+            lambda: lux.newScene(),
+            lambda: lux.createScene(),
+            lambda: lux.newProject(),
+        )
+    except RuntimeError:
+        warnings.append("Started import into the current KeyShot scene (could not create a new scene).")
 
 
 def apply_material(payload, output_files, warnings):
@@ -225,34 +299,53 @@ def set_camera(payload, output_files, warnings):
     if position is None or look_at is None:
         raise RuntimeError("position and lookAt are required")
 
-    camera = first_success(
+    camera = first_camera_object(
         lambda: lux.getCamera(camera_name),
         lambda: lux.newCamera(camera_name),
         lambda: lux.createCamera(camera_name),
-        default=None,
     )
 
     if camera is None and hasattr(lux, "saveCamera"):
-        camera = call_variants("save camera", lambda: lux.saveCamera(camera_name))
+        try:
+            # Current KeyShot versions expose cameras as names rather than camera
+            # objects. saveCamera creates the named camera and setCamera activates it.
+            call_variants(
+                "create named camera",
+                lambda: lux.saveCamera(camera_name),
+                lambda: lux.saveCamera(),
+            )
+            if hasattr(lux, "setCamera"):
+                call_variants("activate camera", lambda: lux.setCamera(camera_name))
+        except RuntimeError:
+            pass
 
-    call_variants(
-        "set camera position",
-        lambda: camera.setPosition(tuple(position)),
-        lambda: lux.setCameraPosition(camera_name, tuple(position)),
-        lambda: lux.setCameraPosition(tuple(position)),
-    )
-    call_variants(
-        "set camera look-at",
-        lambda: camera.setLookAt(tuple(look_at)),
-        lambda: lux.setCameraLookAt(camera_name, tuple(look_at)),
-        lambda: lux.setCameraLookAt(tuple(look_at)),
-    )
-    call_variants(
-        "set camera up",
-        lambda: camera.setUp(tuple(up)),
-        lambda: lux.setCameraUp(camera_name, tuple(up)),
-        lambda: lux.setCameraUp(tuple(up)),
-    )
+    if camera is not None:
+        # Object-level API is available: drive the camera object directly.
+        call_variants("set camera position", lambda: camera.setPosition(tuple(position)))
+        call_variants("set camera look-at", lambda: camera.setLookAt(tuple(look_at)))
+        call_variants("set camera up", lambda: camera.setUp(tuple(up)))
+    else:
+        # No camera object could be obtained: fall back to the lux-level setters,
+        # which address the camera by name. This path never dereferences a None
+        # camera object, so it cannot crash when camera creation is unsupported.
+        call_variants(
+            "set camera position",
+            lambda: lux.setCameraPosition(pos=tuple(position)),
+            lambda: lux.setCameraPosition(tuple(position)),
+            lambda: lux.setCameraPosition(camera_name, tuple(position)),
+        )
+        call_variants(
+            "set camera look-at",
+            lambda: lux.setCameraLookAt(pt=tuple(look_at)),
+            lambda: lux.setCameraLookAt(0, tuple(look_at)),
+            lambda: lux.setCameraLookAt(camera_name, tuple(look_at)),
+        )
+        call_variants(
+            "set camera up",
+            lambda: lux.setCameraUp(up=tuple(up)),
+            lambda: lux.setCameraUp(tuple(up)),
+            lambda: lux.setCameraUp(camera_name, tuple(up)),
+        )
 
     save_to(output_scene_path)
     output_files.append(output_scene_path)
@@ -386,13 +479,13 @@ def save_to(output_scene_path):
 
 
 def call_variants(label, *callbacks):
+    """Try each callback in order. The first one that does not raise wins, even
+    if it returns None (KeyShot setters typically return nothing). Only if every
+    callback raises do we report the combined errors."""
     errors = []
     for callback in callbacks:
         try:
-            value = callback()
-            if value is not None:
-                return value
-            return value
+            return callback()
         except Exception as exc:
             errors.append(str(exc))
     raise RuntimeError("%s is unsupported or failed: %s" % (label, " | ".join(errors)))
@@ -407,6 +500,62 @@ def first_success(*callbacks, default=None):
     return default
 
 
+def first_non_none(*callbacks, default=None):
+    for callback in callbacks:
+        try:
+            value = callback()
+            if value is not None:
+                return value
+        except Exception:
+            pass
+    return default
+
+
+def first_camera_object(*callbacks):
+    for callback in callbacks:
+        try:
+            value = callback()
+            if is_camera_object(value):
+                return value
+        except Exception:
+            pass
+    return None
+
+
+def is_camera_object(value):
+    if value is None or value is False or value is True:
+        return False
+    return any(hasattr(value, method) for method in ("setPosition", "setLookAt", "setUp"))
+
+
+def build_render_options(samples, max_time):
+    if samples is None and max_time is None:
+        return None
+
+    get_options = getattr(lux, "getRenderOptions", None)
+    if get_options is None:
+        raise RuntimeError("KeyShot lux.getRenderOptions is not available for advanced render settings.")
+
+    options = get_options()
+    if options is None:
+        raise RuntimeError("KeyShot returned no RenderOptions object for advanced render settings.")
+
+    if samples is not None:
+        call_variants(
+            "set render samples",
+            lambda: options.setMaxSamplesRendering(samples),
+            lambda: options.setAdvancedRendering(samples),
+        )
+
+    if max_time is not None:
+        call_variants(
+            "set render max time",
+            lambda: options.setMaxTimeRendering(max_time),
+        )
+
+    return options
+
+
 def serialize_value(value):
     if value is None or isinstance(value, (str, int, float, bool)):
         return value

package/server.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.truman-t3/keyshot-mcp",
+  "title": "KeyShot MCP",
+  "description": "Control KeyShot Studio through local headless scripting with MCP.",
+  "websiteUrl": "https://github.com/truman-t3/keyshot-mcp",
+  "repository": {
+    "id": "1290741614",
+    "url": "https://github.com/truman-t3/keyshot-mcp",
+    "source": "github"
+  },
+  "version": "0.4.2",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "keyshot-mcp",
+      "version": "0.4.2",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "KEYSHOT_HEADLESS_EXE",
+          "description": "Absolute path to KeyShot headless, or a command available on PATH.",
+          "isRequired": true,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}