keyshot-mcp 0.2.1 → 0.4.1

package/README.md

@@ -61,6 +61,18 @@ This project does not include KeyShot, does not bypass licensing, and does not s
 
 ## Install
 
+### Install the published npm package
+
+```bash
+npm install -g keyshot-mcp
+```
+
+The current release line is `0.4.1`. 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.
+
+### Install from source
+
 ```bash
 npm install
 npm run build
@@ -165,6 +177,11 @@ Import the model file at /path/to/model.step, apply a brushed metal material to
 Inspect this KeyShot scene and summarize the available objects, cameras, materials, and renderable outputs.
 ```
 
+```text
+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.
+```
+
 ## Environment Variables
 
 - `KEYSHOT_HEADLESS_EXE`: path to `keyshot_headless` or `keyshot_headless.exe`.
@@ -172,18 +189,41 @@ Inspect this KeyShot scene and summarize the available objects, cameras, materia
 - `KEYSHOT_LICENSE_ARGS`: optional KeyShot headless license arguments. Empty by default.
 - `KEYSHOT_TIMEOUT_MS`: operation timeout in milliseconds. Default: `600000`.
 
+`samples` and `maxTimeSeconds` select different KeyShot render modes. Provide one
+or the other, not both.
+
 ## MCP Tools
 
 - `keyshot_status`
 - `keyshot_inspect_scene`
+- `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_queue`: run several render jobs sequentially (stops at first failure unless `continueOnError`)
 - `keyshot_import_model`
 - `keyshot_apply_material`
+- `keyshot_list_material_presets`: list presets from the material preset library
+- `keyshot_apply_material_preset`: apply a named preset from the library to an object
 - `keyshot_set_camera`
 - `keyshot_set_environment`
 - `keyshot_save_scene`
 
+### Material preset library
+
+`keyshot_apply_material_preset` reads a small JSON registry so you can reuse named
+looks instead of remembering exact KeyShot material names. Default location:
+`presets/materials.json` (override with the `KEYSHOT_MATERIAL_PRESETS` env var).
+
+```json
+{
+  "Brushed Steel": { "materialName": "Steel Brushed", "description": "metal parts" },
+  "Clear Glass": { "materialPath": "C:/materials/glass_clear.mtl" }
+}
+```
+
+Each preset must have a `materialName` or a `materialPath`. Use
+`keyshot_list_material_presets` to see what is available.
+
 ## MCP Prompts and Resources
 
 - Prompt: `keyshot_product_render`
@@ -205,13 +245,13 @@ 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
-- [ ] Material preset library
+- [x] Material preset library
 - [ ] Camera preset templates
-- [ ] Render queue status
+- [x] Sequential render queue
 - [ ] Safer output directory restrictions
 - [ ] More tested KeyShot versions
 - [ ] macOS compatibility verification
-- [ ] Claude Desktop / Cursor / Codex config examples
+- [x] Claude Desktop / Cursor / Codex config examples
 
 ## License
 
@@ -278,6 +318,17 @@ MIT
 
 ## 安装
 
+### 安装已发布的 npm 包
+
+```bash
+npm install -g keyshot-mcp
+```
+
+当前发布版本为 `0.4.1`。如果你只是想使用 MCP 服务，直接安装 npm 包最简单。
+电脑仍需要安装 KeyShot Studio，并且已经配置好本地 KeyShot 授权。
+
+### 从源码安装
+
 ```bash
 npm install
 npm run build
@@ -382,25 +433,52 @@ examples/codex.example.json
 检查当前 KeyShot 场景，并总结场景中的对象、相机、材质和可渲染输出。
 ```
 
+```text
+列出当前 KeyShot 场景中的相机，创建或更新一个名为“Hero”的相机，
+把场景保存为新文件，并用这个相机渲染一张预览图。
+```
+
 ## 环境变量
 
 - `KEYSHOT_HEADLESS_EXE`：`keyshot_headless` 或 `keyshot_headless.exe` 的路径。
 - `KEYSHOT_OUTPUT_DIR`：默认渲染输出文件夹。
 - `KEYSHOT_LICENSE_ARGS`：可选的 KeyShot 无界面许可证参数，默认留空。
 - `KEYSHOT_TIMEOUT_MS`：单次操作超时时间，单位毫秒，默认 `600000`。
+- `KEYSHOT_MATERIAL_PRESETS`：材质预设库 JSON 文件路径，默认 `presets/materials.json`。
+
+`samples` 和 `maxTimeSeconds` 是两种不同的 KeyShot 渲染模式，请二选一，不要同时传入。
 
 ## MCP 工具
 
 - `keyshot_status`：检查 KeyShot 是否能启动。
 - `keyshot_inspect_scene`：检查场景内容。
+- `keyshot_list_cameras`：列出场景中所有相机名称（批量渲染前很有用）。
 - `keyshot_render`：渲染单张图片。
 - `keyshot_batch_render`：批量渲染多个相机视角。
+- `keyshot_render_queue`：顺序执行多个渲染任务（默认遇错即停，设置 `continueOnError` 可继续）。
 - `keyshot_import_model`：导入模型。
 - `keyshot_apply_material`：替换材质。
+- `keyshot_list_material_presets`：列出材质预设库中的预设。
+- `keyshot_apply_material_preset`：把预设库中的某个命名材质应用到物体上。
 - `keyshot_set_camera`：设置相机。
 - `keyshot_set_environment`：设置环境。
 - `keyshot_save_scene`：保存场景。
 
+### 材质预设库
+
+`keyshot_apply_material_preset` 会读取一个小的 JSON 注册表，让你用"好记的名字"复用材质，
+而不必记住 KeyShot 里精确的材质名。默认位置：`presets/materials.json`
+（可用环境变量 `KEYSHOT_MATERIAL_PRESETS` 覆盖）。
+
+```json
+{
+  "拉丝钢": { "materialName": "Steel Brushed", "description": "金属件默认材质" },
+  "透明玻璃": { "materialPath": "C:/materials/glass_clear.mtl" }
+}
+```
+
+每个预设必须包含 `materialName` 或 `materialPath`。用 `keyshot_list_material_presets` 查看有哪些预设。
+
 ## MCP 提示词和资源
 
 - 提示词：`keyshot_product_render`
@@ -422,13 +500,30 @@ KeyShot 的 Python `lux` API 会随版本变化。这个 MCP 会尽量保持对
 ## 路线图
 
 - [ ] 自动发现并批量渲染场景中的所有相机
-- [ ] 材质预设库
+- [x] 材质预设库
 - [ ] 相机预设模板
-- [ ] 渲染队列状态
+- [x] 顺序渲染队列
 - [ ] 更安全的输出目录限制
 - [ ] 测试更多 KeyShot 版本
 - [ ] 验证 macOS 兼容性
-- [ ] 补充 Claude Desktop / Cursor / Codex 配置示例
+- [x] 补充 Claude Desktop / Cursor / Codex 配置示例
+
+## 测试
+
+项目带了两套测试，不依赖真实的 KeyShot 也能跑：
+
+- **TypeScript 测试（Vitest）**：覆盖配置读取、参数校验（schemas）、结果封装，以及用"假 KeyShot"跑通一次成功路径并验证 `work/tmp` 临时文件会被清理。
+
+  ```bash
+  npm install
+  npm test
+  ```
+
+- **Python bridge 测试（unittest）**：用假的 `lux` 对象验证 `import_model` 会真正打开基础场景、`set_camera` 在拿不到相机对象时不会崩溃并回退到 `lux` 级 API。
+
+  ```bash
+  python tests/test_bridge.py
+  ```
 
 ## 开源协议
 

package/dist/config.js

@@ -13,6 +13,7 @@ export function getConfig() {
         keyshotTimeoutMs: parsePositiveInt(process.env.KEYSHOT_TIMEOUT_MS, DEFAULT_TIMEOUT_MS),
         tmpDir: path.join(projectRoot, "work", "tmp"),
         bridgeScriptPath: path.join(projectRoot, "scripts", "keyshot_bridge.py"),
+        materialPresetsPath: path.resolve(process.env.KEYSHOT_MATERIAL_PRESETS ?? path.join(projectRoot, "presets", "materials.json")),
     };
 }
 function parsePositiveInt(value, fallback) {

package/dist/index.js

@@ -2,14 +2,19 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { getConfig } from "./config.js";
-import { toolResponse } from "./result.js";
+import { toolResponse, localFailure } from "./result.js";
 import { runKeyShotSerialized } from "./runner.js";
-import { applyMaterialSchema, applyMaterialInputSchema, batchRenderSchema, importModelSchema, renderSchema, saveSceneSchema, scenePathSchema, setCameraSchema, setEnvironmentSchema, } from "./schemas.js";
+import { runRenderQueue } from "./queue.js";
+import { loadMaterialPresets, findMaterialPreset } from "./presets.js";
+import { applyMaterialSchema, applyMaterialInputSchema, applyMaterialPresetInputSchema, applyMaterialPresetSchema, batchRenderSchema, batchRenderInputSchema, importModelSchema, listCamerasSchema, listMaterialPresetsSchema, renderQueueSchema, renderQueueInputSchema, renderSchema, renderInputSchema, saveSceneSchema, scenePathSchema, setCameraSchema, setEnvironmentSchema, } from "./schemas.js";
 const config = getConfig();
 const server = new McpServer({
     name: "keyshot-mcp",
-    version: "0.2.1",
+    version: "0.4.1",
 });
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 server.registerResource("keyshot-workflow", "keyshot://workflow", {
     title: "KeyShot MCP Workflow",
     description: "How this MCP server connects AI agents to KeyShot headless scripting.",
@@ -53,17 +58,67 @@ server.registerPrompt("keyshot_product_render", {
 }));
 server.tool("keyshot_status", "Check KeyShot headless availability and script startup.", {}, async () => toolResponse(await runKeyShotSerialized(config, { operation: "status" })));
 server.tool("keyshot_inspect_scene", "Open a KeyShot scene and return available objects, cameras, materials and scene metadata.", scenePathSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "inspect_scene", ...args })));
-server.tool("keyshot_render", "Render a KeyShot scene to an image file.", renderSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "render", ...args })));
-server.tool("keyshot_batch_render", "Render multiple named cameras from one KeyShot scene into an output directory.", batchRenderSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "batch_render", ...args })));
+server.tool("keyshot_list_cameras", "Open a KeyShot scene and return the list of available camera names (useful before batch rendering).", listCamerasSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "list_cameras", ...args })));
+server.tool("keyshot_render", "Render a KeyShot scene to an image file.", renderSchema.shape, async (args) => {
+    const parsed = renderInputSchema.parse(args);
+    return toolResponse(await runKeyShotSerialized(config, { operation: "render", ...parsed }));
+});
+server.tool("keyshot_render_queue", "Render several jobs sequentially. Stops at the first failure unless continueOnError is set.", renderQueueSchema.shape, async (args) => {
+    const parsed = renderQueueInputSchema.parse(args);
+    return toolResponse(await runRenderQueue(config, parsed.jobs, { continueOnError: parsed.continueOnError ?? false }));
+});
+server.tool("keyshot_batch_render", "Render multiple named cameras from one KeyShot scene into an output directory.", batchRenderSchema.shape, async (args) => {
+    const parsed = batchRenderInputSchema.parse(args);
+    return toolResponse(await runKeyShotSerialized(config, { operation: "batch_render", ...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",
-    scenePath: args.baseScenePath,
     ...args,
 })));
 server.tool("keyshot_apply_material", "Apply a material by name or material file to a scene object and save the resulting scene.", applyMaterialInputSchema.shape, async (args) => {
     const parsed = applyMaterialSchema.parse(args);
     return toolResponse(await runKeyShotSerialized(config, { operation: "apply_material", ...parsed }));
 });
+server.tool("keyshot_list_material_presets", "List material presets from the local preset library (presets/materials.json or KEYSHOT_MATERIAL_PRESETS).", listMaterialPresetsSchema.shape, async () => {
+    try {
+        const presets = await loadMaterialPresets(config);
+        return toolResponse({
+            ok: true,
+            data: { presets, count: presets.length, source: config.materialPresetsPath },
+            outputFiles: [],
+            warnings: presets.length === 0 ? ["No material presets found. Create presets/materials.json to add some."] : [],
+            keyshotStdoutTail: "",
+            error: null,
+        });
+    }
+    catch (error) {
+        return toolResponse(localFailure(errorMessage(error)));
+    }
+});
+server.tool("keyshot_apply_material_preset", "Apply a named material preset (from the preset library) to a scene object and save the resulting scene.", applyMaterialPresetInputSchema.shape, async (args) => {
+    const parsed = applyMaterialPresetSchema.parse(args);
+    let presets;
+    try {
+        presets = await loadMaterialPresets(config);
+    }
+    catch (error) {
+        return toolResponse(localFailure(errorMessage(error)));
+    }
+    const preset = findMaterialPreset(presets, parsed.presetName);
+    if (!preset) {
+        const available = presets.map((entry) => entry.name).join(", ") || "(none)";
+        return toolResponse(localFailure(`Material preset not found: "${parsed.presetName}". Available: ${available}`));
+    }
+    return toolResponse(await runKeyShotSerialized(config, {
+        operation: "apply_material",
+        scenePath: parsed.scenePath,
+        objectName: parsed.objectName,
+        objectPath: parsed.objectPath,
+        materialName: preset.materialName,
+        materialPath: preset.materialPath,
+        outputScenePath: parsed.outputScenePath,
+    }));
+});
 server.tool("keyshot_set_camera", "Create or update a camera from position/look-at vectors and save the resulting scene.", setCameraSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "set_camera", ...args })));
 server.tool("keyshot_set_environment", "Set a scene environment by name or file when supported by KeyShot headless scripting.", setEnvironmentSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "set_environment", ...args })));
 server.tool("keyshot_save_scene", "Save a KeyShot scene to a new path.", saveSceneSchema.shape, async (args) => toolResponse(await runKeyShotSerialized(config, { operation: "save_scene", ...args })));

package/dist/presets.js

@@ -0,0 +1,67 @@
+import fs from "node:fs/promises";
+/**
+ * Load the material preset library from disk.
+ *
+ * The registry file (see config.materialPresetsPath, overridable with the
+ * KEYSHOT_MATERIAL_PRESETS env var) may use either of two shapes:
+ *
+ *   1. Object keyed by preset name:
+ *      { "Brushed Steel": { "materialName": "Steel Brushed", "description": "..." } }
+ *
+ *   2. Array of presets:
+ *      [ { "name": "Brushed Steel", "materialName": "Steel Brushed" } ]
+ *
+ * A missing file is treated as an empty library (not an error), so the feature
+ * works out of the box before the user creates any presets.
+ */
+export async function loadMaterialPresets(config) {
+    let raw;
+    try {
+        raw = await fs.readFile(config.materialPresetsPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Material presets file is not valid JSON: ${config.materialPresetsPath}`);
+    }
+    return normalizePresets(parsed);
+}
+export function normalizePresets(parsed) {
+    const entries = [];
+    if (Array.isArray(parsed)) {
+        for (const item of parsed) {
+            if (item && typeof item === "object") {
+                const record = item;
+                const name = typeof record.name === "string" ? record.name : undefined;
+                if (name)
+                    entries.push(toPreset(name, record));
+            }
+        }
+    }
+    else if (parsed && typeof parsed === "object") {
+        for (const [name, value] of Object.entries(parsed)) {
+            if (value && typeof value === "object") {
+                entries.push(toPreset(name, value));
+            }
+        }
+    }
+    return entries.filter((preset) => preset.materialName || preset.materialPath);
+}
+function toPreset(name, record) {
+    return {
+        name,
+        materialName: typeof record.materialName === "string" ? record.materialName : undefined,
+        materialPath: typeof record.materialPath === "string" ? record.materialPath : undefined,
+        description: typeof record.description === "string" ? record.description : undefined,
+    };
+}
+export function findMaterialPreset(presets, name) {
+    const lower = name.toLowerCase();
+    return (presets.find((preset) => preset.name === name) ??
+        presets.find((preset) => preset.name.toLowerCase() === lower));
+}

package/dist/queue.js

@@ -0,0 +1,70 @@
+import { runKeyShotSerialized } from "./runner.js";
+/**
+ * Run several render jobs one after another.
+ *
+ * Jobs execute sequentially (the underlying runner is already serialized, and a
+ * single KeyShot instance cannot render in parallel). By default the queue stops
+ * at the first failure; pass continueOnError to render every remaining job and
+ * collect all outcomes. Jobs that are skipped after an early stop are reported
+ * with skipped: true so the caller can see exactly what ran.
+ */
+export async function runRenderQueue(config, jobs, options = {}, runFn = runKeyShotSerialized) {
+    const continueOnError = options.continueOnError ?? false;
+    const results = [];
+    const outputFiles = [];
+    const warnings = [];
+    let succeeded = 0;
+    let failed = 0;
+    let stopped = false;
+    for (let index = 0; index < jobs.length; index += 1) {
+        const job = jobs[index];
+        if (stopped) {
+            results.push({
+                index,
+                scenePath: job.scenePath,
+                camera: job.camera,
+                ok: false,
+                outputFiles: [],
+                error: null,
+                skipped: true,
+            });
+            continue;
+        }
+        const result = await runFn(config, { operation: "render", ...job });
+        results.push({
+            index,
+            scenePath: job.scenePath,
+            camera: job.camera,
+            ok: result.ok,
+            outputFiles: result.outputFiles ?? [],
+            error: result.error ?? null,
+        });
+        if (result.ok) {
+            succeeded += 1;
+            outputFiles.push(...(result.outputFiles ?? []));
+        }
+        else {
+            failed += 1;
+            if (result.error)
+                warnings.push(`Job ${index} failed: ${result.error}`);
+            if (!continueOnError)
+                stopped = true;
+        }
+    }
+    const skipped = results.filter((entry) => entry.skipped).length;
+    return {
+        ok: failed === 0,
+        data: {
+            total: jobs.length,
+            succeeded,
+            failed,
+            skipped,
+            continueOnError,
+            results,
+        },
+        outputFiles,
+        warnings,
+        keyshotStdoutTail: "",
+        error: failed === 0 ? null : `${failed} of ${jobs.length} render job(s) failed.`,
+    };
+}

package/dist/runner.js

@@ -42,46 +42,59 @@ async function runKeyShot(config, request) {
         argsPath,
         resultPath,
     ];
-    const processResult = await spawnWithTimeout(config.keyshotHeadlessExe, args, config.keyshotTimeoutMs);
-    const stdoutTail = tail(processResult.stdout, 6000);
-    const stderrTail = tail(processResult.stderr, 6000);
-    let parsed = null;
-    if (await exists(resultPath)) {
-        try {
-            parsed = JSON.parse(await fs.readFile(resultPath, "utf8"));
+    try {
+        const processResult = await spawnWithTimeout(config.keyshotHeadlessExe, args, config.keyshotTimeoutMs);
+        const stdoutTail = tail(processResult.stdout, 6000);
+        const stderrTail = tail(processResult.stderr, 6000);
+        let parsed = null;
+        if (await exists(resultPath)) {
+            try {
+                parsed = JSON.parse(await fs.readFile(resultPath, "utf8"));
+            }
+            catch (error) {
+                return localFailure(`Could not parse KeyShot result JSON: ${errorMessage(error)}`, {
+                    keyshotStdoutTail: stdoutTail,
+                    warnings: stderrTail ? [`stderr: ${stderrTail}`] : [],
+                });
+            }
+        }
+        if (processResult.timedOut) {
+            return localFailure(`KeyShot timed out after ${config.keyshotTimeoutMs}ms`, {
+                data: parsed?.data ?? null,
+                outputFiles: parsed?.outputFiles ?? [],
+                warnings: [...(parsed?.warnings ?? []), ...(stderrTail ? [`stderr: ${stderrTail}`] : [])],
+                keyshotStdoutTail: stdoutTail,
+            });
         }
-        catch (error) {
-            return localFailure(`Could not parse KeyShot result JSON: ${errorMessage(error)}`, {
+        if (!parsed) {
+            return localFailure(`KeyShot did not produce a result file. Exit code: ${processResult.exitCode ?? "unknown"}`, {
                 keyshotStdoutTail: stdoutTail,
                 warnings: stderrTail ? [`stderr: ${stderrTail}`] : [],
             });
         }
+        parsed.keyshotStdoutTail = stdoutTail || parsed.keyshotStdoutTail || "";
+        if (stderrTail)
+            parsed.warnings = [...parsed.warnings, `stderr: ${stderrTail}`];
+        if (processResult.exitCode !== 0 && parsed.ok) {
+            return {
+                ...parsed,
+                ok: false,
+                error: `KeyShot exited with code ${processResult.exitCode}`,
+            };
+        }
+        return parsed;
     }
-    if (processResult.timedOut) {
-        return localFailure(`KeyShot timed out after ${config.keyshotTimeoutMs}ms`, {
-            data: parsed?.data ?? null,
-            outputFiles: parsed?.outputFiles ?? [],
-            warnings: [...(parsed?.warnings ?? []), ...(stderrTail ? [`stderr: ${stderrTail}`] : [])],
-            keyshotStdoutTail: stdoutTail,
-        });
-    }
-    if (!parsed) {
-        return localFailure(`KeyShot did not produce a result file. Exit code: ${processResult.exitCode ?? "unknown"}`, {
-            keyshotStdoutTail: stdoutTail,
-            warnings: stderrTail ? [`stderr: ${stderrTail}`] : [],
-        });
-    }
-    parsed.keyshotStdoutTail = stdoutTail || parsed.keyshotStdoutTail || "";
-    if (stderrTail)
-        parsed.warnings = [...parsed.warnings, `stderr: ${stderrTail}`];
-    if (processResult.exitCode !== 0 && parsed.ok) {
-        return {
-            ...parsed,
-            ok: false,
-            error: `KeyShot exited with code ${processResult.exitCode}`,
-        };
+    finally {
+        // Best-effort cleanup so work/tmp does not accumulate args/result files.
+        await cleanupTmp([argsPath, resultPath]).catch(() => undefined);
     }
-    return parsed;
+}
+async function cleanupTmp(paths) {
+    await Promise.all(paths.map(async (filePath) => {
+        if (await exists(filePath)) {
+            await fs.rm(filePath, { force: true });
+        }
+    }));
 }
 function spawnWithTimeout(command, args, timeoutMs) {
     return new Promise((resolve) => {

package/dist/schemas.js

@@ -1,8 +1,12 @@
 import { z } from "zod";
 const optionalPath = z.string().min(1).optional();
+const imageFormat = z.enum(["png", "jpg", "jpeg", "tif", "tiff", "exr"]);
 export const scenePathSchema = z.object({
     scenePath: z.string().min(1),
 });
+export const listCamerasSchema = z.object({
+    scenePath: z.string().min(1),
+});
 export const renderSchema = z.object({
     scenePath: z.string().min(1),
     outputPath: optionalPath,
@@ -13,6 +17,10 @@ export const renderSchema = z.object({
     camera: z.string().min(1).optional(),
     format: z.enum(["png", "jpg", "jpeg", "tif", "tiff", "exr"]).optional(),
 });
+export const renderInputSchema = renderSchema.refine((value) => !(value.samples !== undefined && value.maxTimeSeconds !== undefined), {
+    message: "Choose either samples or maxTimeSeconds, not both.",
+    path: ["maxTimeSeconds"],
+});
 export const batchRenderSchema = z.object({
     scenePath: z.string().min(1),
     outputDir: z.string().min(1),
@@ -24,6 +32,10 @@ export const batchRenderSchema = z.object({
     format: z.enum(["png", "jpg", "jpeg", "tif", "tiff", "exr"]).optional(),
     overwrite: z.boolean().optional(),
 });
+export const batchRenderInputSchema = batchRenderSchema.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,
@@ -63,3 +75,36 @@ export const saveSceneSchema = z.object({
     scenePath: z.string().min(1),
     outputScenePath: z.string().min(1),
 });
+// --- Render queue ---
+export const renderJobSchema = z.object({
+    scenePath: z.string().min(1),
+    outputPath: optionalPath,
+    camera: z.string().min(1).optional(),
+    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(),
+});
+export const renderJobInputSchema = renderJobSchema.refine((value) => !(value.samples !== undefined && value.maxTimeSeconds !== undefined), {
+    message: "Choose either samples or maxTimeSeconds, not both.",
+    path: ["maxTimeSeconds"],
+});
+export const renderQueueSchema = z.object({
+    jobs: z.array(renderJobSchema).min(1),
+    continueOnError: z.boolean().optional(),
+});
+export const renderQueueInputSchema = z.object({
+    jobs: z.array(renderJobInputSchema).min(1),
+    continueOnError: z.boolean().optional(),
+});
+// --- Material preset library ---
+export const listMaterialPresetsSchema = z.object({});
+export const applyMaterialPresetInputSchema = z.object({
+    scenePath: z.string().min(1),
+    presetName: z.string().min(1),
+    objectName: z.string().min(1).optional(),
+    objectPath: z.string().min(1).optional(),
+    outputScenePath: z.string().min(1),
+});
+export const applyMaterialPresetSchema = applyMaterialPresetInputSchema.refine((value) => value.objectName || value.objectPath, { message: "Provide objectName or objectPath." });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyshot-mcp",
-  "version": "0.2.1",
+  "version": "0.4.1",
   "description": "Local and portable MCP server for KeyShot headless scripting.",
   "type": "module",
   "homepage": "https://github.com/truman-t3/keyshot-mcp#readme",
@@ -19,6 +19,7 @@
     "prepare": "tsc -p tsconfig.json",
     "start": "node ./dist/index.js",
     "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
     "status": "node ./dist/cli/status.js"
   },
   "keywords": [
@@ -33,6 +34,7 @@
     "dist",
     "scripts/keyshot_bridge.py",
     "examples",
+    "presets",
     "README.md",
     "CONTRIBUTING.md",
     "SECURITY.md",
@@ -48,6 +50,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.17.2",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
   }
 }

package/presets/materials.json

@@ -0,0 +1,14 @@
+{
+  "Brushed Steel": {
+    "materialName": "Steel Brushed",
+    "description": "Default brushed stainless steel look for metal parts."
+  },
+  "Matte Black Plastic": {
+    "materialName": "Plastic Matte Black",
+    "description": "Soft-touch matte black plastic for housings and enclosures."
+  },
+  "Clear Glass": {
+    "materialName": "Glass Clear",
+    "description": "Transparent glass for covers and lenses."
+  }
+}

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,45 @@ 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))
-
-    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)),
-    )
+        try:
+            camera = first_camera_object(
+                lambda: lux.saveCamera(camera_name),
+                lambda: lux.saveCamera(),
+            )
+        except RuntimeError:
+            camera = None
+
+    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(camera_name, tuple(position)),
+            lambda: lux.setCameraPosition(tuple(position)),
+        )
+        call_variants(
+            "set camera look-at",
+            lambda: lux.setCameraLookAt(camera_name, tuple(look_at)),
+            lambda: lux.setCameraLookAt(tuple(look_at)),
+        )
+        call_variants(
+            "set camera up",
+            lambda: lux.setCameraUp(camera_name, tuple(up)),
+            lambda: lux.setCameraUp(tuple(up)),
+        )
 
     save_to(output_scene_path)
     output_files.append(output_scene_path)
@@ -386,13 +471,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 +492,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