keyshot-mcp 0.4.1 → 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.1`. 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.
 
@@ -78,21 +79,41 @@ npm install
 npm run build
 ```
 
+### Three MCP configuration options
+
+Use exactly one of these approaches:
+
+**Global npm installation** (`npm install -g keyshot-mcp`):
+
+```json
+{"mcpServers":{"keyshot":{"command":"keyshot-mcp","env":{"KEYSHOT_HEADLESS_EXE":"/absolute/path/to/keyshot_headless"}}}}
+```
+
+**No installation, run with npx**:
+
+```json
+{"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`):
+
+```json
+{"mcpServers":{"keyshot":{"command":"node","args":["/absolute/path/to/keyshot-mcp/dist/index.js"],"env":{"KEYSHOT_HEADLESS_EXE":"/absolute/path/to/keyshot_headless"}}}}
+```
+
 ## Copy-Paste Setup Prompt for an Agent
 
 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 the KeyShot MCP server from https://github.com/truman-t3/keyshot-mcp.
+Install KeyShot MCP 0.5.0 from npm and configure it in my MCP client.
 
 Please:
-1. Clone the repository or use my local copy if it already exists.
-2. Run npm install and npm run build.
-3. Find my KeyShot headless executable path.
-4. Add a keyshot MCP server entry to my MCP client configuration.
-5. Set KEYSHOT_HEADLESS_EXE to the detected keyshot_headless path.
-6. Test the setup by running the keyshot_status tool.
-7. Tell me the exact config that was added and whether the status check passed.
+1. Find my KeyShot headless executable path.
+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.
 
 Do not store license keys or account passwords. Use my existing local KeyShot license configuration.
 ```
@@ -182,12 +203,22 @@ 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`.
 - `KEYSHOT_OUTPUT_DIR`: default output folder for renders.
 - `KEYSHOT_LICENSE_ARGS`: optional KeyShot headless license arguments. Empty by default.
 - `KEYSHOT_TIMEOUT_MS`: operation timeout in milliseconds. Default: `600000`.
+- `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS`: allow output paths outside `KEYSHOT_OUTPUT_DIR`. Default: `false`.
+
+By default every output file must stay inside `KEYSHOT_OUTPUT_DIR`. Relative paths
+are placed there automatically. Set the compatibility switch to `true` only when
+an external output location is intentional; input scenes and models are unrestricted.
 
 `samples` and `maxTimeSeconds` select different KeyShot render modes. Provide one
 or the other, not both.
@@ -199,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`
@@ -208,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
@@ -244,15 +285,26 @@ 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
-- [ ] Safer output directory restrictions
+- [x] Safer output directory restrictions
 - [ ] More tested KeyShot versions
 - [ ] macOS compatibility verification
 - [x] Claude Desktop / Cursor / Codex config examples
 
+## Real KeyShot demo
+
+![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, two-camera creation, save, discovery, and PNG-render workflow locally:
+
+```bash
+npm run smoke:keyshot
+```
+
 ## License
 
 MIT
@@ -285,6 +337,7 @@ MIT
 - 检查 `.bip` 或 KeyShot 支持的场景文件。
 - 把场景渲染成图片。
 - 从同一个场景批量渲染多个指定相机。
+- 自动发现并渲染场景中的全部相机。
 - 把模型导入场景。
 - 给对象替换材质。
 - 创建或更新相机。
@@ -324,7 +377,7 @@ MIT
 npm install -g keyshot-mcp
 ```
 
-当前发布版本为 `0.4.1`。如果你只是想使用 MCP 服务，直接安装 npm 包最简单。
+当前发布版本为 `0.5.0`。如果你只是想使用 MCP 服务，直接安装 npm 包最简单。
 电脑仍需要安装 KeyShot Studio，并且已经配置好本地 KeyShot 授权。
 
 ### 从源码安装
@@ -334,21 +387,41 @@ npm install
 npm run build
 ```
 
+### 三种独立配置方式
+
+下面三种方式选择一种即可：
+
+**全局 npm 安装**（先运行 `npm install -g keyshot-mcp`）：
+
+```json
+{"mcpServers":{"keyshot":{"command":"keyshot-mcp","env":{"KEYSHOT_HEADLESS_EXE":"C:/KeyShot/bin/keyshot_headless.exe"}}}}
+```
+
+**免安装，直接使用 npx**：
+
+```json
+{"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`）：
+
+```json
+{"mcpServers":{"keyshot":{"command":"node","args":["C:/path/to/keyshot-mcp/dist/index.js"],"env":{"KEYSHOT_HEADLESS_EXE":"C:/KeyShot/bin/keyshot_headless.exe"}}}}
+```
+
 ## 复制给 Agent 的安装提示词
 
 如果你使用 Codex 或其他编程 Agent，可以复制下面这段话，让 Agent 帮你安装和配置 MCP：
 
 ```text
-请帮我安装 KeyShot MCP Server：https://github.com/truman-t3/keyshot-mcp。
+请帮我安装 KeyShot MCP 0.5.0，并添加到我的 MCP 客户端。
 
 请你：
-1. 克隆这个仓库；如果本地已有，就使用本地版本。
-2. 运行 npm install 和 npm run build。
-3. 查找我电脑上的 KeyShot headless 可执行文件路径。
-4. 把 keyshot MCP server 添加到我的 MCP 客户端配置里。
-5. 把 KEYSHOT_HEADLESS_EXE 设置为检测到的 keyshot_headless 路径。
-6. 用 keyshot_status 工具测试是否配置成功。
-7. 最后告诉我实际添加的配置，以及状态检查是否通过。
+1. 查找我电脑上的 KeyShot headless 可执行文件路径。
+2. 使用 npx -y keyshot-mcp@0.5.0 添加 keyshot MCP server。
+3. 把 KEYSHOT_HEADLESS_EXE 设置为检测到的 keyshot_headless 路径。
+4. 用 keyshot_status 工具测试是否配置成功。
+5. 最后告诉我实际添加的配置，以及状态检查是否通过。
 
 不要保存许可证密钥、账号密码或授权信息。直接使用我电脑上已有的 KeyShot 本地授权配置。
 ```
@@ -438,6 +511,11 @@ examples/codex.example.json
 把场景保存为新文件，并用这个相机渲染一张预览图。
 ```
 
+```text
+自动找出这个 KeyShot 场景里的全部相机，把所有视角渲染到 all-cameras 文件夹。
+某个相机失败时继续处理其他相机，最后告诉我每个视角的结果。
+```
+
 ## 环境变量
 
 - `KEYSHOT_HEADLESS_EXE`：`keyshot_headless` 或 `keyshot_headless.exe` 的路径。
@@ -445,6 +523,10 @@ examples/codex.example.json
 - `KEYSHOT_LICENSE_ARGS`：可选的 KeyShot 无界面许可证参数，默认留空。
 - `KEYSHOT_TIMEOUT_MS`：单次操作超时时间，单位毫秒，默认 `600000`。
 - `KEYSHOT_MATERIAL_PRESETS`：材质预设库 JSON 文件路径，默认 `presets/materials.json`。
+- `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS`：是否允许写到默认输出目录之外，默认 `false`。
+
+默认情况下，所有输出图片和场景都必须写入 `KEYSHOT_OUTPUT_DIR`，相对路径会自动放入该目录。
+只有确实需要写到外部目录时才设置为 `true`；输入场景和模型路径不受此限制。
 
 `samples` 和 `maxTimeSeconds` 是两种不同的 KeyShot 渲染模式，请二选一，不要同时传入。
 
@@ -455,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`：替换材质。
@@ -464,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 注册表，让你用"好记的名字"复用材质，
@@ -499,15 +589,26 @@ KeyShot 的 Python `lux` API 会随版本变化。这个 MCP 会尽量保持对
 
 ## 路线图
 
-- [ ] 自动发现并批量渲染场景中的所有相机
+- [x] 自动发现并批量渲染场景中的所有相机
 - [x] 材质预设库
 - [ ] 相机预设模板
 - [x] 顺序渲染队列
-- [ ] 更安全的输出目录限制
+- [x] 更安全的输出目录限制
 - [ ] 测试更多 KeyShot 版本
 - [ ] 验证 macOS 兼容性
 - [x] 补充 Claude Desktop / Cursor / Codex 配置示例
 
+## 真实 KeyShot Demo
+
+![KeyShot MCP 自动生成的立方体 Demo](assets/demo/keyshot-mcp-demo.png)
+
+Demo 只使用 `examples/demo` 中项目自己生成的几何体，不包含客户模型或第三方素材。
+设置好 `KEYSHOT_HEADLESS_EXE` 后可复现状态检查、导入、检查场景、创建两个相机、自动发现、保存和真实 PNG 渲染：
+
+```bash
+npm run smoke:keyshot
+```
+
 ## 测试
 
 项目带了两套测试，不依赖真实的 KeyShot 也能跑：

package/dist/config.js

@@ -9,6 +9,7 @@ export function getConfig() {
         projectRoot,
         keyshotHeadlessExe: process.env.KEYSHOT_HEADLESS_EXE ?? DEFAULT_KEYSHOT_EXE,
         keyshotOutputDir,
+        keyshotAllowExternalOutputs: parseBoolean(process.env.KEYSHOT_ALLOW_EXTERNAL_OUTPUTS),
         keyshotLicenseArgs: splitWindowsArgs(process.env.KEYSHOT_LICENSE_ARGS ?? ""),
         keyshotTimeoutMs: parsePositiveInt(process.env.KEYSHOT_TIMEOUT_MS, DEFAULT_TIMEOUT_MS),
         tmpDir: path.join(projectRoot, "work", "tmp"),
@@ -16,6 +17,9 @@ export function getConfig() {
         materialPresetsPath: path.resolve(process.env.KEYSHOT_MATERIAL_PRESETS ?? path.join(projectRoot, "presets", "materials.json")),
     };
 }
+function parseBoolean(value) {
+    return ["1", "true", "yes", "on"].includes((value ?? "").trim().toLowerCase());
+}
 function parsePositiveInt(value, fallback) {
     if (!value)
         return fallback;

package/dist/index.js

@@ -6,11 +6,12 @@ import { toolResponse, localFailure } from "./result.js";
 import { runKeyShotSerialized } from "./runner.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";
+import { VERSION } from "./version.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",
-    version: "0.4.1",
+    version: VERSION,
 });
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -71,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/output-paths.js

@@ -0,0 +1,55 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const OUTPUT_FIELDS = ["outputPath", "outputDir", "outputScenePath"];
+export async function normalizeOutputPaths(config, request) {
+    await fs.mkdir(config.keyshotOutputDir, { recursive: true });
+    const normalized = { ...request };
+    for (const field of OUTPUT_FIELDS) {
+        const value = request[field];
+        if (typeof value !== "string" || value.length === 0)
+            continue;
+        normalized[field] = await normalizeOutputPath(config, value);
+    }
+    return normalized;
+}
+export async function normalizeOutputPath(config, value) {
+    const candidate = path.resolve(config.keyshotOutputDir, value);
+    if (config.keyshotAllowExternalOutputs)
+        return candidate;
+    const outputRoot = await realpathWithMissingTail(config.keyshotOutputDir);
+    const resolvedCandidate = await realpathWithMissingTail(candidate);
+    if (!isWithin(outputRoot, resolvedCandidate)) {
+        throw new Error(`Output path must stay inside KEYSHOT_OUTPUT_DIR (${config.keyshotOutputDir}): ${value}. ` +
+            "Set KEYSHOT_ALLOW_EXTERNAL_OUTPUTS=true only if external writes are intentional.");
+    }
+    return candidate;
+}
+async function realpathWithMissingTail(inputPath) {
+    let current = path.resolve(inputPath);
+    const missing = [];
+    while (!(await exists(current))) {
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        missing.unshift(path.basename(current));
+        current = parent;
+    }
+    const realBase = await fs.realpath(current);
+    return path.resolve(realBase, ...missing);
+}
+function isWithin(root, candidate) {
+    const relative = path.relative(normalizeCase(root), normalizeCase(candidate));
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+function normalizeCase(value) {
+    return process.platform === "win32" ? value.toLowerCase() : value;
+}
+async function exists(value) {
+    try {
+        await fs.lstat(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/runner.js

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { localFailure } from "./result.js";
+import { normalizeOutputPaths } from "./output-paths.js";
 let queue = Promise.resolve();
 export function runKeyShotSerialized(config, request) {
     const run = queue.then(() => runKeyShot(config, request));
@@ -10,8 +11,7 @@ export function runKeyShotSerialized(config, request) {
     return run;
 }
 async function runKeyShot(config, request) {
-    const exeExists = await exists(config.keyshotHeadlessExe);
-    if (!exeExists) {
+    if (isPathLike(config.keyshotHeadlessExe) && !(await exists(config.keyshotHeadlessExe))) {
         return localFailure(`KeyShot headless executable not found: ${config.keyshotHeadlessExe}`);
     }
     const bridgeExists = await exists(config.bridgeScriptPath);
@@ -23,11 +23,18 @@ async function runKeyShot(config, request) {
     }
     await fs.mkdir(config.tmpDir, { recursive: true });
     await fs.mkdir(config.keyshotOutputDir, { recursive: true });
+    let normalizedRequest;
+    try {
+        normalizedRequest = await normalizeOutputPaths(config, request);
+    }
+    catch (error) {
+        return localFailure(errorMessage(error));
+    }
     const id = `${Date.now()}-${randomUUID()}`;
     const argsPath = path.join(config.tmpDir, `${id}.args.json`);
     const resultPath = path.join(config.tmpDir, `${id}.result.json`);
     const payload = {
-        ...request,
+        ...normalizedRequest,
         defaults: {
             outputDir: config.keyshotOutputDir,
         },
@@ -36,7 +43,7 @@ async function runKeyShot(config, request) {
     const args = [
         ...config.keyshotLicenseArgs,
         "-progress",
-        ...(request.scenePath ? [request.scenePath] : []),
+        ...(normalizedRequest.scenePath ? [normalizedRequest.scenePath] : []),
         "-script",
         config.bridgeScriptPath,
         argsPath,
@@ -58,6 +65,12 @@ async function runKeyShot(config, request) {
                 });
             }
         }
+        if (processResult.spawnError) {
+            return localFailure(`Could not start KeyShot headless: ${processResult.spawnError}`, {
+                keyshotStdoutTail: stdoutTail,
+                warnings: stderrTail ? [`stderr: ${stderrTail}`] : [],
+            });
+        }
         if (processResult.timedOut) {
             return localFailure(`KeyShot timed out after ${config.keyshotTimeoutMs}ms`, {
                 data: parsed?.data ?? null,
@@ -96,9 +109,11 @@ async function cleanupTmp(paths) {
         }
     }));
 }
-function spawnWithTimeout(command, args, timeoutMs) {
+export const MAX_CAPTURE_CHARS = 64 * 1024;
+export function spawnWithTimeout(command, args, timeoutMs) {
     return new Promise((resolve) => {
         const child = spawn(command, args, {
+            detached: process.platform !== "win32",
             windowsHide: true,
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -106,30 +121,64 @@ function spawnWithTimeout(command, args, timeoutMs) {
         let stderr = "";
         let settled = false;
         let timedOut = false;
+        let spawnError = null;
         const timer = setTimeout(() => {
             timedOut = true;
-            child.kill("SIGTERM");
+            terminateProcessTree(child.pid, "SIGTERM");
             setTimeout(() => {
-                if (!settled)
-                    child.kill("SIGKILL");
+                if (!settled && process.platform !== "win32")
+                    terminateProcessTree(child.pid, "SIGKILL");
             }, 2500).unref();
         }, timeoutMs);
         child.stdout?.on("data", (chunk) => {
-            stdout += String(chunk);
+            stdout = appendBounded(stdout, String(chunk));
         });
         child.stderr?.on("data", (chunk) => {
-            stderr += String(chunk);
+            stderr = appendBounded(stderr, String(chunk));
         });
         child.on("error", (error) => {
-            stderr += errorMessage(error);
+            spawnError = errorMessage(error);
+            stderr = appendBounded(stderr, spawnError);
         });
         child.on("close", (exitCode) => {
             settled = true;
             clearTimeout(timer);
-            resolve({ exitCode, stdout, stderr, timedOut });
+            resolve({ exitCode, stdout, stderr, timedOut, spawnError });
         });
     });
 }
+function terminateProcessTree(pid, signal) {
+    if (!pid)
+        return;
+    if (process.platform === "win32") {
+        const killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
+            windowsHide: true,
+            stdio: "ignore",
+        });
+        killer.on("error", () => undefined);
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // The process may already have exited.
+        }
+    }
+}
+function appendBounded(current, addition) {
+    const combined = current + addition;
+    return combined.length <= MAX_CAPTURE_CHARS
+        ? combined
+        : combined.slice(combined.length - MAX_CAPTURE_CHARS);
+}
+function isPathLike(command) {
+    return path.isAbsolute(command) || command.includes("/") || command.includes("\\");
+}
 async function exists(filePath) {
     try {
         await fs.access(filePath);

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

@@ -0,0 +1 @@
+export const VERSION = "0.5.0";

package/examples/demo/README.md

@@ -0,0 +1,10 @@
+# KeyShot smoke-test demo
+
+`keyshot-mcp-cube.obj` is original, generated geometry included under this
+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 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/examples/demo/keyshot-mcp-cube.obj

@@ -0,0 +1,23 @@
+# KeyShot MCP generated demo cube
+# Original geometry released under the repository MIT license.
+o KeyShot_MCP_Cube
+v -1.0 -1.0 -1.0
+v  1.0 -1.0 -1.0
+v  1.0  1.0 -1.0
+v -1.0  1.0 -1.0
+v -1.0 -1.0  1.0
+v  1.0 -1.0  1.0
+v  1.0  1.0  1.0
+v -1.0  1.0  1.0
+vn  0.0  0.0 -1.0
+vn  0.0  0.0  1.0
+vn  0.0 -1.0  0.0
+vn  0.0  1.0  0.0
+vn -1.0  0.0  0.0
+vn  1.0  0.0  0.0
+f 1//1 4//1 3//1 2//1
+f 5//2 6//2 7//2 8//2
+f 1//3 2//3 6//3 5//3
+f 4//4 8//4 7//4 3//4
+f 1//5 5//5 8//5 4//5
+f 2//6 3//6 7//6 6//6

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "keyshot-mcp",
-  "version": "0.4.1",
+  "version": "0.5.0",
+  "mcpName": "io.github.truman-t3/keyshot-mcp",
   "description": "Local and portable MCP server for KeyShot headless scripting.",
   "type": "module",
   "homepage": "https://github.com/truman-t3/keyshot-mcp#readme",
@@ -20,7 +21,8 @@
     "start": "node ./dist/index.js",
     "check": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
-    "status": "node ./dist/cli/status.js"
+    "status": "node ./dist/cli/status.js",
+    "smoke:keyshot": "npm run build && node ./scripts/keyshot-smoke.mjs"
   },
   "keywords": [
     "mcp",
@@ -33,8 +35,11 @@
   "files": [
     "dist",
     "scripts/keyshot_bridge.py",
+    "scripts/keyshot-smoke.mjs",
     "examples",
+    "assets/demo",
     "presets",
+    "server.json",
     "README.md",
     "CONTRIBUTING.md",
     "SECURITY.md",
@@ -44,6 +49,7 @@
   "engines": {
     "node": ">=20"
   },
+  "packageManager": "pnpm@10.17.1",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.18.1",
     "zod": "^3.25.76"

package/scripts/keyshot-smoke.mjs

@@ -0,0 +1,107 @@
+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";
+import { runKeyShotSerialized } from "../dist/runner.js";
+
+const repoRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+const config = getConfig();
+const modelPath = path.join(repoRoot, "examples", "demo", "keyshot-mcp-cube.obj");
+
+async function run(label, request) {
+  process.stdout.write(`${label}... `);
+  const result = await runKeyShotSerialized(config, request);
+  if (!result.ok) {
+    process.stdout.write("failed\n");
+    throw new Error(`${label}: ${result.error}\n${result.warnings.join("\n")}`);
+  }
+  process.stdout.write("ok\n");
+  return result;
+}
+
+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",
+});
+const importedScene = imported.outputFiles[0];
+if (!importedScene) throw new Error("Import did not return a saved scene path.");
+
+const inspected = await run("3/7 Inspect imported scene", {
+  operation: "inspect_scene",
+  scenePath: importedScene,
+});
+const objects = inspected.data?.objects;
+if (!Array.isArray(objects) || objects.length === 0) {
+  throw new Error("Imported scene did not contain any inspectable objects.");
+}
+
+const firstCameraResult = await run("4/7 Create first camera and save scene", {
+  operation: "set_camera",
+  scenePath: importedScene,
+  cameraName: "MCP Front",
+  position: [4.5, 3.5, 4.5],
+  lookAt: [0, 0, 0],
+  up: [0, 1, 0],
+  outputScenePath: "demo/keyshot-mcp-demo-camera-front.bip",
+});
+const firstCameraScene = firstCameraResult.outputFiles[0];
+if (!firstCameraScene) throw new Error("First camera operation did not return a saved scene path.");
+
+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,
+  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,
+  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,39 +410,53 @@ def set_camera(payload, output_files, warnings):
         lambda: lux.createCamera(camera_name),
     )
 
-    if camera is None and hasattr(lux, "saveCamera"):
-        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 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(camera_name, tuple(position)),
-            lambda: lux.setCameraPosition(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)),
-            lambda: lux.setCameraLookAt(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(camera_name, tuple(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

@@ -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.5.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "keyshot-mcp",
+      "version": "0.5.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "KEYSHOT_HEADLESS_EXE",
+          "description": "Absolute path to KeyShot headless, or a command available on PATH.",
+          "isRequired": true,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}