keyshot-mcp 0.4.1 → 0.4.2

package/README.md

@@ -67,7 +67,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.4.2`. 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 +78,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.4.2"],"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.4.2 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.4.2.
+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.
 ```
@@ -188,6 +208,11 @@ save the scene to a new file, and render one preview from that camera.
 - `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.
@@ -248,11 +273,22 @@ KeyShot's Python `lux` API changes across versions. This server keeps the MCP in
 - [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, camera, save, and PNG-render workflow locally:
+
+```bash
+npm run smoke:keyshot
+```
+
 ## License
 
 MIT
@@ -324,7 +360,7 @@ MIT
 npm install -g keyshot-mcp
 ```
 
-当前发布版本为 `0.4.1`。如果你只是想使用 MCP 服务，直接安装 npm 包最简单。
+当前发布版本为 `0.4.2`。如果你只是想使用 MCP 服务，直接安装 npm 包最简单。
 电脑仍需要安装 KeyShot Studio，并且已经配置好本地 KeyShot 授权。
 
 ### 从源码安装
@@ -334,21 +370,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.4.2"],"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.4.2，并添加到我的 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.4.2 添加 keyshot MCP server。
+3. 把 KEYSHOT_HEADLESS_EXE 设置为检测到的 keyshot_headless 路径。
+4. 用 keyshot_status 工具测试是否配置成功。
+5. 最后告诉我实际添加的配置，以及状态检查是否通过。
 
 不要保存许可证密钥、账号密码或授权信息。直接使用我电脑上已有的 KeyShot 本地授权配置。
 ```
@@ -445,6 +501,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 渲染模式，请二选一，不要同时传入。
 
@@ -503,11 +563,22 @@ KeyShot 的 Python `lux` API 会随版本变化。这个 MCP 会尽量保持对
 - [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 { 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";
 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);

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/version.js

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

package/examples/demo/README.md

@@ -0,0 +1,9 @@
+# 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 an MCP
+camera, and renders `outputs/demo/keyshot-mcp-demo.png`. Generated `.bip` 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.4.2",
+  "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,67 @@
+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/5 KeyShot status", { operation: "status" });
+const imported = await run("2/5 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/5 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 cameraSceneResult = await run("4/5 Create camera and save scene", {
+  operation: "set_camera",
+  scenePath: importedScene,
+  cameraName: "MCP Demo",
+  position: [4.5, 3.5, 4.5],
+  lookAt: [0, 0, 0],
+  up: [0, 1, 0],
+  outputScenePath: "demo/keyshot-mcp-demo-camera.bip",
+});
+const cameraScene = cameraSceneResult.outputFiles[0];
+if (!cameraScene) throw new Error("Camera operation did not return a saved scene path.");
+
+const rendered = await run("5/5 Render real PNG", {
+  operation: "render",
+  scenePath: cameraScene,
+  camera: "MCP Demo",
+  outputPath: "demo/keyshot-mcp-demo.png",
+  width: 640,
+  height: 480,
+  maxTimeSeconds: 8,
+  format: "png",
+});
+
+console.log(JSON.stringify({
+  keyshotVersion: status.data?.version ?? null,
+  objectCount: objects.length,
+  scenePath: cameraScene,
+  imagePath: rendered.outputFiles[0] ?? null,
+}, null, 2));

package/scripts/keyshot_bridge.py

@@ -307,12 +307,17 @@ def set_camera(payload, output_files, warnings):
 
     if camera is None and hasattr(lux, "saveCamera"):
         try:
-            camera = first_camera_object(
+            # 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:
-            camera = None
+            pass
 
     if camera is not None:
         # Object-level API is available: drive the camera object directly.
@@ -325,18 +330,21 @@ def set_camera(payload, output_files, warnings):
         # 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(pos=tuple(position)),
             lambda: lux.setCameraPosition(tuple(position)),
+            lambda: lux.setCameraPosition(camera_name, tuple(position)),
         )
         call_variants(
             "set camera look-at",
+            lambda: lux.setCameraLookAt(pt=tuple(look_at)),
+            lambda: lux.setCameraLookAt(0, tuple(look_at)),
             lambda: lux.setCameraLookAt(camera_name, tuple(look_at)),
-            lambda: lux.setCameraLookAt(tuple(look_at)),
         )
         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)),
         )
 
     save_to(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.4.2",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "keyshot-mcp",
+      "version": "0.4.2",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "KEYSHOT_HEADLESS_EXE",
+          "description": "Absolute path to KeyShot headless, or a command available on PATH.",
+          "isRequired": true,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}