keyshot-mcp 0.4.2 → 0.5.0

package/README.md

@@ -28,6 +28,7 @@ This project does not include KeyShot, does not bypass licensing, and does not s
 - Inspect a `.bip` or supported KeyShot scene file.
 - Render a scene to an image.
 - Batch render multiple named cameras from one scene.
+- Automatically discover and render every camera in one scene.
 - Import a model into a scene.
 - Apply a material to an object.
 - Create or update a camera.
@@ -67,7 +68,7 @@ This project does not include KeyShot, does not bypass licensing, and does not s
 npm install -g keyshot-mcp
 ```
 
-The current release line is `0.4.2`. The published package is the easiest option
+The current release line is `0.5.0`. The published package is the easiest option
 when you only want to use the MCP server. You still need KeyShot Studio and a
 local KeyShot license.
 
@@ -91,7 +92,7 @@ Use exactly one of these approaches:
 **No installation, run with npx**:
 
 ```json
-{"mcpServers":{"keyshot":{"command":"npx","args":["-y","keyshot-mcp@0.4.2"],"env":{"KEYSHOT_HEADLESS_EXE":"/absolute/path/to/keyshot_headless"}}}}
+{"mcpServers":{"keyshot":{"command":"npx","args":["-y","keyshot-mcp@0.5.0"],"env":{"KEYSHOT_HEADLESS_EXE":"/absolute/path/to/keyshot_headless"}}}}
 ```
 
 **Run from a cloned source directory** (after `npm install && npm run build`):
@@ -105,11 +106,11 @@ Use exactly one of these approaches:
 If you use Codex or another coding agent, you can copy this prompt and let the agent install the MCP server for you:
 
 ```text
-Install KeyShot MCP 0.4.2 from npm and configure it in my MCP client.
+Install KeyShot MCP 0.5.0 from npm and configure it in my MCP client.
 
 Please:
 1. Find my KeyShot headless executable path.
-2. Add a keyshot MCP server using npx -y keyshot-mcp@0.4.2.
+2. Add a keyshot MCP server using npx -y keyshot-mcp@0.5.0.
 3. Set KEYSHOT_HEADLESS_EXE to the detected keyshot_headless path.
 4. Test the setup by running the keyshot_status tool.
 5. Tell me the exact config that was added and whether the status check passed.
@@ -202,6 +203,11 @@ List the cameras in this KeyShot scene, create or update a camera named "Hero",
 save the scene to a new file, and render one preview from that camera.
 ```
 
+```text
+Find every camera in this KeyShot scene and render all views to the all-cameras
+output folder. Continue if one camera fails and report the result for each view.
+```
+
 ## Environment Variables
 
 - `KEYSHOT_HEADLESS_EXE`: path to `keyshot_headless` or `keyshot_headless.exe`.
@@ -224,6 +230,7 @@ or the other, not both.
 - `keyshot_list_cameras`: list available camera names in a scene (handy before batch rendering)
 - `keyshot_render`: render a single image
 - `keyshot_batch_render`
+- `keyshot_render_all_cameras`: discover and render every camera in a scene; continues after individual failures by default
 - `keyshot_render_queue`: run several render jobs sequentially (stops at first failure unless `continueOnError`)
 - `keyshot_import_model`
 - `keyshot_apply_material`
@@ -233,6 +240,15 @@ or the other, not both.
 - `keyshot_set_environment`
 - `keyshot_save_scene`
 
+### Render every camera automatically
+
+`keyshot_render_all_cameras` discovers camera names from the open scene and renders
+them in one KeyShot headless session. `continueOnError` defaults to `true`, so a
+failed camera is reported without blocking the remaining views. Safe duplicate
+filenames receive `-2`, `-3`, and later suffixes. Existing files are preserved
+unless `overwrite` is set to `true`. KeyShot's internal, non-activatable
+`last_active` placeholder is reported and skipped.
+
 ### Material preset library
 
 `keyshot_apply_material_preset` reads a small JSON registry so you can reuse named
@@ -269,7 +285,7 @@ KeyShot's Python `lux` API changes across versions. This server keeps the MCP in
 
 ## Roadmap
 
-- [ ] Auto-discover and batch render all cameras in a scene
+- [x] Auto-discover and batch render all cameras in a scene
 - [x] Material preset library
 - [ ] Camera preset templates
 - [x] Sequential render queue
@@ -283,7 +299,7 @@ KeyShot's Python `lux` API changes across versions. This server keeps the MCP in
 ![KeyShot MCP generated cube demo](assets/demo/keyshot-mcp-demo.png)
 
 The demo uses only the generated geometry in `examples/demo`. To reproduce the
-status, import, inspect, camera, save, and PNG-render workflow locally:
+status, import, inspect, two-camera creation, save, discovery, and PNG-render workflow locally:
 
 ```bash
 npm run smoke:keyshot
@@ -321,6 +337,7 @@ MIT
 - 检查 `.bip` 或 KeyShot 支持的场景文件。
 - 把场景渲染成图片。
 - 从同一个场景批量渲染多个指定相机。
+- 自动发现并渲染场景中的全部相机。
 - 把模型导入场景。
 - 给对象替换材质。
 - 创建或更新相机。
@@ -360,7 +377,7 @@ MIT
 npm install -g keyshot-mcp
 ```
 
-当前发布版本为 `0.4.2`。如果你只是想使用 MCP 服务，直接安装 npm 包最简单。
+当前发布版本为 `0.5.0`。如果你只是想使用 MCP 服务，直接安装 npm 包最简单。
 电脑仍需要安装 KeyShot Studio，并且已经配置好本地 KeyShot 授权。
 
 ### 从源码安装
@@ -383,7 +400,7 @@ npm run build
 **免安装，直接使用 npx**：
 
 ```json
-{"mcpServers":{"keyshot":{"command":"npx","args":["-y","keyshot-mcp@0.4.2"],"env":{"KEYSHOT_HEADLESS_EXE":"C:/KeyShot/bin/keyshot_headless.exe"}}}}
+{"mcpServers":{"keyshot":{"command":"npx","args":["-y","keyshot-mcp@0.5.0"],"env":{"KEYSHOT_HEADLESS_EXE":"C:/KeyShot/bin/keyshot_headless.exe"}}}}
 ```
 
 **使用本地源码**（先运行 `npm install && npm run build`）：
@@ -397,11 +414,11 @@ npm run build
 如果你使用 Codex 或其他编程 Agent，可以复制下面这段话，让 Agent 帮你安装和配置 MCP：
 
 ```text
-请帮我安装 KeyShot MCP 0.4.2，并添加到我的 MCP 客户端。
+请帮我安装 KeyShot MCP 0.5.0，并添加到我的 MCP 客户端。
 
 请你：
 1. 查找我电脑上的 KeyShot headless 可执行文件路径。
-2. 使用 npx -y keyshot-mcp@0.4.2 添加 keyshot MCP server。
+2. 使用 npx -y keyshot-mcp@0.5.0 添加 keyshot MCP server。
 3. 把 KEYSHOT_HEADLESS_EXE 设置为检测到的 keyshot_headless 路径。
 4. 用 keyshot_status 工具测试是否配置成功。
 5. 最后告诉我实际添加的配置，以及状态检查是否通过。
@@ -494,6 +511,11 @@ examples/codex.example.json
 把场景保存为新文件，并用这个相机渲染一张预览图。
 ```
 
+```text
+自动找出这个 KeyShot 场景里的全部相机，把所有视角渲染到 all-cameras 文件夹。
+某个相机失败时继续处理其他相机，最后告诉我每个视角的结果。
+```
+
 ## 环境变量
 
 - `KEYSHOT_HEADLESS_EXE`：`keyshot_headless` 或 `keyshot_headless.exe` 的路径。
@@ -515,6 +537,7 @@ examples/codex.example.json
 - `keyshot_list_cameras`：列出场景中所有相机名称（批量渲染前很有用）。
 - `keyshot_render`：渲染单张图片。
 - `keyshot_batch_render`：批量渲染多个相机视角。
+- `keyshot_render_all_cameras`：自动发现并渲染场景中的全部相机，默认单个视角失败后继续。
 - `keyshot_render_queue`：顺序执行多个渲染任务（默认遇错即停，设置 `continueOnError` 可继续）。
 - `keyshot_import_model`：导入模型。
 - `keyshot_apply_material`：替换材质。
@@ -524,6 +547,13 @@ examples/codex.example.json
 - `keyshot_set_environment`：设置环境。
 - `keyshot_save_scene`：保存场景。
 
+### 自动渲染全部相机
+
+`keyshot_render_all_cameras` 会在同一次 KeyShot 无界面运行中自动读取场景相机并逐个渲染。
+`continueOnError` 默认是 `true`，因此单个相机失败不会阻止其他视角；同名安全文件会自动添加
+`-2`、`-3` 等编号。除非设置 `overwrite: true`，否则不会覆盖已有图片。KeyShot 内部不能激活的
+`last_active` 占位项会被列出并跳过。
+
 ### 材质预设库
 
 `keyshot_apply_material_preset` 会读取一个小的 JSON 注册表，让你用"好记的名字"复用材质，
@@ -559,7 +589,7 @@ KeyShot 的 Python `lux` API 会随版本变化。这个 MCP 会尽量保持对
 
 ## 路线图
 
-- [ ] 自动发现并批量渲染场景中的所有相机
+- [x] 自动发现并批量渲染场景中的所有相机
 - [x] 材质预设库
 - [ ] 相机预设模板
 - [x] 顺序渲染队列
@@ -573,7 +603,7 @@ KeyShot 的 Python `lux` API 会随版本变化。这个 MCP 会尽量保持对
 ![KeyShot MCP 自动生成的立方体 Demo](assets/demo/keyshot-mcp-demo.png)
 
 Demo 只使用 `examples/demo` 中项目自己生成的几何体，不包含客户模型或第三方素材。
-设置好 `KEYSHOT_HEADLESS_EXE` 后可复现状态检查、导入、检查场景、创建相机、保存和真实 PNG 渲染：
+设置好 `KEYSHOT_HEADLESS_EXE` 后可复现状态检查、导入、检查场景、创建两个相机、自动发现、保存和真实 PNG 渲染：
 
 ```bash
 npm run smoke:keyshot

package/dist/index.js

@@ -7,7 +7,7 @@ import { runKeyShotSerialized } from "./runner.js";
 import { runRenderQueue } from "./queue.js";
 import { loadMaterialPresets, findMaterialPreset } from "./presets.js";
 import { VERSION } from "./version.js";
-import { applyMaterialSchema, applyMaterialInputSchema, applyMaterialPresetInputSchema, applyMaterialPresetSchema, batchRenderSchema, batchRenderInputSchema, importModelSchema, listCamerasSchema, listMaterialPresetsSchema, renderQueueSchema, renderQueueInputSchema, renderSchema, renderInputSchema, saveSceneSchema, scenePathSchema, setCameraSchema, setEnvironmentSchema, } from "./schemas.js";
+import { applyMaterialSchema, applyMaterialInputSchema, applyMaterialPresetInputSchema, applyMaterialPresetSchema, batchRenderSchema, batchRenderInputSchema, importModelSchema, listCamerasSchema, listMaterialPresetsSchema, renderQueueSchema, renderQueueInputSchema, renderAllCamerasSchema, renderAllCamerasInputSchema, renderSchema, renderInputSchema, saveSceneSchema, scenePathSchema, setCameraSchema, setEnvironmentSchema, } from "./schemas.js";
 const config = getConfig();
 const server = new McpServer({
     name: "keyshot-mcp",
@@ -72,6 +72,10 @@ server.tool("keyshot_batch_render", "Render multiple named cameras from one KeyS
     const parsed = batchRenderInputSchema.parse(args);
     return toolResponse(await runKeyShotSerialized(config, { operation: "batch_render", ...parsed }));
 });
+server.tool("keyshot_render_all_cameras", "Discover every camera in one KeyShot scene and render each view into an output directory.", renderAllCamerasSchema.shape, async (args) => {
+    const parsed = renderAllCamerasInputSchema.parse(args);
+    return toolResponse(await runKeyShotSerialized(config, { operation: "render_all_cameras", ...parsed }));
+});
 server.tool("keyshot_import_model", "Import a model into an optional base scene and save the resulting scene.", importModelSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, {
     operation: "import_model",
     ...args,

package/dist/schemas.js

@@ -36,6 +36,21 @@ export const batchRenderInputSchema = batchRenderSchema.refine((value) => !(valu
     message: "Choose either samples or maxTimeSeconds, not both.",
     path: ["maxTimeSeconds"],
 });
+export const renderAllCamerasSchema = z.object({
+    scenePath: z.string().min(1),
+    outputDir: z.string().min(1),
+    width: z.number().int().positive().optional(),
+    height: z.number().int().positive().optional(),
+    samples: z.number().int().positive().optional(),
+    maxTimeSeconds: z.number().positive().optional(),
+    format: imageFormat.optional(),
+    overwrite: z.boolean().optional(),
+    continueOnError: z.boolean().default(true),
+});
+export const renderAllCamerasInputSchema = renderAllCamerasSchema.refine((value) => !(value.samples !== undefined && value.maxTimeSeconds !== undefined), {
+    message: "Choose either samples or maxTimeSeconds, not both.",
+    path: ["maxTimeSeconds"],
+});
 export const importModelSchema = z.object({
     modelPath: z.string().min(1),
     baseScenePath: optionalPath,

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.4.2";
+export const VERSION = "0.5.0";

package/examples/demo/README.md

@@ -4,6 +4,7 @@
 repository's MIT license. It contains no customer model or third-party asset.
 
 Run `npm run smoke:keyshot` after setting `KEYSHOT_HEADLESS_EXE`. The command
-checks KeyShot, imports the cube, saves and inspects the scene, creates an MCP
-camera, and renders `outputs/demo/keyshot-mcp-demo.png`. Generated `.bip` files
-remain under `outputs/` and are ignored by Git.
+checks KeyShot, imports the cube, saves and inspects the scene, creates two MCP
+cameras, automatically discovers them, and renders both views under
+`outputs/demo/all-cameras`. Generated `.bip` and PNG files remain under
+`outputs/` and are ignored by Git.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyshot-mcp",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "mcpName": "io.github.truman-t3/keyshot-mcp",
   "description": "Local and portable MCP server for KeyShot headless scripting.",
   "type": "module",

package/scripts/keyshot-smoke.mjs

@@ -1,3 +1,5 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getConfig } from "../dist/config.js";
@@ -18,8 +20,8 @@ async function run(label, request) {
   return result;
 }
 
-const status = await run("1/5 KeyShot status", { operation: "status" });
-const imported = await run("2/5 Import and save generated OBJ", {
+const status = await run("1/7 KeyShot status", { operation: "status" });
+const imported = await run("2/7 Import and save generated OBJ", {
   operation: "import_model",
   modelPath,
   outputScenePath: "demo/keyshot-mcp-demo-import.bip",
@@ -27,7 +29,7 @@ const imported = await run("2/5 Import and save generated OBJ", {
 const importedScene = imported.outputFiles[0];
 if (!importedScene) throw new Error("Import did not return a saved scene path.");
 
-const inspected = await run("3/5 Inspect imported scene", {
+const inspected = await run("3/7 Inspect imported scene", {
   operation: "inspect_scene",
   scenePath: importedScene,
 });
@@ -36,32 +38,70 @@ if (!Array.isArray(objects) || objects.length === 0) {
   throw new Error("Imported scene did not contain any inspectable objects.");
 }
 
-const cameraSceneResult = await run("4/5 Create camera and save scene", {
+const firstCameraResult = await run("4/7 Create first camera and save scene", {
   operation: "set_camera",
   scenePath: importedScene,
-  cameraName: "MCP Demo",
+  cameraName: "MCP Front",
   position: [4.5, 3.5, 4.5],
   lookAt: [0, 0, 0],
   up: [0, 1, 0],
-  outputScenePath: "demo/keyshot-mcp-demo-camera.bip",
+  outputScenePath: "demo/keyshot-mcp-demo-camera-front.bip",
 });
-const cameraScene = cameraSceneResult.outputFiles[0];
-if (!cameraScene) throw new Error("Camera operation did not return a saved scene path.");
+const firstCameraScene = firstCameraResult.outputFiles[0];
+if (!firstCameraScene) throw new Error("First camera operation did not return a saved scene path.");
 
-const rendered = await run("5/5 Render real PNG", {
-  operation: "render",
+const secondCameraResult = await run("5/7 Create second camera and save scene", {
+  operation: "set_camera",
+  scenePath: firstCameraScene,
+  cameraName: "MCP Angle",
+  position: [6.0, 2.5, 3.0],
+  lookAt: [0, 0, 0],
+  up: [0, 1, 0],
+  outputScenePath: "demo/keyshot-mcp-demo-camera-all.bip",
+});
+const cameraScene = secondCameraResult.outputFiles[0];
+if (!cameraScene) throw new Error("Second camera operation did not return a saved scene path.");
+
+const rendered = await run("6/7 Discover and render every camera", {
+  operation: "render_all_cameras",
   scenePath: cameraScene,
-  camera: "MCP Demo",
-  outputPath: "demo/keyshot-mcp-demo.png",
+  outputDir: "demo/all-cameras",
   width: 640,
   height: 480,
   maxTimeSeconds: 8,
   format: "png",
+  overwrite: true,
+  continueOnError: true,
 });
 
+const renderData = rendered.data;
+if (!renderData || renderData.failed !== 0 || renderData.succeeded < 2) {
+  throw new Error("All-camera render did not produce at least two successful camera views.");
+}
+
+const namedResults = renderData.results.filter(
+  (entry) => entry.camera === "MCP Front" || entry.camera === "MCP Angle",
+);
+if (namedResults.length !== 2 || namedResults.some((entry) => !entry.ok)) {
+  throw new Error("The two MCP demo cameras were not both rendered successfully.");
+}
+const hashes = await Promise.all(namedResults.map(async (entry) =>
+  crypto.createHash("sha256").update(await fs.readFile(entry.outputPath)).digest("hex")
+));
+if (hashes[0] === hashes[1]) {
+  throw new Error("The two demo camera renders are identical; expected different viewpoints.");
+}
+const minimumSizes = await Promise.all(namedResults.map(async (entry) => (await fs.stat(entry.outputPath)).size));
+if (minimumSizes.some((size) => size < 10000)) {
+  throw new Error("A demo camera render is unexpectedly small and may be blank.");
+}
+process.stdout.write("7/7 Verify two different camera images... ok\n");
+
 console.log(JSON.stringify({
   keyshotVersion: status.data?.version ?? null,
   objectCount: objects.length,
   scenePath: cameraScene,
-  imagePath: rendered.outputFiles[0] ?? null,
+  cameraCount: renderData.total,
+  renderedImages: rendered.outputFiles,
+  verifiedCameras: namedResults.map((entry) => entry.camera),
 }, null, 2));

package/scripts/keyshot_bridge.py

@@ -37,6 +37,8 @@ def main():
             data = render(payload, output_files, warnings)
         elif operation == "batch_render":
             data = batch_render(payload, output_files, warnings)
+        elif operation == "render_all_cameras":
+            data = render_all_cameras(payload, output_files, warnings)
         elif operation == "import_model":
             data = import_model(payload, output_files, warnings)
         elif operation == "apply_material":
@@ -50,7 +52,10 @@ def main():
         else:
             raise RuntimeError("Unsupported operation: %s" % operation)
 
-        write_result(result_path, True, data, output_files, warnings, None)
+        operation_error = None
+        if operation == "render_all_cameras" and data.get("failed", 0) > 0:
+            operation_error = "%s of %s camera render(s) failed." % (data["failed"], data["total"])
+        write_result(result_path, operation_error is None, data, output_files, warnings, operation_error)
     except Exception as exc:
         warnings.append(traceback.format_exc())
         write_result(result_path, False, None, output_files, warnings, str(exc))
@@ -99,6 +104,11 @@ def inspect_scene():
 
 
 def list_cameras():
+    names = camera_names()
+    return {"cameras": names, "count": len(names)}
+
+
+def camera_names():
     raw = safe_list_call("getCameras")
     names = []
     for camera in raw:
@@ -113,8 +123,8 @@ def list_cameras():
             )
         if name is None:
             name = repr(camera)
-        names.append(name)
-    return {"cameras": names, "count": len(names)}
+        names.append(str(name))
+    return names
 
 
 def render(payload, output_files, warnings):
@@ -214,6 +224,100 @@ def batch_render(payload, output_files, warnings):
     }
 
 
+def render_all_cameras(payload, output_files, warnings):
+    scene_path = payload.get("scenePath")
+    output_dir = payload.get("outputDir")
+    discovered_cameras = camera_names()
+    excluded_cameras = [name for name in discovered_cameras if name.lower() == "last_active"]
+    cameras = [name for name in discovered_cameras if name.lower() != "last_active"]
+    width = payload.get("width") or 1920
+    height = payload.get("height") or 1080
+    image_format = payload.get("format") or "png"
+    overwrite = bool(payload.get("overwrite", False))
+    continue_on_error = payload.get("continueOnError", True) is not False
+
+    if not scene_path:
+        raise RuntimeError("scenePath is required")
+    if not output_dir:
+        raise RuntimeError("outputDir is required")
+    if not cameras:
+        raise RuntimeError("No cameras were found in the scene.")
+
+    if excluded_cameras:
+        warnings.append("Skipped KeyShot internal camera placeholder(s): %s" % ", ".join(excluded_cameras))
+
+    os.makedirs(output_dir, exist_ok=True)
+    results = []
+    used_stems = set()
+    stopped = False
+
+    for index, camera in enumerate(cameras):
+        output_path = unique_camera_output_path(output_dir, camera, image_format, used_stems)
+        if stopped:
+            results.append(camera_render_result(index, camera, output_path, False, None, True))
+            continue
+
+        try:
+            if os.path.exists(output_path) and not overwrite:
+                raise RuntimeError("Output already exists and overwrite is false: %s" % output_path)
+
+            render_payload = dict(payload)
+            render_payload["camera"] = camera
+            render_payload["outputPath"] = output_path
+            render_payload["width"] = width
+            render_payload["height"] = height
+            render_payload["format"] = image_format
+            rendered = render(render_payload, output_files, warnings)
+            results.append(camera_render_result(index, camera, rendered.get("rendered"), True, None, False))
+        except Exception as exc:
+            error = str(exc)
+            warnings.append("Camera %s (%s) failed: %s" % (index, camera, error))
+            results.append(camera_render_result(index, camera, output_path, False, error, False))
+            if not continue_on_error:
+                stopped = True
+
+    succeeded = len([item for item in results if item["ok"]])
+    failed = len([item for item in results if not item["ok"] and not item["skipped"]])
+    skipped = len([item for item in results if item["skipped"]])
+    return {
+        "scenePath": scene_path,
+        "outputDir": output_dir,
+        "cameras": cameras,
+        "excludedCameras": excluded_cameras,
+        "total": len(cameras),
+        "succeeded": succeeded,
+        "failed": failed,
+        "skipped": skipped,
+        "continueOnError": continue_on_error,
+        "results": results,
+        "width": width,
+        "height": height,
+        "format": image_format,
+    }
+
+
+def camera_render_result(index, camera, output_path, ok, error, skipped):
+    return {
+        "index": index,
+        "camera": camera,
+        "outputPath": output_path,
+        "ok": ok,
+        "error": error,
+        "skipped": skipped,
+    }
+
+
+def unique_camera_output_path(output_dir, camera, image_format, used_stems):
+    base = safe_filename(camera)
+    stem = base
+    suffix = 2
+    while stem.lower() in used_stems:
+        stem = "%s-%s" % (base, suffix)
+        suffix += 1
+    used_stems.add(stem.lower())
+    return os.path.join(output_dir, "%s.%s" % (stem, image_format))
+
+
 def import_model(payload, output_files, warnings):
     model_path = payload.get("modelPath")
     output_scene_path = payload.get("outputScenePath")
@@ -298,6 +402,7 @@ def set_camera(payload, output_files, warnings):
 
     if position is None or look_at is None:
         raise RuntimeError("position and lookAt are required")
+    direction = tuple(look_at[index] - position[index] for index in range(3))
 
     camera = first_camera_object(
         lambda: lux.getCamera(camera_name),
@@ -305,47 +410,53 @@ def set_camera(payload, output_files, warnings):
         lambda: lux.createCamera(camera_name),
     )
 
-    if camera is None and hasattr(lux, "saveCamera"):
-        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
-
     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 position", lambda: camera.setPosition(tuple(position)))
+        if hasattr(camera, "setDirection"):
+            call_variants("set camera direction", lambda: camera.setDirection(direction))
         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)),
-        )
+        # which operate on the active camera. Existing named cameras are activated
+        # first. Missing cameras are saved under their new name after the transform
+        # is set; saveCamera is a snapshot operation, not a camera constructor.
+        if camera_name in camera_names() and hasattr(lux, "setCamera"):
+            call_variants("activate camera", lambda: lux.setCamera(camera_name))
         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 position",
+            lambda: lux.setCameraPosition(pos=tuple(position)),
+            lambda: lux.setCameraPosition(tuple(position)),
+            lambda: lux.setCameraPosition(camera_name, tuple(position)),
+        )
+        if hasattr(lux, "setCameraDirection"):
+            call_variants(
+                "set camera direction",
+                lambda: lux.setCameraDirection(dir=direction),
+                lambda: lux.setCameraDirection(direction),
+            )
         call_variants(
             "set camera up",
             lambda: lux.setCameraUp(up=tuple(up)),
             lambda: lux.setCameraUp(tuple(up)),
             lambda: lux.setCameraUp(camera_name, tuple(up)),
         )
+        if hasattr(lux, "saveCamera"):
+            try:
+                call_variants(
+                    "save named camera",
+                    lambda: lux.saveCamera(),
+                    lambda: lux.saveCamera(camera_name),
+                )
+            except RuntimeError:
+                warnings.append("The active camera was updated, but this KeyShot version could not save the named view.")
 
     save_to(output_scene_path)
     output_files.append(output_scene_path)

package/server.json

@@ -9,12 +9,12 @@
     "url": "https://github.com/truman-t3/keyshot-mcp",
     "source": "github"
   },
-  "version": "0.4.2",
+  "version": "0.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "keyshot-mcp",
-      "version": "0.4.2",
+      "version": "0.5.0",
       "transport": {
         "type": "stdio"
       },